The IMAP parallel to browser sessions makes sense. External state that changes independently of your code is the hard case - your doc can describe "the session is authenticated" but by the time the agent reads it that might no longer be true. The document is a snapshot, not a live connection.
One thing we haven't solved cleanly: what happens when the external state change is what triggers the agent task in the first place? Like, a session getting flagged and needing recovery. The event comes from outside the doc system, so there's a gap between "thing happened" and "agent knows about it".
On the "event → agent" gap: we've been thinking about this as a layered problem.
The bridge is a file write. agent-doc is user-initiated (edit a doc, hit submit), but the diff pipeline doesn't care who writes the file. A watcher process — or any external system — can write to the file system, and the agent sees the change on next poll.
We already do this in a different layer: corky (https://github.com/btakita/corky), our email tool, runs a watch daemon that polls IMAP for new messages and syncs them to markdown files on disk. External event (email arrives) gets translated into a file-system change, which is the agent's native input format. Same pattern would work for session recovery: monitoring process detects flagged session → writes to a task file → agent picks it up.
Dashboard-as-document is something we're actively planning. The idea: a markdown template where a watcher fills in operational fields — session status, health checks, proxy assignments. When the watcher updates "active" → "flagged", the diff pipeline sees exactly what changed. The template gives structure; the diff gives the trigger.
The snapshot diff already works for this — partial support exists today via agent-doc's routing layer (external scripts can trigger submission when a file changes). What we're building next is auto-submit on file change and sectional write-back so the agent can update specific dashboard fields rather than only appending.
For sub-second latency, a lightweight daemon that receives webhooks and writes to the notification file or directly triggers an agent submit. But for most operational tasks, a polling interval (ours runs every 30 seconds) closes the gap well enough.
The gap you're describing — "thing happened" to "agent knows about it" — is really about who writes the event into the file system. Once it's a file change, the diff pipeline handles the rest.
the dashboard-as-document idea is pretty much exactly what we ended up needing. in our case the operational state (which sessions are live, which proxies are assigned, what their detection status is) was getting stale almost immediately in any static doc. a watcher that keeps specific fields fresh while leaving the rest of the doc stable solves that without turning the whole thing into a firehose.
we actually built around this problem specifically - CloakBrowser (https://github.com/CloakHQ/CloakBrowser) is focused on browser session isolation, and the state-sync piece was one of the harder parts to get right. each session has runtime state that no static spec can capture. the file-write pattern for feeding live state into agent context would have saved us some pain early on.
curious about the sectional write-back you mentioned building - does the agent target sections by header, or is it more like named anchors in the markdown?
On concurrent editing — it's handled at two levels:
*Ownership:* Each document is claimed by one tmux pane (one agent session). The routing layer prevents two agents from working the same doc simultaneously.
*3-way merge:* If I edit the document while the agent is mid-response, agent-doc detects the change on write-back and runs `git merge-file --diff3` — baseline (pre-commit), agent response, and my concurrent edits all merge. Non-overlapping changes merge cleanly; overlapping changes get conflict markers. Nothing is silently dropped.
The pre-submit git commit is the key — it creates an immutable baseline before the agent touches anything, so there's always a clean reference point for the merge.