fix: apply the review items for #690 at merge

Boot prune keeps the inboxes of sessions on the reboot-restore offer (their records are already pruned and a rebuild reuses the id), with a case in test/agent-inbox-server-wiring.test.ts.
docs/wiki: post, inbox and ack in the codeman agent command block of Driving-Codeman-From-An-Agent, and "Keep agent inbox across restarts" in Settings-Reference.
codeman agent inbox prints message text through terminalSafeText (ANSI stripped, other C0, DEL and C1 controls shown as \xHH); --json stays as stored.
Shutdown flushes the inbox snapshot again after app.close(), for a post that lands after the first flush.
POST /api/cleanup-state drops the inboxes of the records it removes.
InboxPostSchema derives its fence from MAX_MESSAGE_BYTES instead of the literal.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

docs/api-reference.md

@@ -668,7 +668,8 @@ detached. By default inboxes live in memory and a server restart empties them.
 The synced setting `agentInboxPersistEnabled` (default off; Settings → Cross-session features)
 writes them to `agent-inbox.json` in the data dir (mode `0600`, tmp file +
 rename) and restores them at boot. Inboxes of sessions that did not come back
-are pruned only after the session restore succeeded. Switching the setting off
+are pruned only after the session restore succeeded; a session on the
+reboot-restore offer keeps its inbox, so a rebuild finds its mail. Switching the setting off
 deletes the file and keeps what is in memory. The file is never read by
 `/api/search`, and the file viewer refuses it.
 

docs/architecture-invariants.md

