@luanpdd/kit-mcp 1.0.0 → 1.2.0

package/src/cli/render.js

@@ -0,0 +1,187 @@
+// Human-readable renderers for each CLI subcommand. The CLI default switched
+// from JSON-to-stdout to these in v1.1; --json restores the old behavior
+// (still useful for piping to jq, MCP-like consumers, etc.).
+//
+// Conventions:
+//   - Render functions write to process.stdout (no trailing newline beyond
+//     what the formatted output naturally has).
+//   - They never throw on missing fields — the result objects come from
+//     core/ which already shape them.
+//   - Cores happen via src/core/ui.js (which already disables in NO_COLOR
+//     or when --no-tty etc.).
+
+import path from 'node:path';
+import { c, icons, summary } from '../core/ui.js';
+
+// --- generic helpers ---
+
+function table(rows, headers) {
+  if (rows.length === 0) {
+    return `${c.dim('(empty)')}\n`;
+  }
+  const cols = headers.length;
+  const widths = new Array(cols).fill(0);
+  for (let i = 0; i < cols; i++) widths[i] = Math.max(headers[i].length, ...rows.map(r => String(r[i] ?? '').length));
+  const out = [];
+  out.push(headers.map((h, i) => c.bold(h.padEnd(widths[i]))).join('  '));
+  out.push(headers.map((_, i) => c.dim('─'.repeat(widths[i]))).join('  '));
+  for (const r of rows) {
+    out.push(r.map((v, i) => String(v ?? '').padEnd(widths[i])).join('  '));
+  }
+  return out.join('\n') + '\n';
+}
+
+// --- kit ---
+
+export function renderKitList(items, kind) {
+  if (items.length === 0) {
+    return `${c.dim(`No ${kind}s in kit.`)}\n`;
+  }
+  const rows = items.map(x => [x.name, (x.description ?? '').slice(0, 80)]);
+  return table(rows, ['name', 'description']);
+}
+
+export function renderKitSearch(results) {
+  if (results.length === 0) {
+    return `${c.dim('No matches.')}\n`;
+  }
+  const rows = results.map(x => [x.kind, x.name, (x.description ?? '').slice(0, 70)]);
+  return table(rows, ['kind', 'name', 'description']);
+}
+
+// --- sync ---
+
+export function renderSyncTargets(targets) {
+  const rows = targets.map(t => [
+    t.id,
+    t.label,
+    Object.entries(t.capabilities).filter(([, v]) => v).map(([k]) => k).join(', '),
+  ]);
+  return table(rows, ['id', 'label', 'capabilities']);
+}
+
+export function renderSyncStatus(result) {
+  const rows = result.checks.map(c => [c.capability, c.path, c.exists ? '✓' : '—']);
+  return `${c.bold(`Status: ${result.target}`)}  ${c.dim(result.projectRoot)}\n` + table(rows, ['cap', 'path', 'present']);
+}
+
+export function renderSyncInstall(result) {
+  // Tally written paths by capability prefix
+  const counts = {};
+  for (const p of result.written) {
+    const rel = path.relative(result.projectRoot, p).replace(/\\/g, '/');
+    // Hide internal markers from the user-facing tally (they're a kit-mcp impl detail)
+    if (rel.endsWith('/.kit-mcp-managed')) continue;
+    let cap = 'rules';
+    if (rel.includes('.claude/agents/'))    cap = 'agents';
+    else if (rel.includes('.claude/commands/'))  cap = 'commands';
+    else if (rel.includes('.claude/skills/'))    cap = 'skills';
+    else if (rel.includes('.claude/framework/')) cap = 'framework';
+    else if (rel.includes('.claude/hooks/'))     cap = 'hooks';
+    counts[cap] = (counts[cap] ?? 0) + 1;
+  }
+  const rows = [];
+  for (const cap of ['rules', 'agents', 'commands', 'skills', 'framework', 'hooks']) {
+    if (counts[cap] !== undefined) rows.push([cap, counts[cap]]);
+  }
+  const visibleTotal = Object.values(counts).reduce((a, b) => a + b, 0);
+  return summary({
+    title: `Synced kit → ${result.target}${result.dryRun ? ' (dry-run)' : ''}`,
+    rows,
+    total: visibleTotal,
+    hint: c.dim(result.projectRoot),
+  }) + '\n';
+}
+
+export function renderSyncRemove(result) {
+  return summary({
+    title: `Removed kit-mcp stubs from ${result.target}`,
+    rows: [['Files removed', result.removed.length]],
+    total: result.removed.length,
+    hint: c.dim(result.projectRoot),
+  }) + '\n';
+}
+
+// --- reverse-sync ---
+
+export function renderReverseDetect(result) {
+  if (result.candidates.length === 0) {
+    return `${c.green(icons.check)} No edits to bring back. Canonical kit and ${result.target} are in sync.\n`;
+  }
+  const rows = result.candidates.map(x => [x.kind, x.name, x.reason, x.diffSummary ?? '']);
+  return `${c.bold(`Candidates: ${result.candidates.length}`)}  ${c.dim(`(${result.target})`)}\n` +
+    table(rows, ['kind', 'name', 'reason', 'diff']);
+}
+
+export function renderReverseApply(result) {
+  const rows = result.results.map(x => [
+    x.kind,
+    x.name,
+    x.action.startsWith('overwrit') || x.action.startsWith('merge') || x.action.startsWith('renamed')
+      ? c.green(x.action)
+      : x.action.startsWith('skipped') ? c.dim(x.action) : c.yellow(x.action),
+  ]);
+  return `${c.bold(`Applied (strategy=${result.strategy})`)}\n` + table(rows, ['kind', 'name', 'action']);
+}
+
+// --- gates ---
+
+export function renderGatesList(items) {
+  const rows = items.map(g => [g.id, g.stage, g.blocking ? c.red('blocking') : c.dim('warn-only'), g.description]);
+  return table(rows, ['id', 'stage', 'mode', 'description']);
+}
+
+export function renderGateRun(result) {
+  const verdictColor = result.verdict === 'passed' ? c.green
+                     : result.verdict === 'block'  ? c.red
+                     : result.verdict === 'warn'   ? c.yellow
+                     : c.dim;
+  return `${c.bold(`Gate ${result.id}`)}: ${verdictColor(result.verdict)} ${result.exitCode !== undefined ? c.dim(`(exit ${result.exitCode})`) : ''}\n`;
+}
+
+// --- forensics ---
+
+export function renderForensicsCollect(items) {
+  if (items.length === 0) return `${c.dim('No failures collected.')}\n`;
+  const rows = items.map(x => [x.agent ?? '?', x.kind ?? '?', x.absPath ?? x.path ?? '']);
+  return table(rows, ['agent', 'kind', 'path']);
+}
+
+export function renderForensicsSummarize(byAgent) {
+  const entries = Object.entries(byAgent ?? {});
+  if (entries.length === 0) return `${c.dim('No failures.')}\n`;
+  const rows = entries.map(([agent, items]) => [agent, Array.isArray(items) ? items.length : '?']);
+  return table(rows, ['agent', 'failures']);
+}
+
+export function renderListReplays(items) {
+  if (!Array.isArray(items) || items.length === 0) return `${c.dim('No replays recorded.')}\n`;
+  const rows = items.map(r => [r.id ?? '?', r.agent ?? '?', r.timestamp ?? '?']);
+  return table(rows, ['id', 'agent', 'recorded']);
+}
+
+// --- install ---
+
+export function renderInstallTargets(targets) {
+  const rows = targets.map(t => [t.id, t.label, t.scopes?.join(', ') ?? '?']);
+  return table(rows, ['id', 'label', 'scopes']);
+}
+
+export function renderInstallResult(result) {
+  return summary({
+    title: result.dryRun ? `Install preview (${result.target}, scope=${result.scope})` : `Registered kit-mcp → ${result.target} (scope=${result.scope})`,
+    rows: [
+      ['Path',  result.path ?? '?'],
+      ['Name',  result.name ?? 'kit'],
+      ['Via',   result.via ?? '?'],
+    ].map(([k, v]) => [k, v ?? '—']),
+    hint: result.dryRun ? c.dim('No file written (dry-run)') : undefined,
+  }) + '\n';
+}
+
+// --- generic fallback ---
+
+export function renderFallback(value) {
+  // Used when we don't have a custom renderer yet.
+  return JSON.stringify(value, null, 2) + '\n';
+}

