@luanpdd/kit-mcp 1.27.0 → 1.29.0

package/src/core/watch.js

@@ -1,121 +1,121 @@
-// Watch the canonical kit/ and re-sync to one or more IDE targets on every change.
-//
-// Usage from CLI: `kit sync watch <target...> [--all]`
-// Usage from code: `await watchKit(['claude-code', 'cursor'], opts) → { stop }`
-//
-// Behavior:
-//   - Initial full sync to each target on start
-//   - Debounced re-sync (default 300ms) on add/change/unlink under kit/
-//   - Per-event log to opts.onLog (defaults to no-op so callers control output)
-//   - Returns { stop } to cleanly tear down the watcher
-
-import path from 'node:path';
-import fs from 'node:fs/promises';
-import { syncTo } from './sync.js';
-import { listTargets } from './registry.js';
-import { resolveKitRoot, clearKitCache } from './kit.js';
-
-// PERF-16-06: chokidar é optionalDependency. Carregamos lazy dentro de watchKit()
-// para que (a) `kit sync install` (que NÃO usa watch) não pague o custo de boot,
-// e (b) `npm install --omit=optional` produza CLI core funcional (apenas
-// `kit sync watch` falha com mensagem descritiva).
-let _chokidarModule = null;
-async function loadChokidar() {
-  if (_chokidarModule) return _chokidarModule;
-  try {
-    const mod = await import('chokidar');
-    _chokidarModule = mod.default || mod;
-    return _chokidarModule;
-  } catch (err) {
-    throw new Error(
-      'kit sync watch requires chokidar. Install with `npm i chokidar` or use `kit sync install <target>` for one-shot syncing instead.'
-    );
-  }
-}
-
-export async function watchKit(targets, opts = {}) {
-  const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
-  const kitRoot     = resolveKitRoot(opts.kitRoot);
-  const mode        = opts.mode ?? 'reference';
-  // PERF-16-02: bump default 300 → 500ms to coalesce IDE save-bursts (typical
-  // IDE auto-save fires 5-10 events in < 500ms during a single user save).
-  const debounceMs  = Number.isFinite(opts.debounceMs) ? opts.debounceMs : 500;
-  const onLog       = opts.onLog ?? (() => {});
-
-  if (!Array.isArray(targets) || targets.length === 0) {
-    throw new Error('watchKit: targets[] required (or use detectTargets()).');
-  }
-
-  // Initial sync
-  for (const t of targets) {
-    const r = await syncTo(t, { projectRoot, kitRoot, mode });
-    onLog(`✓ initial sync → ${t} (${r.written.length} files)`);
-  }
-
-  const chokidar = await loadChokidar();
-  const watcher = chokidar.watch(kitRoot, {
-    ignored: (p) => /(^|[/\\])\.[^/\\]/.test(p),  // ignore dotfiles/dotdirs
-    persistent: true,
-    ignoreInitial: true,
-    awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 },
-  });
-
-  let pending = null;
-  const trigger = (label, p) => {
-    onLog(`${label} ${path.relative(kitRoot, p)}`);
-    if (pending) clearTimeout(pending);
-    pending = setTimeout(async () => {
-      pending = null;
-      // PERF-16-02: invalidate kitCache (TTL 30s in kit.js PERF-01) BEFORE
-      // re-sync — otherwise listKit() inside syncTo can return the pre-edit
-      // cached value if the burst happened within the TTL window. Coalescing
-      // the edit-burst via debounce means clearKitCache fires AT MOST ONCE
-      // per 500ms window, regardless of how many save events came in.
-      clearKitCache();
-      for (const t of targets) {
-        try {
-          const r = await syncTo(t, { projectRoot, kitRoot, mode });
-          onLog(`↻ resynced → ${t} (${r.written.length} files)`);
-        } catch (e) {
-          onLog(`✗ resync → ${t}: ${e.message}`);
-        }
-      }
-    }, debounceMs);
-  };
-
-  watcher.on('add',    (p) => trigger('+', p));
-  watcher.on('change', (p) => trigger('~', p));
-  watcher.on('unlink', (p) => trigger('-', p));
-  watcher.on('error',  (e) => onLog(`! watcher error: ${e.message}`));
-
-  return {
-    stop: async () => {
-      if (pending) { clearTimeout(pending); pending = null; }
-      await watcher.close();
-      onLog('watcher stopped');
-    },
-  };
-}
-
-// Detect which targets currently have any files projected into projectRoot.
-// Used by `--all` so the user doesn't have to re-list IDEs they already synced to.
-export async function detectExistingTargets(opts = {}) {
-  const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
-  const all = listTargets();
-  const existing = [];
-  for (const t of all) {
-    // We just check if at least one of the capability directories/files exists.
-    const probes = [];
-    const reg = (await import('./registry.js')).getTarget(t.id);
-    if (reg.rules)    probes.push(path.join(projectRoot, reg.rules.path));
-    if (reg.agents)   probes.push(path.join(projectRoot, reg.agents.path));
-    if (reg.commands) probes.push(path.join(projectRoot, reg.commands.path));
-    if (reg.skills)   probes.push(path.join(projectRoot, reg.skills.path));
-    let found = false;
-    for (const p of probes) {
-      try { await fs.access(p); found = true; break; } catch {}
-    }
-    if (found) existing.push(t.id);
-  }
-  return existing;
-}
+// Watch the canonical kit/ and re-sync to one or more IDE targets on every change.
+//
+// Usage from CLI: `kit sync watch <target...> [--all]`
+// Usage from code: `await watchKit(['claude-code', 'cursor'], opts) → { stop }`
+//
+// Behavior:
+//   - Initial full sync to each target on start
+//   - Debounced re-sync (default 300ms) on add/change/unlink under kit/
+//   - Per-event log to opts.onLog (defaults to no-op so callers control output)
+//   - Returns { stop } to cleanly tear down the watcher
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { syncTo } from './sync.js';
+import { listTargets } from './registry.js';
+import { resolveKitRoot, clearKitCache } from './kit.js';
+
+// PERF-16-06: chokidar é optionalDependency. Carregamos lazy dentro de watchKit()
+// para que (a) `kit sync install` (que NÃO usa watch) não pague o custo de boot,
+// e (b) `npm install --omit=optional` produza CLI core funcional (apenas
+// `kit sync watch` falha com mensagem descritiva).
+let _chokidarModule = null;
+async function loadChokidar() {
+  if (_chokidarModule) return _chokidarModule;
+  try {
+    const mod = await import('chokidar');
+    _chokidarModule = mod.default || mod;
+    return _chokidarModule;
+  } catch (err) {
+    throw new Error(
+      'kit sync watch requires chokidar. Install with `npm i chokidar` or use `kit sync install <target>` for one-shot syncing instead.'
+    );
+  }
+}
+
+export async function watchKit(targets, opts = {}) {
+  const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
+  const kitRoot     = resolveKitRoot(opts.kitRoot);
+  const mode        = opts.mode ?? 'reference';
+  // PERF-16-02: bump default 300 → 500ms to coalesce IDE save-bursts (typical
+  // IDE auto-save fires 5-10 events in < 500ms during a single user save).
+  const debounceMs  = Number.isFinite(opts.debounceMs) ? opts.debounceMs : 500;
+  const onLog       = opts.onLog ?? (() => {});
+
+  if (!Array.isArray(targets) || targets.length === 0) {
+    throw new Error('watchKit: targets[] required (or use detectTargets()).');
+  }
+
+  // Initial sync
+  for (const t of targets) {
+    const r = await syncTo(t, { projectRoot, kitRoot, mode });
+    onLog(`✓ initial sync → ${t} (${r.written.length} files)`);
+  }
+
+  const chokidar = await loadChokidar();
+  const watcher = chokidar.watch(kitRoot, {
+    ignored: (p) => /(^|[/\\])\.[^/\\]/.test(p),  // ignore dotfiles/dotdirs
+    persistent: true,
+    ignoreInitial: true,
+    awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 },
+  });
+
+  let pending = null;
+  const trigger = (label, p) => {
+    onLog(`${label} ${path.relative(kitRoot, p)}`);
+    if (pending) clearTimeout(pending);
+    pending = setTimeout(async () => {
+      pending = null;
+      // PERF-16-02: invalidate kitCache (TTL 30s in kit.js PERF-01) BEFORE
+      // re-sync — otherwise listKit() inside syncTo can return the pre-edit
+      // cached value if the burst happened within the TTL window. Coalescing
+      // the edit-burst via debounce means clearKitCache fires AT MOST ONCE
+      // per 500ms window, regardless of how many save events came in.
+      clearKitCache();
+      for (const t of targets) {
+        try {
+          const r = await syncTo(t, { projectRoot, kitRoot, mode });
+          onLog(`↻ resynced → ${t} (${r.written.length} files)`);
+        } catch (e) {
+          onLog(`✗ resync → ${t}: ${e.message}`);
+        }
+      }
+    }, debounceMs);
+  };
+
+  watcher.on('add',    (p) => trigger('+', p));
+  watcher.on('change', (p) => trigger('~', p));
+  watcher.on('unlink', (p) => trigger('-', p));
+  watcher.on('error',  (e) => onLog(`! watcher error: ${e.message}`));
+
+  return {
+    stop: async () => {
+      if (pending) { clearTimeout(pending); pending = null; }
+      await watcher.close();
+      onLog('watcher stopped');
+    },
+  };
+}
+
+// Detect which targets currently have any files projected into projectRoot.
+// Used by `--all` so the user doesn't have to re-list IDEs they already synced to.
+export async function detectExistingTargets(opts = {}) {
+  const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
+  const all = listTargets();
+  const existing = [];
+  for (const t of all) {
+    // We just check if at least one of the capability directories/files exists.
+    const probes = [];
+    const reg = (await import('./registry.js')).getTarget(t.id);
+    if (reg.rules)    probes.push(path.join(projectRoot, reg.rules.path));
+    if (reg.agents)   probes.push(path.join(projectRoot, reg.agents.path));
+    if (reg.commands) probes.push(path.join(projectRoot, reg.commands.path));
+    if (reg.skills)   probes.push(path.join(projectRoot, reg.skills.path));
+    let found = false;
+    for (const p of probes) {
+      try { await fs.access(p); found = true; break; } catch {}
+    }
+    if (found) existing.push(t.id);
+  }
+  return existing;
+}

