agent-orchestrator-kit 0.3.0 → 0.5.0

package/bin/agent-orchestrator.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { program } from 'commander';
 import pc from 'picocolors';
-import { readFileSync, existsSync, mkdirSync, copyFileSync, readdirSync, statSync, writeFileSync, rmSync, renameSync } from 'fs';
+import { readFileSync, existsSync, mkdirSync, copyFileSync, readdirSync, statSync, writeFileSync, rmSync, renameSync, chmodSync } from 'fs';
 import { join, dirname, basename, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
@@ -12,22 +12,23 @@ const KIT_VERSION = JSON.parse(readFileSync(join(KIT_ROOT, 'package.json'), 'utf
 
 const VALID_PROFILES = ['generic', 'vue3', 'node', 'mvp'];
 
-const KIT_SKILL_DIRS = [
-  'agent-orchestration',
-  'openspec-howto',
-  'openspec-explore',
-  'openspec-propose',
-  'openspec-apply-change',
-  'openspec-archive-change',
-  'openspec-sync-specs',
-  'spec-workflow-openspec',
-];
+function listTemplateKitSkillDirs() {
+  const skillsDir = join(KIT_ROOT, 'templates', '.agents', 'skills');
+  if (!existsSync(skillsDir)) return [];
+  return readdirSync(skillsDir)
+    .filter((name) => {
+      if (name.startsWith('subagent-')) return false;
+      const full = join(skillsDir, name);
+      return existsSync(full) && statSync(full).isDirectory();
+    })
+    .sort();
+}
 
 const KIT_MANAGED_PATHS = [
   '.agents/commands',
   '.agents/rules',
   '.agents/subagents',
-  ...KIT_SKILL_DIRS.map((s) => `.agents/skills/${s}`),
+  ...listTemplateKitSkillDirs().map((s) => `.agents/skills/${s}`),
   'scripts/sync-local-agent-skills.sh',
 ];
 
@@ -66,6 +67,8 @@ const GITIGNORE_LINES = [
   '.amp/settings.json',
   '.claude',
   '.agents/figma.local.env',
+  '.agents/github.local.env',
+  '.agents/gitlab.local.env',
 ];
 
 const FIGMA_ENV_REL = join('.agents', 'figma.local.env');
@@ -73,17 +76,67 @@ const FIGMA_ENV_EXAMPLE_REL = join('.agents', 'figma.local.env.example');
 const FIGMA_LAUNCHER_REL = join('scripts', 'figma-mcp-launcher.cjs');
 const MEMORY_LAUNCHER_REL = join('scripts', 'memory-mcp-launcher.cjs');
 const MEMORY_FILE_REL = join('.cursor', 'memory.json');
+const GITHUB_ENV_REL = join('.agents', 'github.local.env');
+const GITHUB_ENV_EXAMPLE_REL = join('.agents', 'github.local.env.example');
+const GITHUB_LAUNCHER_REL = join('scripts', 'github-mcp-launcher.cjs');
+const GITLAB_ENV_REL = join('.agents', 'gitlab.local.env');
+const GITLAB_ENV_EXAMPLE_REL = join('.agents', 'gitlab.local.env.example');
+const GITLAB_LAUNCHER_REL = join('scripts', 'gitlab-mcp-launcher.cjs');
+const BROWSER_LAUNCHER_REL = join('scripts', 'browser-mcp-launcher.cjs');
+const HOOK_SCRIPT_REL = join('scripts', 'pre-commit-gate-check.sh');
+const MCP_EXAMPLE_REL = join('.agents', 'mcp.json.example');
+const AMP_EXAMPLE_REL = join('.agents', 'amp.settings.json.example');
+const OPTIONAL_MCP_SEED_STRIP = ['github', 'gitlab', 'browser'];
+const HOOK_MARKER = '# agent-orchestrator-kit gate';
+const HOOK_LINE = 'sh scripts/pre-commit-gate-check.sh';
+const DEFAULT_GITLAB_API_URL = 'https://gitlab.com/api/v4';
+const DEFAULT_MCP_INVENTORY = {
+  baseline: ['memory'],
+  optional: ['figma', 'github', 'gitlab', 'browser'],
+};
 const FIGMA_MANAGED_PATHS = [
   FIGMA_ENV_EXAMPLE_REL,
   FIGMA_LAUNCHER_REL,
-  join('.agents', 'mcp.json.example'),
-  join('.agents', 'amp.settings.json.example'),
+  MCP_EXAMPLE_REL,
+  AMP_EXAMPLE_REL,
 ];
 const MEMORY_MANAGED_PATHS = [
   MEMORY_LAUNCHER_REL,
-  join('.agents', 'mcp.json.example'),
-  join('.agents', 'amp.settings.json.example'),
+  MCP_EXAMPLE_REL,
+  AMP_EXAMPLE_REL,
+];
+const OPTIONAL_MCP_MANAGED_PATHS = [
+  GITHUB_ENV_EXAMPLE_REL,
+  GITHUB_LAUNCHER_REL,
+  GITLAB_ENV_EXAMPLE_REL,
+  GITLAB_LAUNCHER_REL,
+  BROWSER_LAUNCHER_REL,
+  HOOK_SCRIPT_REL,
+  MCP_EXAMPLE_REL,
+  AMP_EXAMPLE_REL,
 ];
+const MCP_SERVER_CONFIGS = {
+  github: { command: 'node', args: [GITHUB_LAUNCHER_REL.replace(/\\/g, '/')] },
+  gitlab: { command: 'node', args: [GITLAB_LAUNCHER_REL.replace(/\\/g, '/')] },
+  browser: { command: 'node', args: [BROWSER_LAUNCHER_REL.replace(/\\/g, '/')] },
+};
+const MCP_TOOL_META = {
+  memory: { launcher: MEMORY_LAUNCHER_REL, envRel: null, tokenKeys: [] },
+  figma: { launcher: FIGMA_LAUNCHER_REL, envRel: FIGMA_ENV_REL, tokenKeys: ['FIGMA_ACCESS_TOKEN', 'FIGMA_API_KEY'] },
+  github: {
+    launcher: GITHUB_LAUNCHER_REL,
+    envRel: GITHUB_ENV_REL,
+    tokenKeys: ['GITHUB_PERSONAL_ACCESS_TOKEN', 'GITHUB_TOKEN'],
+    vcs: 'github',
+  },
+  gitlab: {
+    launcher: GITLAB_LAUNCHER_REL,
+    envRel: GITLAB_ENV_REL,
+    tokenKeys: ['GITLAB_PERSONAL_ACCESS_TOKEN', 'GITLAB_TOKEN'],
+    vcs: 'gitlab',
+  },
+  browser: { launcher: BROWSER_LAUNCHER_REL, envRel: null, tokenKeys: [] },
+};
 const AMP_SPAWN_PREAMBLE =
   'CRITICAL (Amp / Cursor / Claude): Parent MUST spawn this skill as an isolated subagent with fresh context. Do not execute it in the main thread. If spawn is unavailable, STOP and report blocked — do not perform this specialist\'s work in the parent. Return only the structured subagent report.';
 const HANDOFF_REQUIRED_SECTIONS = ['Closed role', 'Done', 'Next command'];
@@ -98,8 +151,12 @@ const HANDOFF_SECTIONS = [
   'Attach',
   'Subagents to spawn',
   'Constraints',
+  'Runtime',
   'Prompt',
 ];
+const CLOUD_ENV_MARKERS = ['CURSOR_BACKGROUND_AGENT'];
+const VALID_RUNTIMES = new Set(['local', 'cloud']);
+const CLOUD_PUSH_HINT = 'git push -u origin HEAD';
 
 const log = {
   info: (msg) => console.log(pc.cyan('  →'), msg),
@@ -281,6 +338,417 @@ function refreshMemoryManagedFiles(projectDir) {
   }
 }
 
+function chmodX(filePath) {
+  try {
+    chmodSync(filePath, 0o755);
+  } catch {}
+}
+
+function refreshManagedRelPaths(projectDir, rels) {
+  const templateDir = join(KIT_ROOT, 'templates');
+  for (const rel of rels) {
+    const src = join(templateDir, rel);
+    const dest = join(projectDir, rel);
+    if (!existsSync(src)) continue;
+    mkdirSync(dirname(dest), { recursive: true });
+    copyFileSync(src, dest);
+    if (rel.endsWith('.sh')) chmodX(dest);
+    log.ok(rel);
+  }
+}
+
+function refreshOptionalMcpManagedFiles(projectDir) {
+  refreshManagedRelPaths(projectDir, OPTIONAL_MCP_MANAGED_PATHS);
+}
+
+function parseGitRemoteHostname(url) {
+  const raw = String(url || '').trim();
+  if (!raw) return '';
+  try {
+    if (/^(https?|ssh|git):\/\//i.test(raw)) {
+      return new URL(raw).hostname.replace(/^www\./i, '').toLowerCase();
+    }
+  } catch {}
+  const scp = raw.match(/^(?:[^@\s]+@)?([^:/\s]+)[:/]/);
+  return scp ? scp[1].replace(/^www\./i, '').toLowerCase() : '';
+}
+
+function detectVcsHostFromRemoteUrl(url) {
+  const hostname = parseGitRemoteHostname(url);
+  if (!hostname) return { kind: 'none', hostname: '', apiUrl: '' };
+  if (hostname === 'github.com') return { kind: 'github', hostname, apiUrl: '' };
+  if (hostname === 'gitlab.com' || hostname.includes('gitlab')) {
+    return { kind: 'gitlab', hostname, apiUrl: `https://${hostname}/api/v4` };
+  }
+  return { kind: 'none', hostname, apiUrl: '' };
+}
+
+function readGitOriginUrl(projectDir) {
+  try {
+    return execSync('git remote get-url origin', {
+      cwd: projectDir,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf-8',
+    }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function detectVcsHost(projectDir) {
+  return detectVcsHostFromRemoteUrl(readGitOriginUrl(projectDir));
+}
+
+function gitConfigGet(projectDir, key) {
+  try {
+    return execSync(`git config --get ${key}`, {
+      cwd: projectDir,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf-8',
+    }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function isGitRepo(projectDir) {
+  try {
+    execSync('git rev-parse --is-inside-work-tree', {
+      cwd: projectDir,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isKitHooksPath(value) {
+  const v = String(value || '').trim().replace(/\\/g, '/').replace(/\/+$/, '');
+  return v === '.githooks' || v.endsWith('/.githooks');
+}
+
+function ensureHookLine(filePath, { shebang = false } = {}) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  let content = existsSync(filePath) ? readFileSync(filePath, 'utf-8') : shebang ? '#!/usr/bin/env sh\n' : '';
+  if (content.includes('pre-commit-gate-check.sh')) {
+    chmodX(filePath);
+    return { added: false };
+  }
+  const prefix = content.length > 0 && !content.endsWith('\n') ? '\n' : '';
+  writeFileSync(filePath, `${content}${prefix}${HOOK_MARKER}\n${HOOK_LINE}\n`);
+  chmodX(filePath);
+  return { added: true };
+}
+
+function runHooksSetup(projectDir) {
+  refreshManagedRelPaths(projectDir, [HOOK_SCRIPT_REL]);
+  const huskyDir = join(projectDir, '.husky');
+  if (existsSync(huskyDir) && statSync(huskyDir).isDirectory()) {
+    const result = ensureHookLine(join(huskyDir, 'pre-commit'));
+    if (result.added) log.ok('.husky/pre-commit ← gate line');
+    else log.ok('.husky/pre-commit already has gate line');
+    return { ok: true, mode: 'husky' };
+  }
+
+  if (!isGitRepo(projectDir)) {
+    log.err('not a git repository — run git init, then re-run hooks-setup');
+    return { ok: false, mode: 'none' };
+  }
+
+  const current = gitConfigGet(projectDir, 'core.hooksPath');
+  if (current && !isKitHooksPath(current)) {
+    log.err(`refusing to overwrite core.hooksPath (${current})`);
+    log.info('Add this line to your existing pre-commit hook:');
+    log.info(`  ${HOOK_LINE}`);
+    log.info('Or reset: git config --unset core.hooksPath  then re-run hooks-setup');
+    return { ok: false, mode: 'foreign' };
+  }
+
+  const result = ensureHookLine(join(projectDir, '.githooks', 'pre-commit'), { shebang: true });
+  if (result.added) log.ok('.githooks/pre-commit');
+  else log.ok('.githooks/pre-commit already present');
+  if (!isKitHooksPath(current)) {
+    execSync('git config core.hooksPath .githooks', { cwd: projectDir, stdio: 'pipe' });
+    log.ok('core.hooksPath = .githooks');
+  } else {
+    log.ok('core.hooksPath already .githooks');
+  }
+  return { ok: true, mode: 'githooks' };
+}
+
+function ensureEnvFromExample(projectDir, destRel, exampleRel) {
+  const dest = join(projectDir, destRel);
+  const example = join(projectDir, exampleRel);
+  const kitExample = join(KIT_ROOT, 'templates', exampleRel);
+  if (existsSync(dest)) return { created: false, path: dest };
+  const src = existsSync(example) ? example : kitExample;
+  if (!existsSync(src)) throw new Error(`Missing template: ${exampleRel}`);
+  mkdirSync(dirname(dest), { recursive: true });
+  copyFileSync(src, dest);
+  return { created: true, path: dest };
+}
+
+function upsertEnvKey(filePath, key, value) {
+  const raw = existsSync(filePath) ? readFileSync(filePath, 'utf-8') : '';
+  const re = new RegExp(`^${key}=.*$`, 'm');
+  const line = `${key}=${value}`;
+  const next = re.test(raw)
+    ? raw.replace(re, line)
+    : `${raw}${raw && !raw.endsWith('\n') ? '\n' : ''}${line}\n`;
+  writeFileSync(filePath, next.endsWith('\n') ? next : `${next}\n`);
+}
+
+function envHasAnyKey(projectDir, envRel, keys) {
+  if (!envRel || !keys.length) return true;
+  const values = parseEnvFile(join(projectDir, envRel));
+  return keys.some((key) => Boolean(values[key]));
+}
+
+function readJsonFile(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function stripMcpServers(filePath, serversKey, names) {
+  if (!existsSync(filePath) || !names.length) return;
+  const cfg = readJsonFile(filePath);
+  if (!cfg) return;
+  const servers = cfg[serversKey] || {};
+  let changed = false;
+  for (const name of names) {
+    if (servers[name]) {
+      delete servers[name];
+      changed = true;
+    }
+  }
+  if (!changed) return;
+  cfg[serversKey] = servers;
+  writeJsonFile(filePath, cfg);
+}
+
+function seedLiveMcpFromExample(livePath, examplePath, serversKey, stripNames, label) {
+  if (existsSync(livePath) || !existsSync(examplePath)) return false;
+  copyFileSync(examplePath, livePath);
+  stripMcpServers(livePath, serversKey, stripNames);
+  log.ok(`${label} created from example`);
+  return true;
+}
+
+function upsertMcpServer(cfg, key, name, server, label) {
+  const servers = cfg[key] || {};
+  if (servers[name]) {
+    log.ok(`${label} already has ${name} server`);
+  } else {
+    servers[name] = server;
+    log.ok(`${label} ← added ${name} server`);
+  }
+  cfg[key] = servers;
+  return cfg;
+}
+
+function writeMcpServerEntry(filePath, serversKey, name, server, label) {
+  if (!existsSync(filePath)) return;
+  const cfg = readJsonFile(filePath);
+  if (!cfg) {
+    log.warn(`${label} present but invalid JSON — merge ${name} server manually from .agents/mcp.json.example`);
+    return;
+  }
+  writeJsonFile(filePath, upsertMcpServer(cfg, serversKey, name, server, label));
+}
+
+function liveMcpHasServer(projectDir, name) {
+  const cursor = readJsonFile(join(projectDir, '.mcp.json'));
+  const amp = readJsonFile(join(projectDir, '.amp', 'settings.json'));
+  return Boolean(cursor?.mcpServers?.[name] || amp?.['amp.mcpServers']?.[name]);
+}
+
+function undetectedVcsNames(kind) {
+  if (kind === 'github') return ['gitlab'];
+  if (kind === 'gitlab') return ['github'];
+  return ['github', 'gitlab'];
+}
+
+function parseMcpInventory(content) {
+  const baseline = [];
+  const optional = [];
+  let inMcp = false;
+  let section = null;
+  for (const line of String(content || '').split('\n')) {
+    if (/^mcp:\s*$/.test(line)) {
+      inMcp = true;
+      section = null;
+      continue;
+    }
+    if (inMcp && /^\S/.test(line)) break;
+    if (!inMcp) continue;
+    if (/^\s+baseline:\s*$/.test(line)) {
+      section = 'baseline';
+      continue;
+    }
+    if (/^\s+optional:\s*$/.test(line)) {
+      section = 'optional';
+      continue;
+    }
+    const item = line.match(/^\s+-\s+([A-Za-z0-9_-]+)\s*$/);
+    if (item && section === 'baseline') baseline.push(item[1]);
+    else if (item && section === 'optional') optional.push(item[1]);
+  }
+  return { baseline, optional };
+}
+
+function readMcpInventory(projectDir) {
+  const orchPath = join(projectDir, '.agents', 'orchestrator.yaml');
+  if (!existsSync(orchPath)) return { ...DEFAULT_MCP_INVENTORY };
+  const parsed = parseMcpInventory(readFileSync(orchPath, 'utf-8'));
+  if (!parsed.baseline.length && !parsed.optional.length) return { ...DEFAULT_MCP_INVENTORY };
+  return parsed;
+}
+
+function parseSkillsInventory(content) {
+  const kit = [];
+  const stack = [];
+  let external = '';
+  let found = false;
+  let inSkills = false;
+  let section = null;
+  for (const line of String(content || '').split(/\r?\n/)) {
+    if (/^skills:\s*$/.test(line)) {
+      found = true;
+      inSkills = true;
+      section = null;
+      continue;
+    }
+    if (inSkills && /^\S/.test(line)) break;
+    if (!inSkills) continue;
+    if (/^\s+kit:\s*$/.test(line) || /^\s+kit:\s*\[\s*\]\s*$/.test(line)) {
+      section = 'kit';
+      continue;
+    }
+    if (/^\s+stack:\s*$/.test(line) || /^\s+stack:\s*\[\s*\]\s*$/.test(line)) {
+      section = 'stack';
+      continue;
+    }
+    const ext = line.match(/^\s+external:\s*(.*?)\s*$/);
+    if (ext) {
+      section = null;
+      let raw = ext[1];
+      if (
+        (raw.startsWith('"') && raw.endsWith('"') && raw.length >= 2) ||
+        (raw.startsWith("'") && raw.endsWith("'") && raw.length >= 2)
+      ) {
+        raw = raw.slice(1, -1);
+      }
+      external = raw;
+      continue;
+    }
+    const item = line.match(/^\s+-\s+([A-Za-z0-9_-]+)\s*$/);
+    if (item && section === 'kit') kit.push(item[1]);
+    else if (item && section === 'stack') stack.push(item[1]);
+  }
+  return { kit, stack, external, found };
+}
+
+function readSkillsInventory(projectDir) {
+  const fallback = { kit: listTemplateKitSkillDirs(), stack: [], external: '' };
+  const orchPath = join(projectDir, '.agents', 'orchestrator.yaml');
+  if (!existsSync(orchPath)) return fallback;
+  const parsed = parseSkillsInventory(readFileSync(orchPath, 'utf-8'));
+  if (!parsed.found) return fallback;
+  return { kit: parsed.kit, stack: parsed.stack, external: parsed.external };
+}
+
+function printMcpHealth(projectDir) {
+  const inventory = readMcpInventory(projectDir);
+  const tools = [...new Set([...inventory.baseline, ...inventory.optional])];
+  if (!tools.length) return;
+  const detected = detectVcsHost(projectDir);
+  console.log(pc.bold('\nMCP health'));
+  for (const name of tools) {
+    const meta = MCP_TOOL_META[name] || { launcher: join('scripts', `${name}-mcp-launcher.cjs`), envRel: null, tokenKeys: [] };
+    if (meta.vcs && detected.kind !== meta.vcs) {
+      console.log(`  ${name.padEnd(8)} skipped (no origin match)`);
+      continue;
+    }
+    const launcherOk = existsSync(join(projectDir, meta.launcher));
+    const tokenOk = envHasAnyKey(projectDir, meta.envRel, meta.tokenKeys);
+    const entryOk = liveMcpHasServer(projectDir, name);
+    const ok = launcherOk && tokenOk && entryOk;
+    console.log(`  ${name.padEnd(8)} ${ok ? 'ok' : 'not configured'}`);
+  }
+  console.log('');
+}
+
+function resolveMcpSetupVcs(projectDir, override) {
+  const detected = detectVcsHost(projectDir);
+  if (override === 'github' || override === 'gitlab') {
+    if (override === 'gitlab') {
+      const apiUrl = detected.kind === 'gitlab' && detected.apiUrl ? detected.apiUrl : DEFAULT_GITLAB_API_URL;
+      return { kind: 'gitlab', hostname: detected.kind === 'gitlab' ? detected.hostname : 'gitlab.com', apiUrl, overridden: true };
+    }
+    return { kind: 'github', hostname: detected.hostname || 'github.com', apiUrl: '', overridden: true };
+  }
+  return { ...detected, overridden: false };
+}
+
+function runMcpSetup(projectDir, { vcs = '', browser = true } = {}) {
+  refreshFigmaManagedFiles(projectDir);
+  refreshMemoryManagedFiles(projectDir);
+  refreshOptionalMcpManagedFiles(projectDir);
+  mergeGitignore(projectDir, GITIGNORE_LINES);
+
+  const selected = resolveMcpSetupVcs(projectDir, vcs);
+  if (selected.kind === 'github') log.info('VCS MCP: github');
+  else if (selected.kind === 'gitlab') log.info(`VCS MCP: gitlab (${selected.hostname})`);
+  else log.info('VCS MCP: skipped (no origin match)');
+
+  if (selected.kind === 'github') {
+    const env = ensureEnvFromExample(projectDir, GITHUB_ENV_REL, GITHUB_ENV_EXAMPLE_REL);
+    log.ok(env.created ? `Created ${GITHUB_ENV_REL}` : `${GITHUB_ENV_REL} already exists`);
+    if (!envHasAnyKey(projectDir, GITHUB_ENV_REL, ['GITHUB_PERSONAL_ACCESS_TOKEN', 'GITHUB_TOKEN'])) {
+      log.warn('GitHub token: missing — set GITHUB_PERSONAL_ACCESS_TOKEN in .agents/github.local.env (do not paste into chat)');
+    }
+  } else if (selected.kind === 'gitlab') {
+    const env = ensureEnvFromExample(projectDir, GITLAB_ENV_REL, GITLAB_ENV_EXAMPLE_REL);
+    log.ok(env.created ? `Created ${GITLAB_ENV_REL}` : `${GITLAB_ENV_REL} already exists`);
+    upsertEnvKey(env.path, 'GITLAB_API_URL', selected.apiUrl || DEFAULT_GITLAB_API_URL);
+    log.ok(`GITLAB_API_URL host: ${selected.hostname || 'gitlab.com'}`);
+    if (!envHasAnyKey(projectDir, GITLAB_ENV_REL, ['GITLAB_PERSONAL_ACCESS_TOKEN', 'GITLAB_TOKEN'])) {
+      log.warn('GitLab token: missing — set GITLAB_PERSONAL_ACCESS_TOKEN in .agents/gitlab.local.env (do not paste into chat)');
+    }
+  }
+
+  const cursorPath = join(projectDir, '.mcp.json');
+  const ampPath = join(projectDir, '.amp', 'settings.json');
+  const cursorExample = join(projectDir, MCP_EXAMPLE_REL);
+  const ampExample = join(projectDir, AMP_EXAMPLE_REL);
+  const stripOnCreate = [...undetectedVcsNames(selected.kind), ...(browser ? [] : ['browser'])];
+  seedLiveMcpFromExample(cursorPath, cursorExample, 'mcpServers', stripOnCreate, '.mcp.json');
+  mkdirSync(join(projectDir, '.amp'), { recursive: true });
+  seedLiveMcpFromExample(ampPath, ampExample, 'amp.mcpServers', stripOnCreate, '.amp/settings.json');
+
+  const namesToAdd = [];
+  if (selected.kind === 'github' || selected.kind === 'gitlab') namesToAdd.push(selected.kind);
+  if (browser) namesToAdd.push('browser');
+  for (const name of namesToAdd) {
+    const server = MCP_SERVER_CONFIGS[name];
+    writeMcpServerEntry(cursorPath, 'mcpServers', name, server, '.mcp.json');
+    writeMcpServerEntry(ampPath, 'amp.mcpServers', name, server, '.amp/settings.json');
+  }
+
+  if (!existsSync(cursorPath)) {
+    log.warn('.mcp.json missing — copy from .agents/mcp.json.example then re-run mcp-setup');
+  }
+  if (!existsSync(ampPath)) {
+    log.warn('.amp/settings.json missing — copy from .agents/amp.settings.json.example then re-run mcp-setup');
+  }
+
+  log.info('Restart Cursor / Amp after saving tokens');
+}
+
 function writeJsonFile(filePath, value) {
   mkdirSync(dirname(filePath), { recursive: true });
   writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
@@ -308,12 +776,9 @@ function ensureMemoryMcpEntry(projectDir) {
     log.ok('.cursor/memory.json created');
   }
 
-  const examplePath = join(projectDir, '.agents', 'mcp.json.example');
+  const examplePath = join(projectDir, MCP_EXAMPLE_REL);
   const cursorPath = join(projectDir, '.mcp.json');
-  if (!existsSync(cursorPath) && existsSync(examplePath)) {
-    copyFileSync(examplePath, cursorPath);
-    log.ok('.mcp.json created from example');
-  }
+  seedLiveMcpFromExample(cursorPath, examplePath, 'mcpServers', OPTIONAL_MCP_SEED_STRIP, '.mcp.json');
   if (existsSync(cursorPath)) {
     try {
       const cfg = upsertMemoryServer(JSON.parse(readFileSync(cursorPath, 'utf-8')), 'mcpServers', '.mcp.json');
@@ -324,12 +789,9 @@ function ensureMemoryMcpEntry(projectDir) {
   }
 
   mkdirSync(join(projectDir, '.amp'), { recursive: true });
-  const ampExample = join(projectDir, '.agents', 'amp.settings.json.example');
+  const ampExample = join(projectDir, AMP_EXAMPLE_REL);
   const ampPath = join(projectDir, '.amp', 'settings.json');
-  if (!existsSync(ampPath) && existsSync(ampExample)) {
-    copyFileSync(ampExample, ampPath);
-    log.ok('.amp/settings.json created from example');
-  }
+  seedLiveMcpFromExample(ampPath, ampExample, 'amp.mcpServers', OPTIONAL_MCP_SEED_STRIP, '.amp/settings.json');
   if (existsSync(ampPath)) {
     try {
       const cfg = upsertMemoryServer(JSON.parse(readFileSync(ampPath, 'utf-8')), 'amp.mcpServers', '.amp/settings.json');
@@ -378,8 +840,126 @@ function sectionOr(sections, title, fallback = '') {
   return value && value.trim() ? value.trim() : fallback;
 }
 
+function parseRuntimeBulletFields(body) {
+  const text = String(body || '');
+  const runtimeMatch = text.match(/(?:^|\n)\s*[-*]?\s*runtime:\s*(\S+)/i);
+  const agentMatch = text.match(/(?:^|\n)\s*[-*]?\s*agent_id:\s*(\S+)/i);
+  return {
+    runtime: runtimeMatch ? runtimeMatch[1].trim() : '',
+    agentId: agentMatch ? agentMatch[1].trim() : '',
+  };
+}
+
+function normalizeRuntimeToken(value) {
+  const v = String(value || '').trim().toLowerCase();
+  return VALID_RUNTIMES.has(v) ? v : '';
+}
+
+function resolveRuntime(opts, env, existingFields) {
+  const flag = opts && opts.runtime != null ? String(opts.runtime).trim() : '';
+  if (flag) {
+    const normalized = normalizeRuntimeToken(flag);
+    if (!normalized) return { error: 'invalid --runtime (use local or cloud)' };
+    return { value: normalized };
+  }
+  const fromEnv = normalizeRuntimeToken(env && env.AOK_RUNTIME);
+  if (fromEnv) return { value: fromEnv };
+  for (const key of CLOUD_ENV_MARKERS) {
+    const raw = env && env[key];
+    if (raw != null && String(raw).trim() !== '') return { value: 'cloud' };
+  }
+  const existing = normalizeRuntimeToken(existingFields && existingFields.runtime);
+  if (existing) return { value: existing };
+  return { value: 'local' };
+}
+
+function resolveAgentId(opts, env, existingFields) {
+  const flag = opts && opts.agentId != null ? String(opts.agentId).trim() : '';
+  if (flag) return flag;
+  const fromEnv = env && env.AOK_AGENT_ID != null ? String(env.AOK_AGENT_ID).trim() : '';
+  if (fromEnv) return fromEnv;
+  const existing = existingFields && existingFields.agentId != null ? String(existingFields.agentId).trim() : '';
+  if (existing) return existing;
+  return 'none';
+}
+
+function applyRuntimeToFields(fields, opts, env) {
+  const resolved = resolveRuntime(opts, env, fields);
+  if (resolved.error) {
+    log.err(resolved.error);
+    return false;
+  }
+  fields.runtime = resolved.value;
+  fields.agentId = resolveAgentId(opts, env, fields);
+  return true;
+}
+
+function gitTry(projectDir, command) {
+  try {
+    const stdout = execSync(command, {
+      cwd: projectDir,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf-8',
+    });
+    return { ok: true, stdout: String(stdout || '') };
+  } catch (e) {
+    return {
+      ok: false,
+      stdout: String((e && e.stdout) || ''),
+      stderr: String((e && e.stderr) || (e && e.message) || ''),
+    };
+  }
+}
+
+function porcelainChangePaths(stdout) {
+  return String(stdout || '')
+    .split('\n')
+    .map((line) => line.replace(/\r$/, ''))
+    .filter((line) => line.trim())
+    .map((line) => line.slice(3).trim());
+}
+
+function collectCloudCheckFindings(projectDir, name) {
+  const findings = [];
+  const rel = `openspec/changes/${name}/`;
+  const status = gitTry(projectDir, `git status --porcelain -- ${rel}`);
+  if (!status.ok) {
+    const detail = status.stderr.trim().split('\n')[0];
+    findings.push(detail ? `git status failed for ${rel}: ${detail}` : `git status failed for ${rel}`);
+    findings.push(CLOUD_PUSH_HINT);
+  } else {
+    findings.push(...porcelainChangePaths(status.stdout));
+  }
+
+  const upstream = gitTry(projectDir, "git rev-parse --abbrev-ref '@{upstream}'");
+  if (!upstream.ok) {
+    findings.push(CLOUD_PUSH_HINT);
+  } else {
+    const count = gitTry(projectDir, "git rev-list --count '@{upstream}..HEAD'");
+    if (!count.ok) {
+      findings.push(CLOUD_PUSH_HINT);
+    } else {
+      const n = Number.parseInt(String(count.stdout).trim(), 10);
+      if (!Number.isFinite(n) || n > 0) findings.push(CLOUD_PUSH_HINT);
+    }
+  }
+
+  return [...new Set(findings)];
+}
+
+function printCloudPersistNextSteps(name) {
+  console.error('Cloud session exit is incomplete until artifacts are on the remote:');
+  console.error(`  git add openspec/changes/${name}/`);
+  console.error('  git commit');
+  console.error('  git push');
+  console.error(`  npx agent-orchestrator-kit handoff ${name} --cloud-check`);
+  console.error('Require --cloud-check exit 0 before closing.');
+}
+
 function buildHandoffMarkdown(fields) {
   const prompt = fields.prompt ? `\n\n## Prompt\n\n\`\`\`text\n${fields.prompt}\n\`\`\`` : '';
+  const runtime = fields.runtime || 'local';
+  const agentId = fields.agentId || 'none';
   return `# Session Handoff
 
 ## Closed role
@@ -410,12 +990,17 @@ ${fields.attach}
 ${fields.spawn}
 
 ## Constraints
-${fields.constraints}${prompt}
+${fields.constraints}
+
+## Runtime
+- runtime: ${runtime}
+- agent_id: ${agentId}${prompt}
 `;
 }
 
 function fieldsFromSections(changeName, sections, extra = {}) {
   const nextCommand = extra.nextCommand || firstLineCommand(sectionOr(sections, 'Next command'));
+  const runtimeParsed = parseRuntimeBulletFields(sectionOr(sections, 'Runtime', ''));
   return {
     changeName,
     closedRole: extra.closedRole || sectionOr(sections, 'Closed role', extra.closedRole || ''),
@@ -428,6 +1013,8 @@ function fieldsFromSections(changeName, sections, extra = {}) {
     attach: extra.attach || sectionOr(sections, 'Attach', `- \`openspec/changes/${changeName}/\``),
     spawn: extra.spawn || sectionOr(sections, 'Subagents to spawn', ''),
     constraints: extra.constraints || sectionOr(sections, 'Constraints', ''),
+    runtime: extra.runtime || runtimeParsed.runtime,
+    agentId: extra.agentId || runtimeParsed.agentId,
     status: extra.status || '',
     tasks: extra.tasks || '',
     review: extra.review || '',
@@ -603,6 +1190,58 @@ function parseDecisionItems(text) {
     .filter((line) => line && !/^none$/i.test(line));
 }
 
+function decisionTopic(text) {
+  const value = String(text || '');
+  const topicMatch = value.match(/^([^:]+):/);
+  return (topicMatch ? topicMatch[1] : value).trim().slice(0, 80) || value.slice(0, 80);
+}
+
+function normalizeDecisionText(text) {
+  return String(text || '')
+    .trim()
+    .replace(/\s+/g, ' ');
+}
+
+function localIsoDate(now = new Date()) {
+  const y = now.getFullYear();
+  const m = String(now.getMonth() + 1).padStart(2, '0');
+  const d = String(now.getDate()).padStart(2, '0');
+  return `${y}-${m}-${d}`;
+}
+
+function decisionsFilePath(projectDir, changeName) {
+  return join(projectDir, 'openspec', 'changes', changeName, 'decisions.md');
+}
+
+function parseDecisionsFileEntries(content) {
+  const entries = [];
+  for (const line of String(content || '').split(/\r?\n/)) {
+    const match = line.match(/^- (\d{4}-\d{2}-\d{2}) (.+)$/);
+    if (match) entries.push({ date: match[1], text: match[2] });
+  }
+  return entries;
+}
+
+function appendDecisionsFromHandoff(projectDir, changeName, decisionsText) {
+  const items = parseDecisionItems(decisionsText);
+  if (!items.length) return;
+  const filePath = decisionsFilePath(projectDir, changeName);
+  const header = `# Decisions — ${changeName}\n\n<!-- append-only; пише npx agent-orchestrator-kit handoff <name> з handoff.md ## Decisions -->\n\n`;
+  let body = existsSync(filePath) ? readFileSync(filePath, 'utf-8') : header;
+  const seen = new Set(parseDecisionsFileEntries(body).map((entry) => normalizeDecisionText(entry.text)));
+  const date = localIsoDate();
+  const additions = [];
+  for (const item of items) {
+    const norm = normalizeDecisionText(item);
+    if (seen.has(norm)) continue;
+    seen.add(norm);
+    additions.push(`- ${date} ${item}`);
+  }
+  if (!additions.length) return;
+  if (!body.endsWith('\n')) body += '\n';
+  writeFileSync(filePath, `${body}${additions.join('\n')}\n`);
+}
+
 function persistMemoryFromHandoff(projectDir, fields) {
   const filePath = resolve(projectDir, MEMORY_FILE_REL);
   const items = loadMemoryItems(filePath);
@@ -625,10 +1264,11 @@ function persistMemoryFromHandoff(projectDir, fields) {
   ].filter(Boolean);
   if (handoffObs.length) upsertMemoryEntity(items, `Handoff:${name}`, 'Handoff', handoffObs);
 
-  for (const decision of parseDecisionItems(fields.decisions)) {
-    const topicMatch = decision.match(/^([^:]+):/);
-    const topic = (topicMatch ? topicMatch[1] : decision).trim().slice(0, 80) || decision.slice(0, 80);
-    upsertMemoryEntity(items, `Decision:${topic}`, 'Decision', [`chosen: ${decision}`]);
+  const decisionsPath = decisionsFilePath(projectDir, name);
+  if (existsSync(decisionsPath)) {
+    for (const entry of parseDecisionsFileEntries(readFileSync(decisionsPath, 'utf-8'))) {
+      upsertMemoryEntity(items, `Decision:${decisionTopic(entry.text)}`, 'Decision', [`chosen: ${entry.text}`]);
+    }
   }
 
   saveMemoryItems(filePath, items);
@@ -650,6 +1290,215 @@ function readHandoffFields(projectDir, changeName) {
   return { filePath, fields: fieldsFromSections(changeName, sections) };
 }
 
+const METRICS_VERSION = 1;
+const METRICS_SPEND_KEYS = ['inputTokens', 'outputTokens', 'totalTokens', 'costUsd'];
+
+function metricsFilePath(projectDir, changeName) {
+  return join(projectDir, 'openspec', 'changes', changeName, 'metrics.json');
+}
+
+function emptySpendTotals() {
+  return { inputTokens: null, outputTokens: null, totalTokens: null, costUsd: null };
+}
+
+function defaultMetrics(changeName, nowIso) {
+  return {
+    version: METRICS_VERSION,
+    change: changeName,
+    createdAt: nowIso,
+    updatedAt: nowIso,
+    archivedAt: null,
+    spend: emptySpendTotals(),
+    totals: { sessions: 0, durationMs: null, leadTimeMs: null, cloudSessions: 0 },
+    phases: {},
+    sessions: [],
+    pending: null,
+  };
+}
+
+function loadMetricsFile(filePath, changeName, nowIso) {
+  if (!existsSync(filePath)) return defaultMetrics(changeName, nowIso);
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(filePath, 'utf-8'));
+  } catch {
+    return defaultMetrics(changeName, nowIso);
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return defaultMetrics(changeName, nowIso);
+  }
+  const base = defaultMetrics(changeName, parsed.createdAt || nowIso);
+  return {
+    ...base,
+    ...parsed,
+    version: METRICS_VERSION,
+    change: changeName,
+    spend: { ...base.spend, ...(parsed.spend && typeof parsed.spend === 'object' ? parsed.spend : {}) },
+    totals: { ...base.totals, ...(parsed.totals && typeof parsed.totals === 'object' ? parsed.totals : {}) },
+    phases: parsed.phases && typeof parsed.phases === 'object' && !Array.isArray(parsed.phases) ? parsed.phases : {},
+    sessions: Array.isArray(parsed.sessions) ? parsed.sessions : [],
+  };
+}
+
+function saveMetricsFile(filePath, metrics) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, `${JSON.stringify(metrics, null, 2)}\n`);
+}
+
+function numOrNull(value) {
+  if (value == null || value === '') return null;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+function addNullable(a, b) {
+  if (a == null && b == null) return null;
+  return (a ?? 0) + (b ?? 0);
+}
+
+function phaseForRole(role) {
+  const value = String(role || '').toLowerCase();
+  if (/explor/.test(value)) return 'explore';
+  if (/review/.test(value)) return 'review';
+  if (/implement|apply|code-writer|test-writer/.test(value)) return 'apply';
+  if (/architect|propose/.test(value)) return 'spec';
+  if (/design/.test(value)) return 'design';
+  if (/archiv/.test(value)) return 'archive';
+  return 'other';
+}
+
+function isoOrNull(value) {
+  if (!value) return null;
+  const ms = Date.parse(String(value));
+  return Number.isFinite(ms) ? new Date(ms).toISOString() : null;
+}
+
+function recomputeMetricsAggregates(metrics) {
+  const phases = {};
+  const totals = { sessions: 0, durationMs: null, leadTimeMs: null, cloudSessions: 0 };
+  const spend = emptySpendTotals();
+  let firstStart = null;
+  let lastEnd = null;
+  for (const session of metrics.sessions) {
+    totals.sessions += 1;
+    if (session.runtime === 'cloud') totals.cloudSessions += 1;
+    totals.durationMs = addNullable(totals.durationMs, numOrNull(session.durationMs));
+    if (session.startedAt && (firstStart == null || session.startedAt < firstStart)) firstStart = session.startedAt;
+    if (session.endedAt && (lastEnd == null || session.endedAt > lastEnd)) lastEnd = session.endedAt;
+    const key = session.phase || 'other';
+    const phase = phases[key] || { sessions: 0, durationMs: null, ...emptySpendTotals(), agents: [], models: [] };
+    phase.sessions += 1;
+    phase.durationMs = addNullable(phase.durationMs, numOrNull(session.durationMs));
+    for (const spendKey of METRICS_SPEND_KEYS) {
+      const value = numOrNull(session[spendKey]);
+      phase[spendKey] = addNullable(phase[spendKey], value);
+      spend[spendKey] = addNullable(spend[spendKey], value);
+    }
+    if (session.role && !phase.agents.includes(session.role)) phase.agents.push(session.role);
+    if (session.model && !phase.models.includes(session.model)) phase.models.push(session.model);
+    phases[key] = phase;
+  }
+  if (firstStart && lastEnd) {
+    totals.leadTimeMs = Math.max(0, Date.parse(lastEnd) - Date.parse(firstStart));
+  }
+  metrics.phases = phases;
+  metrics.totals = totals;
+  metrics.spend = spend;
+}
+
+function metricsRecordSessionStart(projectDir, changeName, role) {
+  const filePath = metricsFilePath(projectDir, changeName);
+  const nowIso = new Date().toISOString();
+  const metrics = loadMetricsFile(filePath, changeName, nowIso);
+  metrics.pending = { startedAt: nowIso, role: role || '' };
+  metrics.updatedAt = nowIso;
+  saveMetricsFile(filePath, metrics);
+  return filePath;
+}
+
+function metricsRecordSessionEnd(projectDir, fields, opts = {}) {
+  const filePath = metricsFilePath(projectDir, fields.changeName);
+  const nowIso = new Date().toISOString();
+  const metrics = loadMetricsFile(filePath, fields.changeName, nowIso);
+  const startedAt = isoOrNull(opts.startedAt) || (metrics.pending && metrics.pending.startedAt) || null;
+  const durationMs = startedAt ? Math.max(0, Date.parse(nowIso) - Date.parse(startedAt)) : null;
+  const inputTokens = numOrNull(opts.inputTokens);
+  const outputTokens = numOrNull(opts.outputTokens);
+  let totalTokens = numOrNull(opts.totalTokens);
+  if (totalTokens == null && (inputTokens != null || outputTokens != null)) {
+    totalTokens = (inputTokens ?? 0) + (outputTokens ?? 0);
+  }
+  metrics.sessions.push({
+    startedAt,
+    endedAt: nowIso,
+    durationMs,
+    role: fields.closedRole || '',
+    phase: phaseForRole(fields.closedRole),
+    runtime: fields.runtime || 'local',
+    agentId: fields.agentId || 'none',
+    model: opts.model || null,
+    tasks: fields.tasks || null,
+    inputTokens,
+    outputTokens,
+    totalTokens,
+    costUsd: numOrNull(opts.costUsd),
+  });
+  metrics.pending = null;
+  metrics.updatedAt = nowIso;
+  recomputeMetricsAggregates(metrics);
+  saveMetricsFile(filePath, metrics);
+  return filePath;
+}
+
+function metricsFinalizeArchive(targetDir, changeName) {
+  const filePath = join(targetDir, 'metrics.json');
+  if (!existsSync(filePath)) return null;
+  const nowIso = new Date().toISOString();
+  const metrics = loadMetricsFile(filePath, changeName, nowIso);
+  metrics.archivedAt = nowIso;
+  metrics.pending = null;
+  metrics.updatedAt = nowIso;
+  recomputeMetricsAggregates(metrics);
+  saveMetricsFile(filePath, metrics);
+  return filePath;
+}
+
+function formatMetricsDuration(durationMs) {
+  if (durationMs == null || !Number.isFinite(durationMs)) return '—';
+  const totalSeconds = Math.max(0, Math.round(durationMs / 1000));
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+  if (hours > 0) return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
+  if (minutes > 0) return seconds > 0 ? `${minutes}m ${seconds}s` : `${minutes}m`;
+  return `${seconds}s`;
+}
+
+function formatMetricsNumber(value) {
+  return value == null ? '—' : String(value);
+}
+
+function formatMetricsCost(value) {
+  return value == null ? '—' : `$${Number(value).toFixed(2)}`;
+}
+
+function resolveMetricsFile(projectDir, changeName) {
+  const activePath = metricsFilePath(projectDir, changeName);
+  if (existsSync(activePath)) return { filePath: activePath, archived: false };
+  const archiveDir = join(projectDir, 'openspec', 'changes', 'archive');
+  if (existsSync(archiveDir)) {
+    const folders = readdirSync(archiveDir)
+      .filter((name) => name === changeName || name.endsWith(`-${changeName}`))
+      .sort()
+      .reverse();
+    for (const folder of folders) {
+      const archivedPath = join(archiveDir, folder, 'metrics.json');
+      if (existsSync(archivedPath)) return { filePath: archivedPath, archived: true };
+    }
+  }
+  return { filePath: activePath, archived: false, missing: true };
+}
+
 function parseFigmaUrl(url) {
   try {
     const parsed = new URL(url);
@@ -1016,6 +1865,19 @@ function gitDiffTouchesGlob(projectDir, base, srcGlob) {
   }
 }
 
+function gitStagedTouchesGlob(projectDir, srcGlob) {
+  try {
+    const out = execSync(`git diff --cached --name-only -- "${srcGlob}"`, {
+      cwd: projectDir,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf-8',
+    });
+    return out.trim().length > 0;
+  } catch {
+    return null;
+  }
+}
+
 function installOpenspecConfigExample(projectDir, profile, vars, force) {
   const src = resolveTemplate('openspec-config.yaml.example', profile);
   if (!existsSync(src)) return;
@@ -1197,18 +2059,21 @@ function printNextSteps(profile, projectDir, ci = 'github', specVerify = false)
   if (profile === 'vue3') {
     lines.push(`  3. Install Vue/JS stack skills:`);
     lines.push(`     ${pc.cyan('npx frontend-agent-skills install --agent all --yes')}`);
-    lines.push(`  4. MCP: copy .mcp.json (Cursor) / .amp/settings.json (Amp) from *.example files`);
+    lines.push(`  4. MCP: ${pc.cyan('npx agent-orchestrator-kit mcp-setup')} (GitHub/GitLab from origin + browser)`);
     lines.push(`  5. Optional Figma: ${pc.cyan('npx agent-orchestrator-kit figma-setup')} then paste token into ${pc.cyan('.agents/figma.local.env')} (never in chat)`);
-    lines.push(`  6. Start your first change:`);
+    lines.push(`  6. Optional pre-commit gate: ${pc.cyan('npx agent-orchestrator-kit hooks-setup')} or ${pc.cyan('init --hooks')}`);
+    lines.push(`  7. Start your first change:`);
   } else if (profile === 'mvp') {
     lines.push(`  3. For quick demos use ${pc.cyan('/opsx:quick <name>')} (propose + apply, no review gate)`);
-    lines.push(`  4. MCP: copy .mcp.json (Cursor) / .amp/settings.json (Amp) from *.example files`);
+    lines.push(`  4. MCP: ${pc.cyan('npx agent-orchestrator-kit mcp-setup')} (GitHub/GitLab from origin + browser)`);
     lines.push(`  5. Optional Figma: ${pc.cyan('npx agent-orchestrator-kit figma-setup')} then paste token into ${pc.cyan('.agents/figma.local.env')} (never in chat)`);
-    lines.push(`  6. Start exploring:`);
+    lines.push(`  6. Optional pre-commit gate: ${pc.cyan('npx agent-orchestrator-kit hooks-setup')} or ${pc.cyan('init --hooks')}`);
+    lines.push(`  7. Start exploring:`);
   } else {
-    lines.push(`  3. MCP: copy .mcp.json (Cursor) / .amp/settings.json (Amp) from *.example files`);
+    lines.push(`  3. MCP: ${pc.cyan('npx agent-orchestrator-kit mcp-setup')} (GitHub/GitLab from origin + browser)`);
     lines.push(`  4. Optional Figma: ${pc.cyan('npx agent-orchestrator-kit figma-setup')} then paste token into ${pc.cyan('.agents/figma.local.env')} (never in chat)`);
-    lines.push(`  5. Start your first change:`);
+    lines.push(`  5. Optional pre-commit gate: ${pc.cyan('npx agent-orchestrator-kit hooks-setup')} or ${pc.cyan('init --hooks')}`);
+    lines.push(`  6. Start your first change:`);
   }
 
   const startCmd = profile === 'mvp' ? '/opsx:quick' : '/opsx:explore';
@@ -1253,6 +2118,92 @@ function listAmpSubagentWrappers(projectDir) {
   return readdirSync(skillsDir).filter((entry) => entry.startsWith(AMP_SUBAGENT_SKILL_PREFIX));
 }
 
+function parseAmpSubagentSource(content) {
+  const parsed = String(content || '').match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  const name = parsed?.[1].match(/^name:\s*(.+)$/m)?.[1]?.trim();
+  const description = parsed?.[1].match(/^description:\s*(.+)$/m)?.[1]?.trim();
+  if (!parsed || !name || !description) return null;
+  return { parsed, name, description };
+}
+
+function buildAmpSubagentSkillContent(file, parsed) {
+  const name = parsed[1].match(/^name:\s*(.+)$/m)?.[1]?.trim();
+  const description = parsed[1].match(/^description:\s*(.+)$/m)?.[1]?.trim();
+  return [
+    '---',
+    `name: ${AMP_SUBAGENT_SKILL_PREFIX}${name}`,
+    `description: ${description}`,
+    '---',
+    '',
+    `<!-- AUTO-GENERATED from .agents/subagents/${file} — edit the source file, then run: npx agent-orchestrator-kit sync -->`,
+    '',
+    AMP_SPAWN_PREAMBLE,
+    '',
+    parsed[2].trim(),
+    '',
+  ].join('\n');
+}
+
+function skillHealthState(projectDir, name) {
+  const source = join(projectDir, '.agents', 'skills', name, 'SKILL.md');
+  if (!existsSync(source)) return 'missing';
+  const sourceBytes = readFileSync(source);
+  for (const ide of ['.cursor', '.claude']) {
+    const copy = join(projectDir, ide, 'skills', name, 'SKILL.md');
+    if (!existsSync(copy)) return 'stale';
+    if (Buffer.compare(sourceBytes, readFileSync(copy)) !== 0) return 'stale';
+  }
+  return 'ok';
+}
+
+function printSkillHealth(projectDir) {
+  const inventory = readSkillsInventory(projectDir);
+  const names = [...inventory.kit, ...inventory.stack];
+  console.log(pc.bold('\nSkill health'));
+  for (const name of names) {
+    const state = skillHealthState(projectDir, name);
+    const isStack = inventory.stack.includes(name);
+    let line = `  ${name.padEnd(28)} ${state}`;
+    if (state === 'missing' && isStack && inventory.external) {
+      line += `  npx ${inventory.external} install --agent all --yes`;
+    }
+    console.log(line);
+  }
+
+  const subagentsDir = join(projectDir, '.agents', 'subagents');
+  const issues = [];
+  let ok = 0;
+  let total = 0;
+  if (existsSync(subagentsDir)) {
+    for (const file of readdirSync(subagentsDir).filter((f) => f.endsWith('.md'))) {
+      const parsedWrap = parseAmpSubagentSource(readFileSync(join(subagentsDir, file), 'utf-8'));
+      if (!parsedWrap) continue;
+      total += 1;
+      const expected = Buffer.from(buildAmpSubagentSkillContent(file, parsedWrap.parsed));
+      const wrapperPath = join(
+        projectDir,
+        '.agents',
+        'skills',
+        `${AMP_SUBAGENT_SKILL_PREFIX}${parsedWrap.name}`,
+        'SKILL.md',
+      );
+      if (!existsSync(wrapperPath) || Buffer.compare(expected, readFileSync(wrapperPath)) !== 0) {
+        issues.push(`${AMP_SUBAGENT_SKILL_PREFIX}${parsedWrap.name}`);
+      } else {
+        ok += 1;
+      }
+    }
+  }
+  if (!total) {
+    console.log('  subagent wrappers: ok (0/0)');
+  } else if (!issues.length) {
+    console.log(`  subagent wrappers: ok (${ok}/${total})`);
+  } else {
+    console.log(`  subagent wrappers: ${issues.join(', ')} stale/missing (${ok}/${total} ok)`);
+  }
+  console.log('');
+}
+
 function generateAmpSubagentSkills(projectDir) {
   const subagentsDir = join(projectDir, '.agents', 'subagents');
   const skillsDir = join(projectDir, '.agents', 'skills');
@@ -1261,31 +2212,16 @@ function generateAmpSubagentSkills(projectDir) {
   if (existsSync(subagentsDir)) {
     for (const file of readdirSync(subagentsDir).filter((f) => f.endsWith('.md'))) {
       const content = readFileSync(join(subagentsDir, file), 'utf-8');
-      const parsed = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
-      const name = parsed?.[1].match(/^name:\s*(.+)$/m)?.[1]?.trim();
-      const description = parsed?.[1].match(/^description:\s*(.+)$/m)?.[1]?.trim();
-      if (!name || !description) {
+      const parsedWrap = parseAmpSubagentSource(content);
+      if (!parsedWrap) {
         log.warn(`skip Amp wrapper (missing name/description frontmatter): .agents/subagents/${file}`);
         continue;
       }
 
-      const skillName = `${AMP_SUBAGENT_SKILL_PREFIX}${name}`;
+      const skillName = `${AMP_SUBAGENT_SKILL_PREFIX}${parsedWrap.name}`;
       expected.add(skillName);
       mkdirSync(join(skillsDir, skillName), { recursive: true });
-      const skill = [
-        '---',
-        `name: ${skillName}`,
-        `description: ${description}`,
-        '---',
-        '',
-        `<!-- AUTO-GENERATED from .agents/subagents/${file} — edit the source file, then run: npx agent-orchestrator-kit sync -->`,
-        '',
-        AMP_SPAWN_PREAMBLE,
-        '',
-        parsed[2].trim(),
-        '',
-      ].join('\n');
-      writeFileSync(join(skillsDir, skillName, 'SKILL.md'), skill);
+      writeFileSync(join(skillsDir, skillName, 'SKILL.md'), buildAmpSubagentSkillContent(file, parsedWrap.parsed));
       log.ok(`.agents/skills/${skillName}/SKILL.md (Amp wrapper)`);
     }
   }
@@ -1301,11 +2237,10 @@ function generateAmpSubagentSkills(projectDir) {
 function syncAmp(projectDir) {
   log.info('Amp Code reads .agents/ natively — subagents exposed via skill wrappers');
   mkdirSync(join(projectDir, '.amp'), { recursive: true });
-  const ampExample = join(projectDir, '.agents', 'amp.settings.json.example');
+  const ampExample = join(projectDir, AMP_EXAMPLE_REL);
   const ampDest = join(projectDir, '.amp', 'settings.json');
-  if (existsSync(ampExample) && !existsSync(ampDest)) {
-    copyFileSync(ampExample, ampDest);
-    log.ok('.amp/settings.json created from example');
+  if (seedLiveMcpFromExample(ampDest, ampExample, 'amp.mcpServers', OPTIONAL_MCP_SEED_STRIP, '.amp/settings.json')) {
+    // seeded
   } else if (existsSync(ampDest)) {
     log.ok('.amp/settings.json already present');
   } else {
@@ -1327,6 +2262,7 @@ program
   .option('--force', 'Overwrite existing files', false)
   .option('--ci <provider>', 'CI provider: gitlab | github | none', 'github')
   .option('--spec-verify', 'Install AI Spec Verifier blocking gate (GitLab or GitHub)', false)
+  .option('--hooks', 'Opt-in: install pre-commit gate-check hook (husky-first)', false)
   .action((opts) => {
     const projectDir = process.cwd();
     const projectName = opts.name || basename(projectDir);
@@ -1360,6 +2296,7 @@ program
     try {
       execSync(`chmod +x ${join(projectDir, 'scripts', 'sync-local-agent-skills.sh')}`);
     } catch {}
+    chmodX(join(projectDir, HOOK_SCRIPT_REL));
 
     log.title('Installing CI workflow');
     installCi(projectDir, templateDir, ci, opts.force);
@@ -1415,6 +2352,12 @@ program
     refreshMemoryManagedFiles(projectDir);
     ensureMemoryMcpEntry(projectDir);
 
+    if (opts.hooks) {
+      log.title('Installing pre-commit gate');
+      const hookResult = runHooksSetup(projectDir);
+      if (!hookResult.ok) process.exitCode = 1;
+    }
+
     log.title('Done');
     log.ok(`agent-orchestrator-kit v${KIT_VERSION} installed`);
     printNextSteps(profile, projectDir, ci, specVerify);
@@ -1466,6 +2409,8 @@ program
 
     log.title('Refreshing Figma setup templates');
     refreshFigmaManagedFiles(projectDir);
+    log.title('Refreshing MCP launchers and hook script');
+    refreshOptionalMcpManagedFiles(projectDir);
     log.title('Configuring Memory MCP');
     refreshMemoryManagedFiles(projectDir);
     ensureMemoryMcpEntry(projectDir);
@@ -1473,7 +2418,9 @@ program
 
     log.ok(`Updated to v${KIT_VERSION}`);
     log.info('Run ./scripts/sync-local-agent-skills.sh to sync to local IDE');
+    log.info('Optional MCP: npx agent-orchestrator-kit mcp-setup');
     log.info('Optional Figma: npx agent-orchestrator-kit figma-setup');
+    log.info('Optional pre-commit gate: npx agent-orchestrator-kit hooks-setup');
   });
 
 program
@@ -1503,13 +2450,6 @@ program
       }
       copyDir(join(projectDir, '.agents', 'rules'), join(projectDir, '.cursor', 'rules'), { overwrite: true, delete: true });
       copyDir(join(projectDir, '.agents', 'subagents'), join(projectDir, '.cursor', 'agents'), { overwrite: true, delete: true });
-
-      const mcpExample = join(projectDir, '.agents', 'mcp.json.example');
-      const mcpDest = join(projectDir, '.mcp.json');
-      if (existsSync(mcpExample) && !existsSync(mcpDest)) {
-        copyFileSync(mcpExample, mcpDest);
-        log.ok('.mcp.json created from example');
-      }
     }
 
     if (syncClaude) {
@@ -1544,7 +2484,7 @@ program
 
 program
   .command('status')
-  .description('Show status of active OpenSpec changes (tasks progress, review verdict, archive readiness)')
+  .description('Show status of active OpenSpec changes (tasks progress, review verdict, archive readiness, MCP and skill health)')
   .action(() => {
     const projectDir = process.cwd();
     log.title('agent-orchestrator status');
@@ -1552,25 +2492,27 @@ program
     const changes = listActiveChanges(projectDir);
     if (changes.length === 0) {
       log.info('No active changes');
-      return;
+    } else {
+      for (const name of changes) {
+        const changeDir = join(projectDir, 'openspec', 'changes', name);
+        const progress = parseTasksProgress(changeDir);
+        const verdict = parseReviewVerdict(changeDir);
+        const hasBrief = parseDesignBrief(changeDir);
+        const progressStr = progress ? `${progress.done}/${progress.total} tasks` : 'no tasks.md';
+        const verdictStr = verdict || 'none';
+        const readyToArchive = Boolean(progress && progress.total > 0 && progress.done === progress.total);
+
+        console.log(`\n${pc.bold(name)}`);
+        console.log(`  tasks:  ${progressStr}`);
+        console.log(`  review: ${verdictStr}`);
+        console.log(`  brief:  ${hasBrief ? 'yes' : 'no'}`);
+        if (readyToArchive) log.ok('ready to archive');
+      }
+      console.log('');
     }
 
-    for (const name of changes) {
-      const changeDir = join(projectDir, 'openspec', 'changes', name);
-      const progress = parseTasksProgress(changeDir);
-      const verdict = parseReviewVerdict(changeDir);
-      const hasBrief = parseDesignBrief(changeDir);
-      const progressStr = progress ? `${progress.done}/${progress.total} tasks` : 'no tasks.md';
-      const verdictStr = verdict || 'none';
-      const readyToArchive = Boolean(progress && progress.total > 0 && progress.done === progress.total);
-
-      console.log(`\n${pc.bold(name)}`);
-      console.log(`  tasks:  ${progressStr}`);
-      console.log(`  review: ${verdictStr}`);
-      console.log(`  brief:  ${hasBrief ? 'yes' : 'no'}`);
-      if (readyToArchive) log.ok('ready to archive');
-    }
-    console.log('');
+    printMcpHealth(projectDir);
+    printSkillHealth(projectDir);
   });
 
 program
@@ -1578,6 +2520,7 @@ program
   .description('Deterministically check the review gate before apply/merge (exit non-zero if unmet)')
   .option('--src-glob <glob>', 'source path filter used to detect code changes', 'src/')
   .option('--base <ref>', 'git ref to diff against', 'HEAD~1')
+  .option('--staged', 'check staged files (git diff --cached) instead of --base...HEAD', false)
   .option('--tasks <name>', 'lint task contracts (Files/Do/Done-when) of a change')
   .option('--review <name>', 'run deterministic Tier 1 review checks on a change')
   .option('--json', 'with --review: print a {pass, errors[]} JSON report to stdout', false)
@@ -1631,13 +2574,15 @@ program
       return;
     }
 
-    const touchesSrc = gitDiffTouchesGlob(projectDir, opts.base, opts.srcGlob);
+    const touchesSrc = opts.staged
+      ? gitStagedTouchesGlob(projectDir, opts.srcGlob)
+      : gitDiffTouchesGlob(projectDir, opts.base, opts.srcGlob);
     if (touchesSrc === false) {
-      log.ok(`no changes under ${opts.srcGlob} — nothing to gate`);
+      log.ok(`no ${opts.staged ? 'staged ' : ''}changes under ${opts.srcGlob} — nothing to gate`);
       return;
     }
     if (touchesSrc === null) {
-      log.warn('could not compute git diff — skipping gate-check');
+      log.warn(`could not compute git ${opts.staged ? 'staged ' : ''}diff — skipping gate-check`);
       return;
     }
 
@@ -1798,7 +2743,14 @@ program
       return fail('openspec validate --all --strict failed — rolled back: change restored, main specs reverted to pre-sync state');
     }
 
-    // Final handoff: pipeline is complete, no next-session prompt
+    // Final handoff: pipeline is complete, no next-session prompt.
+    // Change dir has already been moved — read prior Runtime from the archive target.
+    const archivedHandoffPath = join(targetDir, 'handoff.md');
+    let priorFields = {};
+    if (existsSync(archivedHandoffPath)) {
+      priorFields = fieldsFromSections(name, parseHandoffMarkdown(readFileSync(archivedHandoffPath, 'utf-8')));
+    }
+    const runtimeResult = resolveRuntime({}, process.env, priorFields);
     const progress = parseTasksProgress(targetDir);
     const fields = {
       changeName: name,
@@ -1812,6 +2764,8 @@ program
       attach: `- \`${targetRel}/\``,
       spawn: 'none',
       constraints: 'Pipeline complete — no next session.',
+      runtime: runtimeResult.value || 'local',
+      agentId: resolveAgentId({}, process.env, priorFields),
       status: 'archived',
       tasks: progress ? `${progress.done}/${progress.total}` : '',
       review: parseReviewVerdict(targetDir) || '',
@@ -1819,6 +2773,7 @@ program
     };
     writeFileSync(join(targetDir, 'handoff.md'), `${buildHandoffMarkdown(fields).trim()}\n`);
     const memoryPath = persistMemoryFromHandoff(projectDir, fields);
+    const metricsPath = metricsFinalizeArchive(targetDir, name);
 
     console.log(`change:   ${name}`);
     console.log(`schema:   ${status.schemaName || 'unknown'}`);
@@ -1826,9 +2781,37 @@ program
     console.log(`sync:     ${syncStatus}`);
     console.log(`handoff:  ${join(targetRel, 'handoff.md')} (next_command: none)`);
     console.log(`memory:   ${memoryPath.replace(`${projectDir}/`, '')}`);
+    if (metricsPath) console.log(`metrics:  ${metricsPath.replace(`${projectDir}/`, '')} (archived_at set)`);
     log.ok(`archived ${name}`);
   });
 
+program
+  .command('hooks-setup')
+  .description('Opt-in pre-commit gate: husky-first, otherwise core.hooksPath=.githooks (never writes .git/hooks)')
+  .action(() => {
+    const projectDir = process.cwd();
+    log.title('agent-orchestrator hooks-setup');
+    const result = runHooksSetup(projectDir);
+    if (!result.ok) process.exitCode = 1;
+  });
+
+program
+  .command('mcp-setup')
+  .description('Install optional GitHub/GitLab (from git origin) and browser MCP launchers (never prints tokens)')
+  .option('--vcs <provider>', 'Override VCS detection: github | gitlab')
+  .option('--no-browser', 'Skip browser MCP')
+  .action((opts) => {
+    const projectDir = process.cwd();
+    log.title('agent-orchestrator mcp-setup');
+    const vcs = opts.vcs ? String(opts.vcs).toLowerCase() : '';
+    if (vcs && vcs !== 'github' && vcs !== 'gitlab') {
+      log.err('invalid --vcs (use github or gitlab)');
+      process.exitCode = 1;
+      return;
+    }
+    runMcpSetup(projectDir, { vcs, browser: opts.browser !== false });
+  });
+
 program
   .command('figma-setup')
   .description('Create local Figma token env file (never prints the token)')
@@ -1995,6 +2978,16 @@ program
   .option('--tasks <progress>', 'Task progress n/m')
   .option('--review <verdict>', 'Review verdict')
   .option('--session-count <n>', 'Handoff session_count')
+  .option('--runtime <runtime>', 'Session runtime: local | cloud')
+  .option('--agent-id <id>', 'Cloud agent identifier')
+  .option('--cloud-check', 'Verify change artifacts are committed and pushed', false)
+  .option('--started-at <iso>', 'Session start timestamp (overrides the pending marker from --restore)')
+  .option('--model <name>', 'Model used in this session (recorded in metrics.json)')
+  .option('--input-tokens <n>', 'Input tokens spent in this session')
+  .option('--output-tokens <n>', 'Output tokens spent in this session')
+  .option('--total-tokens <n>', 'Total tokens spent in this session (default: input + output)')
+  .option('--cost-usd <usd>', 'Cost of this session in USD')
+  .option('--no-metrics', 'Skip recording this session into metrics.json')
   .action((changeName, opts) => {
     const projectDir = process.cwd();
     const resolved = resolveHandoffChange(projectDir, changeName);
@@ -2036,11 +3029,43 @@ program
       } else {
         log.warn('handoff.md missing — using Memory JSON only');
       }
+      const decisionsPath = decisionsFilePath(projectDir, name);
+      if (existsSync(decisionsPath)) {
+        log.ok(`decisions.md: ${decisionsPath}`);
+        const entries = parseDecisionsFileEntries(readFileSync(decisionsPath, 'utf-8'));
+        for (const entry of entries) {
+          console.log(`- ${entry.date} ${entry.text}`);
+        }
+      } else {
+        console.log('decisions: none');
+      }
       if (memoryItems.length) {
         log.ok(`Memory entities: ${memoryItems.length} (${memoryPath})`);
       } else {
         log.warn(`Memory JSON empty or missing at ${memoryPath}`);
       }
+      if (opts.metrics !== false && existsSync(changeDir)) {
+        const metricsPath = metricsRecordSessionStart(projectDir, name, fields ? fields.nextRole : '');
+        log.ok(`metrics: session start recorded (${metricsPath.replace(`${projectDir}/`, '')})`);
+      }
+      return;
+    }
+
+    if (opts.cloudCheck) {
+      const existingCheck = readHandoffFields(projectDir, name);
+      const checkFields = existingCheck.fields || { changeName: name };
+      if (!applyRuntimeToFields(checkFields, opts, process.env)) {
+        process.exitCode = 1;
+        return;
+      }
+      const findings = collectCloudCheckFindings(projectDir, name);
+      if (!findings.length) {
+        log.ok('cloud-check passed');
+        return;
+      }
+      const emit = checkFields.runtime === 'cloud' ? log.err : log.warn;
+      for (const finding of findings) emit(finding);
+      if (checkFields.runtime === 'cloud') process.exitCode = 1;
       return;
     }
 
@@ -2085,16 +3110,114 @@ program
       fields.status = fields.review && /^APPROVE/i.test(fields.review) ? 'spec-approved' : 'in-progress';
     }
 
+    if (!applyRuntimeToFields(fields, opts, process.env)) {
+      process.exitCode = 1;
+      return;
+    }
+
     const prompt = buildNextSessionPrompt(fields, agentLanguage).replace(/^\n+|\n+$/g, '');
     fields.prompt = prompt;
     writeFileSync(existing.filePath, `${buildHandoffMarkdown(fields).trim()}\n`);
     console.error(pc.green('  ✓'), existing.filePath.replace(`${projectDir}/`, ''));
 
+    appendDecisionsFromHandoff(projectDir, name, fields.decisions);
     const memoryPath = persistMemoryFromHandoff(projectDir, fields);
     console.error(pc.green('  ✓'), `Memory JSON upserted: ${memoryPath}`);
 
+    if (opts.metrics !== false) {
+      const metricsPath = metricsRecordSessionEnd(projectDir, fields, {
+        startedAt: opts.startedAt,
+        model: opts.model,
+        inputTokens: opts.inputTokens,
+        outputTokens: opts.outputTokens,
+        totalTokens: opts.totalTokens,
+        costUsd: opts.costUsd,
+      });
+      console.error(pc.green('  ✓'), `metrics.json updated: ${metricsPath.replace(`${projectDir}/`, '')}`);
+    }
+
+    if (fields.runtime === 'cloud') printCloudPersistNextSteps(name);
+
     console.error(pc.dim('Copy the prompt below into the next chat as one fenced block. Do not include this line.'));
     process.stdout.write(`${prompt}\n`);
   });
 
+program
+  .command('metrics [change-name]')
+  .description('Show recorded session metrics for a change: time per phase, tokens, cost, agents, models')
+  .option('--json', 'Print raw metrics.json', false)
+  .action((changeName, opts) => {
+    const projectDir = process.cwd();
+    let name = changeName;
+    if (!name) {
+      const resolved = resolveHandoffChange(projectDir, changeName);
+      if (!resolved) {
+        log.err('No active change found. Pass a name: npx agent-orchestrator-kit metrics <name>');
+        process.exitCode = 1;
+        return;
+      }
+      if (resolved.ambiguous) {
+        log.err(`Multiple active changes: ${resolved.ambiguous.join(', ')}. Pass the change name argument.`);
+        process.exitCode = 1;
+        return;
+      }
+      name = resolved;
+    }
+
+    const { filePath, archived, missing } = resolveMetricsFile(projectDir, name);
+    if (missing) {
+      log.err(`No metrics.json for ${name}`);
+      log.info(`Expected: ${filePath.replace(`${projectDir}/`, '')}`);
+      log.info('Metrics are recorded by: handoff --restore (session start) and handoff <name> (session end)');
+      process.exitCode = 1;
+      return;
+    }
+
+    const metrics = loadMetricsFile(filePath, name, new Date().toISOString());
+    if (opts.json) {
+      process.stdout.write(`${JSON.stringify(metrics, null, 2)}\n`);
+      return;
+    }
+
+    log.title(`metrics  ${name}${archived ? '  (archived)' : ''}`);
+    console.log(`file:      ${filePath.replace(`${projectDir}/`, '')}`);
+    console.log(`sessions:  ${metrics.totals.sessions}${metrics.totals.cloudSessions ? ` (cloud: ${metrics.totals.cloudSessions})` : ''}`);
+    console.log(`work time: ${formatMetricsDuration(metrics.totals.durationMs)}`);
+    console.log(`lead time: ${formatMetricsDuration(metrics.totals.leadTimeMs)}`);
+    console.log(`tokens:    ${formatMetricsNumber(metrics.spend.totalTokens)} (in: ${formatMetricsNumber(metrics.spend.inputTokens)}, out: ${formatMetricsNumber(metrics.spend.outputTokens)})`);
+    console.log(`cost:      ${formatMetricsCost(metrics.spend.costUsd)}`);
+    if (metrics.archivedAt) console.log(`archived:  ${metrics.archivedAt}`);
+    if (metrics.pending) log.warn(`open session since ${metrics.pending.startedAt} (${metrics.pending.role || 'unknown role'})`);
+
+    const phaseOrder = ['explore', 'design', 'spec', 'review', 'apply', 'archive', 'other'];
+    const phaseKeys = phaseOrder.filter((key) => metrics.phases[key]);
+    if (phaseKeys.length) {
+      console.log('');
+      console.log('phase      sessions  time      tokens    cost      agents');
+      for (const key of phaseKeys) {
+        const phase = metrics.phases[key];
+        const cols = [
+          key.padEnd(10),
+          String(phase.sessions).padEnd(9),
+          formatMetricsDuration(phase.durationMs).padEnd(9),
+          formatMetricsNumber(phase.totalTokens).padEnd(9),
+          formatMetricsCost(phase.costUsd).padEnd(9),
+          phase.agents.join(', ') || '—',
+        ];
+        console.log(cols.join(' '));
+      }
+    }
+
+    if (metrics.sessions.length) {
+      console.log('');
+      console.log('recent sessions:');
+      for (const session of metrics.sessions.slice(-5)) {
+        const spendLabel = session.totalTokens != null || session.costUsd != null
+          ? ` — ${formatMetricsNumber(session.totalTokens)} tok, ${formatMetricsCost(session.costUsd)}`
+          : '';
+        console.log(`- ${session.endedAt}  ${session.phase.padEnd(7)} ${formatMetricsDuration(session.durationMs).padEnd(9)} ${session.role || '(no role)'}${session.model ? ` [${session.model}]` : ''}${spendLabel}`);
+      }
+    }
+  });
+
 program.parse();