Merge pull request #103 from Ark0N/beta/session-detach

feat(web): session detach/undock + beta instance isolation (port 5000)
2026-09-30 12:39:42 +02:00 · 2026-06-08 16:36:46 +02:00
parent 44439c951b cf6fabc070
commit cc45191c62
26 changed files with 5751 additions and 47 deletions
@@ -53,7 +53,17 @@ scripts/remotion/out/
 # Artifacts that should not be tracked
 test-results/
 tmp/
-public
+# Root `public` (a symlink to scripts/remotion/public — local artifact). ANCHORED
+# with a leading slash so it does NOT also match src/web/public (a bare `public`
+# would swallow the whole web UI source dir and silently un-stage any new asset
+# added there). No trailing slash so it still matches the symlink, not just dirs.
+/public
+
+# Opt-in gesture overlay runtime assets: large MediaPipe wasm + model (~27 MB)
+# fetched at build/install by scripts/fetch-gesture-assets.mjs, kept out of git.
+# (The gesture bundle itself, gesture-codeman.js, IS tracked.)
+src/web/public/gesture/wasm/
+src/web/public/gesture/*.task

 # Claude Code plan tracking
 plan.json
@@ -30,7 +30,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 2. **Frontend changes**: Use Playwright to load the page and assert the UI renders correctly. Use `waitUntil: 'domcontentloaded'` (not `networkidle` — SSE keeps the connection open). Wait 3-4s for polling/async data to populate, then check element visibility, text content, and CSS values
 3. **Only after verification passes**, proceed with COM

-The production server caches static files for 1 year (`maxAge: '1y'` in `server.ts`). After deploying frontend changes, users may need a hard refresh (Ctrl+Shift+R) to see updates.
+The production server caches static files for 1 year, `immutable` (`maxAge: '1y'` in `server.ts`). To avoid stale frontend after a deploy, `renderIndexHtml` runs `cacheBustAssets(html)` — it appends `?v=<mtime>` to **every same-origin `.js`/`.css`** reference (mtime memoized ~1s so a burst of renders is cheap; external/already-versioned/missing refs untouched). Because `index.html` is served `no-cache`, a **normal reload now picks up edited modules/styles — no hard refresh needed** (the gesture bundle is injected separately with its own `?v=`). If you add an asset referenced by an *absolute* URL or from JS rather than a `<script>/<link>` tag, it won't be auto-busted.

 ## COM Shorthand (Deployment)

@@ -72,7 +72,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph

 ## Additional Commands

-`npm run dev` = dev server. Default port: `3000`. Commands not in Quick Reference:
+`npm run dev` = dev server. Default port: `3000` (override with `--port` or the `CODEMAN_PORT` env var). To run this beta isolated alongside a prod Codeman, use `scripts/run-beta.sh` (sets `CODEMAN_INSTANCE=beta` + `CODEMAN_PORT=5000`). Commands not in Quick Reference:

 | Task | Command |
 |------|---------|
@@ -99,6 +99,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 - **Dual-CLI prefix discipline** — Codeman supports both Claude Code and OpenCode (`claude-cli-resolver.ts` / `opencode-cli-resolver.ts`); env-var prefix is CLI-specific (`CLAUDE_CODE_*` vs `OPENCODE_*`) and the allowlist in `schemas.ts` enforces this. When adding settings, decide which CLI(s) it applies to and gate the env export accordingly — don't blindly forward both prefixes. See `docs/opencode-integration.md` for the OpenCode resolver design
 - **Zod `.optional()` rejects `null`** — accepts `undefined` only. When the frontend builds a request body with `JSON.stringify`, an explicit `null` field is preserved on the wire and fails validation with `INVALID_INPUT`. Convert `null` → `undefined` before stringifying (e.g. `field: value ?? undefined`), or declare the schema `.nullish()`. Real bugs caused: 0.6.4 (`durationMinutes` for ∞ respawn), and the same shape pattern hit `opusContext1mEnabled` in 0.6.3
 - **`xterm-zerolag-input` is duplicated** — the local-echo overlay lives in BOTH `packages/xterm-zerolag-input/src/` (published to npm as a standalone library for external consumers — see README "Published Packages") AND inline inside `src/web/public/app.js` (runtime copy the web UI actually loads, since the page ships as plain JS without a bundler). Any change to overlay behavior MUST be applied to both, or dev and prod diverge — and a public API break in the package warrants a separate version bump for `xterm-zerolag-input` in the changeset. Always test on mobile after touching it. See `docs/local-echo-overlay-plan.md`.
+- **Instance isolation / multi-instance attach danger** — data dir (`~/.codeman`) and tmux socket (`tmux -L codeman`) are PROCESS-WIDE and shared by every Codeman on the machine, derived from `CODEMAN_INSTANCE` via `src/config/instance.ts` (`getDataDir()`/`dataPath()`/`DEFAULT_TMUX_SOCKET`). ⚠️ A 2nd instance on the SAME socket **discovers and attaches PTYs to the first instance's live sessions** (`tmux -L codeman attach-session …`), resizing/mutating them — `$HOME` isolation is NOT enough (tmux is system-global). To run two instances, give each a distinct `CODEMAN_INSTANCE` (scopes BOTH dir+socket: `~/.codeman-<name>` + `-L codeman-<name>`), or set `CODEMAN_TMUX_SOCKET` + `CODEMAN_DATA_DIR` individually. **`CODEMAN_INSTANCE` defaults to empty = the production layout (`~/.codeman`, `-L codeman`, port 3000)**, so this branch is safe to ship to master without disturbing existing installs. To run THIS beta alongside prod, launch with `scripts/run-beta.sh` (`CODEMAN_INSTANCE=beta` + `CODEMAN_PORT=5000`) — it never collides with prod's data dir/socket/port. Any new `~/.codeman/...` path MUST go through `dataPath()`, never `join(homedir(), '.codeman', …)`.

 **Import conventions**: Utils from `./utils`, types from `./types` (barrel), config from specific `./config/*` files.

@@ -159,6 +160,8 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L

 **Z-index layers**: subagent windows (1000), plan agents (1100), log viewers (2000), image popups (3000), local echo overlay (7).

+**Multi-monitor button** (header, top-right; replaces the notification bell, which is hidden by default but still reachable via Settings → Notifications). `app.launchMultiMonitor()` (in `panels-ui.js`) POSTs `/api/system/span-displays`, which spawns `scripts/span-codeman.sh` — a fresh, maximized browser `--app` window sized to the union of all displays (macOS; needs "Displays have separate Spaces" OFF). Supports the gesture layer's in-page floating session panels dragging across the physical monitor seam.
+
 **Respawn presets**: `solo-work` (3s/60min), `subagent-workflow` (45s/240min), `team-lead` (90s/480min), `ralph-todo` (8s/480min), `overnight-autonomous` (10s/480min).

 **Keyboard shortcuts**: Escape (close), Ctrl+? (help), Ctrl+W (kill), Ctrl+Tab (next), Alt+1-9 (switch tab), Ctrl+Shift+{/} (move tab left/right), Shift+Enter (newline), Ctrl+L (clear), Ctrl+Shift+R (restore size), Ctrl+Shift+V (voice input), Ctrl/Cmd +/- (font).
@@ -182,7 +185,7 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L

 ### API Routes

-~130 handlers across 15 route files in `src/web/routes/`: system (36), sessions (28), orchestrator (10), cases (9), ralph (9), plan (8), respawn (7), files (5), mux (5), push (4), scheduled (4), teams (2), hooks (1), clipboard (1), ws (1 WebSocket). Each file has `@fileoverview` with endpoint details.
+~130 handlers across 15 route files in `src/web/routes/`: system (37, incl. `POST /api/system/span-displays` → spawns `scripts/span-codeman.sh`), sessions (28), orchestrator (10), cases (9), ralph (9), plan (8), respawn (7), files (5), mux (5), push (4), scheduled (4), teams (2), hooks (1), clipboard (1), ws (1 WebSocket). Each file has `@fileoverview` with endpoint details.

 ## Adding Features

@@ -32,6 +32,9 @@ run('chmod dist/index.js', 'chmod +x dist/index.js');
 // 2. Copy static assets (clean first to remove stale hashed files from previous builds)
 run('clean public', 'rm -rf dist/web/public');
 run('prepare dirs', 'mkdir -p dist/web dist/templates dist/web/public/vendor');
+// Fetch the opt-in gesture overlay's MediaPipe wasm + model into src/ (idempotent,
+// non-fatal, kept out of git) so the copy below carries them into dist/.
+run('gesture assets', 'node scripts/fetch-gesture-assets.mjs');
 run('copy web assets', 'cp -r src/web/public dist/web/');
 run('copy template', 'cp src/templates/case-template.md dist/templates/');

@@ -0,0 +1,58 @@
+/**
+ * @fileoverview Fetch the gesture-overlay runtime assets (MediaPipe wasm + the
+ * gesture-recognizer model) into src/web/public/gesture/ so Codeman can serve
+ * them same-origin (a browser content-blocker otherwise blocks the public CDNs
+ * and the overlay fails to start). These are large binaries (~27 MB) kept OUT of
+ * git (ignored explicitly via `src/web/public/gesture/wasm/` + `*.task` in
+ * .gitignore); they are fetched here at install (postinstall) and build time.
+ *
+ * Idempotent: skips files already present. Non-fatal: the gesture overlay is
+ * opt-in (CODEMAN_GESTURE=1), so a fetch failure only warns — it must not break
+ * `npm install` / `npm run build`. The build then copies src/web/public into
+ * dist/ as usual, so prod gets these too.
+ *
+ * The @mediapipe/tasks-vision version MUST match the one bundled into the gesture
+ * overlay (Ark0N/codeman-gesture-control) so the wasm loader matches its JS API.
+ */
+import { mkdirSync, existsSync, statSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const GESTURE = join(__dirname, '..', 'src', 'web', 'public', 'gesture');
+const WASM = join(GESTURE, 'wasm');
+
+const MP_VERSION = '0.10.21'; // keep in sync with the gesture overlay's @mediapipe/tasks-vision
+const WASM_BASE = `https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@${MP_VERSION}/wasm`;
+const MODEL_URL =
+  'https://storage.googleapis.com/mediapipe-models/gesture_recognizer/gesture_recognizer/float16/1/gesture_recognizer.task';
+
+const ASSETS = [
+  { url: `${WASM_BASE}/vision_wasm_internal.js`, path: join(WASM, 'vision_wasm_internal.js') },
+  { url: `${WASM_BASE}/vision_wasm_internal.wasm`, path: join(WASM, 'vision_wasm_internal.wasm') },
+  { url: `${WASM_BASE}/vision_wasm_nosimd_internal.js`, path: join(WASM, 'vision_wasm_nosimd_internal.js') },
+  { url: `${WASM_BASE}/vision_wasm_nosimd_internal.wasm`, path: join(WASM, 'vision_wasm_nosimd_internal.wasm') },
+  { url: MODEL_URL, path: join(GESTURE, 'gesture_recognizer.task') },
+];
+
+async function main() {
+  mkdirSync(WASM, { recursive: true });
+  let fetched = 0;
+  let skipped = 0;
+  for (const a of ASSETS) {
+    if (existsSync(a.path) && statSync(a.path).size > 0) {
+      skipped++;
+      continue;
+    }
+    const res = await fetch(a.url);
+    if (!res.ok) throw new Error(`HTTP ${res.status} for ${a.url}`);
+    writeFileSync(a.path, Buffer.from(await res.arrayBuffer()));
+    fetched++;
+  }
+  console.log(`[gesture] MediaPipe assets ready (${fetched} fetched, ${skipped} cached) → ${GESTURE}`);
+}
+
+main().catch((err) => {
+  // Non-fatal: opt-in feature. Warn and exit 0 so install/build still succeed.
+  console.warn(`[gesture] could not fetch MediaPipe assets — overlay disabled until fetched: ${err.message}`);
+});
@@ -312,6 +312,20 @@ if (isGlobalInstall) {
    }
 }

