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>

src/web/public/app.js

@@ -957,7 +957,9 @@ class CodemanApp {
     this.registerServiceWorker();
     // Fetch tunnel status for header indicator (desktop only)
     this.loadTunnelStatus();
-    // Ask whether a host reboot left sessions worth rebuilding (banner, never automatic)
+    // Ask whether a host reboot left sessions worth rebuilding (banner, never
+    // automatic). handleInit() re-reads it on every SSE init; this covers the
+    // path where that event never arrives.
     this.initRebootRestoreBanner?.();
     // Share a single settings fetch between both consumers
     const settingsPromise = fetch('/api/settings').then(r => r.ok ? r.json() : null).then(env => env?.data ?? null).catch(() => null);
@@ -3761,6 +3763,12 @@ class CodemanApp {
     // a fresh load / reconnect (authoritative; wins over the localStorage restore).
     if (data.planUsage) this.updatePlanUsageChip(data.planUsage);
 
+    // A board left open across a host reboot reconnects HERE, to a server that came
+    // back with an empty session list. The reboot-restore offer is built at boot,
+    // before any client could be listening, so re-read it on every init rather than
+    // only on the page-load path.
+    this.refreshRebootRestoreBanner?.();
+
     // Update version displays (header and toolbar)
     if (data.version) {
       const versionEl = this.$('versionDisplay');

src/web/public/mobile.css

@@ -3240,6 +3240,41 @@ html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="cat
    already reserves that space), so it needs the same safe-area padding as the
    other banners. The overlay is fixed and handles its own insets.
    ============================================================================ */
+@media (max-width: 599px) {
+  /* Reboot-restore banner: the same treatment as the offline banner below. Its
+     text and note are nowrap and the two buttons cannot shrink, so without this
+     the actions are pushed off a phone-width viewport and become unreachable. */
+  .reboot-restore-banner {
+    padding: 0.4rem 0.5rem;
+    padding-left: calc(0.5rem + var(--safe-area-left));
+    padding-right: calc(0.5rem + var(--safe-area-right));
+    font-size: 0.7rem;
+    gap: 0.4rem;
+  }
+
+  /* The session names and the scrollback note are the first things to go. The
+     count plus the two buttons carry the message on their own, and the note
+     survives as the accept button's title. */
+  .reboot-restore-banner-detail,
+  .reboot-restore-banner-note {
+    display: none;
+  }
+
+  .reboot-restore-banner-text {
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+
+  .reboot-restore-banner-accept,
+  .reboot-restore-banner-dismiss {
+    padding: 0.25rem 0.5rem;
+  }
+
+  .reboot-restore-banner-accept {
+    margin-left: auto;
+  }
+}
+
 @media (max-width: 599px) {
   .offline-banner {
     padding: 0.4rem 0.5rem;

src/web/public/reboot-restore-ui.js

@@ -8,7 +8,9 @@
  * reboot guess is a heuristic and a wrong automatic restore would spawn CLI
  * processes nobody asked for.
  *
- * Seeded once from `GET /api/reboot-restore` on init. Restore posts to
+ * Seeded from `GET /api/reboot-restore` on init and again on every SSE reconnect,
+ * because the tab most likely to want this is one that was open across the reboot
+ * and reconnects to a server that came back up with an empty board. Restore posts to
  * `POST /api/reboot-restore/restore`, Dismiss posts to
  * `POST /api/reboot-restore/dismiss`, and either way the banner goes away. The
  * restored sessions arrive as ordinary `session:created` events, so no extra
@@ -25,6 +27,24 @@
  * @loadorder 11.7 of 17, after approvals-ui.js
  */
 
+/** Plain-language wording for one skip reason, for the toast after a restore. */
+function rebootSkipReason(reason) {
+  switch (reason) {
+    case 'workspace-missing':
+      return 'workspace is gone';
+    case 'workspace-forbidden':
+      return 'workspace is outside your space';
+    case 'already-live':
+      return 'already open';
+    case 'capacity-reached':
+      return 'session limit reached';
+    case 'rebuild-failed':
+      return 'the agent would not start';
+    default:
+      return reason;
+  }
+}
+
 Object.assign(CodemanApp.prototype, {
   /** Ask the server whether a reboot left anything on offer, and show the banner if so. */
   async initRebootRestoreBanner() {
@@ -59,6 +79,9 @@ Object.assign(CodemanApp.prototype, {
       detail.textContent = count > 4 ? `${names}, …` : names;
       detail.title = sessions.map((s) => `${s.name || s.id}\n${s.workingDir}`).join('\n\n');
     }
+    const accept = this.$('rebootRestoreBannerAccept');
+    // The note is hidden at phone width, so the warning travels on the button too.
+    if (accept) accept.title = 'Conversations return; terminal history does not.';
     banner.hidden = false;
   },
 
@@ -66,8 +89,9 @@ Object.assign(CodemanApp.prototype, {
   async restoreRebootSessions() {
     const button = this.$('rebootRestoreBannerAccept');
     if (button) button.disabled = true;
-    const res = await this._apiPost('/api/reboot-restore/restore', {});
-    const body = res && res.ok ? await res.json().catch(() => null) : null;
+    // _apiJson unwraps the { success, data } envelope every /api response carries;
+    // reading the outer object would report every count as zero.
+    const body = await this._apiJson('/api/reboot-restore/restore', { method: 'POST', body: {} });
     if (!body) {
       if (button) button.disabled = false;
       this.showToast?.('Could not restore the sessions', 'error');
@@ -82,10 +106,21 @@ Object.assign(CodemanApp.prototype, {
       this.showToast?.(`Restored ${restored} ${noun}. Terminal history did not survive the reboot.`, 'success');
     }
     if (skipped > 0) {
-      this.showToast?.(`${skipped} could not be restored (workspace gone, or already open)`, 'warning');
+      // Each reason means a different next step for the user, so they are not
+      // collapsed into one message: capacity clears by closing something, a
+      // failed start usually means the CLI is not on the server's PATH.
+      const reasons = new Set((body.skipped ?? []).map((s) => s.reason));
+      this.showToast?.(`${skipped} not restored: ${[...reasons].map(rebootSkipReason).join('; ')}`, 'warning');
     }
   },
 
+  /** Re-read the offer after a reconnect, for a tab that was open across the reboot. */
+  async refreshRebootRestoreBanner() {
+    const data = await this._apiJson('/api/reboot-restore');
+    this._rebootRestoreSessions = data?.sessions ?? [];
+    this.renderRebootRestoreBanner();
+  },
+
   /** Drop the offer. The Resume list still reaches every one of these conversations. */
   async dismissRebootRestore() {
     this._rebootRestoreSessions = [];