agent-orchestrator-kit 0.13.0 → 0.14.1

package/bin/agent-orchestrator.js

@@ -5,7 +5,8 @@ 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, enrichMetricsCursorEstimates } from './spend-collect.js';
+import { collectSpend } from './spend-collect.js';
+import { describeClaudeCostEstimate } from './claude-cost-estimate.js';
 import { resolveRestoreClient, ampThreadIdFromEnv } from './session-client.js';
 import {
   earlierTimestamp,
@@ -219,6 +220,47 @@ function copyDir(src, dest, opts = {}) {
   }
 }
 
+// `.agents/commands/opsx-<phase>.md` is the source of truth for the /opsx:*
+// role commands. Cursor reads `.cursor/commands/<file>.md` as `/<file>`, so it
+// gets a flat copy. Claude Code namespaces by subdirectory —
+// `.claude/commands/opsx/<phase>.md` is what makes the documented
+// `/opsx:<phase>` actually exist there.
+function syncCommands(projectDir, ideDir, { namespaced }) {
+  const src = join(projectDir, '.agents', 'commands');
+  const dest = join(projectDir, ideDir, 'commands');
+  if (!existsSync(src)) return;
+
+  const files = readdirSync(src).filter((f) => f.endsWith('.md'));
+  const written = new Set();
+  mkdirSync(dest, { recursive: true });
+
+  for (const file of files) {
+    const match = namespaced && file.match(/^([a-z0-9]+)-(.+\.md)$/i);
+    const rel = match ? join(match[1], match[2]) : file;
+    const destPath = join(dest, rel);
+    mkdirSync(dirname(destPath), { recursive: true });
+    copyFileSync(join(src, file), destPath);
+    written.add(rel);
+    log.ok(destPath.replace(process.cwd() + '/', ''));
+  }
+
+  // Drop commands a kit `update` removed, mirroring the skills/subagents sync.
+  const walk = (dir, prefix = '') => {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      const rel = prefix ? join(prefix, entry) : entry;
+      if (statSync(full).isDirectory()) {
+        walk(full, rel);
+        if (readdirSync(full).length === 0) rmSync(full, { recursive: true, force: true });
+      } else if (!written.has(rel)) {
+        rmSync(full, { force: true });
+        log.warn(`removed stale: ${join(dest, rel).replace(process.cwd() + '/', '')}`);
+      }
+    }
+  };
+  walk(dest);
+}
+
 function gitignoreLines(content) {
   return content.split('\n').map((l) => l.trim()).filter(Boolean);
 }
@@ -959,6 +1001,26 @@ function parseHandoffMarkdown(content) {
   return sections;
 }
 
+// The `## Change` section is a bullet list (`- name: <x>`), but the next-thread
+// prompt inlines it after its own bullet. Flatten it so the prompt does not
+// read "- Change: - name: <x>".
+function inlineChangeLabel(value, fallbackName) {
+  const text = String(value || '').trim();
+  if (!text) return fallbackName;
+  const parts = text
+    .split('\n')
+    .map((line) => line.replace(/^\s*[-*]\s*/, '').trim())
+    .filter(Boolean);
+  if (parts.length === 0) return fallbackName;
+  const named = parts.find((p) => /^name:\s*/i.test(p));
+  if (named) {
+    const rest = parts.filter((p) => p !== named);
+    const label = named.replace(/^name:\s*/i, '').trim() || fallbackName;
+    return rest.length ? `${label} (${rest.join('; ')})` : label;
+  }
+  return parts.join('; ');
+}
+
 function firstLineCommand(value) {
   const match = String(value || '').match(/\/opsx:[^\s`]+(?:\s+[^\s`]+)?/);
   if (match) return match[0].trim();
@@ -968,8 +1030,14 @@ function firstLineCommand(value) {
 function firstSpawnName(value) {
   const tick = String(value || '').match(/`([a-z0-9-]+)`/i);
   if (tick) return tick[1];
-  const word = String(value || '').match(/\b([a-z][a-z0-9-]{2,})\b/i);
-  return word ? word[1] : '';
+  const role = canonicalRole(value);
+  return {
+    Explorer: 'explorer',
+    Architect: 'spec-architect',
+    'Spec Reviewer': 'spec-reviewer',
+    Implementer: '',
+    Archiver: '',
+  }[role] || '';
 }
 
 function sectionOr(sections, title, fallback = '') {
@@ -1390,7 +1458,7 @@ function buildNextSessionPrompt(fields, agentLanguage) {
 
 ## Повний контекст попередньої сесії (самодостатній — не покладайся лише на Memory)
 - Закрита роль: ${fields.closedRole || 'не вказано'}
-- Зміна: ${fields.change || name}
+- Зміна: ${inlineChangeLabel(fields.change, name)}
 - Зроблено:
 ${fields.done || 'не вказано'}
 - Рішення:
@@ -1442,7 +1510,7 @@ Do not mix phases. Do not start the following role in this chat until this phase
 
 ## Full previous-session context (self-contained — do not rely on Memory alone)
 - Closed role: ${fields.closedRole || 'not set'}
-- Change: ${fields.change || name}
+- Change: ${inlineChangeLabel(fields.change, name)}
 - Done:
 ${fields.done || 'not set'}
 - Decisions:
@@ -1474,26 +1542,48 @@ function loadMemoryItems(filePath) {
   if (!existsSync(filePath)) return [];
   const raw = readFileSync(filePath, 'utf-8').trim();
   if (!raw) return [];
-  if (raw.startsWith('{')) {
-    try {
-      const parsed = JSON.parse(raw);
+
+  // Aggregate form is a single JSON document: { entities: [...], relations: [...] }.
+  // Every JSONL line is an object too, so the *shape* decides — not the first
+  // character. Keying off `{` classified every JSONL graph as an aggregate,
+  // parsed it as one document, failed, and returned [] — which made the next
+  // persist overwrite the whole graph with just the current change.
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && !Array.isArray(parsed) && (Array.isArray(parsed.entities) || Array.isArray(parsed.relations))) {
       const entities = (parsed.entities || []).map((entity) => ({ type: 'entity', ...entity }));
       const relations = (parsed.relations || []).map((relation) => ({ type: 'relation', ...relation }));
       return [...entities, ...relations];
+    }
+  } catch {
+    // Not a single JSON document — fall through to JSONL.
+  }
+
+  // JSONL: the format @modelcontextprotocol/server-memory reads and writes,
+  // one entity or relation per line. A line we cannot parse is kept verbatim
+  // so a persist never drops memory it failed to understand.
+  const items = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
     } catch {
-      return [];
+      items.push({ __raw: trimmed });
+      continue;
     }
+    if (parsed && typeof parsed === 'object' && parsed.type) items.push(parsed);
+    else items.push({ __raw: trimmed });
   }
-  return raw
-    .split('\n')
-    .map((line) => line.trim())
-    .filter(Boolean)
-    .map((line) => JSON.parse(line));
+  return items;
 }
 
 function saveMemoryItems(filePath, items) {
   mkdirSync(dirname(filePath), { recursive: true });
-  const body = items.map((item) => JSON.stringify(item)).join('\n');
+  const body = items
+    .map((item) => (item && item.__raw !== undefined ? item.__raw : JSON.stringify(item)))
+    .join('\n');
   writeFileSync(filePath, body ? `${body}\n` : '');
 }
 
@@ -1611,7 +1701,7 @@ function readHandoffFields(projectDir, changeName) {
   return { filePath, fields: fieldsFromSections(changeName, sections) };
 }
 
-const METRICS_VERSION = 1;
+const METRICS_VERSION = 2;
 const METRICS_SPEND_KEYS = ['inputTokens', 'outputTokens', 'totalTokens', 'costUsd', 'costUsdEstimated'];
 const LEFTOVER_GRACE_MS = 120000;
 
@@ -1675,6 +1765,92 @@ function defaultMetrics(changeName, nowIso) {
   };
 }
 