+// ----------------------------------------------------------------------------
+// 4b. Fetch gesture-overlay runtime assets (MediaPipe wasm + model) for dev mode
+//     (src/web/public/gesture/). Opt-in feature (CODEMAN_GESTURE=1); non-fatal.
+//     Large binaries kept out of git; the build copies them into dist/.
+// ----------------------------------------------------------------------------
+
+if (!isGlobalInstall) {
+    try {
+        execSync(`node "${join(import.meta.dirname, 'fetch-gesture-assets.mjs')}"`, { stdio: 'inherit' });
+    } catch {
+        // Non-fatal — the gesture overlay is opt-in.
+    }
+}
+
 // ----------------------------------------------------------------------------
 // 5. Install git pre-commit hook (format check)
 // ----------------------------------------------------------------------------
@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+#
+# run-beta.sh — launch a BETA Codeman isolated from a production instance.
+#
+# Codeman's data dir (~/.codeman) and tmux socket (-L codeman) are process-wide
+# and shared by every instance on the machine. The code now DEFAULTS to that
+# production layout on port 3000 (safe for master / existing installs), so a beta
+# build no longer isolates itself automatically — this wrapper opts it in:
+#
+#   CODEMAN_INSTANCE=beta  → data dir ~/.codeman-beta + tmux socket codeman-beta
+#   CODEMAN_PORT=5000      → listen on 5000 instead of 3000
+#
+# Result: the beta runs side-by-side with prod and can never discover/attach to
+# prod's live tmux sessions or clobber prod's state.json. Override either var to
+# run additional named instances, e.g. CODEMAN_INSTANCE=foo CODEMAN_PORT=5050.
+#
+# Usage:  ./scripts/run-beta.sh [extra `codeman web` flags]
+# Build first (the beta runs the compiled dist):  npm run build
+
+set -euo pipefail
+
+export CODEMAN_INSTANCE="${CODEMAN_INSTANCE:-beta}"
+export CODEMAN_PORT="${CODEMAN_PORT:-5000}"
+
+DIST="$(cd "$(dirname "$0")/.." && pwd)/dist/index.js"
+if [ ! -f "$DIST" ]; then
+  echo "dist not found at $DIST — run 'npm run build' first." >&2
+  exit 1
+fi
+
+echo "Starting beta Codeman: instance='$CODEMAN_INSTANCE' (~/.codeman-$CODEMAN_INSTANCE, -L codeman-$CODEMAN_INSTANCE) on port $CODEMAN_PORT"
+exec node "$DIST" web "$@"
@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+#
+# span-codeman.sh — open a Codeman window stretched across ALL displays, so that
+# in-page floating session panels can be dragged from one physical monitor to
+# the other. Spawned by the header "multi-monitor" button (POST
+# /api/system/span-displays), or run by hand at the desk.
+#
+# ── PREREQUISITE (one-time, manual) ──────────────────────────────────────────
+# System Settings → Desktop & Dock → turn OFF "Displays have separate Spaces",
+# then LOG OUT and back in. Until you do, macOS keeps every window on a single
+# display and this script's window will clamp to one monitor instead of spanning.
+# (Equivalent CLI: `defaults write com.apple.spaces spans-displays -bool true`,
+#  still needs a re-login. Revert with `-bool false`.)
+#
+# Why a maximized --app window and not fullscreen: browser fullscreen is
+# per-display and will NOT span. We size a windowed app to the union of all
+# displays instead. macOS only.
+#
+set -euo pipefail
+
+URL="${1:-http://localhost:5000}"
+
+# Union rect of all displays in top-left-origin points — exactly what Chromium's
+# --window-position/--window-size expect. Finder's desktop window bounds already
+# encloses every monitor (and handles a monitor placed left/above via a negative
+# origin), so no per-display math or coordinate flipping is needed.
+bounds=$(osascript -e 'tell application "Finder" to get bounds of window of desktop')
+X=$(echo "$bounds" | awk -F', *' '{print $1}')
+Y=$(echo "$bounds" | awk -F', *' '{print $2}')
+R=$(echo "$bounds" | awk -F', *' '{print $3}')
+B=$(echo "$bounds" | awk -F', *' '{print $4}')
+W=$((R - X))
+H=$((B - Y))
+echo "Display union: position ${X},${Y}  size ${W}x${H}"
+
+# Pick a Chromium-family browser. Brave leads the list — plain Google Chrome
+# bounced when launched this way on the desk machine (created its profile then
+# exited without a window). Force a specific one with, e.g.,
+# BROWSER="Google Chrome" ./span-codeman.sh
+app="${BROWSER:-}"
+if [ -z "$app" ]; then
+  for c in "Brave Browser" "Google Chrome" "Google Chrome Beta" "Chromium" "Microsoft Edge"; do
+    [ -x "/Applications/$c.app/Contents/MacOS/$c" ] && app="$c" && break
+  done
+fi
+bin="/Applications/$app.app/Contents/MacOS/$app"
+[ -n "$app" ] && [ -x "$bin" ] || { echo "No Chrome-family browser found (BROWSER='$app')" >&2; exit 1; }
+
+# A dedicated, PER-BROWSER profile forces a FRESH instance — an already-running
+# browser would hand the URL to itself and silently ignore the geometry flags.
+# Per-browser so a Chrome-made profile can't confuse Brave (or vice-versa).
+slug=$(echo "$app" | tr '[:upper:] ' '[:lower:]-')
+profile="$HOME/.codeman-gesture-$slug"
+
+echo "Browser: $bin"
+echo "URL:     $URL"
+
+# Detach so the caller (terminal / web server) isn't blocked for the window's life.
+nohup "$bin" \
+  --app="$URL" \
+  --user-data-dir="$profile" \
+  --window-position="${X},${Y}" \
+  --window-size="${W},${H}" \
+  --no-first-run \
+  --no-default-browser-check \
+  >/dev/null 2>&1 &
+
+echo "Launched spanning window (pid $!)."
+echo "If it filled only one monitor, the 'separate Spaces' prerequisite above"
+echo "isn't active yet — toggle it off, log out/in, and re-run."
@@ -483,7 +483,7 @@ program
 program
  .command('web')
  .description('Start the web interface')
