@luanpdd/kit-mcp 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -6,6 +6,106 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-05-04
+
+**GUI sidecar de acompanhamento.** Janela web localhost paralela mostra ao vivo (via Server-Sent Events) o que kit-mcp está fazendo enquanto sua IDE chama tools — `sync install`, `reverse-sync apply`, `gates run`. Sidecar é totalmente opt-in: quem não invoca `kit ui` continua com a experiência v1.1 idêntica.
+
+### Adicionado — Phase 11: Lock arquitetural
+- ADR consolidado em `.planning/decisions.md` (porta 7100-7199, lockfile em `os.tmpdir()` keyed por sha1(projectRoot), idle 30min default, sem auth no v1.2 com mitigação compensatória)
+- Threat model em `docs/sidecar-security.md`
+- 2 audit gates novos no CI: stdout discipline em `src/ui/` (proíbe `console.log`/`process.stdout.write`) e dep budget (≤ baseline+1)
+
+### Adicionado — Phase 12: Fundações
+- `src/ui/events.js` — schema de evento, validador puro, `makeEvent`, `newRunId`
+- `src/ui/port.js` — `findFreePort` na faixa 7100-7199 com retry-loop
+- `src/ui/lockfile.js` — `acquireLock` atômico via `O_EXCL`, `probeStale` via `process.kill(pid, 0)` + healthz HTTP
+
+### Adicionado — Phase 13: Servidor HTTP + SSE
+- `src/ui/server.js` — http.Server nativo, bind 127.0.0.1 literal, 5 rotas (`/`, `/events` SSE, `/healthz`, `/state`, `/publish`, `/shutdown`)
+- Heartbeat `: ping\n\n` cada 15s; reconnect auto via EventSource native + `retry: 3000`
+- Ring buffer in-memory de 200 eventos (FIFO; sem persistência em disco)
+- Cap de 32 conexões SSE; cleanup quádruplo (req+res × close+error)
+- Idle shutdown 30min default (`--idle-ms 0` desabilita)
+- Encerramento gracioso em SIGINT/SIGTERM com active sockets destruídos
+- Validação de `Host` header (mitiga DNS rebinding) e `Origin` em endpoints non-GET
+- `bin/ui.js` entry detached
+
+### Adicionado — Phase 14: UI estática single-file
+- `src/ui/static/index.html` (~470 LOC) — vanilla DOM + EventSource, sem build step
+- Lista cronológica + auto-scroll + `<details>` expand
+- Badges coloridos por tipo (`run.start`, `run.end`, `tool_invocation`, `progress`, `milestone`, `error`, `shutdown`)
+- Status conexão (CONNECTING/OPEN/CLOSED) + reconexão automática
+- Filter por tipo (chips) + substring search
+- Pause/resume com buffer + autoscroll toggle
+- Dark mode automático via `prefers-color-scheme`
+- Banner de shutdown PT-BR em CLOSED >5s ou evento `shutdown`
+- CSP estrito (`default-src 'self'; ...; frame-ancestors 'none'`)
+
+### Adicionado — Phase 15: Publisher + wrapper + browser-open
+- `src/ui/client.js` — `publish(event, {projectRoot})` fire-and-forget, cache TTL 5s, falha silenciosa em ECONNREFUSED
+- `src/ui/wrapper.js` — `wrapProgressForUi(onProgress, ctx)` multiplexa terminal + sidecar; helpers `.done/.error/.emit`; `redactPath` central scrubando `$HOME → ~` e `projectRoot → <project>` em TODO payload
+- `src/ui/browser.js` — wrapper sobre `open@11` com detection de headless (CI, DISPLAY, SSH, WSL, sandbox); fallback "imprime URL no stderr"
+- Nova dep: `open@^11.0.0` (única adição; budget atingido em 6/6)
+
+### Adicionado — Phase 16: CLI integration
+- `kit ui start` — sobe sidecar foreground (Ctrl+C mata); flags `--port`, `--idle-ms`, `--no-open`
+- `kit ui stop` — POST /shutdown
+- `kit ui status` — exibe pid, port, uptime, eventos, subscribers
+- `kit ui open` — reabre browser na sidecar atual
+- Auto-detect: `kit sync install` e `kit reverse-sync apply` checam lockfile e wrappam `onProgress` automaticamente quando sidecar está rodando
+- Opt-out global via `--no-ui` flag ou `KIT_MCP_NO_UI=1` env var
+
+### Adicionado — Phase 17: MCP --auto-spawn
+- `src/ui/auto-spawn.js` — `ensureSidecar({projectRoot})` checa lockfile + healthz; se ausente, spawna `bin/ui.js` em **detached** com `windowsHide: true` e `stdio: ['ignore', 'ignore', 'inherit']` (fecha stdout completamente — não pode poluir canal MCP do parent)
+- 3 tools MCP ganham campo opcional `autoSpawn: boolean` no inputSchema:
+  - `sync` (action=install)
+  - `reverse-sync` (action=apply)
+  - `gates` (nova action `run`, com autoSpawn)
+- Tools triviais (`kit`, `forensics`, `install`) **não** ganham autoSpawn — explicit-out por design
+
+### Adicionado — Phase 18: Hardening + release
+- 3 hardening tests novos: kill -9 recovery, multi-publisher race, MCP stdio uncorrupted (validação rigorosa do REQ SEC-04 em produção)
+- README seção "Live UI" com primeiros passos
+- `npm pack --dry-run` valida que `src/ui/static/index.html` é incluído no tarball
+
+### Corrigido
+- **REL-01 (bug pré-existente):** `kit --version` agora lê de `package.json` em vez de retornar string hardcoded `1.0.0`. Em v1.0/v1.1 o comando exibia versão errada — corrigido nesta release.
+
+### Stable API additions (1.x compatible)
+
+A v1.0 commitment continua válida. Estas adições são parte do contrato:
+
+- **MCP tool `sync` inputSchema:** campo opcional `autoSpawn: boolean` em action=install. Tools que não passam mantêm comportamento idêntico.
+- **MCP tool `reverse-sync` inputSchema:** campo opcional `autoSpawn: boolean` em action=apply.
+- **MCP tool `gates` inputSchema:** campo opcional `autoSpawn: boolean` E nova action `run` com `id`/`projectRoot`/`autoSpawn` campos.
+- **CLI subgroup `kit ui`:** novo grupo com `start | stop | status | open` subcommands.
+- **CLI flag `--no-ui` global** + env var `KIT_MCP_NO_UI=1` — opt-out do auto-detect de sidecar.
+- **Stable runtime guarantee:** core (`syncTo`, `applyReverse`, `runGate`) é literalmente intocado. Wrapper de `onProgress` é montado APENAS no callsite (CLI handler ou MCP tool handler).
+
+### Migration
+
+**Usuários v1.1 não precisam fazer nada.** Sidecar é estritamente opt-in.
+
+Para experimentar a UI:
+```bash
+# 1. Em um terminal:
+kit ui start
+
+# 2. Em outro (ou via Claude Code/Cursor):
+kit sync install claude-code
+
+# A janela mostra o progresso em tempo real.
+```
+
+Para tools MCP, passe `autoSpawn: true` quando quiser auto-abrir:
+```jsonc
+{ "tool": "sync", "arguments": { "action": "install", "target": "claude-code", "autoSpawn": true } }
+```
+
+### Threat model resumido
+
+Sidecar é **localhost only**, single-user, dev workstation. Sem auth (mitigado por bind 127.0.0.1 + Host/Origin check + CSP estrito + path scrubbing). Sem persistência. Sem TLS (loopback). Detalhes em [`docs/sidecar-security.md`](docs/sidecar-security.md).
+
 ## [1.1.0] - 2026-05-03
 
 **Visual feedback in the terminal.** Running `kit ...` now prints colored tables, progress bars, summary panels and interactive selectors instead of the raw JSON-to-stdout default of v1.0. Programmatic consumers add `--json` to restore the previous behavior.

