fix(sessions): act on the dual review of the reboot-restore route

Fifteen findings from two independent reviews of #442, three of them
blocking. Every one is addressed here.

The three blockers all sat in the restore route. A rebuild that threw after
addSession left a registered session with no pane behind it, visible on the
board, holding a layout slot and written to state.json, with its plan entry
already spent; the catch now cleans the session up and puts the entry back.
The loop checked neither the global nor the per-user session cap, so one
click could take a board past a documented limit; capacity is now re-checked
per iteration, because the loop is itself creating the sessions it counts.
Worst of the three, a rebuilt session carried none of the state its
constructor has no parameter for and then persisted itself over the record
that held it, zeroing token and cost totals and dropping the pin. The pin
matters most: pruning keeps a record only while it is pinned, so discarding
it handed the record to the next stale sweep. A new
reapplyPersistedSessionState() on the session port restores the pin, the
token totals, auto-compact, auto-clear, auto-resume, nice priority, the
flicker filter and the custom-model selection, and it runs before both
startInteractive and the first persist.

The rest, in the order they bite a user. Every rebuild failure was reported
as workspace-missing, so the banner told users their repo was gone when the
agent had simply failed to start; there are now distinct reasons, and the
toast names each one. The client read restored and skipped off the outer
response object rather than through the uniform envelope, so every count
came back zero and neither toast ever fired. A board left open across the
reboot never learned an offer existed, because the banner was seeded only on
the page-load path; it now re-reads on every SSE init. The workspace check
was existence-only, skipping the multi-user confinement that the create
route applies, so a withdrawn grant would not be noticed. The banner had no
phone breakpoint while its text was nowrap and its buttons could not shrink.

Smaller: a missing workspace is now re-offered rather than dropped, while an
already-open conversation is dropped rather than re-offered forever; a throw
anywhere in the route returns the unspent entries instead of discarding the
plan; the single flight is keyed by owner, since take() already stops two
callers receiving one entry; the env clamp's header no longer claims a
protection it cannot provide on this path today, and names the check that
does bite; the three endpoints are documented in docs/api-reference.md; and
the module header now says that os.uptime() reads the host's clock, so the
feature is effectively off inside a container.

The review also explained why the tests missed all of this: they proved the
construction claim through their own copy of the construction rather than
through the route, and the route tests used workspaces that did not exist,
so no Session was ever built. test/routes/reboot-restore-rebuild-failure.ts
mocks the Session module to drive the route's real path, and covers the
cleanup, the reason reported, the re-application ordering, the broadcast and
the caps. The mock route context gains the port method and the mux call the
route needs.

Refs #411

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

test/mocks/mock-route-context.ts