package/src/core/reverse-sync.js

@@ -171,17 +171,21 @@ async function walkRel(root) {
 
 export async function applyReverse(targetId, opts = {}) {
   const strategy = opts.strategy ?? 'skip';
+  const onProgress = opts.onProgress ?? (() => {});
   const { candidates } = await detectReverse(targetId, opts);
   const results = [];
 
-  for (const c of candidates) {
+  for (let i = 0; i < candidates.length; i++) {
+    const c = candidates[i];
     if (opts.only && !opts.only.includes(`${c.kind}/${c.name}`)) {
       results.push({ ...c, action: 'skipped (filter)' });
+      onProgress({ phase: c.kind, current: i + 1, total: candidates.length, label: c.name });
       continue;
     }
 
     const action = await applyOne(c, strategy, opts);
     results.push({ ...c, action });
+    onProgress({ phase: c.kind, current: i + 1, total: candidates.length, label: c.name });
   }
 
   return { target: targetId, strategy, results };

package/src/core/sync.js

@@ -24,6 +24,7 @@ export async function syncTo(targetId, opts = {}) {
   const kitRoot     = resolveKitRoot(opts.kitRoot);
   const mode        = opts.mode ?? 'reference';
   const dryRun      = !!opts.dryRun;
+  const onProgress  = opts.onProgress ?? (() => {});
 
   const kit  = await listKit(kitRoot);
   const ops  = [];
@@ -82,6 +83,7 @@ export async function syncTo(targetId, opts = {}) {
   }
 
   if (!dryRun) {
+    let i = 0;
     for (const op of ops) {
       await fs.mkdir(path.dirname(op.path), { recursive: true });
       if (op.treeCopy) {
@@ -89,6 +91,8 @@ export async function syncTo(targetId, opts = {}) {
       } else {
         await fs.writeFile(op.path, op.content, 'utf8');
       }
+      i++;
+      onProgress({ phase: op.kind, current: i, total: ops.length, label: path.basename(op.path) });
     }
   }
 

package/src/core/ui.js

@@ -0,0 +1,167 @@
+// UI primitives for the CLI: colors, icons, spinner, progress bar,
+// interactive select/confirm prompts, and a summary panel.
+//
+// Design rules:
+//   - Respect process.stdout.isTTY: animations only when interactive.
+//     In pipes/CI, fall back to linear status text.
+//   - Respect NO_COLOR (https://no-color.org) and FORCE_COLOR=1.
+//   - Animations write to stderr to keep stdout clean for `--json` mode
+//     (the user can still pipe machine-readable output even with spinners).
+//   - Zero hidden globals — every primitive is a plain function/class.
+
+import pc from 'picocolors';
+import { select as inqSelect, confirm as inqConfirm } from '@inquirer/prompts';
+
+// --- color helpers ---
+
+const NO_COLOR = process.env.NO_COLOR && process.env.NO_COLOR !== '0';
+const FORCE    = process.env.FORCE_COLOR === '1';
+const COLOR_ON = FORCE || (!NO_COLOR && process.stdout.isTTY);
+
+function id(s) { return String(s); }
+export const c = COLOR_ON
+  ? {
+      green: pc.green, red: pc.red, yellow: pc.yellow, cyan: pc.cyan,
+      magenta: pc.magenta, blue: pc.blue, dim: pc.dim, bold: pc.bold,
+      gray: pc.gray, underline: pc.underline,
+    }
+  : {
+      green: id, red: id, yellow: id, cyan: id, magenta: id, blue: id,
+      dim: id, bold: id, gray: id, underline: id,
+    };
+
+export const icons = {
+  check:   '✓',
+  cross:   '✗',
+  warn:    '⚠',
+  dot:     '•',
+  arrow:   '→',
+  spinner: ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏'],
+};
+
+// --- spinner ---
+
+export function spinner({ text = '' } = {}) {
+  const tty = process.stderr.isTTY;
+  let i = 0;
+  let current = text;
+  let timer = null;
+
+  function render() {
+    process.stderr.write(`\r${c.cyan(icons.spinner[i])} ${current}\x1b[K`);
+    i = (i + 1) % icons.spinner.length;
+  }
+
+  if (tty) {
+    timer = setInterval(render, 80);
+    render();
+  } else {
+    process.stderr.write(`${icons.dot} ${current}\n`);
+  }
+
+  function clearLine() {
+    if (tty) process.stderr.write('\r\x1b[K');
+  }
+
+  return {
+    update(t) { current = t; if (!tty) process.stderr.write(`${icons.dot} ${t}\n`); },
+    succeed(t) {
+      if (timer) clearInterval(timer);
+      clearLine();
+      process.stderr.write(`${c.green(icons.check)} ${t ?? current}\n`);
+    },
+    fail(t) {
+      if (timer) clearInterval(timer);
+      clearLine();
+      process.stderr.write(`${c.red(icons.cross)} ${t ?? current}\n`);
+    },
+    stop() {
+      if (timer) clearInterval(timer);
+      clearLine();
+    },
+  };
+}
+
+// --- progress bar ---
+
+export function progress({ total, label = '' } = {}) {
+  const tty = process.stderr.isTTY;
+  const width = 24;
+  let current = 0;
+  let lastLabel = label;
+
+  function render() {
+    const pct = total === 0 ? 100 : Math.min(100, Math.round((current / total) * 100));
+    const filled = Math.round((width * pct) / 100);
+    const bar = '━'.repeat(filled) + c.dim('━'.repeat(width - filled));
+    const line = `${c.cyan(bar)} ${pct.toString().padStart(3)}% ${c.dim(`(${current}/${total})`)} ${lastLabel}`;
+    process.stderr.write(`\r${line}\x1b[K`);
+  }
+
+  function tick({ label } = {}) {
+    current++;
+    if (label !== undefined) lastLabel = label;
+    if (tty) {
+      render();
+    } else if (current === total || current % Math.max(1, Math.floor(total / 10)) === 0) {
+      // Every ~10% in non-TTY mode
+      const pct = total === 0 ? 100 : Math.round((current / total) * 100);
+      process.stderr.write(`  ${pct}% ${lastLabel}\n`);
+    }
+  }
+
+  function finish(text) {
+    if (tty) {
+      process.stderr.write('\r\x1b[K');
+    }
+    if (text) process.stderr.write(`${c.green(icons.check)} ${text}\n`);
+  }
+
+  if (tty) render();
+  return { tick, finish };
+}
+
+// --- interactive prompts ---
+
+export async function select(opts) {
+  if (!process.stdin.isTTY) {
+    throw new Error('Interactive prompt unavailable: stdin is not a TTY. Pass the value as a flag instead.');
+  }
+  return inqSelect(opts);
+}
+
+export async function confirm(opts) {
+  if (!process.stdin.isTTY) {
+    throw new Error('Interactive prompt unavailable: stdin is not a TTY. Pass --yes to skip confirmation.');
+  }
+  return inqConfirm(opts);
+}
+
+// --- summary panel ---
+
+export function summary({ title, rows = [], total, hint }) {
+  const lines = [];
+  lines.push(`${c.green(icons.check)} ${c.bold(title)}`);
+  lines.push('');
+
+  // Compute label column width
+  const w = Math.max(...rows.map(r => String(r[0]).length), 0);
+  for (const [label, count, status] of rows) {
+    const cnt = count > 0 ? c.green(String(count).padStart(4)) : c.dim(String(count).padStart(4));
+    const tail = status === 'fail' ? c.red(icons.cross) : c.green(icons.check);
+    lines.push(`  ${label.padEnd(w)}  ${cnt}  ${tail}`);
+  }
+
+  if (total !== undefined || hint) {
+    lines.push('');
+    const totalStr = total !== undefined ? `Total: ${c.bold(total)}` : '';
+    const hintStr = hint ? c.dim(`· ${hint}`) : '';
+    lines.push(`  ${totalStr}${totalStr && hintStr ? ' ' : ''}${hintStr}`);
+  }
+
+  return lines.join('\n');
+}
+
+// --- helpers exposed for tests ---
+
+export const _internal = { COLOR_ON };

package/src/mcp-server/index.js

@@ -17,10 +17,13 @@ import { listTargets } from '../core/registry.js';
 import { syncTo, statusOf, removeFrom } from '../core/sync.js';
 import { detectReverse, applyReverse } from '../core/reverse-sync.js';
 import { listGates, getGate, gatesForStage } from '../core/gates.js';
+import { runGate } from '../core/gate-runner.js';
 import { collectFailures, summarizeByAgent, writeLearnings } from '../core/failures.js';
 import { reflect } from '../core/reflect.js';
 import { recordReplay, listReplays, loadReplay, annotateReplay } from '../core/replays.js';
 import { installMcp, listInstallTargets } from './install.js';
+import { ensureSidecar } from '../ui/auto-spawn.js';
+import { wrapProgressForUi } from '../ui/wrapper.js';
 
 const TOOLS = [
   {
@@ -48,6 +51,7 @@ const TOOLS = [
         projectRoot: { type: 'string', description: 'Defaults to cwd' },
         mode:        { type: 'string', enum: ['reference', 'copy'], description: 'Default: reference' },
         dryRun:      { type: 'boolean' },
+        autoSpawn:   { type: 'boolean', description: 'On action=install: auto-start the sidecar UI (kit ui) if not running and stream progress to it.' },
       },
       required: ['action'],
     },
@@ -64,19 +68,22 @@ const TOOLS = [
         strategy:    { type: 'string', enum: ['skip', 'overwrite', 'merge', 'rename'], description: 'For action=apply' },
         only:        { type: 'array', items: { type: 'string' }, description: 'For action=apply: limit to these kind/name pairs' },
         dryRun:      { type: 'boolean' },
+        autoSpawn:   { type: 'boolean', description: 'On action=apply: auto-start the sidecar UI (kit ui) if not running and stream progress to it.' },
       },
       required: ['action', 'target'],
     },
   },
   {
     name: 'gates',
-    description: 'List or fetch reusable workflow gates (regression, confidence, etc).',
+    description: 'List, fetch, or execute reusable workflow gates (regression, confidence, etc).',
     inputSchema: {
       type: 'object',
       properties: {
-        action: { type: 'string', enum: ['list', 'get', 'for-stage'] },
-        id:     { type: 'string', description: 'For action=get' },
-        stage:  { type: 'string', enum: ['pre-plan', 'pre-execute', 'pre-verify', 'post-verify', 'any'], description: 'For action=for-stage' },
+        action:      { type: 'string', enum: ['list', 'get', 'for-stage', 'run'] },
+        id:          { type: 'string', description: 'For action=get or action=run' },
+        stage:       { type: 'string', enum: ['pre-plan', 'pre-execute', 'pre-verify', 'post-verify', 'any'], description: 'For action=for-stage' },
+        projectRoot: { type: 'string', description: 'For action=run' },
+        autoSpawn:   { type: 'boolean', description: 'On action=run: auto-start the sidecar UI (kit ui) if not running and stream progress to it.' },
       },
       required: ['action'],
     },
@@ -136,11 +143,38 @@ async function handleKit(args) {
   }
 }
 
+// withAutoSpawn — if args.autoSpawn is set, ensure the sidecar is up and wrap
+// the user-supplied onProgress so events flow there. Otherwise pass-through.
+async function withAutoSpawn(args, tool, run) {
+  const projectRoot = args.projectRoot || process.cwd();
+  let wrapped = null;
+  let sidecarInfo = null;
+
+  if (args.autoSpawn) {
+    sidecarInfo = await ensureSidecar({ projectRoot, openBrowserOnSpawn: true });
+    if (sidecarInfo?.ready) {
+      wrapped = wrapProgressForUi(null, { projectRoot, tool });
+    }
+  }
+
+  // run(onProgress) — pass our wrapped callback (or undefined to no-op)
+  try {
+    const result = await run(wrapped);
+    if (wrapped?.done) wrapped.done({ ok: true });
+    return sidecarInfo ? { ...result, _sidecar: sidecarInfo } : result;
+  } catch (err) {
+    if (wrapped?.error) wrapped.error(err);
+    throw err;
+  }
+}
+
 async function handleSync(args) {
   switch (args.action) {
     case 'targets': return listTargets();
     case 'status':  return statusOf(args.target, { projectRoot: args.projectRoot });
-    case 'install': return syncTo(args.target,  { projectRoot: args.projectRoot, mode: args.mode, dryRun: args.dryRun });
+    case 'install':
+      return withAutoSpawn(args, 'sync.install', (onProgress) =>
+        syncTo(args.target, { projectRoot: args.projectRoot, mode: args.mode, dryRun: args.dryRun, onProgress }));
     case 'remove':  return removeFrom(args.target, { projectRoot: args.projectRoot });
     default: return { error: `Unknown action: ${args.action}` };
   }
@@ -149,7 +183,13 @@ async function handleSync(args) {
 async function handleReverseSync(args) {
   switch (args.action) {
     case 'detect': return detectReverse(args.target, { projectRoot: args.projectRoot });
-    case 'apply':  return applyReverse(args.target,  { projectRoot: args.projectRoot, strategy: args.strategy, only: args.only, dryRun: args.dryRun });
+    case 'apply':
+      return withAutoSpawn(args, 'reverse-sync.apply', (onProgress) =>
+        applyReverse(args.target, {
+          projectRoot: args.projectRoot,
+          strategy: args.strategy, only: args.only, dryRun: args.dryRun,
+          onProgress,
+        }));
     default: return { error: `Unknown action: ${args.action}` };
   }
 }
@@ -159,6 +199,13 @@ async function handleGates(args) {
     case 'list':      return listGates();
     case 'get':       return getGate(args.id);
     case 'for-stage': return gatesForStage(args.stage);
+    case 'run':
+      return withAutoSpawn(args, 'gates.run', () =>
+        runGate(args.id, {
+          projectRoot: args.projectRoot,
+          yes: true,            // MCP context: never prompt
+          interactive: false,   // MCP never prompts
+        }));
     default: return { error: `Unknown action: ${args.action}` };
   }
 }

package/src/ui/auto-spawn.js

@@ -0,0 +1,108 @@
+// src/ui/auto-spawn.js
+// Spawn the sidecar in a detached subprocess and wait until it's healthy.
+// Used by MCP tool handlers when the caller passes `autoSpawn: true` and no
+// sidecar lockfile is present for the project.
+//
+// Discipline: stderr/file logging only. Audit gate enforced.
+
+import { spawn } from 'node:child_process';
+import http from 'node:http';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { readLock } from './lockfile.js';
+import { openBrowser } from './browser.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+// src/ui → src → repo root → bin/ui.js
+const UI_BIN = path.resolve(HERE, '..', '..', 'bin', 'ui.js');
+
+const POLL_INTERVAL_MS = 100;
+const POLL_TIMEOUT_MS = 5000;
+
+// healthzOk returns true if GET /healthz on this port responds 200 within 1s.
+function healthzOk(port) {
+  return new Promise((resolve) => {
+    const req = http.request({
+      method: 'GET',
+      host: '127.0.0.1',
+      port,
+      path: '/healthz',
+      agent: false,
+      headers: { host: `127.0.0.1:${port}`, connection: 'close' },
+    }, (res) => {
+      res.resume();
+      res.on('end', () => resolve(res.statusCode === 200));
+    });
+    req.on('error', () => resolve(false));
+    req.setTimeout(800, () => { try { req.destroy(); } catch { /* noop */ } resolve(false); });
+    req.end();
+  });
+}
+
+async function waitForHealth(projectRoot, deadline) {
+  // Poll for lockfile + healthz until deadline.
+  while (Date.now() < deadline) {
+    const lock = readLock(projectRoot);
+    if (lock?.port) {
+      // eslint-disable-next-line no-await-in-loop
+      if (await healthzOk(lock.port)) return lock;
+    }
+    // eslint-disable-next-line no-await-in-loop
+    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+  }
+  return null;
+}
+
+// ensureSidecar({projectRoot, openBrowser?}): if a sidecar is already running
+// for this projectRoot, returns immediately with its lock metadata. Otherwise
+// spawns bin/ui.js detached and waits for it to come online, then optionally
+// opens the browser. Resolves to:
+//   { ready: true, port, spawned: bool, opened: bool }   on success
+//   { ready: false, reason }                             on timeout/spawn-fail
+export async function ensureSidecar({ projectRoot, openBrowserOnSpawn = true } = {}) {
+  if (!projectRoot) return { ready: false, reason: 'no_project_root' };
+
+  // Already running?
+  const existing = readLock(projectRoot);
+  if (existing?.port) {
+    if (await healthzOk(existing.port)) {
+      return { ready: true, port: existing.port, spawned: false, opened: false };
+    }
+    // Stale lockfile — let the spawn step reclaim it.
+  }
+
+  // Spawn detached. Inherits stderr only — stdout is closed so a buggy child
+  // can never poison parent's stdout (e.g. when the parent is the MCP server
+  // running on stdio).
+  let child;
+  try {
+    child = spawn(process.execPath, [UI_BIN, '--project-root', projectRoot], {
+      detached: true,
+      stdio: ['ignore', 'ignore', 'inherit'],
+      windowsHide: true,
+    });
+    child.unref();
+  } catch (err) {
+    return { ready: false, reason: `spawn_failed: ${err.message}` };
+  }
+
+  // Wait for it to come online.
+  const deadline = Date.now() + POLL_TIMEOUT_MS;
+  const lock = await waitForHealth(projectRoot, deadline);
+  if (!lock) {
+    return { ready: false, reason: 'healthz_timeout' };
+  }
+
+  let opened = false;
+  if (openBrowserOnSpawn) {
+    const url = `http://127.0.0.1:${lock.port}/`;
+    const r = await openBrowser(url);
+    opened = r.opened === true;
+  }
+
+  return { ready: true, port: lock.port, spawned: true, opened };
+}
+
+export const __test = { healthzOk, UI_BIN, POLL_INTERVAL_MS, POLL_TIMEOUT_MS };