agent-orchestrator-kit 0.5.0 → 0.7.0

package/bin/spend-collect.js

@@ -0,0 +1,486 @@
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join, basename } from 'path';
+import { homedir as osHomedir } from 'os';
+
+const PLATFORMS = ['cursor', 'claude', 'amp'];
+
+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 emptyPlatform(source = 'none') {
+  return {
+    inputTokens: null,
+    outputTokens: null,
+    totalTokens: null,
+    costUsd: null,
+    ampCredits: null,
+    source,
+  };
+}
+
+function emptyByPlatform() {
+  return {
+    cursor: emptyPlatform(),
+    claude: emptyPlatform(),
+    amp: emptyPlatform(),
+  };
+}
+
+function encodeClaudeProjectDir(cwd) {
+  return String(cwd || '').replace(/[/.]/g, '-');
+}
+
+function stripFileUri(uri) {
+  const value = String(uri || '');
+  return value.startsWith('file://') ? value.slice('file://'.length) : value;
+}
+
+function normalizeFsPath(value) {
+  const stripped = stripFileUri(value).trim();
+  if (!stripped) return '';
+  if (stripped.length > 1 && stripped.endsWith('/')) return stripped.replace(/\/+$/, '');
+  return stripped;
+}
+
+function pathsEqual(a, b) {
+  const left = normalizeFsPath(a);
+  const right = normalizeFsPath(b);
+  return Boolean(left) && left === right;
+}
+
+function parseTime(value) {
+  if (value == null || value === '') return NaN;
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return value < 1e12 ? value * 1000 : value;
+  }
+  return Date.parse(String(value));
+}
+
+function inWindow(timestamp, windowStart, windowEnd) {
+  const t = parseTime(timestamp);
+  if (!Number.isFinite(t)) return false;
+  if (windowStart) {
+    const start = parseTime(windowStart);
+    if (Number.isFinite(start) && t < start) return false;
+  }
+  if (windowEnd) {
+    const end = parseTime(windowEnd);
+    if (Number.isFinite(end) && t > end) return false;
+  }
+  return true;
+}
+
+function sourceRecord({ id, platform, model, inputTokens, outputTokens, costUsd, ampCredits, at }) {
+  const input = numOrNull(inputTokens);
+  const output = numOrNull(outputTokens);
+  let total = null;
+  if (input != null || output != null) total = (input ?? 0) + (output ?? 0);
+  return {
+    id: String(id),
+    platform,
+    model: model == null || model === '' ? null : String(model),
+    inputTokens: input,
+    outputTokens: output,
+    totalTokens: total,
+    costUsd: numOrNull(costUsd),
+    ampCredits: numOrNull(ampCredits),
+    at: at == null ? null : String(at),
+  };
+}
+
+function claudeInputTokens(usage) {
+  if (!usage || typeof usage !== 'object') return null;
+  let has = false;
+  let sum = 0;
+  if (usage.input_tokens != null || usage.inputTokens != null) {
+    has = true;
+    sum += numOrNull(usage.input_tokens ?? usage.inputTokens) ?? 0;
+  }
+  for (const [key, value] of Object.entries(usage)) {
+    if (key.startsWith('cache_') && value != null) {
+      has = true;
+      sum += numOrNull(value) ?? 0;
+    }
+  }
+  return has ? sum : null;
+}
+
+function claudeCostUsd(row, usage) {
+  const candidates = [
+    row && row.total_cost_usd,
+    row && row.totalCostUsd,
+    row && row.cost_usd,
+    row && row.costUsd,
+    usage && usage.total_cost_usd,
+    usage && usage.totalCostUsd,
+    usage && usage.cost_usd,
+    usage && usage.costUsd,
+  ];
+  for (const value of candidates) {
+    const n = numOrNull(value);
+    if (n != null) return n;
+  }
+  return null;
+}
+
+function isClaudeAssistant(row) {
+  if (!row || typeof row !== 'object') return false;
+  if (row.type === 'assistant') return true;
+  if (row.message && row.message.role === 'assistant') return true;
+  return false;
+}
+
+function collectClaude({ cwd, windowStart, windowEnd, existing, env, homedir, notes }) {
+  const home = homedir || env.HOME || osHomedir();
+  const encoded = encodeClaudeProjectDir(cwd);
+  const projectDir = join(home, '.claude', 'projects', encoded);
+  const sources = [];
+  if (!existsSync(projectDir)) {
+    notes.push('claude: project folder missing');
+    return sources;
+  }
+  let files;
+  try {
+    files = readdirSync(projectDir).filter((name) => name.endsWith('.jsonl'));
+  } catch {
+    notes.push('claude: cannot read project folder');
+    return sources;
+  }
+  for (const file of files) {
+    let text;
+    try {
+      text = readFileSync(join(projectDir, file), 'utf-8');
+    } catch {
+      continue;
+    }
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue;
+      let row;
+      try {
+        row = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (!isClaudeAssistant(row)) continue;
+      const message = row.message || {};
+      const usage = message.usage;
+      if (!usage || typeof usage !== 'object') continue;
+      const id = message.id;
+      if (id == null || id === '') continue;
+      if (existing.has(String(id))) continue;
+      if (row.cwd !== cwd) continue;
+      if (!inWindow(row.timestamp, windowStart, windowEnd)) continue;
+      sources.push(sourceRecord({
+        id,
+        platform: 'claude',
+        model: message.model,
+        inputTokens: claudeInputTokens(usage),
+        outputTokens: usage.output_tokens ?? usage.outputTokens,
+        costUsd: claudeCostUsd(row, usage),
+        ampCredits: null,
+        at: row.timestamp,
+      }));
+    }
+  }
+  return sources;
+}
+
+function ampRoot(env, homedir) {
+  if (env.AMP_DATA_DIR && String(env.AMP_DATA_DIR).trim()) return String(env.AMP_DATA_DIR).trim();
+  if (env.XDG_DATA_HOME && String(env.XDG_DATA_HOME).trim()) {
+    return join(String(env.XDG_DATA_HOME).trim(), 'amp');
+  }
+  return join(homedir || env.HOME || osHomedir(), '.local', 'share', 'amp');
+}
+
+function ampTrees(thread) {
+  const trees = thread && thread.env && thread.env.initial && thread.env.initial.trees;
+  return Array.isArray(trees) ? trees : [];
+}
+
+function ampCwdCandidates(thread) {
+  const out = [];
+  const push = (value) => {
+    if (typeof value === 'string' && value.trim()) out.push(value);
+  };
+  push(thread && thread.cwd);
+  push(thread && thread.workdir);
+  const env = thread && thread.env;
+  if (env && typeof env === 'object') {
+    push(env.cwd);
+    push(env.PWD);
+    push(env.pwd);
+    if (env.initial && typeof env.initial === 'object') {
+      push(env.initial.cwd);
+      push(env.initial.PWD);
+      push(env.initial.workdir);
+      push(env.initial.workspace);
+    }
+  }
+  const meta = thread && thread.meta;
+  if (meta && typeof meta === 'object') {
+    push(meta.cwd);
+    push(meta.workdir);
+  }
+  return out;
+}
+
+function ampCurrentThreadId(env) {
+  if (!env || typeof env !== 'object') return '';
+  for (const key of ['AMP_CURRENT_THREAD', 'AMP_THREAD_ID']) {
+    const value = env[key];
+    if (value != null && String(value).trim()) return String(value).trim();
+  }
+  return '';
+}
+
+function ampThreadMentionsCwd(thread, cwd) {
+  const target = normalizeFsPath(cwd);
+  if (!target || target.length < 2) return false;
+  let blob;
+  try {
+    blob = JSON.stringify(thread);
+  } catch {
+    return false;
+  }
+  return blob.includes(target) || blob.includes(`file://${target}`);
+}
+
+function ampThreadMatches(thread, cwd, env, fileName) {
+  const trees = ampTrees(thread);
+  if (trees.length > 0) {
+    return trees.some((tree) => tree && pathsEqual(tree.uri, cwd));
+  }
+  if (ampCwdCandidates(thread).some((candidate) => pathsEqual(candidate, cwd))) return true;
+  const threadKey = thread && thread.id ? String(thread.id) : basename(fileName, '.json');
+  const current = ampCurrentThreadId(env);
+  if (current && current === threadKey) return true;
+  return ampThreadMentionsCwd(thread, cwd);
+}
+
+function ampMessages(thread) {
+  const out = [];
+  if (Array.isArray(thread.messages)) out.push(...thread.messages);
+  else if (thread.messages && typeof thread.messages === 'object') out.push(...Object.values(thread.messages));
+  if (Array.isArray(thread.turns)) out.push(...thread.turns);
+  return out;
+}
+
+function ampUsage(message) {
+  if (message && message.usage && typeof message.usage === 'object') return message.usage;
+  if (message && message.message && message.message.usage && typeof message.message.usage === 'object') {
+    return message.message.usage;
+  }
+  return null;
+}
+
+function ampId(message) {
+  return (
+    (message && (message.messageId || message.toMessageId))
+    || (message && message.message && (message.message.messageId || message.message.toMessageId || message.message.id))
+    || null
+  );
+}
+
+function ampInputTokens(usage) {
+  if (usage.totalInputTokens != null) return numOrNull(usage.totalInputTokens);
+  let has = false;
+  let sum = 0;
+  if (usage.inputTokens != null) {
+    has = true;
+    sum += numOrNull(usage.inputTokens) ?? 0;
+  }
+  if (usage.cacheCreationInputTokens != null) {
+    has = true;
+    sum += numOrNull(usage.cacheCreationInputTokens) ?? 0;
+  }
+  if (usage.cacheReadInputTokens != null) {
+    has = true;
+    sum += numOrNull(usage.cacheReadInputTokens) ?? 0;
+  }
+  return has ? sum : null;
+}
+
+function collectAmp({ cwd, windowStart, windowEnd, existing, env, homedir, notes }) {
+  const root = ampRoot(env, homedir);
+  const threadsDir = join(root, 'threads');
+  const sources = [];
+  if (!existsSync(threadsDir)) {
+    notes.push('amp: threads folder missing');
+    return sources;
+  }
+  let files;
+  try {
+    files = readdirSync(threadsDir).filter((name) => name.endsWith('.json'));
+  } catch {
+    notes.push('amp: cannot read threads');
+    return sources;
+  }
+  for (const file of files) {
+    let thread;
+    try {
+      thread = JSON.parse(readFileSync(join(threadsDir, file), 'utf-8'));
+    } catch {
+      continue;
+    }
+    if (!thread || typeof thread !== 'object') continue;
+    if (!ampThreadMatches(thread, cwd, env, file)) continue;
+    // messageId values are thread-local counters (1, 3, 5, ...), so a bare id
+    // collides across threads; namespace with the thread id for global dedup.
+    const threadKey = thread.id ? String(thread.id) : basename(file, '.json');
+    for (const message of ampMessages(thread)) {
+      const usage = ampUsage(message);
+      if (!usage) continue;
+      const rawId = ampId(message);
+      if (rawId == null || rawId === '') continue;
+      const id = `${threadKey}:${rawId}`;
+      if (existing.has(id)) continue;
+      if (!inWindow(usage.timestamp, windowStart, windowEnd)) continue;
+      sources.push(sourceRecord({
+        id,
+        platform: 'amp',
+        model: usage.model,
+        inputTokens: ampInputTokens(usage),
+        outputTokens: usage.outputTokens,
+        costUsd: null,
+        ampCredits: null,
+        at: usage.timestamp,
+      }));
+    }
+  }
+  return sources;
+}
+
+export const CURSOR_USAGE_FILE_REL = join('.agents', 'spend', 'cursor-usage.jsonl');
+
+function collectCursor({ cwd, windowStart, windowEnd, existing, notes }) {
+  const filePath = join(cwd, CURSOR_USAGE_FILE_REL);
+  if (!existsSync(filePath)) {
+    notes.push('cursor: usage file missing (spend hook not installed or no turns recorded yet)');
+    return [];
+  }
+  let text;
+  try {
+    text = readFileSync(filePath, 'utf-8');
+  } catch {
+    notes.push('cursor: cannot read usage file');
+    return [];
+  }
+  // stop / afterAgentResponse / loop follow-ups may write the same generation_id
+  // several times with cumulative turn totals; keep the largest record per id.
+  const bestById = new Map();
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    let row;
+    try {
+      row = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!row || typeof row !== 'object') continue;
+    const id = row.id == null || row.id === '' ? null : String(row.id);
+    if (!id) continue;
+    if (existing.has(id)) continue;
+    if (!inWindow(row.at, windowStart, windowEnd)) continue;
+    const inputTokens = numOrNull(row.inputTokens);
+    const outputTokens = numOrNull(row.outputTokens);
+    if (inputTokens == null && outputTokens == null) continue;
+    const record = sourceRecord({
+      id,
+      platform: 'cursor',
+      model: row.model || row.modelId,
+      inputTokens,
+      outputTokens,
+      costUsd: null,
+      ampCredits: null,
+      at: row.at,
+    });
+    const previous = bestById.get(id);
+    if (!previous || (record.totalTokens ?? 0) >= (previous.totalTokens ?? 0)) {
+      bestById.set(id, record);
+    }
+  }
+  return [...bestById.values()];
+}
+
+function aggregate(sources) {
+  const byPlatform = emptyByPlatform();
+  const byModel = new Map();
+  for (const src of sources) {
+    const platform = PLATFORMS.includes(src.platform) ? src.platform : null;
+    if (platform) {
+      const bucket = byPlatform[platform];
+      bucket.inputTokens = addNullable(bucket.inputTokens, src.inputTokens);
+      bucket.outputTokens = addNullable(bucket.outputTokens, src.outputTokens);
+      bucket.totalTokens = addNullable(bucket.totalTokens, src.totalTokens);
+      bucket.costUsd = addNullable(bucket.costUsd, src.costUsd);
+      bucket.ampCredits = addNullable(bucket.ampCredits, src.ampCredits);
+      if (platform === 'claude') bucket.source = 'claude-jsonl';
+      else if (platform === 'amp') bucket.source = 'amp-thread';
+      else bucket.source = 'cursor-hook';
+    }
+    const model = src.model;
+    if (model) {
+      const key = `${model}::${src.platform || ''}`;
+      const row = byModel.get(key) || {
+        model,
+        platform: src.platform || null,
+        inputTokens: null,
+        outputTokens: null,
+        totalTokens: null,
+        costUsd: null,
+        ampCredits: null,
+      };
+      row.inputTokens = addNullable(row.inputTokens, src.inputTokens);
+      row.outputTokens = addNullable(row.outputTokens, src.outputTokens);
+      row.totalTokens = addNullable(row.totalTokens, src.totalTokens);
+      row.costUsd = addNullable(row.costUsd, src.costUsd);
+      row.ampCredits = addNullable(row.ampCredits, src.ampCredits);
+      byModel.set(key, row);
+    }
+  }
+  return { byPlatform, byModel: [...byModel.values()] };
+}
+
+export function collectSpend(options = {}) {
+  const env = options.env || process.env;
+  const cwd = options.cwd != null ? options.cwd : process.cwd();
+  const homedir = options.homedir || env.HOME || osHomedir();
+  const existing = new Set(
+    Array.isArray(options.existingSourceIds)
+      ? options.existingSourceIds
+      : options.existingSourceIds instanceof Set
+        ? [...options.existingSourceIds]
+        : [],
+  );
+  const windowStart = options.windowStart;
+  const windowEnd = options.windowEnd;
+  const notes = [];
+  const ctx = { cwd, windowStart, windowEnd, existing, env, homedir, notes };
+  let sources = [];
+  try {
+    sources = sources.concat(collectClaude(ctx));
+  } catch {
+    notes.push('claude: adapter failed');
+  }
+  try {
+    sources = sources.concat(collectAmp(ctx));
+  } catch {
+    notes.push('amp: adapter failed');
+  }
+  try {
+    sources = sources.concat(collectCursor(ctx));
+  } catch {
+    notes.push('cursor: adapter failed');
+  }
+  const { byPlatform, byModel } = aggregate(sources);
+  return { sources, byPlatform, byModel, notes };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-kit",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Universal AI agent orchestration kit for Cursor, Claude Code, and Amp Code — spec-driven OpenSpec pipeline, conductor subagents, durable session handoff, factory gates and MCP setup, cloud-agent handoff, and optional local Figma PAT setup",
   "keywords": [
     "ai-agent",

package/templates/.agents/commands/opsx-archive.md

@@ -5,15 +5,15 @@ category: Workflow
 description: Archive a completed change via the agent-orchestrator-kit CLI
 ---
 
-Session Start / Session Exit: follow the protocol in `.agents/rules/session-handoff.mdc`. Announce the Archiver role.
+Session Start / Exit: `.agents/rules/session-handoff.mdc`. Announce Archiver.
 
-Archive is fully deterministic — one CLI call, no phase subagents.
+Archive is one CLI call, no phase subagents.
 
 **Steps**
 
-1. **Resolve the change name.** Use the name after `/opsx:archive`. If omitted or ambiguous, run `npx openspec list --json` and use the **AskUserQuestion tool** to let the user pick an active change. Never guess.
+1. **Resolve the name.** After `/opsx:archive`, or `npx openspec list --json` + AskUserQuestion. Never guess.
 
-2. **Decide on delta-spec sync.** If the change has delta specs, ask the user: merge them into main specs (`--sync`, recommended) or archive without merging (`--no-sync --force`).
+2. **Sync decision.** If delta specs exist, ask: merge (`--sync`) or skip (`--no-sync --force`).
 
 3. **Run the CLI:**
 
@@ -21,8 +21,8 @@ Archive is fully deterministic — one CLI call, no phase subagents.
    npx agent-orchestrator-kit archive <name> [--sync | --no-sync --force]
    ```
 
-   The CLI checks gates (review APPROVE, all tasks `[x]`, no existing target), merges delta specs on `--sync`, moves the change to `openspec/changes/archive/YYYY-MM-DD-<name>`, runs `npx openspec validate --all --strict` with full rollback on failure, and writes the final `handoff.md` (`next_command: none`) plus memory upsert.
+   Gates, optional `--sync`, move to `archive/YYYY-MM-DD-<name>`, validate+rollback, final `handoff.md` (`next_command: none`) + memory. A successful `archive` always creates or updates `metrics.json` (`archivedAt`, Archiver session) and prints the change-wide metrics summary. Collect runs only with `--collect`; if `spend.costUsd` is `null` — stderr warning, not a gate.
 
-4. **Show the CLI stdout as-is.** On exit ≠ 0, report the failed gate from stderr and stop — do not merge or move anything manually.
+4. **Show stdout as-is.** On exit ≠ 0, report the gate from stderr and stop — no manual merge/move.
 
-The pipeline ends here: no next-thread prompt is required after a successful archive.
+No next-thread prompt after a successful archive.

package/templates/.agents/rules/session-handoff.mdc

@@ -19,13 +19,14 @@ Agents (local or cloud) write session artifacts only to git-tracked paths — ne
 7. Only then start phase work (spawn a specialist when the phase routing requires one).
 
 ## Session Exit (order)
-1. The parent writes `openspec/changes/<name>/handoff.md` itself: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints, Runtime.
-2. `npx agent-orchestrator-kit handoff <name>` — require exit 0 (appends non-empty Decisions into append-only `openspec/changes/<name>/decisions.md`, upserts absolute-path Memory JSON, records the session into `openspec/changes/<name>/metrics.json`, prints the expanded prompt on stdout). `decisions.md` is the git canon of change decisions; Memory `Decision:*` is a file→Memory mirror only. Cloud sessions pass `--runtime cloud` (or set `AOK_RUNTIME=cloud` / `AOK_AGENT_ID` in the cloud-agent environment). When session spend is known, pass it to persist: `--model <name> --input-tokens <n> --output-tokens <n> --cost-usd <usd>` — metrics power planning; never guess values you do not know.
-3. Spawn `session-handoff` in persist mode ONLY if step 2 failed (Amp: isolated `subagent-session-handoff`). Fallback, never routine.
-4. Memory MCP is an optional mirror: if tools are available, update `Change:<name>`, `Handoff:<name>`, `Decision:*` in one call; unavailability never blocks closing.
-5. Paste CLI stdout as one fenced block. First line `/opsx:…`. Body uses `project.agent_language`. Self-contained (Done/Decisions/Blocked/spawn/HARD STOP). No banner.
-6. If runtime is cloud: after persist, `git add openspec/changes/<name>/` → `git commit` → `git push` → `npx agent-orchestrator-kit handoff <name> --cloud-check` (exit 0 required). Closing without this is an incomplete handoff. Persist prints these steps on stderr; the CLI never runs `git commit` / `git push`.
-7. Stop. Next role = new chat.
+1. The parent writes `openspec/changes/<name>/handoff.md` itself: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints, Runtime, Metrics.
+2. Fill `## Metrics` before running persist. Required keys: `platform`, `model`, `input_tokens`, `output_tokens`, `cost_usd`, `amp_credits`, `spend_source`. Use `unknown` when a value is missing — never invent `0`. This self-report is the primary spend source; `metrics.json` records what the CLI resolved.
+3. `npx agent-orchestrator-kit handoff <name> --model <llm-product-id>` — require exit 0 (appends non-empty Decisions into append-only `openspec/changes/<name>/decisions.md`, upserts absolute-path Memory JSON, records the session into `openspec/changes/<name>/metrics.json`, prints the expanded prompt on stdout). `--model` is the LLM product id of this chat (`claude-opus-5`, `claude-fable-5`, `gpt-5.6-sol`, `cursor-grok-4.6`) — NEVER pass a Closed role (`Architect`, `Implementer`, `Explorer`) or a subagent name (`spec-architect`, `session-handoff`) as `--model`. The parent SHOULD still pass `--model`. The parent MUST NOT guess tokens. `--input-tokens` / `--output-tokens` / `--total-tokens` / `--cost-usd` override session-level totals only and do not wipe platform maps; they do not rewrite `## Metrics`. Optional `--platform cursor|claude|amp` or `AOK_PLATFORM`. Optional `--collect` also runs local spend adapters (Claude JSONL, Amp threads, Cursor spend hook file). The same `npx agent-orchestrator-kit handoff <name>` works in Cursor, Claude Code, and Amp and MUST NOT require Cursor SDK, a Claude `/cost` parser, or an Amp billing API as a required step. `decisions.md` is the git canon of change decisions; Memory `Decision:*` is a file→Memory mirror only. Cloud sessions pass `--runtime cloud` (or set `AOK_RUNTIME=cloud` / `AOK_AGENT_ID` in the cloud-agent environment).
+4. Spawn `session-handoff` in persist mode ONLY if step 3 failed (Amp: isolated `subagent-session-handoff`). Fallback, never routine.
+5. Memory MCP is an optional mirror: if tools are available, update `Change:<name>`, `Handoff:<name>`, `Decision:*` in one call; unavailability never blocks closing.
+6. Paste CLI stdout as one fenced block. First line `/opsx:…`. Body uses `project.agent_language`. Self-contained (Done/Decisions/Blocked/spawn/HARD STOP). No banner.
+7. If runtime is cloud: after persist, `git add openspec/changes/<name>/` → `git commit` → `git push` → `npx agent-orchestrator-kit handoff <name> --cloud-check` (exit 0 required). Closing without this is an incomplete handoff. Persist prints these steps on stderr; the CLI never runs `git commit` / `git push`.
+8. Stop. Next role = new chat.
 
 ## Archive exception
 `npx agent-orchestrator-kit archive <name>` writes the final `handoff.md` (`next_command: none`) in the archive folder and upserts memory itself. After a successful archive no fenced next-prompt is required — the pipeline is complete.

package/templates/.agents/skills/agent-orchestration/SKILL.md

@@ -145,11 +145,12 @@ Archive is one deterministic CLI call — `npx agent-orchestrator-kit archive <n
 - Never edit files outside your role's allowed output
 
 **End of each session (HARD STOP — you are NOT done):**
-1. Write `openspec/changes/<name>/handoff.md` in the parent using the template below.
-2. Run `npx agent-orchestrator-kit handoff <name>` and require exit 0. The CLI appends non-empty Decisions into append-only `openspec/changes/<name>/decisions.md` (the git canon), upserts Memory JSON with an absolute path (`Decision:*` is a file→Memory mirror only), and prints the expanded self-contained prompt on stdout. Spawn `session-handoff` in persist mode ONLY if this CLI step failed.
-3. If Memory MCP tools are available, mirror `Change:<name>`, `Handoff:<name>`, and new `Decision:<topic>` entities in one call — optional; its absence never blocks closing.
-4. Paste the CLI stdout as one fenced next-session prompt. First line is `/opsx:<next> <name>`; body uses `project.agent_language`; keep Done/Decisions/Blocked/spawn/HARD STOP complete. No banner. Do not emit a thin “read Memory” stub.
-5. Do not start the next phase in this chat. If apply, include build/lint status in the persisted Done section.
+1. Write `openspec/changes/<name>/handoff.md` in the parent using the template below, including `## Metrics`.
+2. Fill `## Metrics` (`platform`, `model`, `input_tokens`, `output_tokens`, `cost_usd`, `amp_credits`, `spend_source`) before persist. Use `unknown` when a value is missing — never invent `0`.
+3. Run `npx agent-orchestrator-kit handoff <name> --model <llm-product-id>` and require exit 0. `--model` is the LLM product id of this chat (`claude-opus-5`, `claude-fable-5`, `gpt-5.6-sol`, `cursor-grok-4.6`) — NEVER pass a Closed role (`Architect`, `Implementer`, `Explorer`) or a subagent name (`spec-architect`, `session-handoff`) as `--model`. The parent SHOULD still pass `--model`. The parent MUST NOT guess tokens. `--input-tokens` / `--output-tokens` / `--total-tokens` / `--cost-usd` override session-level totals only and do not wipe platform maps or rewrite `## Metrics`. Optional `--platform cursor|claude|amp` or `AOK_PLATFORM`. Optional `--collect` also runs local spend adapters. The same command works in Cursor, Claude Code, and Amp and MUST NOT require Cursor SDK, a Claude `/cost` parser, or an Amp billing API as a required step. The CLI appends non-empty Decisions into append-only `openspec/changes/<name>/decisions.md` (the git canon), upserts Memory JSON with an absolute path (`Decision:*` is a file→Memory mirror only), and prints the expanded self-contained prompt on stdout. Spawn `session-handoff` in persist mode ONLY if this CLI step failed.
+4. If Memory MCP tools are available, mirror `Change:<name>`, `Handoff:<name>`, and new `Decision:<topic>` entities in one call — optional; its absence never blocks closing.
+5. Paste the CLI stdout as one fenced next-session prompt. First line is `/opsx:<next> <name>`; body uses `project.agent_language`; keep Done/Decisions/Blocked/spawn/HARD STOP complete. No banner. Do not emit a thin “read Memory” stub.
+6. Do not start the next phase in this chat. If apply, include build/lint status in the persisted Done section.
 
 `handoff.md` template:
 
@@ -197,6 +198,15 @@ Archive is one deterministic CLI call — `npx agent-orchestrator-kit archive <n
 - runtime: <local | cloud>
 - agent_id: <id | none>
 
+## Metrics
+- platform: <cursor | claude | amp | unknown>
+- model: <llm-product-id | unknown>
+- input_tokens: <n | unknown>
+- output_tokens: <n | unknown>
+- cost_usd: <n | unknown>
+- amp_credits: <n | unknown>
+- spend_source: <self-report | flag | adapter | unreported | unknown>
+
 ## Prompt
 
 The Prompt section is overwritten by `npx agent-orchestrator-kit handoff <name>`. Do not hand-write a thin stub.
@@ -218,7 +228,7 @@ The Prompt section is overwritten by `npx agent-orchestrator-kit handoff <name>`
 
 Before specialist work, the parent MUST restore context in order: honor the pasted `/opsx:*` command; run `npx agent-orchestrator-kit handoff --restore` (the CLI briefing is canonical — no separate Memory MCP read step); if the CLI failed, read `openspec/changes/<name>/handoff.md`; spawn `session-handoff` in restore mode ONLY when both failed. Missing Memory MCP never blocks a session. With one active change, free-form “continue” uses `Handoff.next_command` instead of asking for the phase. Amp spawns any needed subagent as an isolated `subagent-*` skill.
 
-Before declaring a session closed, the parent MUST, in order: (1) write `openspec/changes/<name>/handoff.md` itself, (2) run `npx agent-orchestrator-kit handoff <name>` (exit 0) — this CLI appends `decisions.md` and mirrors `Decision:*` file→Memory; spawn `session-handoff` persist ONLY if this CLI step failed, (3) paste the CLI stdout prompt whose first line is `/opsx:<next> <name>`. Memory MCP mirroring is an optional single call. Never write Memory back into `decisions.md`. The prompt has no `NEXT_SESSION_PROMPT` label, uses `project.agent_language`, and MUST be self-contained (Done, Decisions, Blocked, attach, spawn, HARD STOP) so the next thread can run if Memory MCP is ignored. Never start the next phase in the current chat. Write session artifacts only to git-tracked paths (never `/tmp`, never gitignored caches). If runtime is cloud: after persist, commit → push → `npx agent-orchestrator-kit handoff <name> --cloud-check` with exit 0; closing without that is an incomplete handoff.
+Before declaring a session closed, the parent MUST, in order: (1) write `openspec/changes/<name>/handoff.md` itself including `## Metrics` (keys `platform`, `model`, `input_tokens`, `output_tokens`, `cost_usd`, `amp_credits`, `spend_source`; `unknown` when missing), (2) run `npx agent-orchestrator-kit handoff <name> --model <llm-product-id>` (exit 0) — NEVER pass a Closed role or subagent name as `--model`; the parent SHOULD still pass `--model` and MUST NOT guess tokens; spend flags override session totals only and do not rewrite `## Metrics`; optional `--platform`; optional `--collect` for local adapters; the same CLI works in Cursor, Claude Code, and Amp and MUST NOT require Cursor SDK, Claude `/cost`, or Amp billing as a required step; this CLI appends `decisions.md` and mirrors `Decision:*` file→Memory; spawn `session-handoff` persist ONLY if this CLI step failed, (3) paste the CLI stdout prompt whose first line is `/opsx:<next> <name>`. Memory MCP mirroring is an optional single call. Never write Memory back into `decisions.md`. The prompt has no `NEXT_SESSION_PROMPT` label, uses `project.agent_language`, and MUST be self-contained (Done, Decisions, Blocked, attach, spawn, HARD STOP) so the next thread can run if Memory MCP is ignored. Never start the next phase in the current chat. Write session artifacts only to git-tracked paths (never `/tmp`, never gitignored caches). If runtime is cloud: after persist, commit → push → `npx agent-orchestrator-kit handoff <name> --cloud-check` with exit 0; closing without that is an incomplete handoff.
 
 | Entity | Required fields |
 |--------|-----------------|

package/templates/.agents/subagents/session-handoff.md

@@ -21,11 +21,12 @@ Use when the parent's restore failed (CLI restore and handoff.md both unavailabl
 
 Use when the parent's persist failed (`npx agent-orchestrator-kit handoff <name>` did not exit 0). A session is not closed until persist succeeds.
 
-1. Write or update `openspec/changes/<name>/handoff.md` with every required section: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints, Runtime.
-2. Run `npx agent-orchestrator-kit handoff <name>` and require exit 0. This appends non-empty Decisions into append-only `openspec/changes/<name>/decisions.md` (git canon), upserts `.cursor/memory.json` using an absolute path (`Decision:*` mirrors that file, never the reverse), and prints the expanded next-session prompt on stdout. Cloud sessions pass `--runtime cloud` (or `AOK_RUNTIME` / `AOK_AGENT_ID`).
-3. If Memory MCP tools are available, also create/update `Change:<name>`, `Handoff:<name>`, and each `Decision:<topic>` to match `decisions.md`. MCP failure is not a blocker after the CLI succeeds.
-4. Put the CLI stdout prompt (first line `/opsx:…`) into **Next prompt** unchanged. Do not shorten it. Do not add a banner.
-5. If runtime is cloud: after persist, commit and push `openspec/changes/<name>/`, then `npx agent-orchestrator-kit handoff <name> --cloud-check` (exit 0 required). Closing without this is an incomplete handoff. The CLI never runs `git commit` / `git push`.
+1. Write or update `openspec/changes/<name>/handoff.md` with every required section: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints, Runtime, Metrics.
+2. Fill `## Metrics` (`platform`, `model`, `input_tokens`, `output_tokens`, `cost_usd`, `amp_credits`, `spend_source`) before persist. Use `unknown` when a value is missing. The section is the agent's self-report; the CLI does not overwrite it with resolved values.
+3. Run `npx agent-orchestrator-kit handoff <name> --model <llm-product-id>` and require exit 0. `--model` is the LLM product id of this chat (`claude-opus-5`, `claude-fable-5`, `gpt-5.6-sol`, `cursor-grok-4.6`) — NEVER pass a Closed role (`Architect`, `Implementer`, `Explorer`) or a subagent name (`spec-architect`, `session-handoff`) as `--model`. The parent SHOULD still pass `--model`. The parent MUST NOT guess tokens. `--input-tokens` / `--output-tokens` / `--total-tokens` / `--cost-usd` override session-level totals only and do not wipe platform maps. Optional `--platform cursor|claude|amp` or `AOK_PLATFORM`. Optional `--collect` also runs local spend adapters. The same command works in Cursor, Claude Code, and Amp and MUST NOT require Cursor SDK, a Claude `/cost` parser, or an Amp billing API as a required step. This appends non-empty Decisions into append-only `openspec/changes/<name>/decisions.md` (git canon), upserts `.cursor/memory.json` using an absolute path (`Decision:*` mirrors that file, never the reverse), and prints the expanded next-session prompt on stdout. Cloud sessions pass `--runtime cloud` (or `AOK_RUNTIME` / `AOK_AGENT_ID`).
+4. If Memory MCP tools are available, also create/update `Change:<name>`, `Handoff:<name>`, and each `Decision:<topic>` to match `decisions.md`. MCP failure is not a blocker after the CLI succeeds.
+5. Put the CLI stdout prompt (first line `/opsx:…`) into **Next prompt** unchanged. Do not shorten it. Do not add a banner.
+6. If runtime is cloud: after persist, commit and push `openspec/changes/<name>/`, then `npx agent-orchestrator-kit handoff <name> --cloud-check` (exit 0 required). Closing without this is an incomplete handoff. The CLI never runs `git commit` / `git push`.
 
 ## Rules
 

package/templates/.agents/subagents/spec-archiver.md

@@ -9,8 +9,9 @@ Workflow:
 
 1. Read `.agents/orchestrator.yaml`, the complete change, review verdict, task state, and verification/merge evidence supplied by the conductor.
 2. Refuse to archive unless required review is approved, all tasks are complete, and the configured merge/CI gate is satisfied.
-3. Run the project-supported OpenSpec archive command so delta requirements are merged into main specs and the change moves to the dated archive path.
-4. Run strict validation after the move and report the resulting archive path and modified main specs.
+3. Fill `## Metrics` in the change `handoff.md` (Archiver self-report: platform, model, tokens, cost_usd, amp_credits, spend_source; use `unknown` when missing) before running archive.
+4. Run `npx agent-orchestrator-kit archive <name>` so delta requirements are merged into main specs, the change moves to the dated archive path, and stdout prints the change-wide metrics summary (by phase / by platform / by model).
+5. Run strict validation after the move and report the resulting archive path and modified main specs.
 
 Rules:
 

package/templates/AGENTS.md

@@ -23,7 +23,7 @@ Routing table, HARD STOP, and CLI forms: `.agents/rules/` (`agent-orchestration`
 | Quick (MVP) | `/opsx:quick <name>` |
 | Archive | `/opsx:archive` |
 
-Session Start / Exit are **parent-driven** — canonical protocol in `.agents/rules/session-handoff.mdc`. Start: `status` → `handoff --restore` → `handoff.md` fallback. Exit HARD STOP: parent writes `handoff.md` → `npx agent-orchestrator-kit handoff <name>` (exit 0) → paste the CLI `/opsx:*` prompt. `session-handoff` subagent = fallback only. Do not start the next phase here.
+Session Start / Exit are **parent-driven** — canonical protocol in `.agents/rules/session-handoff.mdc`. Start: `status` → `handoff --restore` → `handoff.md` fallback. Exit HARD STOP: parent writes `handoff.md` including `## Metrics` (use `unknown` when a value is missing) → `npx agent-orchestrator-kit handoff <name>` (exit 0; optional `--collect`) → paste the CLI `/opsx:*` prompt. `session-handoff` subagent = fallback only. Do not start the next phase here.
 
 Quality gates: `gate-check --tasks <name>` lints the task contract (Files/Do/Done-when, `pipeline.task_contract: warn|strict|off`); `gate-check --review <name>` is deterministic Tier 1 of review — spec-reviewer (Tier 2) is spawned only after it passes and writes `apply-notes.md` on APPROVE.