package/README.md

@@ -272,6 +272,38 @@ kit forensics load-replay <id> --project-root .
 
 The proposal is always saved to `.planning/learnings/{agent}.proposal.md` first; the canonical is only modified after explicit confirmation (or `--apply`). MCP `forensics.reflect` never auto-applies.
 
+### `kit ui ...` — live process viewer (sidecar) — _new in 1.2_
+
+A tiny localhost web app that streams what kit-mcp is doing while your IDE drives it. Strictly opt-in: ignore it and v1.1 behavior is unchanged.
+
+```bash
+# In one terminal — keeps running until Ctrl+C
+kit ui start
+
+# In another terminal (or via Claude Code / Cursor) — runs as before, but events
+# are now also broadcast to the sidecar window
+kit sync install claude-code
+
+# Tools too: pass autoSpawn:true on the MCP side, or just `kit ui start` first
+kit ui status
+kit ui stop
+```
+
+What you get:
+
+- A single browser tab at `http://127.0.0.1:7100` (or the next free port up to 7199)
+- Live event stream over Server-Sent Events — `tool_invocation`, `progress`, `error`, `milestone`, `run.start`, `run.end`
+- Filters by event type and substring; pause/resume; auto-scroll; dark mode tracks the OS
+- The sidecar shuts itself down after 30 minutes of idle; `--idle-ms 0` disables that
+
+**Auto-spawn from MCP tools.** Pass `autoSpawn: true` in the inputSchema of `sync` (action=install), `reverse-sync` (action=apply), or `gates` (action=run). The MCP server will spawn `bin/ui.js` detached, wait for it to come online, open your default browser, and stream that tool's progress. Trivial tools (`kit list-*`, `forensics`, `install`) deliberately don't accept `autoSpawn` — the overhead isn't worth it.
+
+**Opt-out always available.** From the CLI: pass `--no-ui` or set `KIT_MCP_NO_UI=1`. The sidecar is never started behind your back; it's only used when a lockfile is already present (someone ran `kit ui start` or `autoSpawn: true`).
+
+**Security model.** Sidecar binds to `127.0.0.1` literally — never `0.0.0.0`, never `localhost` (which resolves to `::1` on Windows). Every route validates the `Host` header to mitigate DNS rebinding. CSP is strict (`default-src 'self'; …; frame-ancestors 'none'`). Paths in payloads are scrubbed (`$HOME → ~`, `<projectRoot> → <project>`) so screenshots don't leak directory structure. No persistence, no TLS, no auth — single-user dev workstation only. Full threat model in [`docs/sidecar-security.md`](docs/sidecar-security.md).
+
+**First-run quirks.** Windows Defender / macOS firewall may prompt the first time `kit ui start` binds. Approving "Private networks" is enough — the server doesn't accept anything from outside loopback regardless. On WSL, `kit ui start` opens the URL in the Windows host browser via `wslview`. In CI / SSH / `TERM=dumb`, browser launch is suppressed and the URL is printed to stderr instead.
+
 ---
 
 ## MCP usage