package/src/mcp-server/index.js

@@ -32,11 +32,18 @@ import { installMcp, listInstallTargets } from './install.js';
 import { ensureSidecar } from '../ui/auto-spawn.js';
 import { wrapProgressForUi } from '../ui/wrapper.js';
 import { incrementInvocation, recordLatency, snapshot as metricsSnapshot, persistSnapshot } from '../core/metrics.js';
+import { logEvent } from '../core/logger.js';
+import { notify, isNotifyEnabled } from '../core/notify.js';
+// Note: roots.js is imported dynamically inside handlers that need it
+// (handleAutoInstall, handleAckRestart) — keeps boot path minimal.
 
 const TOOLS = [
   {
     name: 'kit',
-    description: 'Browse the personal kit: agents, commands, skills.',
+    // Phase 170 (v1.29): description enriched with trigger keywords so MCP
+    // hosts route here on relevant intents even in MCP-pure mode (before
+    // auto-install made .claude/ native). Keep under 1024 chars (host limit).
+    description: 'Browse the personal kit: 66 agents, 89 commands, 76 skills. Call this when the user mentions Supabase (RLS, branching, migrations, Edge Functions, Custom Claims, Postgres Roles, Storage, Realtime, pgvector), multi-tenant SaaS, agentic harness, characterization tests, legacy refactor, observability (SLO, golden signals, error budgets), DDIA topics (consistency, replication lag, schema evolution), SRE (postmortems, toil, PRR), CI/CD (hermetic builds, pipelines), or any workflow that benefits from the canonical patterns. Use action=search to discover, action=get to read the full prompt/skill.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -143,6 +150,37 @@ const TOOLS = [
       properties: {},
     },
   },
