Agent inbox (#445 phase 2): read-until-ack, no pane writes, opt-in persistence?

[Randalix]

Follow-up to #445, as you asked: Phase 2 as its own discussion once Phase 1 is up (#557).

I've been running an agent inbox on my fork since mid-September, with up to five sessions (claude, codex, opencode) coordinating through it daily. Your outline in #445 differs from what I built in three places that matter. Two of them came from failures I hit in practice, the third from how I deploy, so before writing the upstream version I'd like to settle them with you.

Where we agree

No file drop, part of the wire contract. Owner-scoped through findSessionOrFail. A per-session cap (mine is 200 messages, and a full inbox refuses the post instead of dropping the oldest). ?wait= bounded (mine has its own cap of 4 parked reads per session; folding that into the session-wait-registry accounting is fine with me). And from as the resolved caller instead of a client-supplied string: mine takes the label from the body or the X-Codeman-Parent-Session header, which is spoofable in multi-user mode. You're right there and I'd change it.

1. Drain on read

I started with that (a read acknowledged what it handed out) and lost orders with it. On 2026-09-23 an opencode planner posted a task to a codex worker and nudged it with "read your mailbox". The worker ran the read, summarised the message back, and ended its turn. The read had consumed the message, so the inbox was empty and ls showed nothing pending. To the planner, "read and dropped" looked exactly like "done", and the task only got done after a human prompted the worker a second time.

What I have now: a read marks messages as seen and hands them out, and they stay until the receiver calls ack. ls shows pending mail per session, so an order that was read and not handled stays visible. A TTL on top is fine.

2. No pane write

I agree the server shouldn't push into panes by default. The problem is the opposite case: an idle receiver never looks. In a map-editing run on 2026-09-27, a codex coordinator posted tasks to two idle workers and neither read them; afterwards their completion posts sat unread in the coordinator's inbox. Every hand-off needed a manual send.

My fork answers that with a one-line nudge typed into a receiver that would never look. Each message is nudged at most once, posts within 2 s share one nudge, there's a 30 s cooldown, nothing is typed while the receiver is parked on a read, and a busy pane gets it when it goes idle, or after 5 minutes regardless. It doesn't type over a half-written prompt, as far as Codeman can see one (text that came through its own input path without an Enter). It works, but it's a pane write, which is what you ruled out for v1.

A version without pane writes that would still have caught both cases: the server already knows, per session, whether a turn has ended and how much mail is pending. If the coordinator can see "worker X is idle with unread mail" right away, it can nudge X itself with the existing input path. That's an explicit act by an agent, not the server. On my fork that's codeman agent watch, which long-polls on a per-session "turn ended at" latch and reports a reason (inbox-unread, inbox-unacked, open-todos, blocked, …) with a cursor so no turn end is missed between calls. In one test each: for claude the watch returned 6 ms after the stop hook landed, for codex the idle heuristic fired about 5 s after the rollout's task_complete. If that direction interests you, it would be its own proposal after the inbox.

3. Memory only

I restart my server on every deploy (five times today). With an in-memory inbox, every restart would drop pending orders between agents that keep running in tmux across the restart. Mine writes a snapshot on change and restores it at boot, pruning inboxes of sessions that no longer exist. Making persistence opt-in (off by default) would keep your "nothing new on disk" for everyone else.

Proposal for the upstream version

• Read marks seen, ack removes, per-session cap, TTL.
• from resolved server-side.
• No pane writes. Pending/unseen counts and the "parked on ?wait" state are exposed in the session list or a summary route, so a coordinating agent can decide.
• Persistence opt-in.

Does that shape work for you, or do you still want drain-on-read for v1?

[Randalix]

Quick ping on this one, no rush.

The inbox has kept running on my fork every day since I posted, and it works well for us now. Since Oct 8 the server restarted 44 times (deploys), and 41 of those starts brought back mail that was still pending, so point 3 is not a hypothetical here.

One thing went wrong in exactly the way you were worried about. The nudge line starts with [codeman inbox] 1 new message and ends in Enter, and on Oct 11 it landed in an open AskUserQuestion dialog: the 1 picked option 1 and the Enter confirmed it, three seconds after the question opened. The nudger now asks the Approvals Inbox whether a question or permission item is open for the session and waits until it's answered. That has happened 21 times since.

The other lost nudges were a Codex problem that turned out to affect every programmatic send, not just the inbox. I'm opening a separate issue and PR for that.

The shape I'd still propose is the one above (read until ack, persistence opt-in). If you want v1 without any pane writes, I'll leave the nudger on the fork and expose the unread/idle state instead. Which way should the PR go?

[Ark0N]

Thanks for running this daily for three weeks before asking. The incident dates make this easy to decide. Short version: your shape, all four bullets, as one PR.

1. Read until ack: yes, drop drain-on-read. The 09-23 case decides it. With drain-on-read, "read and dropped" and "done" look identical to the sender, and nothing on the server can tell them apart afterwards. It also matches the approvals inbox better than my outline did: an item there is resolved by an answer, never by being looked at. And on the HTTP side, the Origin guard skips GET/HEAD/OPTIONS (SAFE_HTTP_METHODS in middleware/auth.ts), so removal belongs on a POST anyway, which ack gives us.

Four details I'd want pinned, because each one is the 09-23 failure again, one hop further away:

• seen and ack only count when the resolved caller is the receiving session. A coordinator (or later the web UI) reading a worker's inbox is a peek and changes nothing. Otherwise the coordinator's own read flips the worker's mail to seen, and the unseen count lies to whoever checks next.
• ?wait= parks while nothing is unseen, not while the inbox is empty. Otherwise a receiver holding one seen-but-unacked message spins on a long-poll that returns at once.
• ack takes message ids and is idempotent: acking an id that is already gone is a success, so a retry after a dropped response is not an error.
• A byte cap per message and per inbox, next to the 200-message count. A full inbox refuses the post (agreed, never drop the oldest). 409 with CONFLICT and a clear message is enough, no new errorCode needed. The text is stored and handed back as data, never typed, so multi-line is fine here, a nice difference from send.

from: resolve it with resolveParentSessionId() (route-helpers.ts), the resolver lineage already uses: a live session, exact id or unique prefix of at least 8, same owner as the receiver; anything else means no session, and the message is from the user. Say plainly in the docs what that buys: in multi-user mode it can't name another owner's session, in single-user mode it is still a hint, since every local process holds the same credentials.

2. No pane writes in v1: yes, keep the nudger on your fork. Your Oct 11 incident is now a better reason for that line than the one I had. The guard you added asks the Approvals Inbox, and that only knows dialogs some detector reported: Claude's hooks today, codex's blocked detection once #624 lands, nothing for opencode. Every CLI without a detector is a blind spot where a digit and an Enter pick an option. So expose the state instead:

• an owner-scoped summary route with per-session pending, unseen, oldest unseen time and parked. Counts only, never bodies;
• kept out of toState(), so a post doesn't fan out a session:updated to every open browser;
• codeman agent ls merges it into its table.

The watch latch is interesting on its own. Our wait signals are edge-triggered with no history, so a turn end between two calls is simply missed today, and a cursor fixes exactly that. Open it as its own discussion once the inbox is in.

3. Persistence opt-in: yes. 41 of 44 restarts bringing back pending mail settles it. What I'd want in it:

• a synced App Setting, default OFF. Off means no file is written, and switching it off deletes the snapshot (the in-memory inboxes stay);
• its own file through dataPath(), written 0600 with tmp+rename like intents.json, since agent messages carry the same kind of text prompts do. Never fed to /api/search;
• pruning at boot only after the session restore succeeded, the gate tab layouts use (markRestorationComplete() in finalizeRestoredState, server.ts). A failed restore must leave the snapshot alone, or one bad boot loses every live session's mail;
• the TTL counted from each message's own timestamp, so a restore doesn't restart the clock. 12 h like the approvals inbox is fine.

An inbox goes with its session on delete, not on detach (a detached session comes back, same rule as the agent preamble cache).

PR scope: store, routes, the codeman agent verbs, tests, docs/api-reference.md, and the skill plus its plugin mirror (node scripts/sync-plugin.mjs; test/plugin-manifest.test.ts pins the copy). The routes are public under /api/v1 from the first release that carries them, so names matter more than usual: put the route list at the top of the PR body and I'll go through that first. The web badge and MCP tools can follow as separate PRs.

Also thanks for splitting the Codex send problem out into #627.