fix: address the release-prep review of #690

cleanup-state keeps the agent inbox of a removed record whose tmux session the multiplexer still lists (a detached pane the next boot re-adopts under the same id); test and architecture-invariants note added.

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

test/routes/system-routes.test.ts

@@ -367,6 +367,37 @@ describe('system-routes', () => {
         agentInbox.resetForTests();
       }
     });
+
+    it('keeps the agent inbox of a removed record whose tmux session the multiplexer still lists', async () => {
+      // Detach keeps the tmux session and its mux entry; the next boot re-adopts it
+      // under the same id even without a state.json record, so its mail must survive.
+      agentInbox.resetForTests();
+      agentInbox.post('stale-detached', null, 'mail for a session nothing can bring back');
+      agentInbox.post('pane-still-alive', null, 'mail for a detached pane that boot re-adopts');
+      harness.ctx.tabLayouts.runStaleSessionCleanup = vi.fn(
+        async (_activeIds: Set<string>, action: (ids: ReadonlySet<string>) => unknown) =>
+          action(new Set(['stale-detached', 'pane-still-alive']))
+      );
+      vi.mocked(harness.ctx.store.cleanupSessionsByIds).mockReturnValueOnce({
+        count: 2,
+        cleaned: [
+          { id: 'stale-detached', name: 'w9-gone' },
+          { id: 'pane-still-alive', name: 'w8-detached' },
+        ],
+      });
+      // The harness is rebuilt per test, so this mock does not leak into the next one.
+      vi.mocked(harness.ctx.mux.getSession).mockImplementation(((id: string) =>
+        id === 'pane-still-alive' ? { sessionId: id } : null) as unknown as typeof harness.ctx.mux.getSession);
+      try {
+        const res = await harness.app.inject({ method: 'POST', url: '/api/cleanup-state' });
+        expect(res.statusCode).toBe(200);
+        expect(JSON.parse(res.body).cleanedSessions).toBe(2);
+        expect(agentInbox.pendingCount('stale-detached')).toBe(0);
+        expect(agentInbox.pendingCount('pane-still-alive')).toBe(1);
+      } finally {
+        agentInbox.resetForTests();
+      }
+    });
   });
 
   // ========== GET /api/subagents ==========