package/bin/ui.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// bin/ui.js — entry point for the sidecar HTTP server.
+//
+// Used both directly (when the user runs `kit ui start`) and as the spawn target
+// when `--auto-spawn` is enabled on an MCP tool.
+//
+// Logging discipline: all output goes to stderr. stdout is reserved so that
+// callers can pipe `node bin/ui.js | jq` without UI server chatter contaminating
+// data streams (and so that this file can never poison an MCP stdio channel).
+
+import process from 'node:process';
+import { createServer } from '../src/ui/server.js';
+
+function parseArgs(argv) {
+  const args = { projectRoot: process.cwd(), port: undefined, idleMs: undefined };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--project-root' && argv[i + 1]) { args.projectRoot = argv[i + 1]; i += 1; }
+    else if (a === '--port' && argv[i + 1]) { args.port = Number(argv[i + 1]); i += 1; }
+    else if (a === '--idle-ms' && argv[i + 1]) { args.idleMs = Number(argv[i + 1]); i += 1; }
+    else if (a === '--version') { args.printVersion = true; }
+    else if (a === '--help' || a === '-h') { args.help = true; }
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv.slice(2));
+
+if (args.help) {
+  process.stderr.write([
+    'kit-mcp sidecar entry — usually invoked via `kit ui start`',
+    '',
+    'Usage: node bin/ui.js [options]',
+    '  --project-root <path>   project root for lockfile keying (default: cwd)',
+    '  --port <n>              bind to a specific port (default: auto-pick 7100-7199)',
+    '  --idle-ms <ms>          idle shutdown timeout (default: 1800000 = 30min; 0 = never)',
+    '  --version               print version and exit',
+    '  --help                  this text',
+    '',
+  ].join('\n'));
+  process.exit(0);
+}
+
+let pkgVersion = null;
+try {
+  const { default: pkg } = await import('../package.json', { with: { type: 'json' } });
+  pkgVersion = pkg.version;
+} catch {
+  // ok — version may not be available in some packaged contexts
+}
+
+if (args.printVersion) {
+  process.stderr.write(`${pkgVersion ?? 'unknown'}\n`);
+  process.exit(0);
+}
+
+const server = createServer({
+  projectRoot: args.projectRoot,
+  version: pkgVersion,
+  idleMs: args.idleMs,
+});
+
+try {
+  const { port } = await server.start({ port: args.port });
+  process.stderr.write(`[kit-mcp ui] listening on http://127.0.0.1:${port}/\n`);
+  process.stderr.write(`[kit-mcp ui] project: ${args.projectRoot}\n`);
+} catch (err) {
+  if (err.code === 'ELIVE') {
+    process.stderr.write(`[kit-mcp ui] sidecar already running for this project (pid=${err.lock?.pid}, port=${err.lock?.port})\n`);
+    process.exit(2);
+  }
+  process.stderr.write(`[kit-mcp ui] failed to start: ${err.message}\n`);
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luanpdd/kit-mcp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Generic infrastructure to ship YOUR personal kit of agents/commands/skills as an MCP server, with cross-IDE sync (Claude Code, Cursor, Codex, Gemini, Windsurf, Antigravity, Copilot, Trae).",
   "type": "module",
   "bin": {
@@ -51,6 +51,7 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "chokidar": "^5.0.0",
     "commander": "^12.1.0",
+    "open": "^11.0.0",
     "picocolors": "^1.1.1"
   }
 }

