# Why one data store has one Agent

A session appeared on the desktop but not on the phone. Two parallel services led us back to ownership, discovery and explicit client context.

Bruce · 2026-11-05 · Originally recorded: 2026-10-28

https://bruce.flydog.ai/blog/one-store-one-agent?lang=en

<a id="two-different-answers"></a>

## Two entry points that each looked healthy

During one investigation, the resident Agent and a development window's Agent served the same data directory in parallel. The window searched a presumed port, found nothing there and started another service. The phone's entry point belonged to the service that had arrived first. A new desktop session never appeared on the phone, with no obvious error on either side.

Adding another refresh could not explain the situation. The entry points had found different service instances. The October 2026 fix started with a more basic rule: ownership of shared state must be explicit.

<a id="store-identity"></a>

## The boundary is a data store, not the entire device

Bruce now uses the data directory as the ownership boundary. One Agent holds a store. A second launch for that store discovers the existing holder, says who is serving and steps aside. Clients no longer need to guess a fixed port independently.

Separate stores may have separate Agents. This is useful isolation, particularly for tests, which must not mix their fixtures with a person's task list. A rule allowing only one process on an entire computer would erase that useful distinction.

<a id="lock-and-record"></a>

## A lock establishes ownership; a record enables discovery

The implementation separates two jobs. An operating-system file lock establishes who may serve the state, and the Agent acquires it before touching the store. The lock is released when its holder exits. A file remaining on disk must not be mistaken for a lock still being held.

After claiming ownership, the Agent records its process, listening address and startup information. It writes the complete record to a temporary file before renaming it, so readers do not see half a record. Other entry points read that record to locate the serving instance.

A record can outlive its process, so finding it does not establish that the service is online. The caller must still check that the recorded address answers. Keeping ownership, discovery and availability distinct makes failures easier to locate.

```text
One data store
  Lock     → Who may serve this state
  Record   → Where to find the holder
  Response → Whether it is available now
```

<a id="context"></a>

## A shared service still needs explicit project context

Finding the service is only the first step. A window, phone or other client must identify the project, session and requester. The service cannot infer which directory a phone means from the most recently active window.

This separates the interface from the work state. Clients express their current context; the service owns the tasks, terminals and records it holds. Changing entry points should not accidentally switch to a different body of work. Access remains governed by the relevant permissions and connection configuration.

<a id="regression-and-lifetime"></a>

## Test the boundary and explain the lifetime

Regression tests cover a second claim on the same store being rejected, ownership becoming available after release, and independent stores remaining independent. Those conditions are more precise than one successful-looking connection.

Closing a client and restarting the Agent are different operations. A store lock and discovery record do not keep terminal processes alive across an Agent restart. Continued work still depends on an online host, service settings and the actual process lifetime. Lossless handoff requires separate design and verification.

- Confirm that both clients mean the same data and service before investigating synchronization.
- Use explicit ownership to prevent launch races, and discovery records instead of port guesses.
- Declare the project, session and requester rather than inferring them from recent interface activity.
- Give tests isolated storage and preserve the person's working sessions.