+  {
+    // Phase 167 (v1.29): auto-sync the kit content into the host project's
+    // .claude/ (or equivalent) directory so agents become real subagent_types,
+    // skills get native auto-trigger, and commands appear as slash-commands.
+    // Idempotent — re-runs are no-ops if .claude/.kit-mcp-version matches the
+    // running server's package version. Permission-gated by the host.
+    name: 'auto-install',
+    description: 'IMPORTANT for first contact: project kit/ into the host\'s native layout (.claude/agents/, skills/, commands/) so 66 agents become real subagent_types in the Agent tool, 76 skills get native auto-trigger via descriptions, and 89 commands appear as /slash-commands in the IDE. Idempotent — re-running is a no-op if already in sync. Run once per project on first kit-mcp contact; restart the IDE session after to load the new agents/skills/commands. After restart, call ack-restart to clear the marker.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action:      { type: 'string', enum: ['install', 'check'], description: 'install: write files. check: read-only drift report. Default: install.' },
+        target:      { type: 'string', description: 'IDE id (claude-code, cursor, …). Defaults to claude-code.' },
+        projectRoot: { type: 'string', description: 'Override the auto-detected project root. Usually omitted — server reads it from MCP roots capability.' },
+        force:       { type: 'boolean', description: 'Re-write even if .kit-mcp-version already matches. Default: false.' },
+      },
+    },
+  },
+  {
+    // Phase 168 (v1.29): acknowledge the restart-required marker after the
+    // user reloads the IDE session. Removes .claude/.kit-mcp-restart-required
+    // so doctor stops flagging it.
+    name: 'ack-restart',
+    description: 'Acknowledge that the IDE session was restarted after kit:auto-install. Removes the .kit-mcp-restart-required marker so kit:doctor stops warning. Called automatically by the harness when it detects the marker after reload, or manually by the user.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectRoot: { type: 'string' },
+      },
+    },
+  },
 ];
 
 // DRIFT-13-03: read version from package.json at module load (NOT inside
