@luanpdd/kit-mcp 1.1.0 → 1.2.3

package/CHANGELOG.md

@@ -6,6 +6,186 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 
 ## [Unreleased]
 
+## [1.2.3] - 2026-05-04
+
+UI inteira agora fala português e usa termos que fazem sentido pra quem não conhece o código por dentro. Os tipos de evento técnicos viraram nomes legíveis, os caminhos absolutos viraram descrições do tipo "agente planner" / "comando novo-marco" / "skill limpeza", e o status badge da conexão agora lê "CONECTADO/CONECTANDO/DESCONECTADO".
+
+### Adicionado — humanização de labels
+
+- `EVENT_TYPE_LABEL` mapeia `run.start → Iniciado`, `run.end → Finalizado`, `progress → Em andamento`, `tool_invocation → Comando`, `milestone → Marco`, `error → Erro`, `shutdown → Desligado`. O `data-type` raw continua na markup (CSS de cor + filtros funcionam igual), apenas o texto exibido muda.
+- `TOOL_LABEL` mapeia ids técnicos pra descrições amigáveis: `sync.install → Sincronizando kit`, `reverse-sync.apply → Importando edições do IDE`, `gates.run → Executando gate`, `sync.watch → Vigiando kit (watch)`, `sidecar → Servidor sidecar`.
+- `STATUS_LABEL` traduz `running → em execução`, `done → concluído`, `error → erro`. Usado nos badges dos cards de active runs e no label de fade-out.
+- `CONN_LABEL` traduz `CONNECTING → CONECTANDO`, `OPEN → CONECTADO`, `CLOSED → DESCONECTADO`.
+- `humanizePath()` reconhece padrões comuns e devolve descrições amigáveis:
+  - `.claude/agents/planner.md` → `agente planner`
+  - `kit/commands/novo-marco.md` → `comando novo-marco`
+  - `kit/skills/limpeza/SKILL.md` → `skill limpeza`
+  - `.claude/framework/...` → `framework`
+  - `CLAUDE.md` → `manifesto CLAUDE.md`
+- `humanizeLabel()` reconhece o padrão "verbo + caminho" comum em payloads de progresso e traduz: `writing .claude/agents/planner.md` → `criando agente planner`, `merging kit/commands/foo.md` → `mesclando comando foo`. Verbos suportados: reading, writing, projecting, merging, copying, deleting, creating, updating, syncing, applying, fetching.
+
+### Adicionado — copy PT-BR
+
+Toda a interface está em português:
+- Placeholder do search: `filtrar por nome ou conteúdo…`
+- Botões: `⏸ pausar` / `▶ retomar`, `↧ rolagem auto`, `limpar tela`
+- Header active runs: `Em execução agora`
+- Footer: `eventos: N`, `pausado: N em fila`, `fonte: ao vivo`
+- Header port: `porta NNNN`
+- Estados de timing: `há 2m 15s` (substitui `started 2m 15s`)
+- Status do card: `em execução` / `concluído` / `erro`
+- Fim de run: `concluído com sucesso` / `falhou` (em vez de `done` / `failed`)
+- Início de run: `iniciando…` (em vez de `starting…`)
+
+### Por que
+
+A v1.2.2 tinha layout bonito mas linguagem técnica — `RUN.START`, `writing .claude/agents/example-reviewer.md`, `RUNNING`. Pra quem usa o sidecar pra primeira vez ou não conhece a arquitetura interna do kit, esses labels eram opacos. Agora o painel diz "Sincronizando kit · em execução · criando agente example-reviewer · 34/100 · 12s" em vez de jogar paths absolutos e enums no usuário.
+
+### Sem mudanças de API
+
+Pure UI patch, ainda. Stable API v1.0+ preservada. Sem deps novas. `data-type` no DOM continua raw (filtros e CSS não quebram). Apenas `src/ui/static/index.html` mudou.
+
+## [1.2.2] - 2026-05-04
+
+UX upgrade da sidecar: o feed cronológico continua, mas agora a janela mostra TAMBÉM um painel "Active runs" no topo com cards visuais pra cada execução em andamento — barra de progresso animada, percentual grande, label do passo atual, runId truncado e tempo decorrido tickando ao vivo.
+
+### Adicionado
+
+- **Active runs panel** em `src/ui/static/index.html` — uma `<section id="active-runs">` antes do log de eventos. Para cada `runId` ativo, renderiza um card com:
+  - Nome do tool (de `payload.tool` no `run.start`) com badge de status (running/done/error)
+  - Percentual grande (22px tabular-nums) à direita
+  - Barra de progresso 8px com transição suave + shimmer animado em estado `running`
+  - Label do passo atual (último `payload.label` ou `current/total` derivado)
+  - Footer com tempo decorrido (tick a cada 1s) + runId truncado + current/total
+- Estado consolidado via `Map<runId, ActiveRun>`, atualizado por `run.start` (cria), `progress` (incrementa), `tool_invocation` (refina título), `run.end` (marca done, fade-out em 4s), `error` (marca erro, fade-out em 8s).
+- Cards são **atualizados in-place** via `dataset.runid` matching — preserva a transição CSS da barra em vez de recriar o DOM a cada update.
+- Painel some quando 0 runs ativos; aparece automaticamente quando o primeiro `run.start` chega.
+
+### Por que
+
+A v1.2.0 mostrava progresso, mas misturado no feed cronológico — pra saber "tô em quanto" você precisava scanar o último `progress`. O painel novo mostra o estado atual sem rolagem, com afordância visual: barra cresce, percentual sobe, shimmer anda. Quando termina, o card vira verde e some 4s depois (vermelho 8s pra erro). Pareceu "log do servidor", agora parece "process viewer".
+
+### Sem mudanças de API
+
+Pure UI patch. Stable API v1.0+ preservada. Sem deps novas. Apenas `src/ui/static/index.html` (~120 LOC adicionados — CSS dos cards + lógica do `upsertActiveRun` + tick interval).
+
+## [1.2.1] - 2026-05-04
+
+Cosmetic + UX patches descobertos durante o smoke da v1.2.0. Sem mudanças de comportamento de API.
+
+### Corrigido
+
+- **`eventLabel()` agora lê `payload.name`.** Eventos `milestone` que usavam `payload.name` (sem `label`) renderizavam como texto cru "milestone" em vez do nome real. Adicionado fallback `name` na cadeia de helpers no `src/ui/static/index.html`.
+- **SSE reconecta quando o tab volta a ficar visível.** Chrome (e outros browsers Chromium) throttla timers em background tabs, podendo suspender o retry interno do `EventSource` e deixar a conexão presa em `CLOSED` mesmo depois do `kit ui` voltar. Adicionado listener `visibilitychange` que faz `hydrateFromState() → connect()` quando o tab volta a `visible` e o status atual é `CLOSED`. Re-hidrata o ring buffer pra mostrar eventos que chegaram durante o gap.
+
+### Sem mudanças de API
+
+`v1.2.0 → v1.2.1` é puro patch:
+- Stable API v1.0+ preservada
+- Sem deps novas (deps em 6/6)
+- Sem mudança em `src/core/`, `src/cli/`, `src/mcp-server/`, ou em qualquer schema MCP/CLI
+- Apenas `src/ui/static/index.html` recebeu ~10 LOC
+
+## [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.3",
   "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);