package/src/cli/index.js

@@ -13,6 +13,9 @@
 // programmatic consumers.
 
 import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
 import { listKit, searchKit, findItem } from '../core/kit.js';
 import { listTargets } from '../core/registry.js';
 import { syncTo, statusOf, removeFrom } from '../core/sync.js';
@@ -26,13 +29,31 @@ import { listReplays, loadReplay } from '../core/replays.js';
 import { installMcp, listInstallTargets } from '../mcp-server/install.js';
 import * as render from './render.js';
 import { c, icons, spinner, progress, select, confirm } from '../core/ui.js';
+import { createServer } from '../ui/server.js';
+import { readLock, lockPathFor } from '../ui/lockfile.js';
+import { wrapProgressForUi } from '../ui/wrapper.js';
+import { openBrowser } from '../ui/browser.js';
+import http from 'node:http';
+
+// Read package.json version at boot so `--version` is always accurate. Falls
+// back to a string if the file lookup fails (e.g. unusual install layout).
+function readPkgVersion() {
+  try {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const pkgPath = path.resolve(here, '..', '..', 'package.json');
+    return JSON.parse(readFileSync(pkgPath, 'utf8')).version;
+  } catch {
+    return 'unknown';
+  }
+}
 
 const program = new Command()
   .name('kit')
   .description('Personal kit (agents/commands/skills) — CLI mirror of the kit-mcp server.')
-  .version('1.0.0')
+  .version(readPkgVersion())
   .option('--kit-root <path>', 'Override the kit root (default: bundled example kit, or KIT_MCP_KIT_ROOT env)')