-  .option('-p, --port <port>', 'Port to listen on', '3000')
+  .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) => {
@@ -0,0 +1,66 @@
+/**
+ * @fileoverview Per-instance isolation: data directory + tmux socket.
+ *
+ * Codeman keeps all runtime state under `~/.codeman` and runs its tmux sessions
+ * on a dedicated socket (`tmux -L codeman`). Both are PROCESS-WIDE and SHARED by
+ * every Codeman instance on the machine — so a second instance pointed at the
+ * same socket will discover and attach to the first instance's live sessions,
+ * and two instances sharing `~/.codeman/state.json` will clobber each other.
+ *
+ * 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 (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).
+ */
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync } from 'node:fs';
+
+/**
+ * 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 ?? '';
+
+const INSTANCE_SUFFIX = CODEMAN_INSTANCE ? `-${CODEMAN_INSTANCE}` : '';
+
+/** Default tmux socket for this instance. `CODEMAN_TMUX_SOCKET` still overrides. */
+export const DEFAULT_TMUX_SOCKET = `codeman${INSTANCE_SUFFIX}`;
+
+let _ensured = false;
+
+/**
+ * Absolute path to this instance's data directory (created on first use). All
+ * persisted state (`state.json`, `mux-sessions.json`, settings, push keys,
+ * lifecycle log, screenshots, certs, …) lives here.
+ */
+export function getDataDir(): string {
+  const dir = process.env.CODEMAN_DATA_DIR || join(homedir(), `.codeman${INSTANCE_SUFFIX}`);
+  if (!_ensured) {
+    try {
+      mkdirSync(dir, { recursive: true });
+      _ensured = true;
+    } catch {
+      /* best-effort; individual writers also mkdir as needed */
+    }
+  }
+  return dir;
+}
+
+/** Join one or more segments onto this instance's data directory. */
+export function dataPath(...segments: string[]): string {
+  return join(getDataDir(), ...segments);
+}
@@ -8,12 +8,12 @@

 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { homedir } from 'node:os';
 import webpush from 'web-push';
 import type { VapidKeys, PushSubscriptionRecord } from './types.js';
 import { Debouncer } from './utils/index.js';
+import { getDataDir } from './config/instance.js';

-const DATA_DIR = join(homedir(), '.codeman');
+const DATA_DIR = getDataDir();
 const KEYS_FILE = join(DATA_DIR, 'push-keys.json');
 const SUBS_FILE = join(DATA_DIR, 'push-subscriptions.json');
 const SAVE_DEBOUNCE_MS = 500;
