handmux 0.23.0 → 0.25.0

package/src/orphans.js

@@ -1,152 +0,0 @@
-// Detect "orphan" coding-agent sessions: a `claude`/`codex`/… process running on this host that is NOT
-// inside a tmux pane, so handmux can't see or steer it. We can't migrate a live process into tmux (reptyr
-// needs Linux ptrace+/proc — out on macOS — and breaks on multithreaded Node + child processes), so instead
-// we surface these in the Inbox and offer a "takeover": spawn the agent's `resume` command in a fresh tmux
-// pane (the agent's own persistence continues the conversation), then optionally kill the original.
-//
-// Detection is process-based, NOT a scan of the agents' session history (which is unbounded and can't tell
-// a live session from a dead one). Cost scales with the number of LIVE agent processes only.
-//
-// tmux membership is decided by TTY/PPID match against `tmux list-panes`, NOT by reading the process
-// environment: on macOS `ps eww` can't read another process's env (SIP), so `$TMUX` is a false signal.
-// A proc whose controlling tty is one of tmux's pane ttys (or whose parent is a pane's shell) is in tmux;
-// anything else with a real tty is an orphan.
-//
-// This module is now the agent-AGNOSTIC engine: which processes count, where a cwd's session lives, and how
-// to resume it all come from the driver descriptors in ./agents (parseAgentProcs tags each proc with its
-// agent; scan/takeover dispatch through getAgent). The pure parse/file helpers live in ./agents/scanUtils.
-import os from 'node:os';
-import path from 'node:path';
-import { AGENTS, getAgent } from './agents/index.js';
-import { isSessionId } from './tmux/commands.js';
-import { tmuxFormat } from './tmux/format.js';
-import {
-  defaultRun, parseAgentProcs, parsePaneMembership, findOrphans,
-  takeoverSessionName, sanitizeSessionName, freeSessionName, isShell, lsofCwd, isSessionUuid,
-} from './agents/scanUtils.js';
-
-// Back-compat re-exports: these were originally defined here and are imported by tests and callers by this
-// path. They're all agent-agnostic (or Claude's, kept as the default) and now live in scanUtils / claude.
-export {
-  parsePaneMembership, findOrphans, encodeProjectDir, isSessionUuid,
-  lastUserSnippet, etimeToMs, takeoverSessionName,
-  resolveEncodedDirSession as resolveSession,
-} from './agents/scanUtils.js';
-export { projectsDir as defaultProjectsDir } from './agents/claude.js';
-
-// Parse `ps …` to LIVE Claude CLI procs only — the original Claude-specific helper, kept for the tests.
-// The general engine uses parseAgentProcs(psOut, AGENTS) directly.
-export function parseClaudeProcs(psOut) {
-  return parseAgentProcs(psOut, [getAgent('claude')]);
-}
-
-// Take over an orphan: spawn the agent's `resume <sessionId>` in a fresh tmux session (target.mode 'new')
-// or a new window of an existing session ('window'), so handmux can steer the continued conversation.
-// Everything is re-verified server-side — the client's pid/sessionId are inputs to a fresh scan, never
-// trusted directly. The original process is SIGTERM'd only AFTER the resumed agent is confirmed up
-// (foreground command is no longer the shell) AND re-confirmed still the same orphan (guards pid reuse):
-// `<agent> resume` appends to the SAME session file with no OS lock (verified for Claude), so two live
-// writers corrupt history — killing guarantees a single writer. Injectable deps make it unit-testable.
-export async function takeoverOrphan(
-  {
-    commands, scanFn = scanOrphans, scanOpts = {},
-    killProc = (pid, sig) => process.kill(pid, sig),
-    delay = (ms) => new Promise((r) => setTimeout(r, ms)),
-    pollTries = 16, pollMs = 400,
-  },
-  { pid, sessionId, target = { mode: 'new' }, kill = true, name: wantName } = {},
-) {
-  if (!Number.isInteger(pid) || pid <= 0) return { error: 'bad pid', status: 400 };
-  // Both agents use UUID session ids; validate up front (takeover types the id into a shell via send-keys).
-  if (!isSessionUuid(sessionId)) return { error: 'bad session id', status: 400 };
-
-  const o = (await scanFn(scanOpts)).find((x) => x.pid === pid);
-  if (!o) return { error: 'gone', status: 409 };            // no longer a live orphan
-  if (o.sessionId !== sessionId) return { error: 'session changed', status: 409 };
-  if (!o.cwd) return { error: 'no cwd', status: 409 };
-  const agent = getAgent(o.agent);
-  const cmd = agent.sessions.managedResumeCmd
-    ? agent.sessions.managedResumeCmd(sessionId)
-    : agent.sessions.resumeArgs(sessionId).join(' ');
-
-  let sid;
-  let wid;
-  let name; // the target session NAME — returned so the client can bind it into its session list
-  if (target.mode === 'window') {
-    if (!isSessionId(target.session)) return { error: 'bad target session', status: 400 };
-    sid = target.session;
-    name = (await commands.listSessions()).find((s) => s.id === sid)?.name || null;
-    wid = await commands.newWindow(sid, o.cwd, agent.procName, cmd);
-  } else {
-    const existing = new Set((await commands.listSessions()).map((s) => s.name));
-    // Honour a user-typed name (sanitized to tmux rules, deduped with a numeric suffix); fall back to the
-    // generated `<prefix>-<dir>-<n>` when the client sent nothing.
-    const wanted = sanitizeSessionName(wantName);
-    if (wanted) {
-      name = freeSessionName(wanted, existing);
-    } else {
-      for (let i = 1; i < 1000 && !name; i++) {
-        const cand = takeoverSessionName(o.cwdLabel, i, agent.takeoverPrefix);
-        if (!existing.has(cand)) name = cand;
-      }
-    }
-    if (!name) return { error: 'no free session name', status: 409 };
-    sid = await commands.newSession(name, o.cwd, cmd);
-    wid = (await commands.listWindows(sid))[0]?.id;
-  }
-
-  let up = false;
-  let pane = null;
-  for (let i = 0; i < pollTries && !up; i++) {
-    await delay(pollMs);
-    try {
-      const p = (await commands.listPanes(wid))[0];
-      if (p) { pane = p.id; if (!isShell(p.command)) up = true; }
-    } catch { /* window/pane not ready yet */ }
-  }
-
-  let killed = false;
-  if (kill && up) {
-    const still = (await scanFn(scanOpts)).find((x) => x.pid === pid && x.sessionId === sessionId);
-    if (still) { try { killProc(pid, 'SIGTERM'); killed = true; } catch { /* already exited */ } }
-  }
-  // claudeUp kept in the response for back-compat with the existing web client; agentUp is the neutral name.
-  return { session: sid, name, window: wid, pane, agentUp: up, claudeUp: up, killed, agent: agent.id };
-}
-
-// Scan the host for orphan agent sessions across every registered driver. Best-effort: any failing
-// sub-command degrades to fewer/no results rather than throwing. `projectsDir`/`sessionsDir` override a
-// specific agent's session dir (each driver declares which option key it reads — used by tests and the
-// server, which pin the dir off the resolved $HOME).
-export async function scanOrphans({
-  run = defaultRun, home = os.homedir(), busyMs = 8000, now = Date.now, agents = AGENTS, ...dirOverrides
-} = {}) {
-  const [psOut, tmuxOut] = await Promise.all([
-    run('ps', ['-Ao', 'pid=,ppid=,stat=,etime=,tty=,args=']),
-    run('tmux', ['list-panes', '-a', '-F', tmuxFormat(['pane_tty', 'pane_pid'])]),
-  ]);
-  const orphans = findOrphans(parseAgentProcs(psOut, agents), parsePaneMembership(tmuxOut));
-  const results = [];
-  for (const o of orphans) {
-    const agent = getAgent(o.agent);
-    const cwd = await lsofCwd(run, o.pid);
-    const dir = dirOverrides[agent.sessions.dirOptKey] || agent.sessions.dir(home);
-    const meta = cwd ? await agent.sessions.resolve(dir, cwd, { busyMs, now }) : {};
-    const cwdLabel = cwd ? path.basename(cwd) : '';
-    results.push({
-      pid: o.pid,
-      agent: agent.id,
-      agentLabel: agent.label,
-      cwd: cwd || '',
-      cwdLabel,
-      // Default name the takeover sheet prefills (the same `<prefix>-<dir>-1` the server would auto-pick).
-      suggestedName: takeoverSessionName(cwdLabel, 1, agent.takeoverPrefix),
-      sessionId: meta.sessionId || null,
-      state: meta.state || 'unknown',
-      snippet: meta.snippet || '',
-      lastActivity: meta.lastActivity || 0,
-      startedAt: o.etimeMs ? Math.round(now() - o.etimeMs) : 0,
-    });
-  }
-  return results;
-}