-  .option('--json', 'Output JSON to stdout (machine-readable, restores pre-1.1 default)');
+  .option('--json', 'Output JSON to stdout (machine-readable, restores pre-1.1 default)')
+  .option('--no-ui', 'Suppress sidecar event publishing for this run (default: auto-detect lockfile)');
 
 program.hook('preAction', (thisCommand, actionCommand) => {
   const opts = program.opts();
@@ -67,22 +88,57 @@ async function withSpinner(text, fn) {
 }
 
 // withProgress wraps a long op; passes onProgress callback to the core fn.
-async function withProgress(label, total, fn) {
+// Also auto-detects a running sidecar (via lockfile) and multiplexes events to
+// it when present. Opt-out via --no-ui or KIT_MCP_NO_UI=1.
+async function withProgress(label, total, fn, { tool, projectRoot } = {}) {
   const opts = program.opts();
-  if (opts.json) return fn(() => {});
-  const p = progress({ total, label });
-  let last = '';
-  const onProgress = ({ current, label }) => { last = label || last; p.tick({ label: last }); };
+  let onProgress;
+  let p = null;
+  if (opts.json) {
+    onProgress = () => {};
+  } else {
+    p = progress({ total, label });
+    let last = '';
+    onProgress = ({ current, label }) => { last = label || last; p.tick({ label: last }); };
+  }
+
+  // Auto-wrap if a sidecar is running for this projectRoot.
+  const wrapper = maybeWrapForUi(onProgress, { tool, projectRoot });
   try {
-    const r = await fn(onProgress);
-    p.finish(label);
+    const r = await fn(wrapper);
+    if (p) p.finish(label);
+    if (wrapper.done) wrapper.done({ ok: true });
     return r;
   } catch (e) {
-    p.finish();
+    if (p) p.finish();
+    if (wrapper.error) wrapper.error(e);
     throw e;
   }
 }
 
+// maybeWrapForUi — returns the original callback unchanged when no sidecar is up
+// or the user opted out. Otherwise returns a wrapped callback with .done/.error.
+function maybeWrapForUi(onProgress, { tool, projectRoot } = {}) {
+  const globalOpts = program.opts();
+  // commander stores `--no-ui` as opts.ui === false
+  if (globalOpts.ui === false || process.env.KIT_MCP_NO_UI === '1') {
+    return passthroughWrapper(onProgress);
+  }
+  const root = projectRoot || process.cwd();
+  if (!readLock(root)) {
+    return passthroughWrapper(onProgress);
+  }
+  return wrapProgressForUi(onProgress, { projectRoot: root, tool: tool ?? null });
+}
+
+function passthroughWrapper(onProgress) {
+  const cb = (p) => { if (typeof onProgress === 'function') onProgress(p); };
+  cb.done = () => {};
+  cb.error = () => {};
+  cb.emit = () => {};
+  return cb;
+}
+
 function fail(msg) {
   process.stderr.write(`${c.red(icons.cross)} ${msg}\n`);
   process.exit(1);
@@ -134,6 +190,7 @@ sync.command('install [target]')
       `Syncing kit → ${target}`,
       300,
       (onProgress) => syncTo(target, { projectRoot: opts.projectRoot, mode: opts.mode, dryRun: opts.dryRun, onProgress }),
+      { tool: 'sync.install', projectRoot: opts.projectRoot },
     );
     out(result, render.renderSyncInstall);
   });
@@ -181,6 +238,7 @@ reverse.command('apply <target>')
       `Applying reverse-sync (${opts.strategy})`,
       50,
       (onProgress) => applyReverse(target, { projectRoot: opts.projectRoot, strategy: opts.strategy, only: opts.only, dryRun: opts.dryRun, onProgress }),
+      { tool: 'reverse-sync.apply', projectRoot: opts.projectRoot },
     );
     out(result, render.renderReverseApply);
   });
@@ -314,4 +372,147 @@ async function pickTarget(targets, message) {
   }
 }
 