@@ -10,9 +10,9 @@

 import { appendFile, readFile, writeFile } from 'node:fs/promises';
 import { existsSync, mkdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { homedir } from 'node:os';
+import { dirname } from 'node:path';
 import type { LifecycleEventType, LifecycleEntry } from './types.js';
+import { dataPath } from './config/instance.js';

 const MAX_LINES = 10_000;
 const TRIM_TO = 8_000;
@@ -22,7 +22,7 @@ export class SessionLifecycleLog {
  private writeQueue: Promise<void> = Promise.resolve();

  constructor(filePath?: string) {
-    this.filePath = filePath || join(homedir(), '.codeman', 'session-lifecycle.jsonl');
+    this.filePath = filePath || dataPath('session-lifecycle.jsonl');
    const dir = dirname(this.filePath);
    if (!existsSync(dir)) {
      mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -39,6 +39,7 @@ import {
  TokenUsageEntry,
 } from './types.js';
 import { Debouncer, MAX_SESSION_TOKENS } from './utils/index.js';
+import { dataPath, CODEMAN_INSTANCE } from './config/instance.js';

 /** Debounce delay for batching state writes (ms) */
 const SAVE_DEBOUNCE_MS = 500;
@@ -89,8 +90,10 @@ export class StateStore {
  private _saveInFlight: Promise<void> | null = null;

  constructor(filePath?: string) {
-    // Migrate legacy data directory (~/.claudeman → ~/.codeman)
-    if (!filePath) {
+    // Migrate legacy data directory (~/.claudeman → ~/.codeman). Default (prod)
+    // instance only — a named instance (e.g. beta) must never touch the shared
+    // ~/.codeman / ~/codeman-cases layout, preserving instance isolation.
+    if (!filePath && !CODEMAN_INSTANCE) {
      const legacyDir = join(homedir(), '.claudeman');
      const newDir = join(homedir(), '.codeman');
      if (existsSync(legacyDir) && !existsSync(newDir)) {
@@ -105,7 +108,7 @@ export class StateStore {
      }
    }

-    this.filePath = filePath || join(homedir(), '.codeman', 'state.json');
+    this.filePath = filePath || dataPath('state.json');
    this.ralphStatePath = this.filePath.replace('.json', '-inner.json');
    this.state = this.load();
    this.state.config.stateFilePath = this.filePath;
@@ -28,8 +28,8 @@ import { promisify } from 'node:util';
 const execAsync = promisify(exec);
 import { existsSync, readFileSync, mkdirSync } from 'node:fs';
 import { writeFile, rename } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
-import { homedir } from 'node:os';
+import { dirname } from 'node:path';
+import { dataPath, DEFAULT_TMUX_SOCKET } from './config/instance.js';
 import {
  ProcessStats,
  PersistedRespawnConfig,
@@ -92,7 +92,7 @@ export const CLAUDE_CODE_NOFILE_LIMIT = 2147483646;
 const IS_TEST_MODE = !!process.env.VITEST;

 /** Path to persisted mux session metadata */
-const MUX_SESSIONS_FILE = join(homedir(), '.codeman', 'mux-sessions.json');
+const MUX_SESSIONS_FILE = dataPath('mux-sessions.json');

 /** Regex to validate tmux session names (only allow safe characters) */
 const SAFE_MUX_NAME_PATTERN = /^codeman-[a-f0-9-]+$/;
@@ -103,8 +103,9 @@ const LEGACY_MUX_NAME_PATTERN = /^claudeman-[a-f0-9-]+$/;
 /** Regex to validate tmux pane targets (e.g., "%0", "%1", "0", "1") */
 const SAFE_PANE_TARGET_PATTERN = /^(%\d+|\d+)$/;

-/** Dedicated tmux socket for new Codeman-owned sessions. */
-const DEFAULT_CODEMAN_TMUX_SOCKET = 'codeman';
+/** Dedicated tmux socket for new Codeman-owned sessions (instance-scoped:
+ *  `codeman` for prod, `codeman-beta` on the beta branch). */
+const DEFAULT_CODEMAN_TMUX_SOCKET = DEFAULT_TMUX_SOCKET;

 /** Regex to validate tmux socket names passed to `tmux -L`. */
 const SAFE_TMUX_SOCKET_PATTERN = /^[a-zA-Z0-9_.-]+$/;
@@ -154,13 +154,24 @@ export function registerAuthMiddleware(app: FastifyInstance, https: boolean): Au
 * Register security headers and CORS middleware on every response.
 */
 export function registerSecurityHeaders(app: FastifyInstance, https: boolean): void {
+  // Gesture-control overlay (opt-in via CODEMAN_GESTURE=1) runs MediaPipe, which
+  // needs WebAssembly eval (script-src) and blob workers (worker-src). Its wasm
+  // runtime + model are self-hosted under /gesture/ (same-origin, covered by
+  // 'self'), so no CDN connect-src entries are needed. OFF by default so the
+  // production CSP is byte-for-byte unchanged.
+  const gesture = process.env.CODEMAN_GESTURE === '1';
+  const scriptSrc =
+    "script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net" + (gesture ? " 'wasm-unsafe-eval'" : '');
+  const connectSrc = "connect-src 'self' wss://api.deepgram.com";
+  const workerSrc = gesture ? "; worker-src 'self' blob:" : '';
+  const csp =
+    `default-src 'self'; ${scriptSrc}; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; ` +
+    `img-src 'self' data: blob:; ${connectSrc}; font-src 'self' https://cdn.jsdelivr.net; frame-ancestors 'self'${workerSrc}`;
+
  app.addHook('onRequest', (req, reply, done) => {
    reply.header('X-Content-Type-Options', 'nosniff');
    reply.header('X-Frame-Options', 'SAMEORIGIN');
-    reply.header(
-      'Content-Security-Policy',
-      "default-src 'self'; script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; img-src 'self' data: blob:; connect-src 'self' wss://api.deepgram.com; font-src 'self' https://cdn.jsdelivr.net; frame-ancestors 'self'"
-    );
+    reply.header('Content-Security-Policy', csp);
    if (https) {
      reply.header('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
    }
@@ -295,6 +295,22 @@ class CodemanApp {
    this.terminal = null;
    this.fitAddon = null;
    this.activeSessionId = null;
+
+    // ── Session detach / undock (beta) ───────────────────────────────────
+    // A "solo window" is a popped-out browser window showing exactly one
+    // session. Detected from the /session/:id URL path (robust even if a cached
+    // service-worker shell loads), with the server-injected global as a fallback.
+    this.soloSessionId = this._detectSoloSessionId();
+    this.isSoloWindow = !!this.soloSessionId;
+    this.detachedSessions = new Set();   // dashboard-side: ids currently popped out
+    this.detachedWindows = new Map();    // dashboard-side: id -> WindowProxy
+    this._detachWatchTimers = new Map(); // dashboard-side: id -> setInterval handle
+    this.windowChannel = null;           // BroadcastChannel for cross-window sync
+    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
    this._selectGeneration = 0;   // cancel stale selectSession loads
@@ -544,6 +560,11 @@ class CodemanApp {
  init() {
    // Initialize mobile detection first (adds device classes to body)
    MobileDetection.init();
+    // Detach/undock: open the cross-window sync channel; if this is a solo
+    // (popped-out) window, apply its minimal chrome immediately so the tab
+    // strip never flashes before handleInit selects the target session.
+    this._initWindowChannel();
+    if (this.isSoloWindow) document.body.classList.add('solo-mode');
    // Initialize mobile handlers
    KeyboardHandler.init();
    SwipeHandler.init();
@@ -776,6 +797,256 @@ class CodemanApp {
    } catch { /* non-fatal */ }
  }

+  // ══════════════════════════════════════════════════════════════════════
+  // Session detach / undock (beta/session-detach)
+  //
+  // Each detached window is just another normal client of the same session:
+  // the server already fans one PTY's output out to N SSE/WS clients and merges
+  // input from all of them, so a popped-out window is live with no extra server
+  // plumbing. The dashboard tracks which sessions are out, marks their tabs, and
+  // re-docks when the window closes. A BroadcastChannel keeps state in sync
+  // across windows (and survives a dashboard reload via roll-call).
+  // ══════════════════════════════════════════════════════════════════════
+
+  /** Resolve the solo session id from the URL path (preferred) or the
+   *  server-injected global (fallback). Returns null for the normal dashboard. */
+  _detectSoloSessionId() {
+    try {
+      if (typeof window !== 'undefined' && typeof window.__CODEMAN_SOLO__ === 'string' && window.__CODEMAN_SOLO__) {
+        return window.__CODEMAN_SOLO__;
+      }
+      const m = location.pathname.match(/^\/session\/([^/]+)\/?$/);
+      return m ? decodeURIComponent(m[1]) : null;
+    } catch { return null; }
+  }
+
+  /**
+   * Pop a session out into its own browser window. SINGLE, idempotent entry
+   * point: the tab's pop-out icon calls this, and a future gesture layer
+   * ("pinch to drop") calls the exact same method — so keep it cheap and
+   * side-effect-light. Calling it again for an already-open window just raises
+   * that window.
+   * @param {string} id session id
+   */
+  detachSession(id) {
+    if (this.isSoloWindow) return;            // a solo window can't spawn more
+    if (!this.sessions.has(id)) return;
+    // Already detached → raise the existing popup instead of opening (or
+    // reloading) another. Mirrors the tab-click path: after a dashboard reload
+    // we hold no WindowProxy ref, so this raises via the channel rather than
+    // re-running window.open (which would reload the popup's terminal). Returns
+    // false only when we owned a now-closed window (re-dock + fall through to
+    // genuinely re-open below).
+    if (this.detachedSessions.has(id) && this._raiseDetached(id)) return;
+    const features = 'width=960,height=680,menubar=no,toolbar=no,location=no,status=no';
+    let win = null;
+    try { win = window.open('/session/' + encodeURIComponent(id), 'codeman-session-' + id, features); } catch {}
+    if (!win) {
+      this.showToast?.('Pop-out blocked — allow popups for this site to detach a session', 'error');
+      return;
+    }
+    this.detachedWindows.set(id, win);
+    this._markDetached(id, true);
+    this._watchDetachedWindow(id, win);
+    this._postWindowMessage({ type: 'detached', id });
+    try { win.focus(); } catch {}
+  }
+
+  /** Raise the popup for an already-detached session. Returns true if the raise
+   *  was handled (caller should stop); false if we owned a now-closed window and
+   *  re-docked it (caller should fall through to inline / re-open). Unifies the
+   *  pop-out icon and tab-click paths so neither reloads a live popup. */
+  _raiseDetached(id) {
+    const win = this.detachedWindows.get(id);
+    if (win && !win.closed) { try { win.focus(); } catch {} return true; }
+    if (win && win.closed) { this._redock(id); return false; }   // owned ref dead → redock + fall through
+    // No local ref (dashboard reloaded): assume alive and raise via the channel.
+    // A liveness ping (or the popup's own unload) heals the badge if it's gone.
+    this._postWindowMessage({ type: 'focus-request', id });
+    return true;
+  }
+
+  /** Re-dock a session: close its window (which re-docks via its unload
+   *  announcement) and clear dashboard state now. */
+  redockSession(id) {
+    const win = this.detachedWindows.get(id);
+    if (win && !win.closed) { try { win.close(); } catch {} }
+    this._postWindowMessage({ type: 'close-request', id });
+    this._redock(id);
+  }
+
+  /** Clear all dashboard-side detached state/timers for a session. */
+  _redock(id) {
+    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);
+  }
+
+  /** Defer a channel-driven redock briefly. A popup *reload* emits 'redocked'
+   *  then re-announces 'detached'; the grace window lets that re-announce cancel
+   *  the redock, so a reload doesn't blip the dashboard badge. A real close
+   *  leaves the redock unanswered and it fires. */
+  _scheduleRedock(id) {
+    if (this._redockGrace.has(id)) return;
+    const timer = setTimeout(() => { this._redockGrace.delete(id); this._redock(id); }, 1500);
+    this._redockGrace.set(id, timer);
+  }
+
+  _cancelPendingRedock(id) {
+    const t = this._redockGrace.get(id);
+    if (t) { clearTimeout(t); this._redockGrace.delete(id); }
+  }
+
+  /** Toggle the "detached" marker on a tab (immediate DOM update + state set).
+   *  Full re-renders re-apply the class from this.detachedSessions. */
+  _markDetached(id, on) {
+    if (on) this.detachedSessions.add(id); else this.detachedSessions.delete(id);
+    const container = this.$('sessionTabs');
+    const tab = container && container.querySelector(`.session-tab[data-id="${id}"]`);
+    if (tab) tab.classList.toggle('detached', on);
+  }
+
+  /** Poll a window we opened; when it closes, re-dock its tab. This is the
+   *  primary (reliable) close-detection path for windows this tab opened. */
+  _watchDetachedWindow(id, win) {
+    const prev = this._detachWatchTimers.get(id);
+    if (prev) clearInterval(prev);
+    const timer = setInterval(() => {
+      if (!win || win.closed) {
+        clearInterval(timer);
+        this._detachWatchTimers.delete(id);
+        this._redock(id);
+      }
+    }, 800);
+    this._detachWatchTimers.set(id, timer);
+  }
+
+  /** Open the cross-window BroadcastChannel and wire role-specific handlers. */
+  _initWindowChannel() {
+    if (typeof BroadcastChannel === 'undefined') return;
+    try { this.windowChannel = new BroadcastChannel('codeman-windows'); }
+    catch { this.windowChannel = null; return; }
+    this.windowChannel.onmessage = (e) => this._onWindowMessage(e.data);
+    if (this.isSoloWindow) {
+      // Announce presence so the dashboard marks this session's tab detached —
+      // even if this window was opened directly by URL rather than window.open.
+      this._postWindowMessage({ type: 'detached', id: this.soloSessionId });
+      // On close, tell the dashboard to re-dock. pagehide is the reliable signal
+      // on modern browsers; beforeunload is a belt-and-suspenders fallback.
+      const announceClose = () => this._postWindowMessage({ type: 'redocked', id: this.soloSessionId });
+      window.addEventListener('pagehide', announceClose);
+      window.addEventListener('beforeunload', announceClose);
+    } else {
+      // Dashboard: ask any already-open solo windows to re-announce themselves
+      // (covers a dashboard reload while popups remain open), then keep
+      // reconciling so a popup that died WITHOUT a 'redocked' (hard kill / crash)
+      // eventually un-marks its tab.
+      this._postWindowMessage({ type: 'roll-call' });
+      this._startDetachLiveness();
+    }
+  }
+
+  _postWindowMessage(msg) {
+    try { if (this.windowChannel) this.windowChannel.postMessage(msg); } catch {}
+  }
+
+  _onWindowMessage(msg) {
+    if (!msg || typeof msg !== 'object') return;
+    if (this.isSoloWindow) {
+      // Roll-call has no id (broadcast to all) — answer before the id filter.
+      if (msg.type === 'roll-call') { this._postWindowMessage({ type: 'detached', id: this.soloSessionId }); return; }
+      if (msg.id !== this.soloSessionId) return;
+      if (msg.type === 'close-request') { try { window.close(); } catch {} }
+      else if (msg.type === 'focus-request') { try { window.focus(); } catch {} }
+      return;
+    }
+    // Dashboard side.
+    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
+    } else if (msg.type === 'detach-request' && msg.id) {
+      // Future gesture hook: another window asks the dashboard to detach a tab.
+      this.detachSession(msg.id);
+    }
+  }
+
+  /** Dashboard: periodically reconcile detached tabs we hold no window ref for
+   *  (e.g. after a dashboard reload). Owned windows are covered by the
+   *  win.closed poll; channel-only ones can only be checked by asking them to
+   *  re-announce and re-docking any that stay silent. */
+  _startDetachLiveness() {
+    if (this._detachLivenessTimer) return;
+    this._detachLivenessTimer = setInterval(() => this._pingDetached(), 5000);
+  }
+
+  _pingDetached() {
+    const orphans = [];
+    for (const id of this.detachedSessions) {
+      const win = this.detachedWindows.get(id);
+      if (!win) orphans.push(id);            // channel-only — must verify via re-announce
+      else if (win.closed) this._redock(id); // owned & closed — heal now
+    }
+    if (!orphans.length) return;
+    this._detachPingPending = new Set(orphans);
+    this._postWindowMessage({ type: 'roll-call' });
+    // 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) {
+        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);
+  }
+
+  /** Solo window: select the target session and apply minimal single-session
+   *  chrome. Called from handleInit once the session list has loaded. */
+  _applySoloMode() {
+    document.body.classList.add('solo-mode');
+    const session = this.sessions.get(this.soloSessionId);
+    if (!session) { this._showSoloSessionGone(); return; }
+    // Force re-select (handleInit cleared terminal state above).
+    this.activeSessionId = null;
+    this.selectSession(this.soloSessionId);
+    const name = this.getSessionName(session) || 'Session';
+    const titleEl = document.getElementById('soloSessionTitle');
+    if (titleEl) { titleEl.textContent = name; titleEl.style.display = ''; }
+    const redock = document.getElementById('soloRedockBtn');
+    if (redock) redock.style.display = '';
+    document.title = name + ' — Codeman';
+    if (this.notificationManager) this.notificationManager.originalTitle = document.title;
+    // Neutralize the dashboard-only brand click in a solo window.
+    const logo = document.querySelector('.header-brand .logo');
+    if (logo) logo.onclick = (e) => { e.preventDefault(); };
+  }
+
+  /** Solo window: the target session is gone (never existed, or ended while
+   *  this window was open). Show a friendly terminal state. */
+  _showSoloSessionGone() {
+    document.body.classList.add('solo-mode');
+    if (document.querySelector('.solo-gone-overlay')) return;
+    const el = document.createElement('div');
+    el.className = 'solo-gone-overlay';
+    el.innerHTML = '<h2>Session unavailable</h2>'
+      + '<p>This session has ended or is no longer available.</p>'
+      + '<button class="btn-primary" onclick="window.close()">Close window</button>';
+    document.body.appendChild(el);
+    document.title = 'Session ended — Codeman';
+  }
+
  connectSSE() {
    // Check if browser is offline
    if (!navigator.onLine) {
@@ -929,6 +1200,12 @@ class CodemanApp {

  _onSessionDeleted(data) {
    if (this._wsSessionId === data.id) this._disconnectWs();
+    // Solo window whose session just ended → show the "unavailable" state.
+    if (this.isSoloWindow && data.id === this.soloSessionId) {
+      this._showSoloSessionGone();
+    }
+    // Dashboard: a detached session ended → clear its detached state/timers.
+    if (this.detachedSessions.has(data.id)) this._redock(data.id);
    this._cleanupSessionData(data.id);
    if (this.activeSessionId === data.id) {
      this.activeSessionId = null;
@@ -1949,6 +2226,14 @@ class CodemanApp {
    // Reset activeSessionId so selectSession doesn't early-return.
    // Guard: skip if a newer handleInit has already started (race between loadState + SSE init).
    if (gen !== this._initGeneration) return;
+
+    // Solo (detached) window: always show exactly the target session, ignoring
+    // the dashboard's "restore last active" logic.
+    if (this.isSoloWindow) {
+      this._applySoloMode();
+      return;
+    }
+
    const previousActiveId = this.activeSessionId;
    this.activeSessionId = null;
    if (this.sessionOrder.length > 0) {
@@ -2182,19 +2467,21 @@ class CodemanApp {
      const tallTabsEnabled = this._tallTabsEnabled ?? false;
      const showFolder = tallTabsEnabled && session.name && folderName && folderName !== name;

-      parts.push(`<div class="session-tab ${isActive ? 'active' : ''}${alertClass}" data-id="${id}" data-color="${color}" onclick="app.selectSession('${escapeHtml(id)}')" oncontextmenu="event.preventDefault(); app.startInlineRename('${escapeHtml(id)}')" tabindex="0" role="tab" aria-selected="${isActive ? 'true' : 'false'}" aria-label="${escapeHtml(name)} session" ${session.workingDir ? `title="${escapeHtml(session.workingDir)}"` : ''}>
+      parts.push(`<div class="session-tab ${isActive ? 'active' : ''}${alertClass}${this.detachedSessions.has(id) ? ' detached' : ''}" data-id="${id}" data-color="${color}" onclick="app.selectSession('${escapeHtml(id)}')" oncontextmenu="event.preventDefault(); app.startInlineRename('${escapeHtml(id)}')" tabindex="0" role="tab" aria-selected="${isActive ? 'true' : 'false'}" aria-label="${escapeHtml(name)} session" ${session.workingDir ? `title="${escapeHtml(session.workingDir)}"` : ''}>
          ${_tabIdx < 9 ? '<span class="tab-number">' + (_tabIdx + 1) + '</span>' : ''}
          <span class="tab-status ${status}" aria-hidden="true"></span>
          <span class="tab-info">
            <span class="tab-name-row">
              ${mode === 'shell' ? '<span class="tab-mode shell" aria-hidden="true">sh</span>' : mode === 'opencode' ? '<span class="tab-mode opencode" aria-hidden="true">oc</span>' : ''}
              <span class="tab-name" data-session-id="${id}">${(() => { const p = parseSessionPrefix(name); return p && p.suffix ? '<span class="tab-prefix">' + escapeHtml(p.prefix) + '</span><span class="tab-suffix">: ' + escapeHtml(p.suffix) + '</span>' : escapeHtml(name); })()}</span>
+              <span class="tab-detached-badge" aria-hidden="true">detached</span>
            </span>
            ${showFolder ? `<span class="tab-folder">\u{1F4C1} ${escapeHtml(folderName)}</span>` : ''}
          </span>
          ${hasRunningTasks ? `<span class="tab-badge" onclick="event.stopPropagation(); app.toggleTaskPanel()" aria-label="${taskStats.running} running tasks">${taskStats.running}</span>` : ''}
          ${subagentBadge}
          <span class="tab-gear" onclick="event.stopPropagation(); app.openSessionOptions('${escapeHtml(id)}')" title="Session options" aria-label="Session options" tabindex="0">&#x2699;</span>
+          <span class="tab-detach" onclick="event.stopPropagation(); app.detachSession('${escapeHtml(id)}')" title="Open in a new window" aria-label="Open session in a new window" tabindex="0">&#x29C9;</span>
          <span class="tab-close" onclick="event.stopPropagation(); app.requestCloseSession('${escapeHtml(id)}')" title="Close session" aria-label="Close session" tabindex="0">&times;</span>
        </div>`);
      _tabIdx++;
@@ -2525,6 +2812,13 @@ class CodemanApp {
  }

  async selectSession(sessionId) {
+    // If this session is popped out into its own window, raise that window
+    // instead of showing it inline (focus-on-click for detached tabs).
+    if (!this.isSoloWindow && this.detachedSessions.has(sessionId)) {
+      // Raise the popup instead of showing inline. If we owned a now-closed
+      // window, _raiseDetached re-docks and returns false so we fall through.
+      if (this._raiseDetached(sessionId)) return;
+    }
    if (this.activeSessionId === sessionId) return;
    // Focus terminal SYNCHRONOUSLY before any await — iOS Safari only honors
    // programmatic focus() within the user-gesture call stack (e.g. tab click).
@@ -2,6 +2,10 @@
 <html lang="en">
 <head>
  <meta charset="UTF-8">
+  <!-- Resolve all relative assets against the site root so the same shell can be
+       served at /session/:id (detached single-session window) without 404ing
+       on relative <script>/<link> URLs. Must precede the first resource tag. -->
+  <base href="/">
  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover">
  <meta name="description" content="Claude Code session manager with web interface">
  <meta name="theme-color" content="#0a0a0a">
@@ -55,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">
@@ -67,7 +73,11 @@
      <div class="session-tabs" id="sessionTabs" role="tablist" aria-label="Session tabs">
      </div>

+      <!-- Detached single-session window title (shown only in solo mode) -->
+      <div class="solo-session-title" id="soloSessionTitle" style="display: none;" aria-live="polite"></div>
+
      <div class="header-right">
+        <button class="btn-icon-header btn-solo-redock" id="soloRedockBtn" style="display: none;" onclick="window.close()" title="Re-dock to dashboard (close window)" aria-label="Re-dock session to dashboard">&#x229E;</button>
        <button class="tunnel-indicator" id="tunnelIndicator" style="display: none;" onclick="app.toggleTunnelPanel()" title="Cloudflare Tunnel" aria-label="Tunnel status">
          <span class="tunnel-dot"></span>
        </button>
@@ -97,7 +107,8 @@
          </div>
        </div>
        <button class="btn-icon-header btn-response-viewer-header" onclick="app.toggleResponseViewer()" title="View last response" aria-label="View last response"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z"/><circle cx="12" cy="12" r="3"/></svg></button>
-        <button class="btn-icon-header btn-notifications" onclick="app.toggleNotifications()" title="Notifications" aria-label="Toggle notifications">
+        <button class="btn-icon-header btn-multimonitor" onclick="app.launchMultiMonitor()" title="Open Codeman across all displays" aria-label="Open Codeman across all displays"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="4" width="13" height="9" rx="1.5"/><rect x="11" y="9" width="11" height="8" rx="1.5"/></svg></button>
+        <button class="btn-icon-header btn-notifications" onclick="app.toggleNotifications()" title="Notifications" aria-label="Toggle notifications" style="display:none;">
          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"/><path d="M13.73 21a2 2 0 0 1-3.46 0"/></svg>
          <span class="notification-badge" id="notifBadge" style="display:none;">0</span>
        </button>
@@ -3129,6 +3129,23 @@ Object.assign(CodemanApp.prototype, {
    this.notificationManager?.toggleDrawer();
  },

+  // Open a Codeman window stretched across all displays (multi-monitor mode).
+  // The server spawns scripts/span-codeman.sh, which launches a fresh, spanning
+  // browser --app window so in-page floating panels can cross the monitor seam.
+  async launchMultiMonitor() {
+    try {
+      const res = await fetch('/api/system/span-displays', { method: 'POST' });
+      const data = await res.json().catch(() => ({}));
+      if (res.ok && data.success) {
+        this.showToast('Opening Codeman across all displays…', 'success');
+      } else {
+        this.showToast(data.error || 'Could not open spanning window', 'error');
+      }
+    } catch (err) {
+      this.showToast('Could not open spanning window: ' + (err?.message || err), 'error');
+    }
+  },
+
  // Alias for showToast
  toast(message, type = 'info') {
    return this.showToast(message, type);
@@ -905,6 +905,97 @@ body {
  transform: rotate(45deg);
 }

+/* ===== Session detach / undock (beta/session-detach) ===================== */
+
+/* Pop-out (detach) icon on each tab — mirrors .tab-gear reveal-on-hover. */
+.session-tab .tab-detach {
+  opacity: 0;
+  width: 0;
+  padding: 0;
+  font-size: 0.95rem;
+  line-height: 1;
+  color: var(--text-muted);
+  cursor: pointer;
+  overflow: hidden;
+  transition: opacity 0.15s, width 0.15s, padding 0.15s;
+}
+.session-tab:hover .tab-detach {
+  opacity: 1;
+  width: auto;
+  padding: 0 0.3rem;
+}
+.session-tab .tab-detach:hover {
+  color: var(--accent-hover);
+  background: rgba(255, 255, 255, 0.1);
+  border-radius: 3px;
+}
+
+/* A tab whose session is popped out into its own window. */
+.session-tab.detached {
+  opacity: 0.72;
+}
+.session-tab.detached .tab-detach {
+  /* Keep the pop-out icon visible while detached as a re-focus affordance. */
+  opacity: 1;
+  width: auto;
+  padding: 0 0.3rem;
+  color: var(--accent-hover);
+}
+.session-tab .tab-detached-badge {
+  display: none;
+  align-items: center;
+  font-size: 0.55rem;
+  font-weight: 700;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  padding: 1px 4px;
+  margin-left: 4px;
+  border-radius: 3px;
+  background: rgba(96, 165, 250, 0.18);
+  color: var(--accent-hover);
+}
+.session-tab.detached .tab-detached-badge {
+  display: inline-flex;
+}
+
+/* ===== Solo (detached single-session) window chrome ===================== */
+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;
+}
+.solo-session-title {
+  flex: 1;
+  min-width: 0;
+  font-weight: 600;
+  font-size: 13px;
+  color: var(--text);
+  padding: 0 12px;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+/* "Session unavailable" overlay for a solo window whose session has ended. */
+.solo-gone-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 5000;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 14px;
+  background: rgba(9, 9, 11, 0.92);
+  color: var(--text);
+  text-align: center;
+  padding: 24px;
+}
+.solo-gone-overlay h2 { margin: 0; font-size: 18px; }
+.solo-gone-overlay p { margin: 0; color: var(--text-muted); font-size: 13px; }
+
 /* Mode indicator on session tab */
 .session-tab .tab-mode {
  font-size: 0.6rem;
@@ -16,10 +16,12 @@ import { parseRalphLoopConfig, extractCompletionPhrase } from '../ralph-config.j
 import { SseEvent } from './sse-events.js';
 import type { SessionPort } from './ports/session-port.js';
 import type { EventPort } from './ports/event-port.js';
+import { dataPath } from '../config/instance.js';

-// Shared path constants used across route modules
+// Shared path constants used across route modules. CASES_DIR (project folders)
+// stays shared across instances; SETTINGS_PATH is per-instance runtime state.
 export const CASES_DIR = join(homedir(), 'codeman-cases');
-export const SETTINGS_PATH = join(homedir(), '.codeman', 'settings.json');
+export const SETTINGS_PATH = dataPath('settings.json');

 /**
 * Validates that a path component doesn't escape the base directory.
@@ -17,8 +17,9 @@ import { writeHooksConfig } from '../../hooks-config.js';
 import { CASES_DIR, SETTINGS_PATH, validatePathWithinBase, parseBody, readJsonConfig } from '../route-helpers.js';
 import { SseEvent } from '../sse-events.js';
 import type { EventPort, ConfigPort } from '../ports/index.js';
+import { dataPath, getDataDir } from '../../config/instance.js';

-const LINKED_CASES_FILE = join(homedir(), '.codeman', 'linked-cases.json');
+const LINKED_CASES_FILE = dataPath('linked-cases.json');
 const SAFE_CASE_NAME = /^[a-zA-Z0-9_-]+$/;

 /** Read and parse linked-cases.json, returning empty object on missing/invalid file. */
@@ -151,7 +152,7 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
    // Save the linked case
    linkedCases[name] = expandedPath;
    try {
-      const codemanDir = join(homedir(), '.codeman');
+      const codemanDir = getDataDir();
      if (!existsSync(codemanDir)) {
        mkdirSync(codemanDir, { recursive: true });
      }
@@ -206,7 +207,7 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
    const { order } = parseBody(CaseOrderSchema, req.body, 'Invalid order data');

    try {
-      const dir = join(homedir(), '.codeman');
+      const dir = getDataDir();
      if (!existsSync(dir)) {
        mkdirSync(dir, { recursive: true });
      }
@@ -54,9 +54,10 @@ import { MAX_CONCURRENT_SESSIONS } from '../../config/map-limits.js';
 import { RunSummaryTracker } from '../../run-summary.js';

 import { MAX_INPUT_LENGTH, MAX_SESSION_NAME_LENGTH } from '../../config/terminal-limits.js';
+import { dataPath } from '../../config/instance.js';

 // Path to linked-cases registry (same file used by case-routes resolveCasePath)
-const LINKED_CASES_FILE = join(homedir(), '.codeman', 'linked-cases.json');
+const LINKED_CASES_FILE = dataPath('linked-cases.json');

 // Pre-compiled regex for terminal buffer cleaning (avoids per-request compilation)
 // eslint-disable-next-line no-control-regex
@@ -6,11 +6,13 @@

 import { FastifyInstance } from 'fastify';
 import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { existsSync, mkdirSync, readdirSync } from 'node:fs';
 import fs from 'node:fs/promises';
-import { homedir, totalmem, freemem, loadavg, cpus } from 'node:os';
-import { execSync } from 'node:child_process';
+import { totalmem, freemem, loadavg, cpus } from 'node:os';
+import { execSync, spawn } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
+import { dataPath } from '../../config/instance.js';
 import { ApiErrorCode, createErrorResponse, getErrorMessage, type NiceConfig } from '../../types.js';
 import {
  ConfigUpdateSchema,
@@ -41,7 +43,7 @@ import { AUTH_SESSION_TTL_MS } from '../../config/auth-config.js';
 // Maximum screenshot upload size (10MB)
 const MAX_SCREENSHOT_SIZE = 10 * 1024 * 1024;
 // Screenshots directory
-const SCREENSHOTS_DIR = join(homedir(), '.codeman', 'screenshots');
+const SCREENSHOTS_DIR = dataPath('screenshots');

 /** Cached CPU count — doesn't change at runtime */
 const CPU_COUNT = cpus().length;
@@ -92,12 +94,24 @@ 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
 ): void {
-  const windowStatesPath = join(homedir(), '.codeman', 'subagent-window-states.json');
-  const parentMapPath = join(homedir(), '.codeman', 'subagent-parents.json');
+  const windowStatesPath = dataPath('subagent-window-states.json');
+  const parentMapPath = dataPath('subagent-parents.json');

  // ═══════════════════════════════════════════════════════════════
  // System Status & Health
@@ -239,6 +253,40 @@ export function registerSystemRoutes(
    return { success: true };
  });

+  // ═══════════════════════════════════════════════════════════════
+  // Multi-monitor: span Codeman across all displays
+  // ═══════════════════════════════════════════════════════════════
+
+  // Spawn scripts/span-codeman.sh, which opens a fresh, maximized browser --app
+  // window sized to the union of all displays — so in-page floating session
+  // 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 (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'));
+      child.unref();
+      return { success: true, url };
+    } catch (err) {
+      return reply.code(500).send(createErrorResponse(ApiErrorCode.INTERNAL_ERROR, getErrorMessage(err)));
+    }
+  });
+
  // ═══════════════════════════════════════════════════════════════
  // CLI Integrations (OpenCode)
  // ═══════════════════════════════════════════════════════════════
@@ -36,10 +36,11 @@ import fastifyMultipart from '@fastify/multipart';
 import { startPasteImageGc } from './paste-image-gc.js';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { existsSync, mkdirSync, readFileSync, chmodSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, chmodSync, rmSync, statSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import { execSync } from 'node:child_process';
-import { homedir, hostname as getHostname } from 'node:os';
+import { hostname as getHostname } from 'node:os';
+import { dataPath } from '../config/instance.js';
 import { EventEmitter } from 'node:events';
 import { Session, type BackgroundTask } from '../session.js';
 import type { ClaudeMode, SessionState } from '../types.js';
@@ -146,7 +147,7 @@ import {
 * Certs are stored in ~/.codeman/certs/ and reused across restarts.
 */
 function getOrCreateSelfSignedCert(): { key: string; cert: string } {
-  const certsDir = join(homedir(), '.codeman', 'certs');
+  const certsDir = dataPath('certs');
  const keyPath = join(certsDir, 'server.key');
  const certPath = join(certsDir, 'server.crt');

@@ -562,6 +563,17 @@ export class WebServer extends EventEmitter {
    this.app.get('/index.html', async (_req, reply) => {
      return reply.header('Cache-Control', 'no-cache').type('text/html; charset=utf-8').send(this.renderIndexHtml());
    });
+    // Detached single-session window (undock). Serves the same SPA shell but
+    // flags the client into "solo mode" for one session. Auth applies normally
+    // (the popup carries the dashboard's cookie on navigation). We serve 200
+    // even for an unknown id — the client renders a friendly "session
+    // unavailable" state, which also covers a session that ends while its
+    // detached window is still open. Registered before the static plugin so the
+    // explicit route wins over the '/' static prefix.
+    this.app.get('/session/:id', async (req, reply) => {
+      const { id } = req.params as { id: string };
+      return reply.header('Cache-Control', 'no-cache').type('text/html; charset=utf-8').send(this.renderIndexHtml(id));
+    });
    // Service worker must never be cached — browsers check for SW updates on navigation
    this.app.get('/sw.js', async (_req, reply) => {
      return reply
@@ -980,11 +992,77 @@ export class WebServer extends EventEmitter {
    this.broadcast(SseEvent.SessionDeleted, { id: sessionId });
  }

-  private renderIndexHtml(): string {
-    return this.indexHtmlTemplate.replace(
+  private renderIndexHtml(soloSessionId?: string): string {
+    let html = this.indexHtmlTemplate.replace(
      '<title>Codeman</title>',
      `<title>${escapeHtmlText(this.windowTitle)}</title>`
    );
+    // Cache-bust same-origin module scripts + stylesheets so a normal reload
+    // always serves the latest (static assets carry a 1-year immutable cache).
+    html = this.cacheBustAssets(html);
+    // Detached single-session ("solo") window: inject the target session id so
+    // the client can enter solo mode even if a (network-first) service worker
+    // later serves a cached shell. The client primarily detects solo mode from
+    // the /session/:id URL path; this global is a belt-and-suspenders fallback.
+    // The id is gated to JSON + <-escaped so it can't break out of the inline
+    // <script> (ids are UUIDs in practice, but defense-in-depth is cheap).
+    if (soloSessionId) {
+      const safeId = JSON.stringify(soloSessionId).replace(/</g, '\\u003c');
+      html = html.replace('</head>', `<script>window.__CODEMAN_SOLO__=${safeId};</script>\n</head>`);
+    }
+    // Gesture-control overlay (Phase 5): dashboard only (not solo popups, which
+    // have no tab strip), opt-in via CODEMAN_GESTURE=1. The bundle is served
+    // same-origin from /gesture/ so 'self' covers it; CSP is widened to match in
+    // registerSecurityHeaders under the same flag.
+    if (!soloSessionId && process.env.CODEMAN_GESTURE === '1') {
+      const v = this.gestureBundleVersion();
+      html = html.replace('</head>', `<script type="module" src="/gesture/gesture-codeman.js${v}"></script>\n</head>`);
+    }
+    return html;
+  }
+
+  /** 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 v = Math.floor(statSync(absPath).mtimeMs);
+      this._assetVersionMemo.set(absPath, { v, ts: now });
+      return v;
+    } catch {
+      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 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) => {
+      const v = this.assetVersion(join(publicDir, ref));
+      return v === null ? full : `${pre}${ref}?v=${v}${post}`;
+    });
  }

  private async setupSessionListeners(session: Session): Promise<void> {
@@ -1088,7 +1166,7 @@ export class WebServer extends EventEmitter {

  // Helper to get custom CLAUDE.md template path from settings
  private async getDefaultClaudeMdPath(): Promise<string | undefined> {
-    const settingsPath = join(homedir(), '.codeman', 'settings.json');
+    const settingsPath = dataPath('settings.json');

    try {
      const content = await fs.readFile(settingsPath, 'utf-8');
@@ -1112,7 +1190,7 @@ export class WebServer extends EventEmitter {
    if (this._settingsCache && now - this._settingsCache.ts < 2000) {
      return this._settingsCache.data;
    }
-    const settingsPath = join(homedir(), '.codeman', 'settings.json');
+    const settingsPath = dataPath('settings.json');
    try {
      const content = await fs.readFile(settingsPath, 'utf-8');
      const data = JSON.parse(content) as Record<string, unknown>;
@@ -1619,7 +1697,7 @@ export class WebServer extends EventEmitter {
    // Tunnel only starts when user clicks the toggle in the UI — never on boot.
    // Reset persisted tunnelEnabled so the UI toggle reflects actual state.
    if (await this.isTunnelEnabled()) {
-      const settingsPath = join(homedir(), '.codeman', 'settings.json');
+      const settingsPath = dataPath('settings.json');
      try {
        const content = await fs.readFile(settingsPath, 'utf-8');
        const settings = JSON.parse(content);
@@ -1640,7 +1718,7 @@ export class WebServer extends EventEmitter {
   * Check if subagent tracking is enabled in settings (default: true)
   */
  private async isSubagentTrackingEnabled(): Promise<boolean> {
-    const settingsPath = join(homedir(), '.codeman', 'settings.json');
+    const settingsPath = dataPath('settings.json');
    try {
      const content = await fs.readFile(settingsPath, 'utf-8');
      const settings = JSON.parse(content);
@@ -1658,7 +1736,7 @@ export class WebServer extends EventEmitter {
   * Check if image watcher is enabled in settings (default: false)
   */
  private async isImageWatcherEnabled(): Promise<boolean> {
-    const settingsPath = join(homedir(), '.codeman', 'settings.json');
+    const settingsPath = dataPath('settings.json');
    try {
      const content = await fs.readFile(settingsPath, 'utf-8');
      const settings = JSON.parse(content);
@@ -1676,7 +1754,7 @@ export class WebServer extends EventEmitter {
   * Check if Cloudflare tunnel is enabled in settings (default: false)
   */
  private async isTunnelEnabled(): Promise<boolean> {
-    const settingsPath = join(homedir(), '.codeman', 'settings.json');
+    const settingsPath = dataPath('settings.json');
    try {
      const content = await fs.readFile(settingsPath, 'utf-8');
      const settings = JSON.parse(content);
@@ -0,0 +1,79 @@
+/**
+ * Per-instance isolation (src/config/instance.ts): the data dir + tmux socket
+ * derive from CODEMAN_INSTANCE, defaulting to the production layout so the
+ * feature branch is safe to merge to master.
+ *
+ * instance.ts reads env at module load, so each case re-imports it via
+ * vi.resetModules() under a controlled env. node:fs mkdirSync is mocked so
+ * getDataDir() never creates real directories on the test machine.
+ *
+ * Port: N/A (no server).
+ */
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+vi.mock('node:fs', async (orig) => {
+  const actual = await orig<typeof import('node:fs')>();
+  return { ...actual, mkdirSync: vi.fn() };
+});
+
+const ENV_KEYS = ['CODEMAN_INSTANCE', 'CODEMAN_DATA_DIR'] as const;
+const ORIG: Record<string, string | undefined> = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
+
+async function load(env: Partial<Record<(typeof ENV_KEYS)[number], string | undefined>> = {}) {
+  vi.resetModules();
+  for (const k of ENV_KEYS) {
+    const v = env[k];
+    if (v === undefined) delete process.env[k];
+    else process.env[k] = v;
+  }
+  return import('../../src/config/instance.js');
+}
+
+afterEach(() => {
+  for (const k of ENV_KEYS) {
+    if (ORIG[k] === undefined) delete process.env[k];
+    else process.env[k] = ORIG[k];
+  }
+  vi.resetModules();
+});
+
+describe('config/instance', () => {
+  it('defaults to the production layout when CODEMAN_INSTANCE is unset', async () => {
+    const m = await load({ CODEMAN_INSTANCE: undefined, CODEMAN_DATA_DIR: undefined });
+    expect(m.CODEMAN_INSTANCE).toBe('');
+    expect(m.DEFAULT_TMUX_SOCKET).toBe('codeman');
+    expect(m.getDataDir()).toBe(join(homedir(), '.codeman'));
+    expect(m.dataPath('state.json')).toBe(join(homedir(), '.codeman', 'state.json'));
+  });
+
+  it('treats an explicitly-empty CODEMAN_INSTANCE as the production layout', async () => {
+    const m = await load({ CODEMAN_INSTANCE: '', CODEMAN_DATA_DIR: undefined });
+    expect(m.CODEMAN_INSTANCE).toBe('');
+    expect(m.DEFAULT_TMUX_SOCKET).toBe('codeman');
+    expect(m.getDataDir()).toBe(join(homedir(), '.codeman'));
+  });
+
+  it('scopes BOTH the data dir and the tmux socket for a named instance', async () => {
+    const m = await load({ CODEMAN_INSTANCE: 'beta', CODEMAN_DATA_DIR: undefined });
+    expect(m.CODEMAN_INSTANCE).toBe('beta');
+    expect(m.DEFAULT_TMUX_SOCKET).toBe('codeman-beta');
+    expect(m.getDataDir()).toBe(join(homedir(), '.codeman-beta'));
+    expect(m.dataPath('mux-sessions.json')).toBe(join(homedir(), '.codeman-beta', 'mux-sessions.json'));
+  });
+
+  it('supports an arbitrary instance name', async () => {
+    const m = await load({ CODEMAN_INSTANCE: 'foo', CODEMAN_DATA_DIR: undefined });
+    expect(m.DEFAULT_TMUX_SOCKET).toBe('codeman-foo');
+    expect(m.getDataDir()).toBe(join(homedir(), '.codeman-foo'));
+  });
+
+  it('CODEMAN_DATA_DIR overrides the derived data dir (socket still instance-scoped)', async () => {
+    const m = await load({ CODEMAN_INSTANCE: 'beta', CODEMAN_DATA_DIR: '/tmp/codeman-test-xyz' });
+    expect(m.getDataDir()).toBe('/tmp/codeman-test-xyz');
+    expect(m.dataPath('a', 'b')).toBe(join('/tmp/codeman-test-xyz', 'a', 'b'));
+    // Socket is derived from the instance name, not the data dir override.
+    expect(m.DEFAULT_TMUX_SOCKET).toBe('codeman-beta');
+  });
+});
@@ -0,0 +1,76 @@
+/**
+ * POST /api/system/span-displays (multi-monitor launcher) + resolveSpanUrl.
+ *
+ * The route shells out to scripts/span-codeman.sh, so we mock child_process.spawn
+ * to avoid actually opening a browser (and to assert the sanitized URL passed to
+ * it). process.platform is overridden per-case so the macOS-only guard is tested
+ * deterministically regardless of where the suite runs.
+ *
+ * Port: N/A (app.inject).
+ */
+import { describe, it, expect, afterEach, vi } from 'vitest';
+
+const spawnMock = vi.hoisted(() => vi.fn(() => ({ on: vi.fn(), unref: vi.fn() })));
+vi.mock('node:child_process', async (orig) => {
+  const actual = await orig<typeof import('node:child_process')>();
+  return { ...actual, spawn: spawnMock };
+});
+
+import { createRouteTestHarness } from './_route-test-utils.js';
+import { registerSystemRoutes, resolveSpanUrl } from '../../src/web/routes/system-routes.js';
+
+const REAL_PLATFORM = process.platform;
+function setPlatform(p: NodeJS.Platform) {
+  Object.defineProperty(process, 'platform', { value: p, configurable: true });
+}
+afterEach(() => {
+  setPlatform(REAL_PLATFORM);
+  spawnMock.mockClear();
+});
+
+describe('resolveSpanUrl', () => {
+  it('takes a digits-only port from the Host header, pinned to localhost', () => {
+    expect(resolveSpanUrl('localhost:5000')).toBe('http://localhost:5000');
+    // Hostname is discarded — always localhost (same machine).
+    expect(resolveSpanUrl('attacker.example.com:3000')).toBe('http://localhost:3000');
+  });
+
+  it('falls back to the default port for missing / non-numeric ports', () => {
+    expect(resolveSpanUrl(undefined)).toBe('http://localhost:3000');
+    expect(resolveSpanUrl('localhost')).toBe('http://localhost:3000');
+    expect(resolveSpanUrl('localhost:99;rm -rf /')).toBe('http://localhost:3000');
+    expect(resolveSpanUrl('localhost:80abc')).toBe('http://localhost:3000');
+    expect(resolveSpanUrl('x', '5000')).toBe('http://localhost:5000');
+  });
+});
+
+describe('POST /api/system/span-displays', () => {
+  it('returns 400 (macOS-only) on non-darwin and never spawns', async () => {
+    setPlatform('linux');
+    const { app } = await createRouteTestHarness(registerSystemRoutes);
+    const res = await app.inject({ method: 'POST', url: '/api/system/span-displays' });
+    expect(res.statusCode).toBe(400);
+    expect(res.json().success).toBe(false);
+    expect(res.json().error).toMatch(/macOS/i);
+    expect(spawnMock).not.toHaveBeenCalled();
+    await app.close();
+  });
+
+  it('spawns the launcher with the sanitized localhost URL on darwin', async () => {
+    setPlatform('darwin');
+    const { app } = await createRouteTestHarness(registerSystemRoutes);
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/system/span-displays',
+      headers: { host: 'localhost:5000' },
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toMatchObject({ success: true, url: 'http://localhost:5000' });
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+    const [cmd, args] = spawnMock.mock.calls[0] as [string, string[]];
+    expect(cmd).toBe('bash');
+    expect(args[0]).toMatch(/span-codeman\.sh$/);
+    expect(args[1]).toBe('http://localhost:5000');
+    await app.close();
+  });
+});