package/src/pendingPrompt.js

@@ -1,163 +0,0 @@
-// Parse a pending interactive PROMPT (an AskUserQuestion menu — single OR multi-question — or a tool-
-// permission menu) out of a Claude Code pane's `capture-pane` text. This is deliberately screen-scraping: a
-// pending prompt's options exist ONLY in the rendered TUI — they are NOT written to the session .jsonl until
-// AFTER the user answers (verified live), so the transcript can't be the source. Same approach amux/
-// VibeTunnel/Conductor use for the "attach to a running TUI" model; there is no structured channel short of
-// relaunching Claude via the SDK.
-//
-// Verified against a live Claude Code (2026-07-17):
-//
-//  SINGLE question / permission menu:            MULTI-question (tabbed):        REVIEW / submit screen:
-//    ☐ 颜色         ← header (optional)             ←  ☒ 水果  ☐ 颜色  ✔ Submit  →   ←  ☒ 水果  ☒ 颜色 ✔ Submit →
-//   你喜欢哪个?      ← question                      选个颜色?      ← current tab     Review your answers
-//   ❯ 1. 红色       ← ❯ marks the cursor            ❯ 1. 红                          ❯ 1. Submit answers
-//        热情、醒目   ← description (optional)          2. 蓝                            2. Cancel
-//     2. 蓝色                                       Enter to select · Tab/… · Esc    (NO footer line)
-//     4. Type something.  ← built-in meta (dropped)
-//   Enter to select · ↑/↓ to navigate · Esc to cancel
-//
-// Driving (verified live): sending the literal DIGIT of an option selects it. For a SINGLE question it
-// selects AND submits immediately; for MULTI it selects AND auto-advances to the next tab; on the review
-// screen digit 1 = "Submit answers". So the caller drives the whole flow by sending `String(option.n)` and
-// re-polling — each screen (Q1 → Q2 → review) is itself a parseable menu. Escape cancels.
-//
-// The parser ANCHORS on the ❯ cursor line, NOT a footer: the review screen has options but no footer.
-
-// Cursor-selected option line: ❯ (or ›»>) then "N.".
-const CURSOR_RE = /^\s*[❯›»>]\s*\d+\.\s/;
-// Any option row: optional cursor, then "N. label".
-const OPTION_RE = /^\s*[❯›»>]?\s*(\d+)\.\s+(.+?)\s*$/;
-// A description row: indented, not itself an option.
-const isDesc = (l) => /^\s{3,}\S/.test(l) && !OPTION_RE.test(l);
-// A horizontal rule Claude draws inside/around the card (kept within an option block so meta rows past it
-// are still seen and dropped).
-const RULE_RE = /^[\s─━—–\-_=·⎯]{8,}$/;
-// The multi-question tab strip: "←  ☒ 水果  ☐ 颜色  ✔ Submit  →".
-const TAB_BAR_RE = /✔\s*Submit|[☐☒].*[☐☒]/;
-// Claude's built-in trailing meta-options — not real answers.
-const META_LABELS = new Set(['type something', 'type something.', 'chat about this', 'chat about this.']);
-// Leading decoration on the header line.
-const HEADER_DECOR_RE = /^[\s☐☑☒◯●○·•\-*]+/;
-// A menu footer (single-question / permission), used only as a title boundary — NOT required to detect a menu.
-const FOOTER_RE = /enter to select|esc to (cancel|reject)/i;
-// A Claude activity/spinner line — the top edge of the card, above which is prior transcript.
-const ACTIVITY_RE = /^\s*[✻✳✶✽⏺]\s|worked for|cogitated|crafting|cooked for|crunched for|esc to interrupt/i;
-// The input cursor ❯ leading the user's echoed prompt (above the card).
-const PROMPT_ECHO_RE = /^\s*[❯›»>]\s*\D/; // ❯ NOT followed by a digit (that would be an option)
-const isTitleBoundary = (l) =>
-  ACTIVITY_RE.test(l) || RULE_RE.test(l) || TAB_BAR_RE.test(l) || FOOTER_RE.test(l) || PROMPT_ECHO_RE.test(l);
-
-const stripRight = (s) => String(s == null ? '' : s).replace(/\s+$/, '');
-// Strip ANSI/OSC escapes so a capture taken WITH `-e` (SGR) still parses — belt-and-suspenders even though
-// the endpoint captures plain.
-const stripAnsi = (s) => String(s || '').replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '').replace(/\x1b[[0-9;?]*[ -/]*[@-~]/g, '');
-
-// The assistant text immediately PRECEDING the menu, scraped because the turn (text + AskUserQuestion) is NOT
-// flushed to the session jsonl until AFTER the user answers (verified live: probe + out-of-order line
-// timestamps) — so the 对话 lens's transcript view structurally can't show it while the gate is up. The title
-// walk below stops at the first boundary (activity spinner / box rule / prompt echo), which is exactly where
-// the lead-in text usually sits. Walk on upward: skip boundary chrome, take the nearest content block, keep
-// its LAST lines (the freshest context, "问题的最后一行"). `fromIdx` = the first line NOT consumed by the
-// title walk, so adjacent lead-in the title already absorbed is never duplicated here.
-const LEADIN_MAX = 2;
-const MSG_MARK_RE = /^\s*⏺/; // ⏺ opens an assistant message in the scrollback — include it, stop there
-function extractLeadIn(lines, fromIdx) {
-  const block = [];
-  let i = fromIdx;
-  // Skip the chrome between the menu and the preceding text (spinner / rules / tab bar / stale footer /
-  // blanks) — but never past a ❯ prompt echo (above it is the PREVIOUS exchange, stale context) nor past a
-  // ⏺ message head (it IS the text's first line — the collect loop includes it).
-  while (i >= 0 && (!lines[i].trim() || (isTitleBoundary(lines[i]) && !PROMPT_ECHO_RE.test(lines[i]) && !MSG_MARK_RE.test(lines[i])))) i--;
-  for (; i >= 0 && block.length < 12; i--) {
-    const l = lines[i];
-    if (!l.trim()) break;                                        // blank = the block's top (last paragraph)
-    if (MSG_MARK_RE.test(l)) { block.unshift(l.trim()); break; } // the ⏺ message head: include & stop
-    if (isTitleBoundary(l)) break;                               // hard chrome (incl. ❯ echo): stop
-    block.unshift(l.trim());
-  }
-  const tail = block.slice(-LEADIN_MAX).map((l) => l.replace(/^⏺\s*/, '').trim()).filter(Boolean);
-  return tail.length ? tail.join(' ') : null;
-}
-
-// Parse the multi-question tab strip → [{ label, answered }]. ☒ = answered, ☐ = not. "✔ Submit" is excluded.
-function parseTabs(line) {
-  const tabs = [];
-  const re = /([☐☒])\s*(\S+)/g;
-  let m;
-  while ((m = re.exec(line))) tabs.push({ label: m[2], answered: m[1] === '☒' });
-  return tabs;
-}
-
-// capture-pane text → a normalized pending prompt, or null when no interactive menu is on screen.
-//   { kind:'question'|'permission', title, options:[{n,label,description}], cursor,
-//     multi, step, total, submit }
-// `n` is the digit to send to pick that option. For multi, `step`/`total` drive the "第 i/N 题" progress and
-// `submit` marks the final review screen (options are Submit answers / Cancel).
-export function parsePendingPrompt(text) {
-  const lines = stripAnsi(text).split('\n').map(stripRight);
-
-  // Anchor on the cursor-selected option (present in every menu: question, permission, review). Take the
-  // LAST one so stale menus higher in the scrollback are ignored — the live menu is at the bottom.
-  const anchor = lines.findLastIndex((l) => CURSOR_RE.test(l));
-  if (anchor < 0) return null;
-
-  // The option block = the contiguous run of option / description / rule lines around the anchor.
-  const inBlock = (l) => OPTION_RE.test(l) || isDesc(l) || RULE_RE.test(l);
-  let top = anchor;
-  let bot = anchor;
-  while (top - 1 >= 0 && inBlock(lines[top - 1])) top--;
-  while (bot + 1 < lines.length && inBlock(lines[bot + 1])) bot++;
-
-  const options = [];
-  let cursor = null;
-  for (let i = top; i <= bot; i++) {
-    const m = lines[i].match(OPTION_RE);
-    if (!m) continue;
-    const n = Number(m[1]);
-    const label = m[2].trim();
-    if (CURSOR_RE.test(lines[i])) cursor = n;
-    let description = '';
-    for (let j = i + 1; j <= bot; j++) {
-      if (OPTION_RE.test(lines[j])) break;
-      if (!isDesc(lines[j])) break;
-      description += (description ? ' ' : '') + lines[j].trim();
-    }
-    if (META_LABELS.has(label.toLowerCase())) continue; // drop Claude's built-in meta-options
-    options.push({ n, label, description });
-  }
-  if (!options.length) return null;
-
-  // Title = header/question text above the block, skipping in-card blanks, stopping at the card's top edge.
-  const head = [];
-  let headStop = top - 1;
-  for (let i = top - 1; i >= 0 && head.length < 5; i--) {
-    if (!lines[i].trim()) { headStop = i - 1; continue; }
-    if (isTitleBoundary(lines[i])) { headStop = i; break; }
-    head.unshift(lines[i]);
-    headStop = i - 1;
-  }
-  const title = head.map((l) => l.replace(HEADER_DECOR_RE, '').trim()).filter(Boolean).join(' — ') || '需要你选择';
-
-  // Multi-question: the tab strip drives progress. `answered` ☒ tabs → current step is the next unanswered.
-  const tabLine = lines.find((l) => TAB_BAR_RE.test(l));
-  const tabs = tabLine ? parseTabs(tabLine) : [];
-  const multi = tabs.length > 1;
-  const answered = tabs.filter((t) => t.answered).length;
-  const submit = /^submit answers?$/i.test(options[0].label) || (multi && answered >= tabs.length);
-
-  const kind = /do you want to proceed/i.test(title) || /^yes\b/i.test(options[0].label)
-    ? 'permission' : 'question';
-
-  const out = { kind, title, options, cursor };
-  // Lead-in context the title walk didn't absorb (it stopped at a boundary or its 5-line cap) — the
-  // assistant's last line(s) before the question, shown above the gate so the phone isn't asked blind.
-  const leadIn = extractLeadIn(lines, headStop);
-  if (leadIn) out.leadIn = leadIn;
-  if (multi) {
-    out.multi = true;
-    out.total = tabs.length;
-    out.step = Math.min(answered + 1, tabs.length);
-    out.submit = submit;
-  }
-  return out;
-}

package/src/previewServer.js

@@ -1,168 +0,0 @@
-// server/src/previewServer.js
-// Serves registered static-preview directories under a per-registration capability path. The main
-// Handmux token is never a preview credential. Absolute-rooted assets (/assets/...) are served from the
-// right preview dir via an authenticated Referer fallback (design's "方案 A").
-// Dynamic ports and arbitrary websites are handled by the built-in browser instead.
-import express from 'express';
-import { promises as fs } from 'node:fs';
-import path from 'node:path';
-import { tokenEquals } from './auth.js';
-function credentialOk(provided, token) {
-  if (!provided) return false;
-  try { return tokenEquals(provided, token); } catch { return false; }
-}
-
-// Resolve the on-disk file for a request path under a preview: '' or '<dir>/' → its index.html.
-function fileFor(rest) { return (!rest || rest.endsWith('/')) ? `${rest}index.html` : rest; }
-
-function previewHeaders(res) {
-  res.setHeader('Cache-Control', 'no-store');
-  res.setHeader('Referrer-Policy', 'same-origin');
-  res.setHeader('X-Content-Type-Options', 'nosniff');
-  // Keep preview code isolated even if its capability URL is opened outside the in-app iframe.
-  res.setHeader('Content-Security-Policy', 'sandbox allow-scripts allow-forms allow-downloads allow-modals allow-popups');
-  // A sandboxed static document intentionally has an opaque origin. Its capability path needs to remain
-  // readable by relative fetch(), module scripts, and fonts without restoring same-origin parent access.
-  res.setHeader('Access-Control-Allow-Origin', 'null');
-}
-
-function prefixedRoot(url, prefix) {
-  return url.startsWith('/') && !url.startsWith('//') ? `${prefix}${url.slice(1)}` : url;
-}
-
-function rewriteCssRoots(source, prefix) {
-  return source
-    .replace(/(url\(\s*["']?)\/(?!\/)/gi, `$1${prefix}`)
-    .replace(/(@import\s+["'])\/(?!\/)/gi, `$1${prefix}`);
-}
-
-function rewriteModuleRoots(source, prefix) {
-  return source.replace(
-    /(\b(?:from|import)\s*(?:\(\s*)?)(["'])\/(?!\/)/g,
-    `$1$2${prefix}`,
-  );
-}
-
-export function rewritePreviewText(source, extension, prefix) {
-  if (extension === '.css') return rewriteCssRoots(source, prefix);
-  if (extension === '.js' || extension === '.mjs') return rewriteModuleRoots(source, prefix);
-  if (extension !== '.html' && extension !== '.htm') return source;
-  let output = source.replace(
-    /(\b(?:src|href|action|poster|data|formaction)\s*=\s*)(["'])(\/[^"']*)\2/gi,
-    (_match, start, quote, url) => `${start}${quote}${prefixedRoot(url, prefix)}${quote}`,
-  );
-  output = output.replace(
-    /(\bsrcset\s*=\s*)(["'])([^"']*)\2/gi,
-    (_match, start, quote, value) => {
-      const rewritten = value.split(',').map((candidate) => {
-        const match = /^(\s*)(\S+)(.*)$/.exec(candidate);
-        return match ? `${match[1]}${prefixedRoot(match[2], prefix)}${match[3]}` : candidate;
-      }).join(',');
-      return `${start}${quote}${rewritten}${quote}`;
-    },
-  );
-  output = output.replace(
-    /(<style\b[^>]*>)([\s\S]*?)(<\/style>)/gi,
-    (_match, open, css, close) => `${open}${rewriteCssRoots(css, prefix)}${close}`,
-  );
-  output = output.replace(
-    /(\bstyle\s*=\s*)(["'])([^"']*)\2/gi,
-    (_match, start, quote, css) => `${start}${quote}${rewriteCssRoots(css, prefix)}${quote}`,
-  );
-  return output.replace(
-    /(<script\b[^>]*\btype\s*=\s*["']module["'][^>]*>)([\s\S]*?)(<\/script>)/gi,
-    (_match, open, script, close) => `${open}${rewriteModuleRoots(script, prefix)}${close}`,
-  );
-}
-
-export function createPreview({
-  previews,
-}) {
-  const router = express.Router();
-
-  function resolveEntry(name, accessToken, res) {
-    const { state, entry } = previews.get(name);
-    if (state === 'missing') return res.status(404).type('html').send('<!doctype html><meta charset="utf-8"><h1>预览不存在</h1>');
-    if (state === 'expired') return res.status(410).type('html').send('<!doctype html><meta charset="utf-8"><h1>预览已过期</h1><p>请回到 app 重新启动预览。</p>');
-    if (!credentialOk(accessToken, entry.accessToken)) return res.status(401).send('unauthorized');
-    return entry;
-  }
-
-  async function serve(entry, rest, prefix, res) {
-    previewHeaders(res);
-    const requested = fileFor(rest);
-    const segments = requested.split('/');
-    const target = path.resolve(entry.dir, requested);
-    const relative = path.relative(entry.dir, target);
-    if (!relative || relative.startsWith('..') || path.isAbsolute(relative)
-      || segments.some((segment) => segment.startsWith('.'))) {
-      if (!relative && requested === 'index.html') {
-        // The root index is the normal preview entry point.
-      } else {
-        res.status(404).end();
-        return;
-      }
-    }
-    const extension = path.extname(target).toLowerCase();
-    if (['.html', '.htm', '.css', '.js', '.mjs'].includes(extension)) {
-      try {
-        const source = await fs.readFile(target, 'utf8');
-        res.type(extension).send(rewritePreviewText(source, extension, prefix));
-      } catch (error) {
-        if (!res.headersSent) res.status(error?.code === 'ENOENT' ? 404 : 500).end();
-      }
-      return;
-    }
-    res.sendFile(requested, { root: entry.dir, dotfiles: 'deny' }, (err) => {
-      if (err && !res.headersSent) res.status(err.statusCode || 404).end();
-    });
-  }
-
-  // A name without its independent capability is never accepted, including the old ?token=<app-token>
-  // shape. Keeping this explicit makes the failure an authentication result instead of an SPA fallback.
-  router.get('/:name', (_req, res) => res.status(401).send('unauthorized'));
-  router.get('/:name/:accessToken', (req, res) => {
-    const entry = resolveEntry(req.params.name, req.params.accessToken, res);
-    if (!entry || res.headersSent) return;
-    const prefix = `/preview/${encodeURIComponent(req.params.name)}/${encodeURIComponent(req.params.accessToken)}/`;
-    if (!req.url.split('?')[0].endsWith('/')) {
-      return res.redirect(301, prefix);
-    }
-    return void serve(entry, '', prefix, res);
-  });
-  router.get('/:name/:accessToken/*', (req, res) => {
-    const entry = resolveEntry(req.params.name, req.params.accessToken, res);
-    if (!entry || res.headersSent) return;
-    const prefix = `/preview/${encodeURIComponent(req.params.name)}/${encodeURIComponent(req.params.accessToken)}/`;
-    void serve(entry, req.params[0], prefix, res);
-  });
-
-  // Referer fallback (mount AFTER /preview, BEFORE express.static): an absolute /assets/... request
-  // whose Referer is a preview page is served from that preview's dir. Reuses credOk so it can never
-  // read a dir without a valid token/cookie. Misses fall through to the normal static/SPA layer.
-  function refererFallback(req, res, next) {
-    if (req.method !== 'GET') return next();
-    if (req.path.startsWith('/api') || req.path.startsWith('/preview')) return next();
-    const ref = req.headers.referer;
-    if (!ref) return next();
-    let refPath;
-    try { refPath = new URL(ref).pathname; } catch { return next(); }
-    const m = /^\/preview\/([^/]+)\/([^/]+)\//.exec(refPath);
-    if (!m) return next();
-    let name;
-    let accessToken;
-    try {
-      name = decodeURIComponent(m[1]);
-      accessToken = decodeURIComponent(m[2]);
-    } catch { return next(); }
-    const { state, entry } = previews.get(name);
-    if (state !== 'active') return next();
-    if (!credentialOk(accessToken, entry.accessToken)) return next();
-    previewHeaders(res);
-    res.sendFile(req.path, { root: entry.dir, dotfiles: 'deny' }, (err) => {
-      if (err && !res.headersSent) next();
-    });
-  }
-
-  return { router, refererFallback };
-}

package/src/previews.js

@@ -1,116 +0,0 @@
-// server/src/previews.js
-// Preview registry. Maps a safe single-segment name to an on-disk directory under $HOME with a lease.
-// in-memory registry (loaded once at construction, flushed atomically on each mutation) — the previous
-// reload-and-write-back on every op was an unguarded read-modify-write that could lose an entry when a
-// GET's lease update raced a concurrent register(). Pure-ish: home/now/store/ttl are injected for tests.
-import fs from 'node:fs';
-import path from 'node:path';
-import { homedir } from 'node:os';
-import { randomBytes } from 'node:crypto';
-import { fileURLToPath } from 'node:url';
-import { isUnder } from './docPath.js';
-import { readJsonArray, writeJsonAtomic } from './jsonStore.js';
-
-export function safePreviewName(raw) {
-  if (typeof raw !== 'string') return null;
-  if (!/^[A-Za-z0-9._-]+$/.test(raw)) return null;
-  if (raw === '.' || raw === '..' || raw[0] === '.') return null;
-  // Keep lookups stable across clients that may normalize user-provided names differently.
-  return raw.toLowerCase();
-}
-
-export function createPreviews({
-  home = homedir(),
-  store = process.env.PREVIEW_STORE || path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../data/previews.json'),
-  now = () => Date.now(),
-  ttlMs = 2 * 60 * 60_000,
-  randomToken = () => randomBytes(24).toString('base64url'),
-} = {}) {
-  let realHome;
-  try { realHome = fs.realpathSync(home); } catch { realHome = home; }
-
-  // Loaded ONCE — this in-memory array is the source of truth; every op mutates it and flushes atomically.
-  let entries = readJsonArray(store);
-  let flushedExpiries = new Map(entries.map((entry) => [entry?.name, entry?.expiresAt]));
-  const flush = () => {
-    // Access tokens are runtime capabilities. Open device tabs re-register after a restart and receive
-    // a fresh token, so a stale registry file can never resurrect an old preview URL.
-    writeJsonAtomic(store, entries.map(({ accessToken: _accessToken, ...entry }) => entry));
-    flushedExpiries = new Map(entries.map((entry) => [entry?.name, entry?.expiresAt]));
-  };
-
-  const resultFor = (entry) => ({
-    name: entry.name,
-    kind: entry.kind,
-    accessToken: entry.accessToken,
-    expiresAt: entry.expiresAt,
-  });
-
-  // Re-registering the same active directory is a lease renewal. Preserve its capability so a
-  // foreground check does not change the iframe URL and reload an already-mounted page. A changed
-  // directory, expired row, or process-restored row without a runtime token receives a fresh one.
-  const upsert = (fields) => {
-    const ts = now();
-    const current = entries.find((entry) => entry && entry.name === fields.name);
-    if (current?.kind === fields.kind
-      && current.dir === fields.dir
-      && current.expiresAt > ts
-      && typeof current.accessToken === 'string'
-      && current.accessToken) {
-      current.expiresAt = ts + ttlMs;
-      flush();
-      return resultFor(current);
-    }
-    entries = entries.filter((e) => e && e.name !== fields.name);
-    const entry = {
-      ...fields,
-      accessToken: randomToken(),
-      createdAt: ts,
-      expiresAt: ts + ttlMs,
-    };
-    entries.push(entry);
-    flush();
-    return resultFor(entry);
-  };
-
-  async function register({ name, dir, port }) {
-    const nm = safePreviewName(name);
-    if (!nm) return { error: 'bad name', status: 400 };
-    if (port !== undefined && port !== null && port !== '') return { error: 'bad request', status: 400 };
-    if (typeof dir !== 'string' || dir[0] !== '/') return { error: 'not absolute', status: 400 };
-    let real;
-    try { real = fs.realpathSync(dir); } catch { return { error: 'not found', status: 404 }; }
-    if (!isUnder(real, realHome)) return { error: 'outside home', status: 400 };
-    let st;
-    try { st = fs.statSync(real); } catch { return { error: 'not accessible', status: 404 }; }
-    if (!st.isDirectory()) return { error: 'not a directory', status: 400 };
-    return upsert({ name: nm, kind: 'static', dir: real });
-  }
-
-  function get(name) {
-    const entry = entries.find((e) => e && e.name === name);
-    if (!entry) return { state: 'missing' };
-    const ts = now();
-    if (entry.expiresAt <= ts) { entries = entries.filter((e) => e.name !== name); flush(); return { state: 'expired' }; }
-    if (entry.kind === 'dynamic') { entries = entries.filter((e) => e.name !== name); flush(); return { state: 'missing' }; }
-    // Match proxy leases: actual page/resource traffic renews the lease. Throttle persistence so a page
-    // with many assets does not rewrite the registry once per request.
-    const nextExpiry = ts + ttlMs;
-    entry.expiresAt = nextExpiry;
-    if (nextExpiry - (flushedExpiries.get(entry.name) || 0) >= 60_000) flush();
-    return { state: 'active', entry: { kind: 'static', ...entry } }; // legacy rows (no kind) → static
-  }
-
-  function list() {
-    const active = entries.filter((e) => e && e.kind !== 'dynamic' && e.expiresAt > now());
-    if (active.length !== entries.length) { entries = active; flush(); }
-    return active.map((e) => ({ name: e.name, kind: 'static', dir: e.dir, expiresAt: e.expiresAt }));
-  }
-
-  function remove(name) {
-    const next = entries.filter((e) => e && e.name !== name);
-    if (next.length !== entries.length) { entries = next; flush(); }
-  }
-
-  return { register, get, list, remove };
-}