agent-orchestrator-kit 0.4.0 → 0.6.0

package/bin/agent-orchestrator.js

@@ -5,6 +5,7 @@ import { readFileSync, existsSync, mkdirSync, copyFileSync, readdirSync, statSyn
 import { join, dirname, basename, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
+import { collectSpend } from './spend-collect.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const KIT_ROOT = join(__dirname, '..');
@@ -69,6 +70,7 @@ const GITIGNORE_LINES = [
   '.agents/figma.local.env',
   '.agents/github.local.env',
   '.agents/gitlab.local.env',
+  '.agents/spend/',
 ];
 
 const FIGMA_ENV_REL = join('.agents', 'figma.local.env');
@@ -84,6 +86,11 @@ 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 CURSOR_SPEND_HOOK_REL = join('scripts', 'cursor-spend-hook.cjs');
+const CURSOR_HOOKS_JSON_REL = join('.cursor', 'hooks.json');
+const CURSOR_SPEND_HOOK_COMMAND = 'node scripts/cursor-spend-hook.cjs';
+const CURSOR_SPEND_HOOK_EVENTS = ['stop', 'subagentStop'];
+const CURSOR_USAGE_FILE_REL = join('.agents', 'spend', 'cursor-usage.jsonl');
 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'];
@@ -361,6 +368,108 @@ function refreshOptionalMcpManagedFiles(projectDir) {
   refreshManagedRelPaths(projectDir, OPTIONAL_MCP_MANAGED_PATHS);
 }
 
+function cursorSpendHookEntryOk(projectDir) {
+  const hooksPath = join(projectDir, CURSOR_HOOKS_JSON_REL);
+  if (!existsSync(hooksPath)) return false;
+  let config;
+  try {
+    config = JSON.parse(readFileSync(hooksPath, 'utf-8'));
+  } catch {
+    return false;
+  }
+  const hooks = config && typeof config === 'object' ? config.hooks : null;
+  if (!hooks || typeof hooks !== 'object') return false;
+  return CURSOR_SPEND_HOOK_EVENTS.every((event) => {
+    const entries = hooks[event];
+    return Array.isArray(entries)
+      && entries.some((entry) => entry && String(entry.command || '').includes('cursor-spend-hook.cjs'));
+  });
+}
+
+// Mandatory spend capture: every kit project must record Cursor token usage
+// locally so handoff/archive can collect real spend without manual flags.
+function ensureCursorSpendHook(projectDir) {
+  const result = { script: false, hooksJson: false, error: null };
+  const src = join(KIT_ROOT, 'templates', CURSOR_SPEND_HOOK_REL);
+  const dest = join(projectDir, CURSOR_SPEND_HOOK_REL);
+  if (existsSync(src)) {
+    mkdirSync(dirname(dest), { recursive: true });
+    copyFileSync(src, dest);
+    result.script = true;
+  }
+
+  const hooksPath = join(projectDir, CURSOR_HOOKS_JSON_REL);
+  let config = { version: 1, hooks: {} };
+  if (existsSync(hooksPath)) {
+    try {
+      config = JSON.parse(readFileSync(hooksPath, 'utf-8'));
+    } catch {
+      result.error = `${CURSOR_HOOKS_JSON_REL} is not valid JSON — fix it, then re-run any kit command`;
+      return result;
+    }
+  }
+  if (!config || typeof config !== 'object') config = { version: 1, hooks: {} };
+  if (config.version == null) config.version = 1;
+  if (!config.hooks || typeof config.hooks !== 'object') config.hooks = {};
+  let changed = !existsSync(hooksPath);
+  for (const event of CURSOR_SPEND_HOOK_EVENTS) {
+    const entries = Array.isArray(config.hooks[event]) ? config.hooks[event] : [];
+    const present = entries.some((entry) => entry && String(entry.command || '').includes('cursor-spend-hook.cjs'));
+    if (!present) {
+      entries.push({ command: CURSOR_SPEND_HOOK_COMMAND });
+      config.hooks[event] = entries;
+      changed = true;
+    }
+  }
+  if (changed) {
+    mkdirSync(dirname(hooksPath), { recursive: true });
+    writeFileSync(hooksPath, `${JSON.stringify(config, null, 2)}\n`);
+    result.hooksJson = true;
+  }
+  return result;
+}
+
+function reportCursorSpendHook(projectDir, emit) {
+  const result = ensureCursorSpendHook(projectDir);
+  if (result.error) {
+    emit.warn(`Cursor spend hook: ${result.error}`);
+    return result;
+  }
+  if (result.script) emit.ok(CURSOR_SPEND_HOOK_REL);
+  if (result.hooksJson) emit.ok(`${CURSOR_HOOKS_JSON_REL} (stop + subagentStop spend hook)`);
+  return result;
+}
+
+function countCursorUsageRecords(projectDir) {
+  const filePath = join(projectDir, CURSOR_USAGE_FILE_REL);
+  if (!existsSync(filePath)) return null;
+  try {
+    return readFileSync(filePath, 'utf-8').split('\n').filter((line) => line.trim()).length;
+  } catch {
+    return null;
+  }
+}
+
+function printSpendHealth(projectDir) {
+  console.log(pc.bold('\nSpend capture'));
+  const scriptOk = existsSync(join(projectDir, CURSOR_SPEND_HOOK_REL));
+  const entryOk = cursorSpendHookEntryOk(projectDir);
+  const records = countCursorUsageRecords(projectDir);
+  const cursorState = scriptOk && entryOk
+    ? `ok${records != null ? ` (${records} records)` : ' (no turns recorded yet)'}`
+    : 'not configured — run npx agent-orchestrator-kit update';
+  console.log(`  cursor   ${cursorState}`);
+  const home = process.env.HOME || '';
+  const claudeOk = home && existsSync(join(home, '.claude', 'projects'));
+  console.log(`  claude   ${claudeOk ? 'ok (~/.claude/projects)' : 'no local Claude data'}`);
+  const ampDir = process.env.AMP_DATA_DIR && String(process.env.AMP_DATA_DIR).trim()
+    ? String(process.env.AMP_DATA_DIR).trim()
+    : join(home, '.local', 'share', 'amp');
+  const ampOk = existsSync(join(ampDir, 'threads'));
+  console.log(`  amp      ${ampOk ? 'ok (threads found)' : 'no local Amp data'}`);
+  console.log('');
+}
+
 function parseGitRemoteHostname(url) {
   const raw = String(url || '').trim();
   if (!raw) return '';
@@ -698,6 +807,7 @@ function runMcpSetup(projectDir, { vcs = '', browser = true } = {}) {
   refreshFigmaManagedFiles(projectDir);
   refreshMemoryManagedFiles(projectDir);
   refreshOptionalMcpManagedFiles(projectDir);
+  reportCursorSpendHook(projectDir, log);
   mergeGitignore(projectDir, GITIGNORE_LINES);
 
   const selected = resolveMcpSetupVcs(projectDir, vcs);
@@ -894,6 +1004,42 @@ function applyRuntimeToFields(fields, opts, env) {
   return true;
 }
 
+const VALID_PLATFORMS = new Set(['cursor', 'claude', 'amp']);
+
+function resolveModel(opts, env) {
+  const flag = opts && opts.model != null ? String(opts.model).trim() : '';
+  if (flag) return flag;
+  const fromEnv = env && env.AOK_MODEL != null ? String(env.AOK_MODEL).trim() : '';
+  if (fromEnv) return fromEnv;
+  return null;
+}
+
+function resolvePlatform(opts, env) {
+  const flag = opts && opts.platform != null ? String(opts.platform).trim() : '';
+  if (flag) {
+    const lower = flag.toLowerCase();
+    if (!VALID_PLATFORMS.has(lower)) {
+      return { error: 'invalid --platform (use cursor, claude, or amp)' };
+    }
+    return { value: lower };
+  }
+  const fromEnv = env && env.AOK_PLATFORM != null ? String(env.AOK_PLATFORM).trim() : '';
+  if (fromEnv) {
+    const lower = fromEnv.toLowerCase();
+    if (VALID_PLATFORMS.has(lower)) return { value: lower };
+    return { value: null, warn: 'invalid AOK_PLATFORM (use cursor, claude, or amp)' };
+  }
+  return { value: null };
+}
+
+function warnMissingModel() {
+  console.error('metrics: session.model is null — pass --model <llm-product-id> or set AOK_MODEL');
+}
+
+function warnMissingUsd() {
+  console.error('metrics: spend.costUsd is null — USD spend was not collected');
+}
+
 function gitTry(projectDir, command) {
   try {
     const stdout = execSync(command, {
@@ -1290,6 +1436,433 @@ 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 emptyPlatformSpend(source = 'none') {
+  return {
+    inputTokens: null,
+    outputTokens: null,
+    totalTokens: null,
+    costUsd: null,
+    ampCredits: null,
+    source,
+  };
+}
+
+function defaultSpendByPlatform() {
+  return {
+    cursor: emptyPlatformSpend(),
+    claude: emptyPlatformSpend(),
+    amp: emptyPlatformSpend(),
+  };
+}
+
+function mergeSpendByPlatform(raw) {
+  const base = defaultSpendByPlatform();
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return base;
+  for (const key of ['cursor', 'claude', 'amp']) {
+    const row = raw[key] && typeof raw[key] === 'object' && !Array.isArray(raw[key]) ? raw[key] : {};
+    base[key] = { ...base[key], ...row };
+  }
+  return base;
+}
+
+function defaultMetrics(changeName, nowIso) {
+  return {
+    version: METRICS_VERSION,
+    change: changeName,
+    createdAt: nowIso,
+    updatedAt: nowIso,
+    archivedAt: null,
+    spend: emptySpendTotals(),
+    spendByPlatform: defaultSpendByPlatform(),
+    spendByModel: [],
+    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 : {}) },
+    spendByPlatform: mergeSpendByPlatform(parsed.spendByPlatform),
+    spendByModel: Array.isArray(parsed.spendByModel) ? parsed.spendByModel : [],
+    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 sessionFieldOrSources(session, key) {
+  if (session[key] != null && session[key] !== '') return numOrNull(session[key]);
+  let sum = null;
+  for (const src of session.sources || []) {
+    sum = addNullable(sum, numOrNull(src[key]));
+  }
+  return sum;
+}
+
+function lastSessionEndedAt(metrics) {
+  let last = null;
+  for (const session of metrics.sessions || []) {
+    if (session.endedAt && (last == null || session.endedAt > last)) last = session.endedAt;
+  }
+  return last;
+}
+
+function existingSourceIdSet(metrics) {
+  const ids = new Set();
+  for (const session of metrics.sessions || []) {
+    for (const src of session.sources || []) {
+      if (src && src.id != null && src.id !== '') ids.add(String(src.id));
+    }
+  }
+  return ids;
+}
+
+function uniqueSourceModels(sources) {
+  const seen = [];
+  for (const src of sources || []) {
+    if (src.model && !seen.includes(src.model)) seen.push(src.model);
+  }
+  return seen;
+}
+
+function primaryModelFromSources(sources) {
+  if (!sources || !sources.length) return null;
+  const ranked = [...sources].sort((a, b) => {
+    const ta = a.totalTokens ?? 0;
+    const tb = b.totalTokens ?? 0;
+    if (tb !== ta) return tb - ta;
+    const platformCmp = String(a.platform || '').localeCompare(String(b.platform || ''));
+    if (platformCmp !== 0) return platformCmp;
+    return String(a.id || '').localeCompare(String(b.id || ''));
+  });
+  const model = ranked[0] && ranked[0].model;
+  return model == null || model === '' ? null : String(model);
+}
+
+function hasSpendOverride(opts) {
+  return opts.inputTokens != null || opts.outputTokens != null || opts.totalTokens != null || opts.costUsd != null;
+}
+
+function sessionTotalsFromFlags(opts) {
+  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);
+  }
+  return {
+    inputTokens,
+    outputTokens,
+    totalTokens,
+    costUsd: numOrNull(opts.costUsd),
+  };
+}
+
+function sessionTotalsFromSources(sources) {
+  let inputTokens = null;
+  let outputTokens = null;
+  let totalTokens = null;
+  let costUsd = null;
+  for (const src of sources || []) {
+    inputTokens = addNullable(inputTokens, numOrNull(src.inputTokens));
+    outputTokens = addNullable(outputTokens, numOrNull(src.outputTokens));
+    totalTokens = addNullable(totalTokens, numOrNull(src.totalTokens));
+    if (src.costUsd != null) costUsd = addNullable(costUsd, numOrNull(src.costUsd));
+  }
+  return { inputTokens, outputTokens, totalTokens, costUsd };
+}
+
+function runCollectSpend(metrics, windowStart, windowEnd) {
+  try {
+    return collectSpend({
+      cwd: process.cwd(),
+      windowStart,
+      windowEnd,
+      existingSourceIds: existingSourceIdSet(metrics),
+      env: process.env,
+      homedir: process.env.HOME,
+    });
+  } catch {
+    return { sources: [], byPlatform: defaultSpendByPlatform(), byModel: [], notes: [] };
+  }
+}
+
+function applyCollectedSessionFields(session, sources, resolvedModel, opts) {
+  session.sources = sources;
+  const uniqueModels = uniqueSourceModels(sources);
+  session.model = primaryModelFromSources(sources) || resolvedModel || null;
+  if (uniqueModels.length > 1) session.models = uniqueModels;
+  const totals = hasSpendOverride(opts) ? sessionTotalsFromFlags(opts) : sessionTotalsFromSources(sources);
+  session.inputTokens = totals.inputTokens;
+  session.outputTokens = totals.outputTokens;
+  session.totalTokens = totals.totalTokens;
+  session.costUsd = totals.costUsd;
+}
+
+function recomputeSpendMaps(metrics) {
+  const byPlatform = defaultSpendByPlatform();
+  const byModel = new Map();
+  for (const session of metrics.sessions || []) {
+    for (const src of session.sources || []) {
+      const platform = src.platform;
+      if (platform && byPlatform[platform]) {
+        const bucket = byPlatform[platform];
+        bucket.inputTokens = addNullable(bucket.inputTokens, numOrNull(src.inputTokens));
+        bucket.outputTokens = addNullable(bucket.outputTokens, numOrNull(src.outputTokens));
+        bucket.totalTokens = addNullable(bucket.totalTokens, numOrNull(src.totalTokens));
+        bucket.costUsd = addNullable(bucket.costUsd, numOrNull(src.costUsd));
+        bucket.ampCredits = addNullable(bucket.ampCredits, numOrNull(src.ampCredits));
+        if (platform === 'claude') bucket.source = 'claude-jsonl';
+        else if (platform === 'amp') bucket.source = 'amp-thread';
+        else if (platform === 'cursor') bucket.source = 'cursor-hook';
+      }
+      if (src.model) {
+        const key = `${src.model}::${src.platform || ''}`;
+        const row = byModel.get(key) || {
+          model: src.model,
+          platform: src.platform || null,
+          inputTokens: null,
+          outputTokens: null,
+          totalTokens: null,
+          costUsd: null,
+          ampCredits: null,
+        };
+        row.inputTokens = addNullable(row.inputTokens, numOrNull(src.inputTokens));
+        row.outputTokens = addNullable(row.outputTokens, numOrNull(src.outputTokens));
+        row.totalTokens = addNullable(row.totalTokens, numOrNull(src.totalTokens));
+        row.costUsd = addNullable(row.costUsd, numOrNull(src.costUsd));
+        row.ampCredits = addNullable(row.ampCredits, numOrNull(src.ampCredits));
+        byModel.set(key, row);
+      }
+    }
+  }
+  metrics.spendByPlatform = byPlatform;
+  metrics.spendByModel = [...byModel.values()];
+}
+
+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 = sessionFieldOrSources(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);
+    if (Array.isArray(session.models)) {
+      for (const model of session.models) {
+        if (model && !phase.models.includes(model)) phase.models.push(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;
+  recomputeSpendMaps(metrics);
+}
+
+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 resolvedModel = opts.model === undefined ? resolveModel(opts, process.env) : opts.model;
+  const windowStart = (metrics.pending && metrics.pending.startedAt) || lastSessionEndedAt(metrics) || metrics.createdAt;
+  const collected = opts.collect === false
+    ? { sources: [] }
+    : runCollectSpend(metrics, windowStart, nowIso);
+  const session = {
+    startedAt,
+    endedAt: nowIso,
+    durationMs,
+    role: fields.closedRole || '',
+    phase: phaseForRole(fields.closedRole),
+    runtime: fields.runtime || 'local',
+    agentId: fields.agentId || 'none',
+    model: resolvedModel || null,
+    platform: opts.platform || null,
+    tasks: fields.tasks || null,
+    sources: [],
+    inputTokens: null,
+    outputTokens: null,
+    totalTokens: null,
+    costUsd: null,
+  };
+  applyCollectedSessionFields(session, collected.sources || [], resolvedModel, opts);
+  metrics.sessions.push(session);
+  metrics.pending = null;
+  metrics.updatedAt = nowIso;
+  recomputeMetricsAggregates(metrics);
+  if (session.model == null) warnMissingModel();
+  saveMetricsFile(filePath, metrics);
+  return filePath;
+}
+
+function metricsFinalizeArchive(targetDir, changeName, opts = {}) {
+  const filePath = join(targetDir, 'metrics.json');
+  const nowIso = new Date().toISOString();
+  const metrics = loadMetricsFile(filePath, changeName, nowIso);
+  const windowStart = lastSessionEndedAt(metrics) || metrics.createdAt;
+  const collected = opts.collect === false
+    ? { sources: [] }
+    : runCollectSpend(metrics, windowStart, nowIso);
+  const resolvedModel = opts.model === undefined ? resolveModel(opts, process.env) : opts.model;
+  const session = {
+    startedAt: nowIso,
+    endedAt: nowIso,
+    durationMs: null,
+    role: 'Archiver',
+    phase: phaseForRole('Archiver'),
+    runtime: opts.runtime || 'local',
+    agentId: opts.agentId || 'none',
+    model: resolvedModel || null,
+    platform: opts.platform || null,
+    tasks: opts.tasks || null,
+    sources: [],
+    inputTokens: null,
+    outputTokens: null,
+    totalTokens: null,
+    costUsd: null,
+  };
+  applyCollectedSessionFields(session, collected.sources || [], resolvedModel, {});
+  metrics.sessions.push(session);
+  metrics.archivedAt = nowIso;
+  metrics.pending = null;
+  metrics.updatedAt = nowIso;
+  recomputeMetricsAggregates(metrics);
+  if (session.model == null) warnMissingModel();
+  if (metrics.spend.costUsd === null) warnMissingUsd();
+  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);
@@ -2143,6 +2716,9 @@ program
     refreshMemoryManagedFiles(projectDir);
     ensureMemoryMcpEntry(projectDir);
 
+    log.title('Configuring Cursor spend hook');
+    reportCursorSpendHook(projectDir, log);
+
     if (opts.hooks) {
       log.title('Installing pre-commit gate');
       const hookResult = runHooksSetup(projectDir);
@@ -2205,6 +2781,8 @@ program
     log.title('Configuring Memory MCP');
     refreshMemoryManagedFiles(projectDir);
     ensureMemoryMcpEntry(projectDir);
+    log.title('Configuring Cursor spend hook');
+    reportCursorSpendHook(projectDir, log);
     mergeGitignore(projectDir, GITIGNORE_LINES);
 
     log.ok(`Updated to v${KIT_VERSION}`);
@@ -2267,6 +2845,9 @@ program
     log.title('Configuring Memory MCP');
     ensureMemoryMcpEntry(projectDir);
 
+    log.title('Configuring Cursor spend hook');
+    reportCursorSpendHook(projectDir, log);
+
     mergeGitignore(projectDir, GITIGNORE_LINES);
 
     log.ok('Sync complete');
@@ -2303,6 +2884,7 @@ program
     }
 
     printMcpHealth(projectDir);
+    printSpendHealth(projectDir);
     printSkillHealth(projectDir);
   });
 
@@ -2431,6 +3013,9 @@ program
   .option('--sync', 'merge delta specs into openspec/specs/ before archiving')
   .option('--no-sync', 'skip delta-spec merge (requires --force when delta specs exist)')
   .option('--force', 'confirm archiving without merge when delta specs exist', false)
+  .option('--model <name>', 'LLM product id recorded on the Archiver session')
+  .option('--platform <platform>', 'Session platform: cursor | claude | amp')
+  .option('--no-collect', 'Skip local spend adapters when finalizing metrics')
   .action((name, opts) => {
     const projectDir = process.cwd();
     const fail = (msg) => {
@@ -2441,6 +3026,15 @@ program
 
     if (!isSafeChangeName(name)) return fail(`invalid change name: ${name}`);
 
+    const platformResult = resolvePlatform(opts, process.env);
+    if (platformResult.error) {
+      log.err(platformResult.error);
+      process.exitCode = 1;
+      return;
+    }
+    if (platformResult.warn) console.error(platformResult.warn);
+    const resolvedModel = resolveModel(opts, process.env);
+
     let status;
     try {
       const out = execSync(`npx openspec status --change ${name} --json`, {
@@ -2564,6 +3158,14 @@ program
     };
     writeFileSync(join(targetDir, 'handoff.md'), `${buildHandoffMarkdown(fields).trim()}\n`);
     const memoryPath = persistMemoryFromHandoff(projectDir, fields);
+    const metricsPath = metricsFinalizeArchive(targetDir, name, {
+      model: resolvedModel,
+      platform: platformResult.value || null,
+      runtime: fields.runtime,
+      agentId: fields.agentId,
+      tasks: fields.tasks,
+      collect: opts.collect !== false,
+    });
 
     console.log(`change:   ${name}`);
     console.log(`schema:   ${status.schemaName || 'unknown'}`);
@@ -2571,6 +3173,7 @@ program
     console.log(`sync:     ${syncStatus}`);
     console.log(`handoff:  ${join(targetRel, 'handoff.md')} (next_command: none)`);
     console.log(`memory:   ${memoryPath.replace(`${projectDir}/`, '')}`);
+    console.log(`metrics:  ${metricsPath.replace(`${projectDir}/`, '')} (archived_at set)`);
     log.ok(`archived ${name}`);
   });
 
@@ -2770,6 +3373,15 @@ program
   .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>', 'LLM product id recorded in metrics.json')
+  .option('--platform <platform>', 'Session platform: cursor | claude | amp')
+  .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')
+  .option('--no-collect', 'Skip local spend adapters for this persist')
   .action((changeName, opts) => {
     const projectDir = process.cwd();
     const resolved = resolveHandoffChange(projectDir, changeName);
@@ -2826,6 +3438,13 @@ program
       } 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}/`, '')})`);
+      }
+      const spendHook = ensureCursorSpendHook(projectDir);
+      if (spendHook.error) log.warn(`Cursor spend hook: ${spendHook.error}`);
+      else if (spendHook.hooksJson) log.ok('Cursor spend hook installed — restart Cursor once to activate it');
       return;
     }
 
@@ -2893,6 +3512,15 @@ program
       return;
     }
 
+    const platformResult = resolvePlatform(opts, process.env);
+    if (platformResult.error) {
+      log.err(platformResult.error);
+      process.exitCode = 1;
+      return;
+    }
+    if (platformResult.warn) console.error(platformResult.warn);
+    const resolvedModel = resolveModel(opts, process.env);
+
     const prompt = buildNextSessionPrompt(fields, agentLanguage).replace(/^\n+|\n+$/g, '');
     fields.prompt = prompt;
     writeFileSync(existing.filePath, `${buildHandoffMarkdown(fields).trim()}\n`);
@@ -2902,10 +3530,140 @@ program
     const memoryPath = persistMemoryFromHandoff(projectDir, fields);
     console.error(pc.green('  ✓'), `Memory JSON upserted: ${memoryPath}`);
 
+    const spendHook = ensureCursorSpendHook(projectDir);
+    if (spendHook.error) console.error(pc.yellow('  !'), `Cursor spend hook: ${spendHook.error}`);
+    else if (spendHook.hooksJson) console.error(pc.green('  ✓'), 'Cursor spend hook installed — restart Cursor once to activate it');
+
+    if (opts.metrics !== false) {
+      const metricsPath = metricsRecordSessionEnd(projectDir, fields, {
+        startedAt: opts.startedAt,
+        model: resolvedModel,
+        platform: platformResult.value || null,
+        inputTokens: opts.inputTokens,
+        outputTokens: opts.outputTokens,
+        totalTokens: opts.totalTokens,
+        costUsd: opts.costUsd,
+        collect: opts.collect !== false,
+      });
+      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, roles, and 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      roles                models');
+      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(', ') || '—').padEnd(20),
+          phase.models.join(', ') || '—',
+        ];
+        console.log(cols.join(' '));
+      }
+    }
+
+    const byPlatform = metrics.spendByPlatform || defaultSpendByPlatform();
+    console.log('');
+    console.log('by platform:');
+    console.log('platform   tokens    cost      credits   source');
+    for (const key of ['cursor', 'claude', 'amp']) {
+      const row = byPlatform[key] || emptyPlatformSpend();
+      console.log([
+        key.padEnd(10),
+        formatMetricsNumber(row.totalTokens).padEnd(9),
+        formatMetricsCost(row.costUsd).padEnd(9),
+        formatMetricsNumber(row.ampCredits).padEnd(9),
+        row.source || 'none',
+      ].join(' '));
+    }
+
+    console.log('');
+    console.log('by model:');
+    console.log('model                platform   tokens    cost      credits');
+    const byModel = Array.isArray(metrics.spendByModel) ? metrics.spendByModel : [];
+    if (!byModel.length) {
+      console.log('—                     —          —         —         —');
+    } else {
+      for (const row of byModel) {
+        console.log([
+          String(row.model || '—').padEnd(20),
+          String(row.platform || '—').padEnd(10),
+          formatMetricsNumber(row.totalTokens).padEnd(9),
+          formatMetricsCost(row.costUsd).padEnd(9),
+          formatMetricsNumber(row.ampCredits),
+        ].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();