@@ -700,7 +700,7 @@ Frontend `readmymind-ui.js`: header 🧠 marker-hidden (`btn-readmymind--hidden`
 
 ⚠️ **Caps refuse, they never drop.** 16 KiB per message (UTF-8 bytes), 512 KiB and 200 messages per inbox; a full inbox is 409 CONFLICT and nothing is stored. Dropping the oldest would lose exactly the message a slow receiver has not handled yet. TTL is 12 h from each message's own `createdAt`, swept lazily, and a restore keeps `createdAt`, so a restart does not restart the clock.
 
-⚠️ **Lifetime follows the session, not the pane.** `_doCleanupSession` drops the inbox only when `killMux` is set (a real delete); a detach or server shutdown keeps it, and `DELETE /api/sessions/:id` on a row that is no longer live (the persisted-only branch in `session-routes.ts`) drops what the detach kept. A detach also ends a parked read with `ended: true`, which is why `codeman agent inbox --wait` asks the session list before it exits 3. Persistence (`agentInboxPersistEnabled`, SYNCED, default OFF) writes `agent-inbox.json` via `dataPath()`, 0600 through tmp+rename, debounced and flushed on stop; off means no file, and switching it off deletes the snapshot while memory stays. It is never fed to `/api/search`, and `sensitive-path.ts` keeps the file viewer off it. Boot loads the snapshot before `restoreMuxSessions`, but prunes inboxes of sessions that no longer exist only in `finalizeRestoredState`'s SUCCESS path: a failed restore must not delete mail for sessions that are about to come back. Tests: `test/agent-inbox.test.ts`, `test/agent-inbox-persistence.test.ts`, `test/routes/inbox-routes.test.ts`, `test/agent-inbox-server-wiring.test.ts`, the inbox block in `test/session-wait-registry.test.ts`.
+⚠️ **Lifetime follows the session, not the pane.** `_doCleanupSession` drops the inbox only when `killMux` is set (a real delete); a detach or server shutdown keeps it, and `DELETE /api/sessions/:id` on a row that is no longer live (the persisted-only branch in `session-routes.ts`) drops what the detach kept. A detach also ends a parked read with `ended: true`, which is why `codeman agent inbox --wait` asks the session list before it exits 3. Persistence (`agentInboxPersistEnabled`, SYNCED, default OFF) writes `agent-inbox.json` via `dataPath()`, 0600 through tmp+rename, debounced and flushed on stop; off means no file, and switching it off deletes the snapshot while memory stays. It is never fed to `/api/search`, and `sensitive-path.ts` keeps the file viewer off it. Boot loads the snapshot before `restoreMuxSessions`, but prunes inboxes of sessions that no longer exist only in `finalizeRestoredState`'s SUCCESS path: a failed restore must not delete mail for sessions that are about to come back. The keep set is the live sessions, the records `state.json` still holds AND the sessions on the reboot-restore offer (`rebootRestoreRegistry`): `cleanupStaleSessions()` has already pruned an offered session's record by then, and a rebuild reuses its id, so leaving the offer out returned every rebuilt session with an empty inbox (the 12 h TTL bounds what is never rebuilt). `POST /api/cleanup-state` drops the inboxes of the records it removes, since it is a delete for a detached row. Tests: `test/agent-inbox.test.ts`, `test/agent-inbox-persistence.test.ts`, `test/routes/inbox-routes.test.ts`, `test/agent-inbox-server-wiring.test.ts`, the inbox block in `test/session-wait-registry.test.ts`.
 
 ### Voice dictation via Claude
 

docs/wiki/Driving-Codeman-From-An-Agent.md

@@ -47,6 +47,9 @@ codeman agent read "$SID" --tail 3000                     # terminal tail, ANSI
 codeman agent send "$SID" 'run the tests, then print WORKDONE followed by _4711'   # hook-less modes: the marker in halves …
 codeman agent wait "$SID" --match WORKDONE_4711           # … and the wait on the joined form
 codeman agent interrupt "$SID"                            # a bare ESC, conversation intact
+codeman agent post "$SID" 'context for later, not a prompt'   # stored in its inbox, not typed into the pane
+codeman agent inbox --wait --timeout 300000               # your own inbox: blocks while nothing is new
+codeman agent ack <msg-id>                                # remove what you handled (read never removes)
 codeman agent rm "$SID"                                   # any session except this one
 ```
 
@@ -56,6 +59,14 @@ codeman agent rm "$SID"                                   # any session except t
   starts with `-` goes after `--`: `codeman agent send "$SID" -- "- fix the bug"`.
 - **Markers** follow [the split-marker trick](#the-split-marker-trick): the echo of your own
   prompt is output too, so ask for the marker in halves and wait on the joined form.
+- **`post`, `inbox`, `ack`** are the agent inbox: a message for another session that starts
+  no turn. `post` stores ONE quoted argument (multi-line is fine, so `"$(cat task.md)"` works)
+  and types nothing into the pane. `inbox` reads this session's mail, or peeks at another's
+  with an id, and removes nothing; `ack <id>…` removes what you handled. `inbox --wait`
+  blocks while nothing is new, so mail you read but did not ack does not wake it again.
+  `ls` shows each session's mail in an INBOX column. Mail lives in memory unless
+  **Keep agent inbox across restarts** is on (see [Settings Reference](Settings-Reference)),
+  and goes when its session is deleted.
 - **Exit codes** are the same for every verb: `0` done, `1` error, `2` timeout, `3` the
   worker exited, `4` refused. `--json` prints the response's `data`.
 

docs/wiki/Settings-Reference.md

@@ -89,6 +89,13 @@ way; it also enables the `Ctrl+Shift+G` grid toggle on this device. See
 This section also holds background-agent tracking, including whether to track agents for
 every session or only the active tab.
 
+**Keep agent inbox across restarts** (under **Cross-session features**, synced, off by
+default) saves the pending `codeman agent post` messages to `agent-inbox.json` in the data
+dir, readable by you only, so they survive a server restart. Off, the agent inbox lives in
+memory and a restart empties it; switching it off deletes the file and keeps what is in
+memory. Messages expire 12 hours after they were posted either way. See
+[Driving Codeman From An Agent](Driving-Codeman-From-An-Agent#the-codeman-agent-commands).
+
 ### Appearance
 
 | Setting                | Notes                                                                                     |