+// --- ui (sidecar process viewer) ---
+const ui = program.command('ui').description('Live process viewer in a localhost browser tab.');
+
+ui.command('start')
+  .description('Start the sidecar HTTP server in foreground (Ctrl+C to stop). Prints URL on stderr.')
+  .option('--project-root <path>', 'Project root for lockfile keying (default: cwd)')
+  .option('--port <n>', 'Bind to a specific port (default: auto-pick 7100-7199)')
+  .option('--idle-ms <ms>', 'Idle shutdown timeout (default 30min; 0 = never)')
+  .option('--no-open', 'Skip auto-opening the browser')
+  .action(async (opts) => {
+    const projectRoot = opts.projectRoot || process.cwd();
+    const port = opts.port ? Number(opts.port) : undefined;
+    const idleMs = opts.idleMs !== undefined ? Number(opts.idleMs) : undefined;
+    const srv = createServer({ projectRoot, idleMs });
+    try {
+      const { port: actualPort } = await srv.start({ port });
+      const url = `http://127.0.0.1:${actualPort}/`;
+      process.stderr.write(`${c.cyan(icons.info)} kit-mcp ui listening on ${url}\n`);
+      process.stderr.write(`${c.dim(`  project: ${projectRoot}`)}\n`);
+      if (opts.open !== false) {
+        await openBrowser(url);
+      }
+      // The server's own SIGINT handler will perform shutdown + cleanup.
+      // We just stay alive — server is foreground.
+    } catch (err) {
+      if (err.code === 'ELIVE') {
+        process.stderr.write(`${c.yellow(icons.warn)} sidecar already running for this project\n`);
+        process.stderr.write(`  pid: ${err.lock?.pid}, port: ${err.lock?.port}\n`);
+        process.stderr.write(`  use 'kit ui status' or 'kit ui open' to inspect\n`);
+        process.exit(2);
+      }
+      fail(err.message);
+    }
+  });
+
+ui.command('stop')
+  .description('Stop the sidecar running for this project (POST /shutdown).')
+  .option('--project-root <path>')
+  .action(async (opts) => {
+    const projectRoot = opts.projectRoot || process.cwd();
+    const lock = readLock(projectRoot);
+    if (!lock) return out({ ok: false, reason: 'no_sidecar' }, () => `${icons.warn} no sidecar running for this project\n`);
+    try {
+      await postShutdown(lock.port);
+      out({ ok: true, port: lock.port }, () => `${icons.check} sidecar at port ${lock.port} stopped\n`);
+    } catch (err) {
+      fail(`could not stop sidecar at port ${lock.port}: ${err.message}`);
+    }
+  });
+
+ui.command('status')
+  .description('Show whether a sidecar is running for this project.')
+  .option('--project-root <path>')
+  .action(async (opts) => {
+    const projectRoot = opts.projectRoot || process.cwd();
+    const lock = readLock(projectRoot);
+    if (!lock) {
+      out({ running: false, reason: 'no_lockfile' }, () => `${icons.warn} no sidecar running\n`);
+      process.exit(1);
+    }
+    try {
+      const health = await getHealthz(lock.port);
+      out({ running: true, ...health, lockfile: lockPathFor(projectRoot) }, render.renderUiStatus ?? renderUiStatusFallback);
+    } catch (err) {
+      out({ running: false, reason: 'unreachable', lockfile: lockPathFor(projectRoot), error: err.message },
+          () => `${icons.cross} lockfile present but sidecar unreachable: ${err.message}\n`);
+      process.exit(1);
+    }
+  });
+
+ui.command('open')
+  .description('Open the running sidecar in a browser. Fails if no sidecar is up.')
+  .option('--project-root <path>')
+  .action(async (opts) => {
+    const projectRoot = opts.projectRoot || process.cwd();
+    const lock = readLock(projectRoot);
+    if (!lock) return fail('no sidecar running — start one with `kit ui start`');
+    const url = `http://127.0.0.1:${lock.port}/`;
+    const r = await openBrowser(url, { force: true });
+    if (!r.opened) {
+      process.stderr.write(`${c.yellow(icons.warn)} could not open browser (${r.reason}); copy the URL above\n`);
+      process.exit(1);
+    }
+  });
+
+// Helpers for kit ui (live in cli/ — stdout/console allowed here)
+async function postShutdown(port) {
+  return new Promise((resolve, reject) => {
+    const req = http.request({
+      method: 'POST',
+      host: '127.0.0.1',
+      port,
+      path: '/shutdown',
+      agent: false,
+      headers: { host: `127.0.0.1:${port}`, origin: `http://127.0.0.1:${port}`, 'content-length': 0, connection: 'close' },
+    }, (res) => {
+      res.resume();
+      res.on('end', () => res.statusCode < 400 ? resolve() : reject(new Error(`http_${res.statusCode}`)));
+    });
+    req.on('error', reject);
+    req.setTimeout(2000, () => { try { req.destroy(); } catch {} ; reject(new Error('timeout')); });
+    req.end();
+  });
+}
+
+async function getHealthz(port) {
+  return new Promise((resolve, reject) => {
+    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) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        if (res.statusCode >= 400) return reject(new Error(`http_${res.statusCode}`));
+        try { resolve(JSON.parse(Buffer.concat(chunks).toString('utf8'))); }
+        catch (e) { reject(e); }
+      });
+    });
+    req.on('error', reject);
+    req.setTimeout(2000, () => { try { req.destroy(); } catch {} ; reject(new Error('timeout')); });
+    req.end();
+  });
+}
+
+function renderUiStatusFallback(v) {
+  if (!v.running) return `${icons.warn} not running\n`;
+  return [
+    `${icons.check} sidecar running`,
+    `  port:        ${v.port}`,
+    `  pid (sdcr):  ${v.lockfile ? readLock(process.cwd())?.pid : '?'}`,
+    `  uptime:      ${Math.round((v.uptime || 0) / 1000)}s`,
+    `  events:      ${v.eventsTotal}`,
+    `  subscribers: ${v.subscribers}`,
+    `  url:         http://127.0.0.1:${v.port}/`,
+    '',
+  ].join('\n');
+}
+
 program.parseAsync(process.argv);

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}` };
   }
 }