heyspex 0.1.0 → 0.2.1

package/scripts/hs-view.mjs

@@ -0,0 +1,496 @@
+#!/usr/bin/env node
+/**
+ * hs view <surface> [spec-id] — open ONE console surface in a chromeless
+ * app-mode browser window (the "solo surface" console gauge).
+ *
+ * Per [[HS-RU2R-I87U-RES-solo-surface-cli-launcher-single]]: launches
+ * Edge/Chrome with `--app=<url>` (NOT `--kiosk`, which forces fullscreen and
+ * ignores window sizing) pointed at the console's `/solo/<surface>` route.
+ * Probes ground-truth dev-server status first (same core as `hs server
+ * status`) so a down console yields a clear message, never a blank window.
+ *
+ * Open = run it; close = close the window; re-run = reopen (idempotent).
+ *
+ * Usage:
+ *   hs view                               # inspector, Pipeline tab, following the focus pin
+ *   hs view HLFJ                          # same, anchored on HS-HLFJ (any case, HS- optional)
+ *   hs view pipeline HS-I87U-CAP          # same — "pipeline" is the inspector's Pipeline tab
+ *   hs view inspector HS-I87U-CAP         # inspector on its default tab
+ *   hs view docs HS-NP1Y                  # doc + inspector Pipeline tab side by side
+ *   hs view pipeline --follow capture     # track the capture-on-deck pin
+ *   hs view pipeline --follow capture --url https://console.example.com
+ *   hs view pipeline --width 510 --height 900 --browser edge|chrome
+ */
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { getDevServerStatus } from './dev-server-status.mjs';
+import { resolveConsoleUrl, DEFAULT_CONSOLE_URL } from './lib/console-url-resolver.mjs';
+// The runnable form of a HeySpex command on THIS machine — `hs …` when the bin
+// is on PATH, else an absolute-path `node "<install>/bin/hs.mjs" …`. Never an
+// `npx` form: npx resolves from the READER's working directory, and outside a
+// checkout `npx hs` installs the unrelated public package hs@2.0.1
+// ([[HS-I6HT-EKYU-DIAG-every-message-tells-the-user-to-run-hs]]).
+import { hsCommand } from './lib/hs-command.mjs';
+import {
+  complementarySide,
+  computeWindowPlacement,
+  getPrimaryWorkArea,
+  parsePlaceSide,
+  placementFlags,
+} from './lib/window-placement.mjs';
+import { collectOccupiedFamilyKeysFromVault, parseSpecId } from '../vendor/heyspex-mcp/spec-id-lib.mjs';
+
+function defaultVaultRoot() {
+  // This file lives at <vaultRoot>/scripts/, so one level up is the root.
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+}
+
+/** Levenshtein edit distance — small local helper, no dependency pulled in for it. */
+function editDistance(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, (_, i) => [i, ...Array(n).fill(0)]);
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] =
+        a[i - 1] === b[j - 1]
+          ? dp[i - 1][j - 1]
+          : 1 + Math.min(dp[i - 1][j - 1], dp[i - 1][j], dp[i][j - 1]);
+    }
+  }
+  return dp[m][n];
+}
+
+/**
+ * Nearest occupied family keys to a typo'd spec token — walks the vault
+ * (fresh every call, unlike `.heyspex/vault-index.json`) via the shared
+ * spec-id-lib helper, never re-implements the vault scan.
+ */
+function suggestFamilyKeys(rawSpec, vaultRoot, limit = 5) {
+  const parsed = parseSpecId(rawSpec);
+  const needle = (parsed?.familyKey ?? rawSpec.replace(/^HS-/i, '')).toUpperCase();
+  const occupied = [...collectOccupiedFamilyKeysFromVault(vaultRoot)];
+  return occupied
+    .map((key) => ({ key, dist: editDistance(needle, key) }))
+    .sort((x, y) => x.dist - y.dist || x.key.localeCompare(y.key))
+    .slice(0, limit)
+    .filter((c) => c.dist <= Math.max(2, Math.ceil(needle.length / 2)))
+    .map((c) => `HS-${c.key}`);
+}
+
+/**
+ * Resolve a spec id/token against the running console before opening a
+ * browser window (same resolution rules as `GET /api/specs/:id`, including
+ * its bare-family-token prefix fallback). Returns `{ ok: true }`,
+ * `{ ok: false, kind: 'ambiguous', candidates }`, or
+ * `{ ok: false, kind: 'not_found', suggestions }`.
+ */
+async function resolveSpec(base, rawSpec, vaultRoot) {
+  let res;
+  try {
+    res = await fetch(`${base}/api/specs/${encodeURIComponent(rawSpec)}`);
+  } catch (err) {
+    // Network hiccup against a console we already confirmed is up — don't
+    // block the window on it, just open unvalidated.
+    return { ok: true, skipped: true, reason: err?.message || String(err) };
+  }
+  if (res.ok) return { ok: true };
+  let body = null;
+  try {
+    body = await res.json();
+  } catch {
+    // non-JSON error body — fall through to generic not_found handling
+  }
+  if (res.status === 404 && body?.error === 'ambiguous_id' && Array.isArray(body.candidates)) {
+    return { ok: false, kind: 'ambiguous', candidates: body.candidates };
+  }
+  if (res.status !== 404) {
+    // Not a verdict on the spec — a hosted console answers an unauthenticated
+    // probe with a sign-in redirect or a 401/403. Open unvalidated rather than
+    // claiming the doc does not exist.
+    return { ok: true, skipped: true, reason: `HTTP ${res.status}` };
+  }
+  return { ok: false, kind: 'not_found', suggestions: suggestFamilyKeys(rawSpec, vaultRoot) };
+}
+
+/**
+ * The solo surfaces `/solo/<surface>` mounts — mirror of the registry in
+ * spex-console/src/app/solo/[surface]/page.tsx. A first positional that is not
+ * one of these is read as a spec id, opened on the pipeline surface.
+ */
+export const SOLO_SURFACES = new Set([
+  'pipeline',
+  'docs',
+  'inspector',
+  'whats-next',
+  'captures',
+  'session-log',
+  'settings',
+]);
+
+/**
+ * The view a bare `hs view` / `hs view <spec-id>` opens. There is no
+ * standalone pipeline window: the inspector already carries the Pipeline tab,
+ * so "pipeline" resolves to the inspector opened on that tab (owner ruling
+ * 2026-10-10) — see {@link INSPECTOR_TAB_ALIASES}.
+ */
+export const DEFAULT_SPEC_SURFACE = 'pipeline';
+
+/**
+ * Surface words that are really an inspector tab. `hs view pipeline <id>` and
+ * every older caller still work — they land on the inspector, that tab open.
+ */
+export const INSPECTOR_TAB_ALIASES = { pipeline: 'pipeline' };
+
+/**
+ * Canonicalise a typed spec token: `hlfj`, `hs-hlfj` and `HS-HLFJ` all become
+ * `HS-HLFJ`. A missing `HS-` prefix is added (the console's family-token
+ * fallback only matches `HS-<token>-…` prefixes, so a bare `hlfj` found
+ * nothing). Only a short key form (`HLFJ`, `HLFJ-AB12`, `HLFJ-TASK`) is
+ * upper-cased; a full basename keeps its lower-case slug so it still matches
+ * exactly.
+ */
+export function normalizeSpecToken(raw) {
+  const token = String(raw ?? '').trim();
+  if (!token) return token;
+  const body = token.replace(/^hs-/i, '');
+  if (/^[a-z0-9]{4}(?:-[a-z0-9]{2,8}){0,2}$/i.test(body)) return `HS-${body.toUpperCase()}`;
+  return `HS-${body}`;
+}
+
+/**
+ * Split positionals into `{ surface, panel, spec }`. `hs view <surface> [spec]`
+ * keeps its surface; `hs view <spec>` and bare `hs view` open the inspector on
+ * its Pipeline tab, as does the `pipeline` word. The spec token is normalised.
+ */
+export function resolveSurfaceAndSpec(positionals) {
+  let [surface = null, spec = null] = positionals;
+  if (surface && !SOLO_SURFACES.has(surface.toLowerCase()) && !spec) {
+    spec = surface;
+    surface = null;
+  }
+  surface = (surface ?? DEFAULT_SPEC_SURFACE).toLowerCase();
+  let panel = null;
+  if (INSPECTOR_TAB_ALIASES[surface]) {
+    panel = INSPECTOR_TAB_ALIASES[surface];
+    surface = 'inspector';
+  }
+  return { surface, panel, spec: spec ? normalizeSpecToken(spec) : null };
+}
+
+/** Anchor sources the window can follow live. `pin` is the default behavior. */
+const FOLLOW_MODES = new Set(['pin', 'capture']);
+
+/** Opening width for a surface with nothing better to say. */
+export const DEFAULT_WINDOW_WIDTH = 510;
+
+/**
+ * Surfaces that want a different opening width than the default.
+ *
+ * `inspector` is one narrow pane meant to sit beside a terminal — at 510 it
+ * takes screen it does not need. It opens at 350 and grows leftward to the
+ * `docs` width when a doc pane opens
+ * ([[HS-I2YN-ST07-EPIC-two-pane-layout-pipeline-view-on-the]]).
+ */
+export const SURFACE_WINDOW_WIDTH = {
+  inspector: 350,
+  // Two panes: the doc, then the inspector rail (360) to its right.
+  docs: 960,
+};
+
+/**
+ * Resolve the window width: an explicit `--width` always wins, otherwise the
+ * surface's own default, otherwise {@link DEFAULT_WINDOW_WIDTH}.
+ *
+ * `explicitWidth` is null/undefined when the flag was not passed. Deciding that
+ * by COMPARING against the fallback would silently drop `--width 510` on the
+ * inspector back to 350, so the caller tracks "was it passed" instead.
+ */
+export function resolveWindowWidth(surface, explicitWidth) {
+  if (typeof explicitWidth === 'number' && Number.isFinite(explicitWidth) && explicitWidth > 0) {
+    return explicitWidth;
+  }
+  return SURFACE_WINDOW_WIDTH[surface] ?? DEFAULT_WINDOW_WIDTH;
+}
+
+/**
+ * Which half of the primary monitor's work area the window takes.
+ *
+ * Explicit `--place` wins, then `HEYSPEX_VIEW_PLACE`, then the default: the
+ * two-pane capture view (`docs --follow capture`) sits on the RIGHT so the
+ * SpexCode agent window can take the left
+ * ([[HS-I2YN-ST07-EPIC-two-pane-layout-pipeline-view-on-the]]). Every other
+ * window keeps the OS's own placement (`none`), as before.
+ */
+export function resolvePlaceSide({ place, surface, follow }, env = process.env) {
+  const explicit = parsePlaceSide(place);
+  if (explicit) return explicit;
+  const fromEnv = parsePlaceSide(env.HEYSPEX_VIEW_PLACE);
+  if (fromEnv) return fromEnv;
+  return surface === 'docs' && follow === 'capture' ? 'right' : 'none';
+}
+
+/** The side the paired agent (terminal) window should take for this view. */
+export const agentSideFor = (viewSide) => complementarySide(viewSide);
+
+function parseArgs(argv) {
+  const args = {
+    place: null,
+    printOnly: false,
+    surface: null,
+    spec: null,
+    // null until `--width` is seen; resolved per-surface once the surface is known.
+    width: null,
+    height: 900,
+    browser: 'edge',
+    follow: null,
+    url: null,
+  };
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') return { help: true };
+    if (a === '--width') { args.width = Number(argv[++i]) || args.width; continue; }
+    if (a === '--height') { args.height = Number(argv[++i]) || args.height; args.heightExplicit = true; continue; }
+    if (a === '--place') {
+      const side = parsePlaceSide(argv[++i]);
+      if (!side) {
+        process.stderr.write('hs view: --place expects left, right or none\n');
+        process.exitCode = 2;
+        return { help: true };
+      }
+      args.place = side;
+      continue;
+    }
+    if (a === '--print' || a === '--dry-run') { args.printOnly = true; continue; }
+    if (a === '--browser') { args.browser = String(argv[++i] || 'edge'); continue; }
+    if (a === '--url') {
+      const raw = String(argv[++i] || '').trim();
+      if (!/^https?:\/\/\S+$/.test(raw)) {
+        process.stderr.write(`hs view: --url expects an http(s) URL (got "${raw || '(nothing)'}")\n`);
+        process.exitCode = 2;
+        return { help: true };
+      }
+      args.url = raw.replace(/\/+$/, '');
+      continue;
+    }
+    if (a === '--follow') {
+      const mode = String(argv[++i] || '').trim().toLowerCase();
+      if (!FOLLOW_MODES.has(mode)) {
+        process.stderr.write(
+          `hs view: --follow expects ${[...FOLLOW_MODES].join(' or ')} (got "${mode || '(nothing)'}")\n`,
+        );
+        process.exitCode = 2;
+        return { help: true };
+      }
+      args.follow = mode;
+      continue;
+    }
+    if (a.startsWith('--')) {
+      process.stderr.write(`hs view: unknown flag ${a}\n`);
+      process.exitCode = 2;
+      return { help: true };
+    }
+    positionals.push(a);
+  }
+  return { ...args, ...resolveSurfaceAndSpec(positionals) };
+}
+
+function usage() {
+  process.stdout.write(
+    [
+      'hs view <surface> [spec-id] [--follow pin|capture] [--url https://…]',
+      '                                [--width N] [--height N] [--browser edge|chrome]',
+      '                                [--place left|right|none] [--print]',
+      'hs view [spec-id]                 # inspector on its Pipeline tab',
+      '',
+      'Open one console surface in a chromeless app-mode browser window.',
+      'Surfaces: inspector, docs, whats-next, captures, session-log, settings',
+      '  ("pipeline" = the inspector opened on its Pipeline tab; there is no',
+      '  standalone pipeline window.)',
+      '  (registry: src/app/solo/[surface]/page.tsx).',
+      'Spec ids are forgiving: hlfj, hs-hlfj and HS-HLFJ are the same spec.',
+      'Without a spec-id the inspector and docs views follow the focus pin live.',
+      '--follow capture tracks the capture-on-deck pin instead, so the window',
+      '  re-anchors itself onto each new capture rather than opening another.',
+      '--url opens against a named console (a hosted one) instead of probing for',
+      '  a local dev server — the cloud-relay path the desktop companion uses.',
+      '--place pins the window to the left or right half of the primary monitor',
+      '  work area (taskbar excluded; never another monitor). Default: right for',
+      '  `docs --follow capture` (the two-pane capture view, leaving the left half',
+      '  for the SpexCode agent window), none otherwise. Env: HEYSPEX_VIEW_PLACE.',
+      '--print shows the browser command line and does not open a window.',
+      '',
+    ].join('\n'),
+  );
+}
+
+/**
+ * Only a localhost/loopback resolution still requires a running local dev
+ * server; anything else (a paired or `hs dev mode:cloud` hosted console) is
+ * opened directly. An unparseable URL is treated as local so it still goes
+ * through the dev-server probe instead of being launched blind.
+ */
+function isLocalConsoleUrl(url) {
+  try {
+    const host = new URL(url).hostname;
+    return host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '[::1]';
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * The exact command line a launch would run, as `{ file, args }`. Pure, so
+ * `--print` and the tests see precisely what `launchAppWindow` spawns.
+ */
+export function buildLaunchCommand(url, { width, height, browser }, placement = null, platform = process.platform) {
+  const exe = browser === 'chrome' ? 'chrome' : 'msedge';
+  const flags = [`--app=${url}`, ...(placement ? placementFlags(placement) : [`--window-size=${width},${height}`])];
+  if (platform === 'win32') return { file: 'cmd.exe', args: ['/c', 'start', '', exe, ...flags] };
+  if (platform === 'darwin') {
+    const app = browser === 'chrome' ? 'Google Chrome' : 'Microsoft Edge';
+    return { file: 'open', args: ['-na', app, '--args', ...flags] };
+  }
+  return { file: browser === 'chrome' ? 'google-chrome' : 'microsoft-edge', args: flags };
+}
+
+function launchAppWindow(url, opts, placement = null) {
+  const { width, height, browser } = opts;
+  const exe = browser === 'chrome' ? 'chrome' : 'msedge';
+  const flags = [`--app=${url}`, ...(placement ? placementFlags(placement) : [`--window-size=${width},${height}`])];
+  let child;
+  if (process.platform === 'win32') {
+    // `start` resolves msedge/chrome via the App Paths registry; the empty ''
+    // is start's window-title slot, without it the exe would be eaten as title.
+    child = spawn('cmd.exe', ['/c', 'start', '', exe, ...flags], {
+      detached: true,
+      stdio: 'ignore',
+    });
+  } else if (process.platform === 'darwin') {
+    const app = browser === 'chrome' ? 'Google Chrome' : 'Microsoft Edge';
+    child = spawn('open', ['-na', app, '--args', ...flags], { detached: true, stdio: 'ignore' });
+  } else {
+    const bin = browser === 'chrome' ? 'google-chrome' : 'microsoft-edge';
+    child = spawn(bin, flags, { detached: true, stdio: 'ignore' });
+  }
+  child.unref();
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    usage();
+    return;
+  }
+
+  // Now that the surface is known, settle the width: an explicit `--width`
+  // stands, otherwise the surface's own opening width.
+  args.width = resolveWindowWidth(args.surface, args.width);
+
+  // `--url` names the console explicitly — the cloud-relay path, where the
+  // companion opens a window against the hosted console it is paired with and
+  // there is no local dev server to probe. Without it, the machine's own
+  // console resolution decides: `hs dev mode:cloud` / `hs mcp pair` stamp a
+  // hosted URL into ~/.heyspex/credentials.yaml, and a non-local resolution
+  // needs no dev server either. Only a localhost resolution keeps the old
+  // behavior of requiring (and probing for) a running local console.
+  const vaultRoot = process.env.HS_VAULT_ROOT || defaultVaultRoot();
+  let base = args.url;
+  if (!base) {
+    const resolved = resolveConsoleUrl({ repoRoot: vaultRoot });
+    if (!isLocalConsoleUrl(resolved)) {
+      base = resolved.replace(/\/+$/, '');
+    } else {
+      const status = await getDevServerStatus({ vaultRoot: process.env.HS_VAULT_ROOT });
+      if (!status.running) {
+        process.stderr.write(
+          'hs view: this machine points at a local console but no spex-console dev server is running.\n' +
+            '  Start it first (npm run dev), then re-run this command.\n' +
+            `  (Meant the hosted console? Run \`${hsCommand('dev mode:cloud')}\`, or pass --url https://…)\n`,
+        );
+        process.exitCode = 1;
+        return;
+      }
+      const consoleServer = (status.servers || []).find((s) => s.probe === 'console');
+      base = (consoleServer?.url || DEFAULT_CONSOLE_URL).replace(/\/+$/, '');
+    }
+  }
+
+  if (args.spec) {
+    const resolution = await resolveSpec(base, args.spec, vaultRoot);
+    if (!resolution.ok) {
+      if (resolution.kind === 'ambiguous') {
+        process.stderr.write(
+          `hs view: "${args.spec}" is ambiguous — it matches more than one spec:\n` +
+            resolution.candidates.map((c) => `  ${c}\n`).join('') +
+            'Pass the full basename to disambiguate.\n',
+        );
+      } else {
+        process.stderr.write(`hs view: no spec found for "${args.spec}".\n`);
+        if (resolution.suggestions.length) {
+          process.stderr.write(
+            'Did you mean:\n' + resolution.suggestions.map((s) => `  ${s}\n`).join(''),
+          );
+        }
+      }
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  // A fixed `?spec=` wins over any follow mode (both here and in the route),
+  // so only send `follow` when there is no fixed anchor to override it.
+  const params = new URLSearchParams();
+  if (args.spec) params.set('spec', args.spec);
+  else if (args.follow) params.set('follow', args.follow);
+  if (args.panel) params.set('panel', args.panel);
+  const search = params.toString();
+  const query = search ? `?${search}` : '';
+  const url = `${base}/solo/${encodeURIComponent(args.surface)}${query}`;
+
+  // Placement is best-effort: no work area (non-Windows, probe failure) means
+  // no position flags and today's behavior.
+  const side = resolvePlaceSide(args);
+  const placement =
+    side === 'none'
+      ? null
+      : computeWindowPlacement({
+          workArea: getPrimaryWorkArea(),
+          side,
+          width: args.width,
+          // Full work-area height unless --height was passed.
+          height: args.heightExplicit ? args.height : undefined,
+        });
+
+  if (args.printOnly) {
+    const cmd = buildLaunchCommand(url, args, placement);
+    process.stdout.write(
+      `hs view (--print, nothing opened): place=${side}${placement ? '' : ' (no placement)'}\n` +
+        `  ${cmd.file} ${cmd.args.join(' ')}\n` +
+        (placement ? `  agent window should take: ${agentSideFor(side)}\n` : ''),
+    );
+    return;
+  }
+
+  launchAppWindow(url, args, placement);
+  const size = placement
+    ? `${placement.width}x${placement.height} at ${placement.x},${placement.y}`
+    : `${args.width}x${args.height}`;
+  process.stdout.write(
+    `hs view: opened ${url} in an app-mode ${args.browser === 'chrome' ? 'Chrome' : 'Edge'} window ` +
+      `(${size}). Close the window to close; re-run to reopen.\n`,
+  );
+}
+
+// Run only as the CLI entry point. Without this guard, importing the module —
+// which is how `resolveWindowWidth` is tested — would spawn a browser window.
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  main().catch((err) => {
+    process.stderr.write(`hs view: ${err?.message || err}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/hs-worktree.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+// scripts/hs-worktree.mjs — `hs worktree list|alloc|release|reap|rebind`.
+// Task: HS-V9XH (epic HS-03DO "Claim-bound worktree isolation for parallel agent
+// sessions"). Thin shell: parse argv (scripts/lib/hs-worktree-args.mjs), then call
+// dev-factory/lib/worktree-allocator.mjs's exported functions IN-PROCESS — never
+// shells out to the allocator's own CLI mode, so there is exactly one process per
+// invocation and JSON output never has to round-trip through a child's stdout.
+//
+// Exit codes:
+//   0  ok
+//   1  usage (unknown verb/flag — from the parser)
+//   2  check-failed — ONLY `reap --expect-removed` that removed nothing
+//   11 bad-arg (missing required flag / value-flag with no value — from the parser)
+//   13 write-failed (the allocator threw on a git/fs write — alloc or rebind)
+
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+import { parseWorktreeArgs } from "./lib/hs-worktree-args.mjs";
+import {
+  makeCtx,
+  DEFAULT_DEPS,
+  keyInfoFor,
+  worktreePathFor,
+  allocateForClaim,
+  markReleased,
+  rebind,
+  listWorktrees,
+  reapWorktrees,
+} from "../dev-factory/lib/worktree-allocator.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, "..");
+
+const EXIT_OK = 0;
+const EXIT_CHECK_FAILED = 2;
+const EXIT_WRITE_FAILED = 13;
+
+// ── human-output formatting ─────────────────────────────────────────────────
+
+function formatAge(ms) {
+  if (ms == null || !Number.isFinite(ms) || ms < 0) return "-";
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h`;
+  const d = Math.floor(h / 24);
+  return `${d}d`;
+}
+
+function formatPid(pid, alive) {
+  if (pid == null) return "-";
+  return `${pid}(${alive ? "alive" : "dead"})`;
+}
+
+function renderTable(rows) {
+  const headers = ["PATH", "BRANCH", "KIND", "SPEC", "SESSION", "PID", "AGE", "DIRTY", "RELEASED"];
+  const data = rows.map((w) => [
+    w.path,
+    w.branch || "(detached)",
+    w.kind,
+    w.specId || "-",
+    w.sessionId || "-",
+    formatPid(w.pid, w.pidAlive),
+    formatAge(w.ageMs),
+    w.dirtyCount == null ? "?" : String(w.dirtyCount),
+    w.releasedAt ? "yes" : "-",
+  ]);
+  const widths = headers.map((h, i) => Math.max(h.length, ...data.map((r) => String(r[i]).length)));
+  const line = (cols) => cols.map((c, i) => String(c).padEnd(widths[i])).join("  ").trimEnd();
+  return [line(headers), ...data.map(line)];
+}
+
+// ── agent identity ──────────────────────────────────────────────────────────
+
+/**
+ * Session id default per task brief: env only, never the MCP's fuller
+ * detectAgentIdentity precedence (Cursor/CI vars, etc) — a --session flag
+ * always wins.
+ */
+function resolveSessionId(flags) {
+  return (
+    flags.session
+    || process.env.CLAUDE_CODE_SESSION_ID
+    || process.env.HEYSPEX_SESSION_ID
+    || "cli"
+  );
+}
+
+/**
+ * Agent default per task brief: the same detection the MCP uses
+ * (vendor/heyspex-mcp/mcp-config.mjs detectAgentIdentity) when it is
+ * trivially importable, else HEYSPEX_AGENT env or "cli". A --agent flag
+ * always wins over both.
+ */
+async function resolveAgent(flags, sessionId) {
+  if (flags.agent) return flags.agent;
+  try {
+    const mod = await import("../vendor/heyspex-mcp/mcp-config.mjs");
+    if (typeof mod.detectAgentIdentity === "function") {
+      const identity = mod.detectAgentIdentity(undefined, sessionId);
+      if (identity?.agent) return identity.agent;
+    }
+  } catch {
+    // Not importable in this install shape (e.g. a published package without
+    // vendor/heyspex-mcp) — fall back below.
+  }
+  return process.env.HEYSPEX_AGENT || "cli";
+}
+
+// ── main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const parsed = parseWorktreeArgs(process.argv.slice(2));
+  if (!parsed.ok) {
+    process.stderr.write(`hs worktree: ${parsed.message}\n`);
+    process.exitCode = parsed.code;
+    return;
+  }
+  const { verb, flags } = parsed;
+  const ctx = makeCtx({ repo: REPO_ROOT, worktreeRoot: flags.root || undefined });
+
+  const emit = (obj, lines) => {
+    if (flags.json) process.stdout.write(`${JSON.stringify(obj, null, 2)}\n`);
+    else for (const l of lines) process.stdout.write(`${l}\n`);
+  };
+
+  if (verb === "list") {
+    const worktrees = listWorktrees(ctx);
+    emit({ worktrees }, renderTable(worktrees));
+    process.exitCode = EXIT_OK;
+    return;
+  }
+
+  if (verb === "alloc") {
+    const info = keyInfoFor(flags.spec);
+    if (flags.dryRun) {
+      const wtPath = worktreePathFor(ctx, flags.spec);
+      const baseSha = (DEFAULT_DEPS.git(ctx, ctx.repo, "rev-parse", "HEAD").stdout || "").trim() || null;
+      emit(
+        { dryRun: true, path: wtPath, branch: info.branch, baseSha },
+        [`would allocate ${wtPath} on ${info.branch} from ${baseSha ?? "(unknown)"}`],
+      );
+      process.exitCode = EXIT_OK;
+      return;
+    }
+    const sessionId = resolveSessionId(flags);
+    const agent = await resolveAgent(flags, sessionId);
+    try {
+      const r = allocateForClaim(ctx, { specId: flags.spec, sessionId, agent, pid: process.pid });
+      emit(r, [`${r.created ? "allocated" : "re-attached"} ${r.path} on ${r.branch}`]);
+      process.exitCode = EXIT_OK;
+    } catch (e) {
+      process.stderr.write(`hs worktree alloc: ${e.message}\n`);
+      process.exitCode = EXIT_WRITE_FAILED;
+    }
+    return;
+  }
+
+  if (verb === "release") {
+    const r = markReleased(ctx, { specId: flags.spec });
+    emit(r, [
+      r.found
+        ? `${r.alreadyReleased ? "already released" : "released"} ${worktreePathFor(ctx, flags.spec)}`
+        : `no worktree for ${flags.spec}`,
+    ]);
+    process.exitCode = EXIT_OK;
+    return;
+  }
+
+  if (verb === "rebind") {
+    try {
+      const r = rebind(ctx, { fromSpecId: flags.spec, toSpecId: flags.to });
+      emit(r, [r.found ? `rebound ${flags.spec} -> ${flags.to} on ${r.branch}` : `no worktree for ${flags.spec}`]);
+      process.exitCode = EXIT_OK;
+    } catch (e) {
+      process.stderr.write(`hs worktree rebind: ${e.message}\n`);
+      process.exitCode = EXIT_WRITE_FAILED;
+    }
+    return;
+  }
+
+  // reap
+  const r = await reapWorktrees(ctx, {
+    dryRun: flags.dryRun,
+    includeForeign: flags.includeForeign,
+    yes: flags.yes,
+  });
+  emit(r, [
+    `${r.dryRun ? "would remove" : "removed"} ${r.removed.length}: ${r.removed.join(", ") || "(none)"}`,
+    ...r.skipped.map((s) => `  skipped ${s.path} - ${s.reason}`),
+  ]);
+  process.exitCode = flags.expectRemoved && r.removed.length === 0 ? EXIT_CHECK_FAILED : EXIT_OK;
+}
+
+main().catch((err) => {
+  process.stderr.write(`hs worktree: ${err?.stack ?? err}\n`);
+  process.exitCode = 1;
+});