@@ -61,6 +61,7 @@ export function createMockRouteContext(options?: {
     setupSessionListeners: vi.fn(async () => {}),
     persistSessionState: vi.fn(),
     persistSessionStateNow: vi.fn(),
+    reapplyPersistedSessionState: vi.fn(async () => {}),
     getSessionStateWithRespawn: vi.fn((s: MockSession) => s.toState()),
 
     // -- EventPort --
@@ -149,6 +150,7 @@ export function createMockRouteContext(options?: {
       clearRespawnConfig: vi.fn(),
       updateRespawnConfig: vi.fn(),
       setHistoryLimit: vi.fn(async () => {}),
+      startStatsCollection: vi.fn(),
     },
     runSummaryTrackers: new Map(),
     activePlanOrchestrators: new Map(),

test/routes/reboot-restore-rebuild-failure.test.ts

@@ -0,0 +1,210 @@
+/**
+ * Reboot-restore route: what happens when a rebuild gets part-way and then fails.
+ *
+ * The other route test file deliberately uses workspaces that do not exist, so it
+ * never reaches `new Session()`. This one mocks the `Session` module so the route
+ * runs its whole construction path — `addSession`, `setupSessionListeners`,
+ * `reapplyPersistedSessionState`, `startInteractive` — and then throws where a
+ * real one would when the CLI binary is missing from a freshly booted machine's
+ * PATH. Without the mock there is no way to exercise that path, which is how the
+ * original version of this route shipped a session leak the tests could not see.
+ *
+ * It also covers the session caps, because those too are only reachable once the
+ * route is actually willing to build something.
+ */
+import { describe, it, expect, afterEach, vi, beforeEach } from 'vitest';
+import Fastify, { type FastifyInstance } from 'fastify';
+import fastifyCookie from '@fastify/cookie';
+
+/** Set per test: whether the mocked `startInteractive()` rejects. */
+let startShouldThrow = false;
+
+vi.mock('../../src/session.js', () => ({
+  Session: class {
+    id: string;
+    mode: string;
+    name?: string;
+    workingDir: string;
+    owner?: string;
+    claudeSessionId: string | null = null;
+    constructor(config: { id: string; mode?: string; name?: string; workingDir: string; owner?: string }) {
+      this.id = config.id;
+      this.mode = config.mode ?? 'claude';
+      this.name = config.name;
+      this.workingDir = config.workingDir;
+      this.owner = config.owner;
+    }
+    async startInteractive() {
+      if (startShouldThrow) throw new Error('spawn claude ENOENT');
+    }
+    /** The mock route context projects a session through this on broadcast. */
+    toState() {
+      return { id: this.id, mode: this.mode, name: this.name, workingDir: this.workingDir, owner: this.owner };
+    }
+  },
+}));
+
+const { registerRebootRestoreRoutes } = await import('../../src/web/routes/reboot-restore-routes.js');
+const { rebootRestoreRegistry } = await import('../../src/web/reboot-restore-registry.js');
+const { installRouteErrorHandler } = await import('../../src/web/route-error-handler.js');
+const { httpStatusForErrorCode } = await import('../../src/types.js');
+const { createMockRouteContext } = await import('../mocks/index.js');
+type ApiErrorCode = import('../../src/types.js').ApiErrorCode;
+type RebootRestoreEntry = import('../../src/reboot-restore.js').RebootRestoreEntry;
+type SessionState = import('../../src/types.js').SessionState;
+
+/** A real directory, so the route's workspace checks pass and it reaches the build. */
+const WORKSPACE = process.cwd();
+
+function offerEntry(sessionId: string, owner?: string): RebootRestoreEntry {
+  return {
+    sessionId,
+    name: `session ${sessionId}`,
+    workingDir: WORKSPACE,
+    owner,
+    mode: 'claude',
+    resumeConversationId: `conv-${sessionId}`,
+    state: {
+      id: sessionId,
+      pid: null,
+      status: 'idle',
+      workingDir: WORKSPACE,
+      currentTaskId: null,
+      createdAt: 1_760_000_000_000,
+      mode: 'claude',
+      owner,
+    } as SessionState,
+  };
+}
+
+async function createHarness(ctx: ReturnType<typeof createMockRouteContext>): Promise<FastifyInstance> {
+  const app = Fastify({ logger: false });
+  await app.register(fastifyCookie);
+  registerRebootRestoreRoutes(app, ctx as never);
+  app.addHook('preSerialization', (req, reply, payload: unknown, done) => {
+    if (!req.url.startsWith('/api')) return done(null, payload);
+    if (payload === null || typeof payload !== 'object') return done(null, payload);
+    const p = payload as { success?: unknown; errorCode?: unknown };
+    if (p.success === false) {
+      if (reply.statusCode === 200 && typeof p.errorCode === 'string') {
+        reply.code(httpStatusForErrorCode(p.errorCode as ApiErrorCode));
+      }
+      return done(null, payload);
+    }
+    if (p.success === true) return done(null, payload);
+    return done(null, { success: true, data: payload });
+  });
+  installRouteErrorHandler(app);
+  await app.ready();
+  return app;
+}
+
+beforeEach(() => {
+  startShouldThrow = false;
+});
+
+afterEach(() => {
+  rebootRestoreRegistry.reset();
+  vi.clearAllMocks();
+});
+
+describe('a rebuild that fails after the session is registered', () => {
+  it('reports why it failed rather than blaming the workspace', async () => {
+    startShouldThrow = true;
+    rebootRestoreRegistry.set([offerEntry('a')]);
+    const ctx = createMockRouteContext({ workspaceHooksEnabled: false });
+    const app = await createHarness(ctx);
+
+    const res = (await app.inject({ method: 'POST', url: '/api/reboot-restore/restore', payload: {} })).json().data;
+    expect(res.restored).toEqual([]);
+    // Not `workspace-missing`: the directory is there, the agent would not start.
+    expect(res.skipped).toEqual([{ sessionId: 'a', reason: 'rebuild-failed' }]);
+    await app.close();
+  });
+
+  it('does not leave a registered session with no pane behind it', async () => {
+    startShouldThrow = true;
+    rebootRestoreRegistry.set([offerEntry('a')]);
+    const ctx = createMockRouteContext({ workspaceHooksEnabled: false });
+    const app = await createHarness(ctx);
+
+    await app.inject({ method: 'POST', url: '/api/reboot-restore/restore', payload: {} });
+    // The session reached ctx.sessions via addSession; the route has to take it
+    // back out, or the board shows a tab whose pane never existed.
+    expect(ctx.cleanupSession).toHaveBeenCalledWith('a', true, expect.any(String));
+    await app.close();
+  });
+
+  it('keeps the entry on offer, so the user can fix the PATH and click again', async () => {
+    startShouldThrow = true;
+    rebootRestoreRegistry.set([offerEntry('a')]);
+    const ctx = createMockRouteContext({ workspaceHooksEnabled: false });
+    const app = await createHarness(ctx);
+
+    await app.inject({ method: 'POST', url: '/api/reboot-restore/restore', payload: {} });
+    const left = (await app.inject({ method: 'GET', url: '/api/reboot-restore' })).json().data;
+    expect(left.sessions.map((s: { id: string }) => s.id)).toEqual(['a']);
+    await app.close();
+  });
+});
+
+describe('a rebuild that succeeds', () => {
+  it('re-applies the persisted state before the record is written again', async () => {
+    rebootRestoreRegistry.set([offerEntry('a')]);
+    const ctx = createMockRouteContext({ workspaceHooksEnabled: false });
+    const app = await createHarness(ctx);
+
+    const res = (await app.inject({ method: 'POST', url: '/api/reboot-restore/restore', payload: {} })).json().data;
+    expect(res.restored.map((s: { id: string }) => s.id)).toEqual(['a']);
+    // A session built from a record carries none of the pin, token totals or
+    // custom-model selection, so persisting it first would replace the fuller
+    // record with the reduced one.
+    expect(ctx.reapplyPersistedSessionState).toHaveBeenCalled();
+    const reapplyOrder = (ctx.reapplyPersistedSessionState as ReturnType<typeof vi.fn>).mock.invocationCallOrder[0];
+    const persistOrder = (ctx.persistSessionState as ReturnType<typeof vi.fn>).mock.invocationCallOrder[0];
+    expect(reapplyOrder).toBeLessThan(persistOrder);
+    await app.close();
+  });
+
+  it('tells every other board about the rebuilt session', async () => {
+    rebootRestoreRegistry.set([offerEntry('a')]);
+    const ctx = createMockRouteContext({ workspaceHooksEnabled: false });
+    const app = await createHarness(ctx);
+
+    await app.inject({ method: 'POST', url: '/api/reboot-restore/restore', payload: {} });
+    expect(ctx.broadcast).toHaveBeenCalledWith('session:created', expect.anything());
+    await app.close();
+  });
+
+  it('spends the entry, so it is no longer on offer', async () => {
+    rebootRestoreRegistry.set([offerEntry('a')]);
+    const ctx = createMockRouteContext({ workspaceHooksEnabled: false });
+    const app = await createHarness(ctx);
+
+    await app.inject({ method: 'POST', url: '/api/reboot-restore/restore', payload: {} });
+    const left = (await app.inject({ method: 'GET', url: '/api/reboot-restore' })).json().data;
+    expect(left.sessions).toEqual([]);
+    await app.close();
+  });
+});
+
+describe('the session caps', () => {
+  it('stops restoring at the global cap and leaves the rest on offer', async () => {
+    rebootRestoreRegistry.set([offerEntry('a'), offerEntry('b')]);
+    const ctx = createMockRouteContext({ workspaceHooksEnabled: false });
+    // Fill the board to the documented maximum of 50 concurrent sessions.
+    for (let i = 0; i < 50; i += 1) {
+      ctx.sessions.set(`filler-${i}`, { id: `filler-${i}`, owner: undefined } as never);
+    }
+    const app = await createHarness(ctx);
+
+    const res = (await app.inject({ method: 'POST', url: '/api/reboot-restore/restore', payload: {} })).json().data;
+    expect(res.restored).toEqual([]);
+    expect(res.skipped.map((s: { reason: string }) => s.reason)).toEqual(['capacity-reached', 'capacity-reached']);
+
+    // Refused rather than lost: closing a session and clicking again works.
+    const left = (await app.inject({ method: 'GET', url: '/api/reboot-restore' })).json().data;
+    expect(left.sessions.map((s: { id: string }) => s.id).sort()).toEqual(['a', 'b']);
+    await app.close();
+  });
+});

test/routes/reboot-restore-routes.test.ts

@@ -23,6 +23,13 @@ import type { RebootRestoreEntry } from '../../src/reboot-restore.js';
 import type { SessionState } from '../../src/types.js';
 
 async function createHarness(authUser?: { username: string; role: 'admin' | 'user' }): Promise<FastifyInstance> {
+  return createHarnessWithCtx(createMockRouteContext(), authUser);
+}
+
+async function createHarnessWithCtx(
+  ctx: ReturnType<typeof createMockRouteContext>,
+  authUser?: { username: string; role: 'admin' | 'user' }
+): Promise<FastifyInstance> {
   const app = Fastify({ logger: false });
   await app.register(fastifyCookie);
   if (authUser) {
@@ -30,7 +37,7 @@ async function createHarness(authUser?: { username: string; role: 'admin' | 'use
       (req as unknown as { authUser: typeof authUser }).authUser = authUser;
     });
   }
-  registerRebootRestoreRoutes(app, createMockRouteContext() as never);
+  registerRebootRestoreRoutes(app, ctx as never);
 
   app.addHook('preSerialization', (req, reply, payload: unknown, done) => {
     if (!req.url.startsWith('/api')) return done(null, payload);
@@ -106,18 +113,36 @@ describe('GET /api/reboot-restore', () => {
 });
 
 describe('POST /api/reboot-restore/restore', () => {
-  it('spends the offer, so a second click finds nothing left to spend', async () => {
+  it('reports a workspace that is gone, and keeps offering it in case it comes back', async () => {
     rebootRestoreRegistry.set([offerEntry('a')]);
     const app = await createHarness();
 
     const first = (await app.inject({ method: 'POST', url: '/api/reboot-restore/restore', payload: {} })).json().data;
-    // The workspace is gone, so nothing was rebuilt — but the entry was taken.
     expect(first.restored).toEqual([]);
     expect(first.skipped).toEqual([{ sessionId: 'a', reason: 'workspace-missing' }]);
 
-    const second = (await app.inject({ method: 'POST', url: '/api/reboot-restore/restore', payload: {} })).json().data;
-    expect(second.restored).toEqual([]);
-    expect(second.skipped).toEqual([]);
+    // Nothing was built, so the entry goes back: a repo can be restored from a
+    // backup between two clicks, and losing the offer would be unrecoverable.
+    const left = (await app.inject({ method: 'GET', url: '/api/reboot-restore' })).json().data;
+    expect(left.sessions.map((s: { id: string }) => s.id)).toEqual(['a']);
+    await app.close();
+  });
+
+  it('never re-offers a conversation that is already open', async () => {
+    const entry = offerEntry('a');
+    rebootRestoreRegistry.set([entry]);
+    const app = await createHarness();
+    const ctx = createMockRouteContext({ sessionId: entry.sessionId });
+    // A session with that id is live, which is what the Resume list would produce.
+    const liveApp = await createHarnessWithCtx(ctx);
+
+    const res = (await liveApp.inject({ method: 'POST', url: '/api/reboot-restore/restore', payload: {} })).json().data;
+    expect(res.skipped).toEqual([{ sessionId: 'a', reason: 'already-live' }]);
+
+    // Unlike a missing workspace, this one is dropped: it cannot stop being true.
+    const left = (await liveApp.inject({ method: 'GET', url: '/api/reboot-restore' })).json().data;
+    expect(left.sessions).toEqual([]);
+    await liveApp.close();
     await app.close();
   });
 
@@ -132,8 +157,9 @@ describe('POST /api/reboot-restore/restore', () => {
     });
     expect(res.json().data.skipped).toEqual([{ sessionId: 'b', reason: 'workspace-missing' }]);
 
+    // 'a' was never taken, and 'b' came back because no pane was built for it.
     const left = (await app.inject({ method: 'GET', url: '/api/reboot-restore' })).json().data;
-    expect(left.sessions.map((s: { id: string }) => s.id)).toEqual(['a']);
+    expect(left.sessions.map((s: { id: string }) => s.id).sort()).toEqual(['a', 'b']);
     await app.close();
   });
 
@@ -150,12 +176,13 @@ describe('POST /api/reboot-restore/restore', () => {
 
   it('turns a second concurrent restore away rather than interleaving it', async () => {
     rebootRestoreRegistry.set([offerEntry('a')]);
-    // Claimed by a restore already in flight.
-    expect(rebootRestoreRegistry.beginSpending()).toBe(true);
+    // Claimed by a restore already in flight for this same owner (undefined in
+    // single-user mode, which is what the harness runs as).
+    expect(rebootRestoreRegistry.beginSpending(undefined)).toBe(true);
     const app = await createHarness();
     const res = await app.inject({ method: 'POST', url: '/api/reboot-restore/restore', payload: {} });
     expect(res.statusCode).toBe(409);
-    rebootRestoreRegistry.endSpending();
+    rebootRestoreRegistry.endSpending(undefined);
     await app.close();
   });
 });