+const VALID_COST_SOURCES = new Set(['api-estimate', 'api-estimate-fallback', 'amp-usage']);
+
+function compactModelRows(sources) {
+  const byModel = new Map();
+  for (const source of sources || []) {
+    if (!source) continue;
+    const platform = VALID_PLATFORMS.has(source.platform) ? source.platform : null;
+    const model = source.model == null || source.model === '' ? null : String(source.model);
+    const key = `${platform || ''}::${model || ''}`;
+    const row = byModel.get(key) || {
+      model,
+      platform,
+      inputTokens: null,
+      outputTokens: null,
+      totalTokens: null,
+      costUsd: null,
+      costUsdEstimated: null,
+    };
+    for (const field of ['inputTokens', 'outputTokens', 'totalTokens', 'costUsd']) {
+      row[field] = addNullable(row[field], numOrNull(source[field]));
+    }
+    row.costUsdEstimated = roundUsd4(addNullable(row.costUsdEstimated, numOrNull(source.costUsdEstimated)));
+    if (VALID_COST_SOURCES.has(source.costSource)) {
+      if (!row.costSource || row.costSource === source.costSource) row.costSource = source.costSource;
+      else delete row.costSource;
+    }
+    byModel.set(key, row);
+  }
+  return [...byModel.values()];
+}
+
+function compactSourceTotals(sources) {
+  const sourceIds = [];
+  const sourceTotals = {};
+  for (const source of sources || []) {
+    if (!source || source.id == null || source.id === '') continue;
+    const id = String(source.id);
+    if (!sourceIds.includes(id)) sourceIds.push(id);
+    const total = numOrNull(source.totalTokens);
+    if (total != null) sourceTotals[id] = Math.max(numOrNull(sourceTotals[id]) ?? 0, total);
+  }
+  return { sourceIds, sourceTotals };
+}
+
+function normalizeSessionV2(session) {
+  const normalized = session && typeof session === 'object' && !Array.isArray(session) ? { ...session } : {};
+  const legacySources = Array.isArray(normalized.sources) ? normalized.sources : null;
+  if (legacySources) {
+    const bestById = new Map();
+    for (const source of legacySources) {
+      if (!source || source.id == null || source.id === '') continue;
+      const id = String(source.id);
+      const previous = bestById.get(id);
+      if (!previous || (numOrNull(source.totalTokens) ?? 0) >= (numOrNull(previous.totalTokens) ?? 0)) bestById.set(id, source);
+    }
+    const compactSources = [...bestById.values()].map((source) => ({
+      ...source,
+      model: source.model || normalized.model || null,
+      platform: source.platform || normalized.platform || null,
+    }));
+    const compact = compactSourceTotals(compactSources);
+    normalized.sourceIds = compact.sourceIds;
+    normalized.sourceTotals = compact.sourceTotals;
+    normalized.byModel = compactModelRows(compactSources);
+    if (!normalized.platform && compactSources[0] && compactSources[0].platform) normalized.platform = compactSources[0].platform;
+    if (!normalized.model && compactSources[0] && compactSources[0].model) normalized.model = compactSources[0].model;
+    delete normalized.sources;
+  } else {
+    normalized.sourceIds = Array.isArray(normalized.sourceIds)
+      ? [...new Set(normalized.sourceIds.filter((id) => id != null && id !== '').map(String))]
+      : [];
+    normalized.sourceTotals = normalized.sourceTotals && typeof normalized.sourceTotals === 'object' && !Array.isArray(normalized.sourceTotals)
+      ? { ...normalized.sourceTotals }
+      : {};
+    normalized.byModel = Array.isArray(normalized.byModel) ? normalized.byModel.map((row) => ({ ...row })) : [];
+  }
+  return normalized;
+}
+
+function normalizeMetricsV2(metrics) {
+  if (!metrics || typeof metrics !== 'object' || Array.isArray(metrics)) return metrics;
+  metrics.version = METRICS_VERSION;
+  metrics.sessions = Array.isArray(metrics.sessions) ? metrics.sessions.map(normalizeSessionV2) : [];
+  return metrics;
+}
+
 function loadMetricsFile(filePath, changeName, nowIso) {
   if (!existsSync(filePath)) return defaultMetrics(changeName, nowIso);
   let parsed;
@@ -1687,7 +1863,7 @@ function loadMetricsFile(filePath, changeName, nowIso) {
     return defaultMetrics(changeName, nowIso);
   }
   const base = defaultMetrics(changeName, parsed.createdAt || nowIso);
-  return {
+  return normalizeMetricsV2({
     ...base,
     ...parsed,
     version: METRICS_VERSION,
@@ -1698,12 +1874,12 @@ function loadMetricsFile(filePath, changeName, nowIso) {
     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 });
-  const out = { ...metrics };
+  const out = normalizeMetricsV2({ ...metrics });
   delete out.timezone;
   writeFileSync(filePath, `${JSON.stringify(out, null, 2)}\n`);
 }
@@ -1750,7 +1926,7 @@ function phaseForRole(role) {
 function sessionFieldOrSources(session, key) {
   if (session[key] != null && session[key] !== '') return numOrNull(session[key]);
   let sum = null;
-  for (const src of session.sources || []) {
+  for (const src of session.byModel || []) {
     sum = addNullable(sum, numOrNull(src[key]));
   }
   return sum;
@@ -1764,8 +1940,14 @@ function lastSessionEndedAt(metrics) {
   return last;
 }
 
-function collectWindowStart(metrics, extra) {
-  return (extra && extra.startedAt) || (metrics.pending && metrics.pending.startedAt) || null;
+function collectWindowStart(metrics, extra = {}) {
+  const explicit = isoOrNull(extra.explicitStartedAt);
+  const pending = isoOrNull(metrics.pending && metrics.pending.startedAt);
+  const selected = explicit || pending || isoOrNull(extra.lastEndedAt) || isoOrNull(metrics.createdAt);
+  if (!selected) return nowUtcIso();
+  if (!explicit && !pending) return selected;
+  const selectedMs = parseFlexibleIso(selected);
+  return Number.isFinite(selectedMs) ? new Date(selectedMs - LEFTOVER_GRACE_MS).toISOString() : selected;
 }
 
 function leftoverGraceEnd(endedAt) {
@@ -1774,6 +1956,15 @@ function leftoverGraceEnd(endedAt) {
   return new Date(ms + LEFTOVER_GRACE_MS).toISOString();
 }
 
+function sessionLeftoverEnd(session, pendingStartedAt) {
+  const pending = isoOrNull(pendingStartedAt);
+  const grace = leftoverGraceEnd(session && session.endedAt);
+  if (session && session.threadId) return pending || grace;
+  if (!pending) return grace;
+  if (!grace) return pending;
+  return earlierTimestamp(pending, grace);
+}
+
 function leftoverTimestampInWindow(at, windowStart, leftoverEnd, exclusiveEnd) {
   const t = parseFlexibleIso(at);
   if (!Number.isFinite(t)) return false;
@@ -1788,10 +1979,10 @@ function leftoverTimestampInWindow(at, windowStart, leftoverEnd, exclusiveEnd) {
   return true;
 }
 
-function uniqueAmpSourceThreadPrefix(sources) {
+function uniqueAmpSourceThreadPrefix(sourceIds) {
   const prefixes = [];
-  for (const src of sources || []) {
-    const id = src && src.id != null ? String(src.id) : '';
+  for (const sourceId of sourceIds || []) {
+    const id = sourceId == null ? '' : String(sourceId);
     if (!id.startsWith('T-')) continue;
     const prefix = id.split(':')[0];
     if (!prefix) continue;
@@ -1803,14 +1994,14 @@ function uniqueAmpSourceThreadPrefix(sources) {
 function leftoverAmpThreadId(session) {
   if (!session) return null;
   if (session.threadId) return String(session.threadId);
-  return uniqueAmpSourceThreadPrefix(session.sources);
+  return uniqueAmpSourceThreadPrefix(session.sourceIds);
 }
 
 function sessionAmpThreadKeys(session) {
   const keys = new Set();
   if (session && session.threadId) keys.add(String(session.threadId));
-  for (const src of (session && session.sources) || []) {
-    const id = src && src.id != null ? String(src.id) : '';
+  for (const sourceId of (session && session.sourceIds) || []) {
+    const id = sourceId == null ? '' : String(sourceId);
     if (!id.startsWith('T-')) continue;
     const prefix = id.split(':')[0];
     if (prefix) keys.add(prefix);
@@ -1848,11 +2039,11 @@ function sessionSpendIsFrozen(session) {
   return session.spendSource === 'self-report' && reportedHasSpendNumbers(session);
 }
 
-function existingSourceRecords(metrics) {
-  const out = [];
+function existingSourceTotals(metrics) {
+  const out = {};
   for (const session of metrics.sessions || []) {
-    for (const src of session.sources || []) {
-      if (src) out.push(src);
+    for (const [id, total] of Object.entries(session.sourceTotals || {})) {
+      out[id] = Math.max(numOrNull(out[id]) ?? 0, numOrNull(total) ?? 0);
     }
   }
   return out;
@@ -1861,13 +2052,15 @@ function existingSourceRecords(metrics) {
 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));
-    }
+    for (const id of session.sourceIds || []) ids.add(String(id));
   }
   return ids;
 }
 
+function existingSessionThreadIds(metrics) {
+  return [...new Set((metrics.sessions || []).map((session) => session && session.threadId).filter(Boolean).map(String))];
+}
+
 function lastNonArchiverSession(sessions) {
   const list = Array.isArray(sessions) ? sessions : [];
   for (let i = list.length - 1; i >= 0; i -= 1) {
@@ -1903,6 +2096,63 @@ function uniqueSourceModels(sources) {
   return seen;
 }
 
+function sessionTotalsFromModels(byModel) {
+  const totals = { inputTokens: null, outputTokens: null, totalTokens: null, costUsd: null, costUsdEstimated: null };
+  for (const row of byModel || []) {
+    for (const key of Object.keys(totals)) totals[key] = addNullable(totals[key], numOrNull(row[key]));
+  }
+  totals.costUsdEstimated = roundUsd4(totals.costUsdEstimated);
+  return totals;
+}
+
+function mergeModelRows(current, incoming) {
+  const merged = new Map();
+  for (const raw of [...(current || []), ...(incoming || [])]) {
+    if (!raw) continue;
+    const model = raw.model == null || raw.model === '' ? null : String(raw.model);
+    const key = `${raw.platform || ''}::${model || ''}`;
+    const row = merged.get(key) || {
+      model,
+      platform: raw.platform || null,
+      inputTokens: null,
+      outputTokens: null,
+      totalTokens: null,
+      costUsd: null,
+      costUsdEstimated: null,
+    };
+    for (const field of ['inputTokens', 'outputTokens', 'totalTokens', 'costUsd']) {
+      row[field] = addNullable(row[field], numOrNull(raw[field]));
+    }
+    row.costUsdEstimated = roundUsd4(addNullable(row.costUsdEstimated, numOrNull(raw.costUsdEstimated)));
+    if (raw.costSource) row.costSource = raw.costSource;
+    merged.set(key, row);
+  }
+  return [...merged.values()];
+}
+
+function compactCollectedDelta(session, sources) {
+  const adjusted = [];
+  for (const source of sources || []) {
+    if (!source || source.id == null) continue;
+    const previous = numOrNull(session.sourceTotals && session.sourceTotals[source.id]);
+    const next = numOrNull(source.totalTokens);
+    if (previous == null || next == null) {
+      adjusted.push(source);
+      continue;
+    }
+    const delta = Math.max(0, next - previous);
+    if (delta === 0) continue;
+    const ratio = next > 0 ? delta / next : 0;
+    const copy = { ...source };
+    for (const field of ['inputTokens', 'outputTokens', 'totalTokens', 'costUsd', 'costUsdEstimated']) {
+      const value = numOrNull(copy[field]);
+      if (value != null) copy[field] = field.includes('Usd') ? roundUsd4(value * ratio) : Math.round(value * ratio);
+    }
+    adjusted.push(copy);
+  }
+  return adjusted;
+}
+
 function rankSources(sources) {
   return [...sources].sort((a, b) => {
     const ta = a.totalTokens ?? 0;
@@ -1974,7 +2224,15 @@ function ampThreadTotals(threads) {
       if (row && row.model && !models.includes(row.model)) models.push(row.model);
     }
   }
-  return { costUsd, agentMode, models };
+  let inputTokens = null;
+  let outputTokens = null;
+  let totalTokens = null;
+  for (const thread of list) {
+    inputTokens = addNullable(inputTokens, numOrNull(thread && thread.inputTokens));
+    outputTokens = addNullable(outputTokens, numOrNull(thread && thread.outputTokens));
+    totalTokens = addNullable(totalTokens, numOrNull(thread && thread.totalTokens));
+  }
+  return { costUsd, agentMode, models, inputTokens, outputTokens, totalTokens };
 }
 
 function resolveSessionSpend(opts, reported, sources, extra = {}) {
@@ -1988,9 +2246,9 @@ function resolveSessionSpend(opts, reported, sources, extra = {}) {
   const flagTotal = numOrNull(flags.totalTokens);
   const flagCost = numOrNull(flags.costUsd);
   const flagCredits = numOrNull(flags.ampCredits);
-  const inputTokens = firstNonNull(flagInput, self.inputTokens, fromSources.inputTokens);
-  const outputTokens = firstNonNull(flagOutput, self.outputTokens, fromSources.outputTokens);
-  let totalTokens = firstNonNull(flagTotal, self.totalTokens, fromSources.totalTokens);
+  const inputTokens = firstNonNull(flagInput, self.inputTokens, fromAmp.inputTokens, fromSources.inputTokens);
+  const outputTokens = firstNonNull(flagOutput, self.outputTokens, fromAmp.outputTokens, fromSources.outputTokens);
+  let totalTokens = firstNonNull(flagTotal, self.totalTokens, fromAmp.totalTokens, fromSources.totalTokens);
   if (totalTokens == null && (inputTokens != null || outputTokens != null)) {
     totalTokens = (inputTokens ?? 0) + (outputTokens ?? 0);
   }
@@ -2050,7 +2308,7 @@ function runCollectSpend(metrics, windowStart, windowEnd, extra = {}) {
       windowStart,
       windowEnd,
       existingSourceIds: existingSourceIdSet(metrics),
-      existingSources: existingSourceRecords(metrics),
+      existingSourceTotals: existingSourceTotals(metrics),
       env: extra.env || process.env,
       homedir: extra.homedir || process.env.HOME,
       platforms: extra.platforms,
@@ -2061,9 +2319,12 @@ function runCollectSpend(metrics, windowStart, windowEnd, extra = {}) {
       usageAmpThread: extra.usageAmpThread,
       listRecentAmpThreads: extra.listRecentAmpThreads,
       listAmpThreads: extra.listAmpThreads,
+      collectAll: extra.collectAll === true,
+      existingThreadIds: existingSessionThreadIds(metrics),
+      rebillThreadId: extra.rebillThreadId,
     });
   } catch {
-    return { sources: [], byPlatform: defaultSpendByPlatform(), byModel: [], notes: [] };
+    return { sources: [], ids: [], totals: {}, byPlatform: defaultSpendByPlatform(), byModel: [], notes: [] };
   }
 }
 
@@ -2078,7 +2339,7 @@ function leftoverCollectPlatforms(session, collectAll, ampThreadId) {
 }
 
 function resyncLeftoverSessionSpend(session, priorCost, priorSource) {
-  const fromSources = sessionTotalsFromSources(session.sources || []);
+  const fromSources = sessionTotalsFromModels(session.byModel || []);
   session.inputTokens = fromSources.inputTokens;
   session.outputTokens = fromSources.outputTokens;
   let totalTokens = fromSources.totalTokens;
@@ -2116,6 +2377,7 @@ function attachLeftoverSources(metrics, session, leftoverEnd, extra = {}) {
     env: extra.env,
     cwd: extra.cwd,
     homedir: extra.homedir,
+    rebillThreadId: ampThreadId,
   });
   let incoming = (collected.sources || []).filter((src) => leftoverTimestampInWindow(
     src.at,
@@ -2131,32 +2393,43 @@ function attachLeftoverSources(metrics, session, leftoverEnd, extra = {}) {
     });
   }
   if (!incoming.length) return 0;
-  const merged = [...(session.sources || []), ...incoming];
+  const beforeIds = new Set(session.sourceIds || []);
   if (sessionSpendIsFrozen(session)) {
-    session.sources = merged;
-    const uniqueModels = uniqueSourceModels(merged);
+    const delta = compactCollectedDelta(session, incoming);
+    session.sourceIds = [...new Set([...(session.sourceIds || []), ...incoming.map((source) => String(source.id))])];
+    session.sourceTotals = { ...(session.sourceTotals || {}) };
+    for (const source of incoming) session.sourceTotals[source.id] = Math.max(numOrNull(session.sourceTotals[source.id]) ?? 0, numOrNull(source.totalTokens) ?? 0);
+    session.byModel = mergeModelRows(session.byModel, compactModelRows(delta));
+    const uniqueModels = uniqueSourceModels(session.byModel);
     if (uniqueModels.length > 1) session.models = uniqueModels;
   } else {
     const priorCost = numOrNull(session.costUsd);
     const priorSource = session.spendSource;
-    applyCollectedSessionFields(session, merged, session.model, {}, {
+    applyCollectedSessionFields(session, incoming, session.model, {}, {
       model: session.model,
       platform: session.platform,
     }, { ampThreads: Array.isArray(extra.ampThreads) ? extra.ampThreads : collected.ampThreads });
     resyncLeftoverSessionSpend(session, priorCost, priorSource);
   }
-  return incoming.length;
+  return incoming.filter((source) => !beforeIds.has(String(source.id))).length;
 }
 
 function applyCollectedSessionFields(session, sources, resolvedModel, opts, reported, extra = {}) {
-  session.sources = sources || [];
-  const uniqueModels = uniqueSourceModels(session.sources);
+  const incoming = sources || [];
+  const delta = compactCollectedDelta(session, incoming);
+  session.sourceIds = [...new Set([...(session.sourceIds || []), ...incoming.map((source) => String(source.id))])];
+  session.sourceTotals = { ...(session.sourceTotals || {}) };
+  for (const source of incoming) {
+    session.sourceTotals[source.id] = Math.max(numOrNull(session.sourceTotals[source.id]) ?? 0, numOrNull(source.totalTokens) ?? 0);
+  }
+  session.byModel = mergeModelRows(session.byModel, compactModelRows(delta));
+  const uniqueModels = uniqueSourceModels(session.byModel);
   const fromAmp = ampThreadTotals(extra.ampThreads);
   for (const model of fromAmp.models) {
     if (model && !uniqueModels.includes(model)) uniqueModels.push(model);
   }
   if (uniqueModels.length > 1) session.models = uniqueModels;
-  const sourceModel = primaryModelFromSources(session.sources);
+  const sourceModel = primaryModelFromSources(incoming);
   if (sourceModel) {
     session.model = sourceModel;
   } else {
@@ -2164,8 +2437,8 @@ function applyCollectedSessionFields(session, sources, resolvedModel, opts, repo
       || fromAmp.models[0]
       || null;
   }
-  if (!session.platform) session.platform = primaryPlatformFromSources(session.sources) || null;
-  const spend = resolveSessionSpend(opts, reported, session.sources, extra);
+  if (!session.platform) session.platform = primaryPlatformFromSources(incoming) || null;
+  const spend = resolveSessionSpend(opts, reported, incoming, extra);
   session.inputTokens = spend.inputTokens;
   session.outputTokens = spend.outputTokens;
   session.totalTokens = spend.totalTokens;
@@ -2178,10 +2451,42 @@ function applyCollectedSessionFields(session, sources, resolvedModel, opts, repo
   if (usageModels.length || Array.isArray(session.usageModels)) {
     session.usageModels = usageModels;
   }
+  if (session.platform === 'amp' && usageModels.length) {
+    session.byModel = usageModels.map((row) => ({
+      model: row.model,
+      platform: 'amp',
+      inputTokens: numOrNull(row.inputTokens),
+      outputTokens: numOrNull(row.outputTokens),
+      totalTokens: numOrNull(row.totalTokens) ?? ((numOrNull(row.inputTokens) ?? 0) + (numOrNull(row.outputTokens) ?? 0)),
+      costUsd: numOrNull(row.costUsd),
+      costUsdEstimated: null,
+      ...(numOrNull(row.costUsd) != null ? { costSource: 'amp-usage' } : {}),
+    }));
+  }
+  if (session.costUsd == null) {
+    for (const row of session.byModel) {
+      if (row.costUsd != null) continue;
+      // adapters already estimated with the cache-read / cache-write split; do not
+      // overwrite it with the coarse input+output estimate below
+      if (row.costUsdEstimated != null) continue;
+      const described = describeClaudeCostEstimate({
+        model: String(row.model || '').replace(/^Claude\s+/i, 'claude-').replaceAll(' ', '-').toLowerCase(),
+        inputTokens: row.inputTokens,
+        outputTokens: row.outputTokens,
+      });
+      if (described) {
+        row.costUsdEstimated = described.usd;
+        row.costSource = described.costSource;
+      }
+    }
+    session.costUsdEstimated = sessionTotalsFromModels(session.byModel).costUsdEstimated;
+  } else {
+    session.costUsdEstimated = null;
+  }
 }
 
 function sessionTotalsLookOverridden(session) {
-  const fromSources = sessionTotalsFromSources(session.sources || []);
+  const fromSources = sessionTotalsFromModels(session.byModel || []);
   return ['inputTokens', 'outputTokens', 'totalTokens', 'costUsd'].some((key) => {
     const sessionVal = numOrNull(session[key]);
     const sourceVal = numOrNull(fromSources[key]);
@@ -2212,16 +2517,16 @@ function metricsBackfillFile(filePath, changeName) {
   });
   const incoming = collected.sources || [];
   if (!incoming.length) return { filePath, added: 0 };
-  const merged = [...(last.sources || []), ...incoming];
   if (sessionSpendIsFrozen(last)) {
-    last.sources = merged;
-    const uniqueModels = uniqueSourceModels(merged);
-    if (uniqueModels.length > 1) last.models = uniqueModels;
+    applyCollectedSessionFields(last, incoming, last.model, {}, last, { ampThreads: collected.ampThreads });
   } else {
-    applyCollectedSessionFields(last, merged, last.model, {}, {
+    const priorCost = numOrNull(last.costUsd);
+    const priorSource = last.spendSource;
+    applyCollectedSessionFields(last, incoming, last.model, {}, {
       model: last.model,
       platform: last.platform,
     }, { ampThreads: collected.ampThreads });
+    resyncLeftoverSessionSpend(last, priorCost, priorSource);
   }
   metrics.updatedAt = nowIso;
   recomputeMetricsAggregates(metrics);
@@ -2286,35 +2591,19 @@ function recomputeSpendMaps(metrics) {
     byModel.set(key, row);
   }
 
-  function addSourceRow(src) {
-    const nums = spendTuple(src);
-    if (src.platform && byPlatform[src.platform]) {
-      addSpendNums(byPlatform[src.platform], nums);
-      const label = adapterSourceName(src.platform, src.via);
-      if (label) byPlatform[src.platform].source = label;
-    }
-    addModelRow(src.model, src.platform, nums);
-  }
-
   for (const session of metrics.sessions || []) {
-    const sources = session.sources || [];
-    if (sources.length > 0) {
-      for (const src of sources) addSourceRow(src);
-      let sourceCost = null;
-      for (const src of sources) sourceCost = addNullable(sourceCost, numOrNull(src.costUsd));
-      if (sourceCost == null && session.platform && byPlatform[session.platform]) {
-        byPlatform[session.platform].costUsd = addNullable(
-          byPlatform[session.platform].costUsd,
-          numOrNull(session.costUsd),
-        );
-      }
-      continue;
-    }
     const sessionNums = spendTuple(session);
     if (session.platform && byPlatform[session.platform]) {
       addSpendNums(byPlatform[session.platform], sessionNums);
+      if ((session.sourceIds || []).length) {
+        byPlatform[session.platform].source = adapterSourceName(session.platform, session.platform === 'amp' ? 'amp-cli' : null);
+      }
+    }
+    if ((session.byModel || []).length) {
+      for (const row of session.byModel) addModelRow(row.model, row.platform || session.platform, spendTuple(row));
+    } else {
+      addModelRow(session.model, session.platform, sessionNums);
     }
-    addModelRow(session.model, session.platform, sessionNums);
   }
   for (const key of Object.keys(byPlatform)) {
     byPlatform[key].costUsdEstimated = roundUsd4(byPlatform[key].costUsdEstimated);
@@ -2327,7 +2616,7 @@ function recomputeSpendMaps(metrics) {
 }
 
 function recomputeMetricsAggregates(metrics) {
-  enrichMetricsCursorEstimates(metrics, process.cwd());
+  normalizeMetricsV2(metrics);
   const phases = {};
   const totals = { sessions: 0, durationMs: null, leadTimeMs: null, cloudSessions: 0 };
   const spend = emptySpendTotals();
@@ -2367,22 +2656,8 @@ function recomputeMetricsAggregates(metrics) {
         ? session.endedAt
         : laterTimestamp(phase.endedAt, session.endedAt);
     }
-    const sources = session.sources || [];
-    let sourceCost = null;
-    for (const src of sources) sourceCost = addNullable(sourceCost, numOrNull(src.costUsd));
     for (const spendKey of METRICS_SPEND_KEYS) {
-      let value = null;
-      if (sources.length > 0) {
-        if (spendKey === 'costUsd') {
-          value = sourceCost == null ? numOrNull(session.costUsd) : sourceCost;
-        } else {
-          for (const src of sources) {
-            value = addNullable(value, numOrNull(src[spendKey]));
-          }
-        }
-      } else {
-        value = sessionFieldOrSources(session, spendKey);
-      }
+      const value = sessionFieldOrSources(session, spendKey);
       phase[spendKey] = addNullable(phase[spendKey], value);
       spend[spendKey] = addNullable(spend[spendKey], value);
     }
@@ -2435,19 +2710,29 @@ function metricsRecordSessionEnd(projectDir, fields, opts = {}) {
   const nowIso = nowUtcIso();
   const metrics = loadMetricsFile(filePath, fields.changeName, nowIso);
   const lastClosed = (metrics.sessions || [])[(metrics.sessions || []).length - 1];
-  const leftoverEnd = (metrics.pending && metrics.pending.startedAt)
-    ? metrics.pending.startedAt
-    : leftoverGraceEnd(lastClosed && lastClosed.endedAt);
+  const leftoverEnd = sessionLeftoverEnd(lastClosed, metrics.pending && metrics.pending.startedAt);
   attachLeftoverSources(metrics, lastClosed, leftoverEnd, {
     exclusiveEnd: Boolean(metrics.pending && metrics.pending.startedAt),
     collect: opts.collect === true,
   });
-  let startedAt = isoOrNull(opts.startedAt) || isoOrNull(metrics.pending && metrics.pending.startedAt) || null;
+  const explicitStartedAt = isoOrNull(opts.startedAt);
+  const pendingStartedAt = isoOrNull(metrics.pending && metrics.pending.startedAt);
+  const startedAt = explicitStartedAt || pendingStartedAt || isoOrNull(lastClosed && lastClosed.endedAt) || isoOrNull(metrics.createdAt) || nowIso;
+  if (!explicitStartedAt && !pendingStartedAt) console.error('Warning: persist without restore; collecting from the last closed session boundary.');
   const reported = opts.reported || fields.metrics || emptyMetricsFields();
   const resolvedModel = opts.model === undefined ? resolveModel(opts, process.env, reported) : opts.model;
-  const windowStart = collectWindowStart(metrics, { startedAt });
+  const windowStart = collectWindowStart(metrics, {
+    explicitStartedAt,
+    lastEndedAt: lastClosed && lastClosed.endedAt,
+  });
   const pending = metrics.pending || {};
   const platform = opts.platform || pending.platform || null;
+  const cursorThreadId = platform === 'cursor'
+    ? (pending.threadId || String(process.env.CURSOR_CONVERSATION_ID || '').trim() || null)
+    : null;
+  const ampThreadId = platform === 'amp'
+    ? (opts.ampThreadId || pending.threadId || ampThreadIdFromEnv(process.env) || null)
+    : null;
   const collectAll = opts.collect === true;
   const platforms = collectAll ? undefined : (platform ? [platform] : []);
   const shouldCollect = collectAll || (Array.isArray(platforms) && platforms.length > 0);
@@ -2455,9 +2740,11 @@ function metricsRecordSessionEnd(projectDir, fields, opts = {}) {
   const collected = shouldCollect
     ? runCollectSpend(metrics, windowStart, endedAt, {
       platforms,
-      ampThreadId: opts.ampThreadId || pending.threadId || ampThreadIdFromEnv(process.env) || null,
+      ampThreadId,
       ampCli: collectAll || platform === 'amp',
-      cursorConversationId: platform === 'cursor' ? pending.threadId : undefined,
+      cursorConversationId: cursorThreadId || undefined,
+      listRecentAmpThreads: false,
+      collectAll,
     })
     : { sources: [] };
   const startedMs = parseFlexibleIso(startedAt);
@@ -2476,9 +2763,11 @@ function metricsRecordSessionEnd(projectDir, fields, opts = {}) {
     agentId: fields.agentId || 'none',
     model: resolvedModel || null,
     platform: opts.platform || pending.platform || null,
-    threadId: opts.ampThreadId || pending.threadId || null,
+    threadId: cursorThreadId || ampThreadId || pending.threadId || null,
     tasks: fields.tasks || null,
-    sources: [],
+    sourceIds: [],
+    sourceTotals: {},
+    byModel: [],
     inputTokens: null,
     outputTokens: null,
     totalTokens: null,
@@ -2488,22 +2777,6 @@ function metricsRecordSessionEnd(projectDir, fields, opts = {}) {
     spendSource: 'unreported',
   };
   applyCollectedSessionFields(session, collected.sources || [], resolvedModel, opts, reported, collected);
-  if (!session.startedAt) {
-    let earliest = null;
-    for (const src of session.sources || []) {
-      const at = isoOrNull(src.at);
-      if (!at) continue;
-      earliest = earliest == null ? at : earlierTimestamp(earliest, at);
-    }
-    if (earliest) {
-      session.startedAt = earliest;
-      const fromMs = parseFlexibleIso(session.startedAt);
-      const toMs = parseFlexibleIso(session.endedAt);
-      session.durationMs = Number.isFinite(fromMs) && Number.isFinite(toMs)
-        ? Math.max(0, toMs - fromMs)
-        : null;
-    }
-  }
   metrics.sessions.push(session);
   metrics.pending = null;
   metrics.updatedAt = nowIso;
@@ -2534,12 +2807,15 @@ function metricsFinalizeArchive(targetDir, changeName, opts = {}) {
   const platforms = collectAll ? undefined : (platform ? [platform] : []);
   const shouldCollect = collectAll || (Array.isArray(platforms) && platforms.length > 0);
   const ampThreadId = opts.ampThreadId || pending.threadId || ampThreadIdFromEnv(process.env) || null;
+  const archiveWindowStart = collectWindowStart(metrics, {});
   const collected = shouldCollect
-    ? runCollectSpend(metrics, startedAt, endedAt, {
+    ? runCollectSpend(metrics, archiveWindowStart, endedAt, {
       platforms,
       ampThreadId,
       ampCli: collectAll || platform === 'amp',
       cursorConversationId: platform === 'cursor' ? (pending.threadId || ampThreadId) : undefined,
+      listRecentAmpThreads: false,
+      collectAll,
     })
     : { sources: [] };
   const reported = dropStaleArchiveSelfReport(opts.reported, metrics.sessions);
@@ -2556,7 +2832,9 @@ function metricsFinalizeArchive(targetDir, changeName, opts = {}) {
     platform,
     threadId: ampThreadId || null,
     tasks: opts.tasks || null,
-    sources: [],
+    sourceIds: [],
+    sourceTotals: {},
+    byModel: [],
     inputTokens: null,
     outputTokens: null,
     totalTokens: null,
@@ -2595,8 +2873,9 @@ function metricsPrepareArchiveStart(changeRoot, changeName, client = {}, extra =
       clientSource: client.source || null,
     };
   }
-  const leftoverEnd = metrics.pending && metrics.pending.startedAt;
-  attachLeftoverSources(metrics, lastNonArchiverSession(metrics.sessions), leftoverEnd, {
+  const previous = lastNonArchiverSession(metrics.sessions);
+  const leftoverEnd = sessionLeftoverEnd(previous, metrics.pending && metrics.pending.startedAt);
+  attachLeftoverSources(metrics, previous, leftoverEnd, {
     exclusiveEnd: true,
     collect: extra.collect === true,
   });
@@ -2862,11 +3141,13 @@ function readPipelineConfig(projectDir) {
   const requireBriefMatch = content.match(/require_design_brief:\s*(true|false)/);
   const maxActiveMatch = content.match(/max_active_changes:\s*(\d+)/);
   const taskContractMatch = content.match(/task_contract:\s*(warn|strict|off)/);
+  const srcGlobMatch = content.match(/src_glob:\s*["']?([^"'\s#]+)["']?/);
   return {
     requireSpecReview: requireReviewMatch ? requireReviewMatch[1] === 'true' : true,
     requireDesignBrief: requireBriefMatch ? requireBriefMatch[1] === 'true' : false,
     maxActiveChanges: maxActiveMatch ? parseInt(maxActiveMatch[1], 10) : null,
     taskContract: taskContractMatch ? taskContractMatch[1] : 'warn',
+    srcGlob: srcGlobMatch ? srcGlobMatch[1] : null,
   };
 }
 
@@ -3698,6 +3979,7 @@ 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 });
+      syncCommands(projectDir, '.cursor', { namespaced: false });
     }
 
     if (syncClaude) {
@@ -3707,6 +3989,7 @@ program
         rmSync(join(projectDir, '.claude', 'skills', wrapper), { recursive: true, force: true });
       }
       copyDir(join(projectDir, '.agents', 'subagents'), join(projectDir, '.claude', 'agents'), { overwrite: true, delete: true });
+      syncCommands(projectDir, '.claude', { namespaced: true });
 
       const claudeMd = join(projectDir, 'CLAUDE.md');
       const claudeDir = join(projectDir, '.claude');
@@ -3744,6 +4027,13 @@ program
     if (changes.length === 0) {
       log.info('No active changes');
     } else {
+      // Readiness must mirror the gates `archive` actually enforces — reporting
+      // "ready" on task count alone told the conductor to archive a change the
+      // CLI would then refuse.
+      const config = readPipelineConfig(projectDir);
+      const requireReview = config ? config.requireSpecReview : true;
+      const requireBrief = config ? config.requireDesignBrief : false;
+
       for (const name of changes) {
         const changeDir = join(projectDir, 'openspec', 'changes', name);
         const progress = parseTasksProgress(changeDir);
@@ -3751,13 +4041,24 @@ program
         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);
+
+        const blockers = [];
+        if (!(progress && progress.total > 0 && progress.done === progress.total)) {
+          blockers.push('tasks incomplete');
+        }
+        if (requireReview && !(verdict && /^APPROVE/i.test(verdict))) {
+          blockers.push(verdict ? `review verdict "${verdict}" (need APPROVE)` : 'no review.md');
+        }
+        if (requireBrief && !hasBrief && !hasDesignOptOut(changeDir)) {
+          blockers.push('no design-brief.md');
+        }
 
         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');
+        if (blockers.length === 0) log.ok('ready to archive');
+        else log.info(`not ready to archive — ${blockers.join('; ')}`);
       }
       console.log('');
     }
@@ -3770,7 +4071,7 @@ program
 program
   .command('gate-check [change-name]')
   .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('--src-glob <glob>', 'source path filter used to detect code changes (default: pipeline.src_glob, else 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')
@@ -3826,16 +4127,21 @@ program
       return;
     }
 
+    // A repo whose code does not live in src/ used to fall through to
+    // "nothing to gate" on every run, silently disabling the review gate.
+    const srcGlob = opts.srcGlob || config.srcGlob || 'src/';
+
     const touchesSrc = opts.staged
-      ? gitStagedTouchesGlob(projectDir, opts.srcGlob)
-      : gitDiffTouchesGlob(projectDir, opts.base, opts.srcGlob);
+      ? gitStagedTouchesGlob(projectDir, srcGlob)
+      : gitDiffTouchesGlob(projectDir, opts.base, srcGlob);
     if (touchesSrc === false) {
-      log.ok(`no ${opts.staged ? 'staged ' : ''}changes under ${opts.srcGlob} — nothing to gate`);
+      log.ok(`no ${opts.staged ? 'staged ' : ''}changes under ${srcGlob} — nothing to gate`);
       return;
     }
     if (touchesSrc === null) {
-      log.warn(`could not compute git ${opts.staged ? 'staged ' : ''}diff — skipping gate-check`);
-      return;
+      // Cannot prove nothing changed (shallow clone, missing base ref, no
+      // commits yet) — verify the gate instead of passing a blocking check.
+      log.warn(`could not compute git ${opts.staged ? 'staged ' : ''}diff — verifying the review gate anyway`);
     }
 
     const changes = listActiveChanges(projectDir);
@@ -3846,7 +4152,7 @@ program
     let target = changeName;
     if (!target) {
       if (changes.length === 0) {
-        log.warn(`${opts.srcGlob} changed but no active OpenSpec change found — cannot verify review gate`);
+        log.warn(`${srcGlob} changed but no active OpenSpec change found — cannot verify review gate`);
         return;
       }
       target = changes
@@ -4485,6 +4791,8 @@ 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)
+  .option('--summary-json', 'Print compact aggregate JSON for dashboards', false)
+  .option('--migrate', 'Rewrite metrics.json using the current schema without recomputing numbers', false)
   .option('--collect', 'Backfill the last session from local spend adapters without adding a new session', false)
   .action((changeName, opts) => {
     const projectDir = process.cwd();
@@ -4541,6 +4849,29 @@ program
     }
 
     const metrics = loadMetricsFile(filePath, name, nowUtcIso());
+    if (opts.migrate) {
+      saveMetricsFile(filePath, metrics);
+      if (!opts.json && !opts.summaryJson) {
+        log.ok(`migrated: ${filePath.replace(`${projectDir}/`, '')}`);
+        return;
+      }
+    }
+    if (opts.summaryJson) {
+      recomputeMetricsAggregates(metrics);
+      const summary = {
+        version: metrics.version,
+        change: metrics.change,
+        createdAt: metrics.createdAt,
+        archivedAt: metrics.archivedAt,
+        totals: metrics.totals,
+        phases: metrics.phases,
+        spend: metrics.spend,
+        spendByPlatform: metrics.spendByPlatform,
+        spendByModel: metrics.spendByModel,
+      };
+      process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+      return;
+    }
     if (opts.json) {
       process.stdout.write(`${JSON.stringify(metrics, null, 2)}\n`);
       return;
@@ -4574,4 +4905,6 @@ export {
   sessionSpendIsFrozen,
   attachLeftoverSources,
   runCollectSpend,
+  normalizeMetricsV2,
+  firstSpawnName,
 };