@@ -316,6 +354,163 @@ async function handleInstall(args) {
 let _lastAutoPersistTs = 0;
 const AUTO_PERSIST_THROTTLE_MS = 1000;
 
+// Phase 167 (v1.29): auto-install handler.
+// Bridges MCP → host-native integration by writing kit/ files into .claude/
+// (or whatever the target IDE expects). Idempotent via .kit-mcp-version marker.
+// Phase 168 hooks add the restart_recommended signal to the result.
+async function handleAutoInstall(args) {
+  const action = args.action || 'install';
+  const target = args.target || 'claude-code';
+  const force = !!args.force;
+
+  // Resolve projectRoot: explicit arg > cwd fallback. (Future v1.30 will add
+  // MCP `roots` capability consumer for a tighter projectRoot signal — for now
+  // we use cwd to keep the boot path race-free with the SDK init handshake.)
+  let projectRoot = args.projectRoot;
+  const _rootsSource = projectRoot ? 'explicit' : 'cwd';
+  if (!projectRoot) projectRoot = process.cwd();
+
+  // SEC-14-03: validate project root (allowlist-of-1 — must be a real dir).
+  const guard = await validateProjectRoot(projectRoot);
+  if (!guard.ok) {
+    return { ok: false, reason: guard.reason, projectRoot, rootsSource: _rootsSource };
+  }
+  projectRoot = guard.resolvedPath;
+
+  const fs = await import('node:fs/promises');
+  const path = await import('node:path');
+  const markerPath = path.join(projectRoot, '.claude', '.kit-mcp-version');
+
+  // Read current marker if present.
+  let currentVersion = null;
+  try {
+    currentVersion = (await fs.readFile(markerPath, 'utf8')).trim();
+  } catch { /* not installed yet */ }
+
+  const targetVersion = PKG_VERSION;
+  const inSync = currentVersion === targetVersion;
+
+  // Phase 167 — action=check: read-only drift report.
+  if (action === 'check') {
+    return {
+      ok: true,
+      action: 'check',
+      target,
+      projectRoot,
+      rootsSource: _rootsSource,
+      installedVersion: currentVersion,
+      currentVersion: targetVersion,
+      inSync,
+      restartRecommended: false,
+    };
+  }
+
+  // action=install: skip if in sync and not forced.
+  if (inSync && !force) {
+    return {
+      ok: true,
+      action: 'install',
+      target,
+      projectRoot,
+      rootsSource: _rootsSource,
+      version: targetVersion,
+      skipped: true,
+      reason: 'already in sync',
+      restartRecommended: false,
+    };
+  }
+
+  // Run the sync.
+  let syncResult;
+  try {
+    syncResult = await syncTo(target, { projectRoot, mode: 'reference', dryRun: false });
+  } catch (e) {
+    return {
+      ok: false,
+      action: 'install',
+      target,
+      projectRoot,
+      rootsSource: _rootsSource,
+      reason: `sync_failed: ${e.message}`,
+    };
+  }
+
+  // Write/update marker file (.claude/.kit-mcp-version).
+  try {
+    await fs.mkdir(path.dirname(markerPath), { recursive: true });
+    await fs.writeFile(markerPath, targetVersion + '\n', 'utf8');
+  } catch (e) {
+    // Marker is best-effort — sync already succeeded. Just warn.
+    process.stderr.write(`[kit-mcp] auto-install marker write failed: ${e.message}\n`);
+  }
+
+  // Phase 168 (v1.29): write .kit-mcp-restart-required so doctor/host can detect
+  // pending restart even if the user closes/reopens kit-mcp without restarting IDE.
+  try {
+    const restartMarker = path.join(projectRoot, '.claude', '.kit-mcp-restart-required');
+    const payload = JSON.stringify({
+      version: targetVersion,
+      previousVersion: currentVersion,
+      writtenAt: new Date().toISOString(),
+      reason: currentVersion
+        ? `Kit updated ${currentVersion} → ${targetVersion}`
+        : 'Initial kit install',
+    }, null, 2);
+    await fs.writeFile(restartMarker, payload + '\n', 'utf8');
+  } catch (e) {
+    process.stderr.write(`[kit-mcp] restart marker write failed: ${e.message}\n`);
+  }
+
+  return {
+    ok: true,
+    action: 'install',
+    target,
+    projectRoot,
+    rootsSource: _rootsSource,
+    version: targetVersion,
+    previousVersion: currentVersion,
+    written: (syncResult.written || []).length,
+    restartRecommended: true,
+    _kit_action: 'session_restart_recommended',
+    _kit_reason: currentVersion
+      ? `Kit updated from ${currentVersion} to ${targetVersion} — restart the IDE session so agents/skills/commands reload.`
+      : `Kit installed (v${targetVersion}) into ${path.join('.claude', '')} — restart the IDE session for native subagent_type + slash-command + skill auto-trigger integration.`,
+  };
+}
+
+// Phase 168 (v1.29): acknowledge that the IDE was restarted after a kit:auto-install.
+// Removes the .kit-mcp-restart-required marker. Read by kit:doctor (Phase 171)
+// to stop flagging "pending restart".
+async function handleAckRestart(args) {
+  let projectRoot = args.projectRoot || process.cwd();
+
+  const guard = await validateProjectRoot(projectRoot);
+  if (!guard.ok) return { ok: false, reason: guard.reason, projectRoot };
+  projectRoot = guard.resolvedPath;
+
+  const fs = await import('node:fs/promises');
+  const path = await import('node:path');
+  const restartMarker = path.join(projectRoot, '.claude', '.kit-mcp-restart-required');
+
+  let acked = false;
+  try {
+    await fs.unlink(restartMarker);
+    acked = true;
+  } catch (e) {
+    if (e.code !== 'ENOENT') {
+      return { ok: false, reason: `unlink_failed: ${e.message}`, projectRoot };
+    }
+    // ENOENT — nothing to ack, already clean. Not an error.
+  }
+
+  return {
+    ok: true,
+    projectRoot,
+    acked,
+    reason: acked ? 'restart marker removed' : 'no restart marker present (nothing to ack)',
+  };
+}
+
 async function handleMetricsSnapshot() {
   const payload = metricsSnapshot();
   const now = Date.now();
@@ -334,13 +529,22 @@ async function handleMetricsSnapshot() {
 }
 
 const HANDLERS = {
-  kit:               handleKit,
-  sync:              handleSync,
-  'reverse-sync':    handleReverseSync,
-  gates:             handleGates,
-  forensics:         handleForensics,
-  install:           handleInstall,
+  kit:                handleKit,
+  sync:               handleSync,
+  'reverse-sync':     handleReverseSync,
+  gates:              handleGates,
+  forensics:          handleForensics,
+  install:            handleInstall,
   'metrics-snapshot': handleMetricsSnapshot,
+  'auto-install':     handleAutoInstall,
+  'ack-restart':      handleAckRestart,
+};
+
+// Phase 167+168 test affordances — exported for unit coverage.
+// Production callers should go through the MCP dispatch (HANDLERS map).
+export const __TEST_HANDLERS = {
+  handleAutoInstall,
+  handleAckRestart,
 };
 
 function slim(x) {
@@ -363,7 +567,7 @@ function slimTerse(x) {
 export async function createServer() {
   const server = new Server(
     { name: 'kit-mcp', version: PKG_VERSION },
-    { capabilities: { tools: {} } }
+    { capabilities: { tools: {} } },
   );
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
@@ -384,18 +588,58 @@ export async function createServer() {
     // being ready. Date.now() is sub-millisecond-cheap and aligns with the bucket
     // granularity we report (50/100/250/500ms thresholds in CONTEXT.md).
     const start = Date.now();
+    const argsSize = args ? JSON.stringify(args).length : 0;
     try {
       const result = await handler(args ?? {});
-      recordLatency(name, Date.now() - start);
+      const duration = Date.now() - start;
+      recordLatency(name, duration);
       incrementInvocation(name, 'ok');
+      // Phase 158 (v1.28): JSONL log per tool call → ~/.kit-mcp/logs/*.log.
+      // Fire-and-forget; never blocks the handler.
+      try {
+        const ev = {
+          tool: name,
+          action: args?.action,
+          args_size: argsSize,
+          result_size: result ? JSON.stringify(result).length : 0,
+          duration_ms: duration,
+          status: 'ok',
+        };
+        // Phase 163 (v1.28): when KIT_MCP_INSPECT=1, also capture raw args/result
+        // so `kit inspect` can render full request/response live. Off by default
+        // because payloads can be large and may contain user paths.
+        if (process.env.KIT_MCP_INSPECT === '1' || process.env.KIT_MCP_INSPECT === 'true') {
+          ev.args = args ?? null;
+          ev.result = result ?? null;
+        }
+        logEvent(ev);
+      } catch { /* swallow */ }
+      // Phase 164 (v1.28): opt-in OS notification on success path.
+      if (isNotifyEnabled()) {
+        try { notify({ title: `kit-mcp ${name}`, body: `${args?.action ?? ''} ok (${duration}ms)` }); } catch { /* swallow */ }
+      }
       return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
     } catch (e) {
       // OBS-18: still record latency on the error path — half the value of a
       // latency histogram is catching tail-latency-then-fail patterns. Status
       // 'error' covers any thrown exception, including Phase 79.01 gates guard
       // and the validateProjectRoot rejection (Phase 83.01).
-      recordLatency(name, Date.now() - start);
+      const duration = Date.now() - start;
+      recordLatency(name, duration);
       incrementInvocation(name, 'error');
+      try {
+        logEvent({
+          tool: name,
+          action: args?.action,
+          args_size: argsSize,
+          duration_ms: duration,
+          status: 'error',
+          error_type: e?.code || e?.name || 'Error',
+        });
+      } catch { /* swallow */ }
+      if (isNotifyEnabled()) {
+        try { notify({ title: `kit-mcp ${name} (error)`, body: e?.code || e?.name || 'Error' }); } catch { /* swallow */ }
+      }
       // SEC-14-06: full stack stays in stderr for operator debug; client envelope is sanitized.
       // sanitizeMcpError redacts secrets/paths from e.message, preserves e.code (Phase 83
       // EMANIFESTMISMATCH invariant), and emits NO stack field.
@@ -415,6 +659,7 @@ export async function startStdio() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
 
+
   // SRE-20-02 (Phase 105): pre-warm the kit cache to push MCP dispatch p95
   // below 100ms. Without this, the very first tools/call against `kit` pays
   // the full disk read (~144ms baseline on the v1.17 reference machine; ~96ms
@@ -424,4 +669,25 @@ export async function startStdio() {
   // the boot path, where it's invisible behind IDE startup. See skill
   // production-readiness-review (Performance axe) for the rationale.
   listKit(BUNDLED_KIT_ROOT).catch(() => {});
+
+  // Phase 157 (v1.28): sidecar UI auto-spawn ON by default. Resolves the
+  // "kit-mcp has no terminal feedback" pain — operators can now see live
+  // tool calls in a browser without needing to set autoSpawn: true per tool.
+  // Escape hatch: KIT_MCP_NO_UI=1 (CI, headless, opt-out). Fire-and-forget:
+  // sidecar failure must never block the MCP transport (spec requires clean
+  // stdout). Errors are swallowed silently — kit doctor will surface them.
+  //
+  // Skip when running under node --test (or coverage) to avoid leaking detached
+  // child processes that hold the event loop and cause non-zero exits. Same
+  // for CI=true (GitHub Actions, etc.) — sidecar is interactive and meaningless
+  // there. End users running locally still get the default-on behavior.
+  const isTestRun = (process.execArgv || []).some(
+    (a) => a === '--test' || a === '--experimental-test-coverage',
+  ) || process.env.NODE_TEST_CONTEXT !== undefined;
+  const noUi = process.env.KIT_MCP_NO_UI === '1' || process.env.KIT_MCP_NO_UI === 'true';
+  const isCi = process.env.CI === 'true' || process.env.CI === '1';
+  if (!noUi && !isTestRun && !isCi) {
+    const projectRoot = process.cwd();
+    ensureSidecar({ projectRoot, openBrowserOnSpawn: false }).catch(() => {});
+  }
 }