fix(web): address self-review findings on #103 (master-safe defaults + hardening)

Make the branch genuinely master-mergeable and fix several review findings:

- Defaults are now prod-safe: CODEMAN_INSTANCE defaults to '' (→ ~/.codeman,
  -L codeman) and the web port back to 3000, so an existing install upgrades
  cleanly. Port also honors a new CODEMAN_PORT env var. Run the beta isolated
  alongside prod with scripts/run-beta.sh (CODEMAN_INSTANCE=beta + PORT 5000).
- .gitignore: anchor the root `public` symlink rule to `/public` (a bare
  `public` also swallowed src/web/public, silently un-staging new web assets);
  ignore the gesture wasm/model binaries explicitly instead.
- span-displays: add a macOS-only guard (400 elsewhere instead of spawning a
  bash that fails invisibly); extract resolveSpanUrl() for unit testing.
- server.ts: memoize asset-version stat() calls (~1s TTL) so each index render
  doesn't re-stat every script/link tag.
- styles.css: hide the multi-monitor button in solo (detached) windows.
- app.js: require two consecutive unanswered roll-calls before redocking, so a
  timer-throttled background popup isn't wrongly un-marked.
- index.html: make the "skip to terminal" link base-href-safe (onclick scroll)
  so it doesn't navigate to the dashboard from a /session/:id window.
- Tests: test/config/instance.test.ts, test/routes/system-span-displays.test.ts.

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

src/cli.ts

@@ -483,7 +483,7 @@ program
 program
   .command('web')
   .description('Start the web interface')
-  .option('-p, --port <port>', 'Port to listen on', '5000')
+  .option('-p, --port <port>', 'Port to listen on (env: CODEMAN_PORT)', process.env.CODEMAN_PORT || '3000')
   .option('--https', 'Enable HTTPS with self-signed certificate (only needed for remote access, not localhost)')
   .option('--title-hostname <hostname>', 'Override the hostname shown in the browser title')
   .action(async (options) => {

src/config/instance.ts

@@ -9,9 +9,15 @@
  *
  * To let a beta build coexist with a production one, this module derives both
  * the data dir and the tmux socket from a single "instance" name:
- *   - default (this branch): `beta` → `~/.codeman-beta` + `tmux -L codeman-beta`
- *   - `CODEMAN_INSTANCE=`     (empty) → `~/.codeman`     + `tmux -L codeman`   (prod layout)
- *   - `CODEMAN_INSTANCE=foo`          → `~/.codeman-foo`  + `tmux -L codeman-foo`
+ *   - default (unset/empty) → `~/.codeman`      + `tmux -L codeman`        (prod layout)
+ *   - `CODEMAN_INSTANCE=beta` → `~/.codeman-beta` + `tmux -L codeman-beta`
+ *   - `CODEMAN_INSTANCE=foo`  → `~/.codeman-foo`  + `tmux -L codeman-foo`
+ *
+ * The DEFAULT is the production layout so this is safe to ship to master: an
+ * existing install keeps reading `~/.codeman`. To run a beta ALONGSIDE prod,
+ * launch it with `CODEMAN_INSTANCE=beta` (and a distinct port, see below) —
+ * `scripts/run-beta.sh` does both. The port is unrelated to the instance and is
+ * set separately via `--port` / `CODEMAN_PORT` (see `src/cli.ts`).
  *
  * Individual overrides still win: `CODEMAN_DATA_DIR` (absolute data dir) and
  * `CODEMAN_TMUX_SOCKET` (socket name, validated in tmux-manager).
@@ -22,12 +28,12 @@ import { join } from 'node:path';
 import { mkdirSync } from 'node:fs';
 
 /**
- * Instance name. Empty string = production layout (`~/.codeman`, `-L codeman`).
- * Defaults to `beta` on the beta/session-detach branch so it never collides
- * with a production Codeman. Set `CODEMAN_INSTANCE=` (empty) to opt back into
- * the production layout.
+ * Instance name. Empty string (the default) = production layout (`~/.codeman`,
+ * `-L codeman`), so this is safe on master and existing installs are untouched.
+ * Set `CODEMAN_INSTANCE=beta` (e.g. via `scripts/run-beta.sh`) to run an
+ * isolated beta alongside prod.
  */
-export const CODEMAN_INSTANCE = process.env.CODEMAN_INSTANCE ?? 'beta';
+export const CODEMAN_INSTANCE = process.env.CODEMAN_INSTANCE ?? '';
 
 const INSTANCE_SUFFIX = CODEMAN_INSTANCE ? `-${CODEMAN_INSTANCE}` : '';
 

src/web/public/app.js

@@ -309,6 +309,7 @@ class CodemanApp {
     this._redockGrace = new Map();       // id -> timer: deferred redock (debounces popup reloads)
     this._detachPingPending = null;      // Set of ids awaiting a liveness answer
     this._detachLivenessTimer = null;    // periodic reconcile of channel-only detached windows
+    this._detachOrphanStrikes = new Map(); // id -> consecutive unanswered roll-calls (redock at 2)
 
     this._initGeneration = 0;     // dedup concurrent handleInit calls
     this._initFallbackTimer = null; // fallback timer if SSE init doesn't arrive
@@ -879,6 +880,7 @@ class CodemanApp {
     const t = this._detachWatchTimers.get(id);
     if (t) { clearInterval(t); this._detachWatchTimers.delete(id); }
     this._cancelPendingRedock(id);
+    this._detachOrphanStrikes.delete(id);
     this.detachedWindows.delete(id);
     this._markDetached(id, false);
   }
@@ -965,6 +967,7 @@ class CodemanApp {
     if (msg.type === 'detached' && msg.id) {
       this._cancelPendingRedock(msg.id);    // a re-announce (e.g. popup reload) cancels a deferred redock
       this._detachPingPending?.delete(msg.id);  // and proves liveness for this tick
+      this._detachOrphanStrikes.delete(msg.id); // any answer clears accumulated misses
       this._markDetached(msg.id, true);
     } else if (msg.type === 'redocked' && msg.id) {
       this._scheduleRedock(msg.id);         // defer: a popup reload fires redocked→detached; grace avoids a badge blip
@@ -993,10 +996,18 @@ class CodemanApp {
     if (!orphans.length) return;
     this._detachPingPending = new Set(orphans);
     this._postWindowMessage({ type: 'roll-call' });
-    // Live popups answer 'detached' (clearing themselves above); survivors are gone.
+    // Live popups answer 'detached' (clearing themselves above); survivors stay in
+    // the pending set. Redock only after TWO consecutive unanswered roll-calls — a
+    // backgrounded popup is timer-throttled and may miss a single 1.2s window, and
+    // we don't want to wrongly un-mark a still-open tab. A later answer resets the
+    // strike count (see _onWindowMessage).
     setTimeout(() => {
       if (!this._detachPingPending) return;
-      for (const id of this._detachPingPending) this._redock(id);
+      for (const id of this._detachPingPending) {
+        const strikes = (this._detachOrphanStrikes.get(id) || 0) + 1;
+        if (strikes >= 2) { this._detachOrphanStrikes.delete(id); this._redock(id); }
+        else this._detachOrphanStrikes.set(id, strikes);
+      }
       this._detachPingPending = null;
     }, 1200);
   }

src/web/public/index.html

@@ -59,7 +59,9 @@
     <div class="skeleton-toolbar"></div>
   </div>
   <!-- Skip link for keyboard users -->
-  <a href="#terminalContainer" class="skip-link">Skip to terminal</a>
+  <!-- onclick scrolls/focuses directly: with <base href="/"> a bare href="#..." would
+       navigate to /#... (the dashboard) from a /session/:id solo window. -->
+  <a href="#terminalContainer" class="skip-link" onclick="event.preventDefault(); var t=document.getElementById('terminalContainer'); if(t){t.scrollIntoView(); var f=t.querySelector('textarea,[tabindex]'); (f||t).focus&&(f||t).focus();}">Skip to terminal</a>
   <div class="app">
     <!-- Compact Header with Session Tabs -->
     <header class="header">

src/web/public/styles.css

@@ -963,6 +963,7 @@ body.solo-mode .session-tabs,
 body.solo-mode .header-system-stats,
 body.solo-mode .header-tokens,
 body.solo-mode .btn-notifications,
+body.solo-mode .btn-multimonitor,
 body.solo-mode .btn-lifecycle-log {
   display: none !important;
 }

src/web/routes/system-routes.ts

@@ -94,6 +94,18 @@ function getSystemStats(): {
   }
 }
 
+/**
+ * Build the URL the spanning browser window should open, pinned to localhost.
+ * Takes only a digits-only port from the (untrusted) Host header so nothing
+ * attacker-controllable reaches the launched browser; falls back to the default
+ * port when the header is absent/odd. Exported for unit testing.
+ */
+export function resolveSpanUrl(hostHeader: string | undefined, fallbackPort = '3000'): string {
+  const hostPort = String(hostHeader ?? '').split(':')[1] ?? '';
+  const port = /^\d+$/.test(hostPort) ? hostPort : fallbackPort;
+  return `http://localhost:${port}`;
+}
+
 export function registerSystemRoutes(
   app: FastifyInstance,
   ctx: SessionPort & EventPort & ConfigPort & InfraPort & AuthPort
@@ -250,17 +262,21 @@ export function registerSystemRoutes(
   // panels can be dragged across the physical monitor seam. macOS only; needs
   // the one-time "Displays have separate Spaces" OFF prerequisite (see script).
   app.post('/api/system/span-displays', async (req, reply) => {
+    // macOS only: the launcher uses osascript + Finder desktop bounds and Chrome
+    // --app geometry flags. Fail clearly elsewhere instead of spawning a bash
+    // that errors out invisibly (the toast would otherwise lie "Opening…").
+    if (process.platform !== 'darwin') {
+      return reply
+        .code(400)
+        .send(createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Multi-monitor spanning is only supported on macOS.'));
+    }
     // Resolve the bundled launcher relative to this module (works from src/ and dist/).
     const scriptPath = join(dirname(fileURLToPath(import.meta.url)), '../../../scripts/span-codeman.sh');
     if (!existsSync(scriptPath)) {
       return reply.code(500).send(createErrorResponse(ApiErrorCode.INTERNAL_ERROR, 'span-codeman.sh not found'));
     }
-    // Point the spanning window at THIS server. Pin the host to localhost (same
-    // machine) and take only a digits-only port from the Host header so nothing
-    // attacker-controllable reaches the launched browser.
-    const hostPort = String(req.headers.host ?? '').split(':')[1] ?? '';
-    const port = /^\d+$/.test(hostPort) ? hostPort : '5000';
-    const url = `http://localhost:${port}`;
+    // Point the spanning window at THIS server (localhost + sanitized port).
+    const url = resolveSpanUrl(req.headers.host);
     try {
       const child = spawn('bash', [scriptPath, url], { detached: true, stdio: 'ignore' });
       child.on('error', (err) => app.log.error({ err }, 'span-displays launch failed'));

src/web/server.ts

@@ -1021,37 +1021,47 @@ export class WebServer extends EventEmitter {
     return html;
   }
 
-  /** Cache-busting query for the gesture bundle: its mtime, re-read per render.
-   *  The bundle is served from /gesture/ with a 1-year cache, so without a
-   *  version that changes on redeploy the browser would keep running a stale
-   *  bundle forever. Re-stat'ing each render means a freshly copied-in bundle is
-   *  picked up with no server restart. Empty string if the file is missing. */
-  private gestureBundleVersion(): string {
+  /** mtime memo for asset cache-busting (keyed by absolute path). A full index
+   *  render does one stat per script/link tag (~25-30); without this each `/`,
+   *  `/index.html` and `/session/:id` hit would re-stat them all. A 1s TTL keeps
+   *  a burst of renders cheap while still picking up an edited/redeployed file
+   *  within a second (no server restart needed). */
+  private _assetVersionMemo = new Map<string, { v: number; ts: number }>();
+  private assetVersion(absPath: string): number | null {
+    const now = Date.now();
+    const hit = this._assetVersionMemo.get(absPath);
+    if (hit && now - hit.ts < 1000) return hit.v;
     try {
-      const p = join(__dirname, 'public', 'gesture', 'gesture-codeman.js');
-      return `?v=${Math.floor(statSync(p).mtimeMs)}`;
+      const v = Math.floor(statSync(absPath).mtimeMs);
+      this._assetVersionMemo.set(absPath, { v, ts: now });
+      return v;
     } catch {
-      return '';
+      return null;
     }
   }
 
+  /** Cache-busting query for the gesture bundle: its mtime (memoized, see
+   *  assetVersion). The bundle is served from /gesture/ with a 1-year cache, so
+   *  without a version that changes on redeploy the browser would keep running a
+   *  stale bundle forever. Empty string if the file is missing. */
+  private gestureBundleVersion(): string {
+    const v = this.assetVersion(join(__dirname, 'public', 'gesture', 'gesture-codeman.js'));
+    return v === null ? '' : `?v=${v}`;
+  }
+
   /** Append ?v=<mtime> to every same-origin .js/.css reference in the page so a
    *  normal reload always serves the latest. Codeman's static assets are sent
    *  with `Cache-Control: max-age=1y, immutable` and the script/link tags carry
    *  no version, so without this an edited module (panels-ui.js, styles.css, …)
-   *  stays cached until a manual hard refresh. mtime is re-stat'd per render, so
-   *  a changed file is picked up with no server restart. External URLs (have a
+   *  stays cached until a manual hard refresh. mtime is memoized (1s TTL) so a
+   *  changed file is picked up with no server restart. External URLs (have a
    *  `:` scheme), already-versioned refs (have a `?`), and refs with no matching
    *  file on disk are left untouched. */
   private cacheBustAssets(html: string): string {
     const publicDir = join(__dirname, 'public');
     return html.replace(/(\s(?:src|href)=")([^"?:]+\.(?:js|css))(")/g, (full, pre, ref, post) => {
-      try {
-        const v = Math.floor(statSync(join(publicDir, ref)).mtimeMs);
-        return `${pre}${ref}?v=${v}${post}`;
-      } catch {
-        return full;
-      }
+      const v = this.assetVersion(join(publicDir, ref));
+      return v === null ? full : `${pre}${ref}?v=${v}${post}`;
     });
   }