agent-orchestrator-kit 0.10.0 → 0.11.0

package/bin/spend-collect.js

@@ -20,6 +20,53 @@ function addNullable(a, b) {
   return (a ?? 0) + (b ?? 0);
 }
 
+export function cursorSpendFingerprint(row) {
+  if (!row || typeof row !== 'object') return null;
+  const input = numOrNull(row.inputTokens);
+  const output = numOrNull(row.outputTokens);
+  if (input == null && output == null) return null;
+  const model = String(row.model || row.modelId || '');
+  const cache = numOrNull(row.cacheReadTokens) ?? 0;
+  return `${model}|${input ?? 0}|${output ?? 0}|${cache}`;
+}
+
+function preferCursorSource(previous, next) {
+  if (!previous) return next;
+  if (!next) return previous;
+  if (next.event === 'stop' && previous.event !== 'stop') return next;
+  if (previous.event === 'stop' && next.event !== 'stop') return previous;
+  const prevAt = Date.parse(previous.at);
+  const nextAt = Date.parse(next.at);
+  if (Number.isFinite(nextAt) && Number.isFinite(prevAt) && nextAt !== prevAt) {
+    return nextAt > prevAt ? next : previous;
+  }
+  return (next.totalTokens ?? 0) >= (previous.totalTokens ?? 0) ? next : previous;
+}
+
+function stripCursorCollectMeta(record) {
+  if (!record || typeof record !== 'object') return record;
+  const { event, ...rest } = record;
+  return rest;
+}
+
+export function dedupeCursorSources(sources) {
+  const best = new Map();
+  const rest = [];
+  for (const src of sources || []) {
+    if (!src || src.platform !== 'cursor') {
+      rest.push(src);
+      continue;
+    }
+    const fp = cursorSpendFingerprint(src);
+    if (!fp) {
+      rest.push(src);
+      continue;
+    }
+    best.set(fp, preferCursorSource(best.get(fp), src));
+  }
+  return [...rest, ...[...best.values()].map(stripCursorCollectMeta)];
+}
+
 function emptyPlatform(source = 'none') {
   return {
     inputTokens: null,
@@ -501,7 +548,130 @@ function collectAmpCli(ctx) {
 
 export const CURSOR_USAGE_FILE_REL = join('.agents', 'spend', 'cursor-usage.jsonl');
 
-function collectCursor({ cwd, windowStart, windowEnd, existing, notes }) {
+function loadCursorUsageById(cwd) {
+  const filePath = join(cwd, CURSOR_USAGE_FILE_REL);
+  const bestById = new Map();
+  if (!existsSync(filePath)) return bestById;
+  let text;
+  try {
+    text = readFileSync(filePath, 'utf-8');
+  } catch {
+    return bestById;
+  }
+  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;
+    const inputTokens = numOrNull(row.inputTokens);
+    const outputTokens = numOrNull(row.outputTokens);
+    if (inputTokens == null && outputTokens == null) continue;
+    const totalTokens = (inputTokens ?? 0) + (outputTokens ?? 0);
+    const previous = bestById.get(id);
+    const previousTotal = previous
+      ? (numOrNull(previous.inputTokens) ?? 0) + (numOrNull(previous.outputTokens) ?? 0)
+      : -1;
+    if (!previous || totalTokens >= previousTotal) bestById.set(id, row);
+  }
+  return bestById;
+}
+
+export function attachCursorEstimates(sources, cwd) {
+  const byId = loadCursorUsageById(cwd);
+  let changed = false;
+  for (const src of sources || []) {
+    if (!src || src.platform !== 'cursor') continue;
+    const row = src.id ? byId.get(String(src.id)) : null;
+    if (row) {
+      const cache = numOrNull(row.cacheReadTokens);
+      if (src.cacheReadTokens == null && cache != null) {
+        src.cacheReadTokens = cache;
+        changed = true;
+      }
+      if (!src.model && (row.model || row.modelId)) {
+        src.model = row.model || row.modelId;
+        changed = true;
+      }
+    }
+    const described = describeCursorCostEstimate({
+      model: src.model,
+      inputTokens: src.inputTokens,
+      outputTokens: src.outputTokens,
+      cacheReadTokens: src.cacheReadTokens,
+      totalTokens: src.totalTokens,
+    });
+    if (!described) continue;
+    if (src.costUsdEstimated !== described.usd) {
+      src.costUsdEstimated = described.usd;
+      changed = true;
+    }
+    if (src.costSource !== described.costSource) {
+      src.costSource = described.costSource;
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+export function enrichMetricsCursorEstimates(metrics, cwd) {
+  let changed = false;
+  for (const session of metrics.sessions || []) {
+    const deduped = dedupeCursorSources(session.sources || []);
+    if (deduped.length !== (session.sources || []).length) {
+      session.sources = deduped;
+      changed = true;
+    } else {
+      session.sources = deduped;
+    }
+    if (attachCursorEstimates(session.sources || [], cwd)) changed = true;
+    let estimated = null;
+    for (const src of session.sources || []) {
+      estimated = addNullable(estimated, numOrNull(src.costUsdEstimated));
+    }
+    if (estimated != null && session.costUsdEstimated !== estimated) {
+      session.costUsdEstimated = estimated;
+      changed = true;
+    }
+    if (!session.spendSource || session.spendSource === 'adapter' || session.spendSource === 'unreported') {
+      let inputTokens = null;
+      let outputTokens = null;
+      let totalTokens = null;
+      for (const src of session.sources || []) {
+        inputTokens = addNullable(inputTokens, numOrNull(src.inputTokens));
+        outputTokens = addNullable(outputTokens, numOrNull(src.outputTokens));
+        totalTokens = addNullable(totalTokens, numOrNull(src.totalTokens));
+      }
+      if (session.inputTokens !== inputTokens) {
+        session.inputTokens = inputTokens;
+        changed = true;
+      }
+      if (session.outputTokens !== outputTokens) {
+        session.outputTokens = outputTokens;
+        changed = true;
+      }
+      if (session.totalTokens !== totalTokens) {
+        session.totalTokens = totalTokens;
+        changed = true;
+      }
+    }
+    if (
+      session.spendSource === 'unreported'
+      && (session.inputTokens != null || session.totalTokens != null || (session.sources || []).length)
+    ) {
+      session.spendSource = 'adapter';
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+function collectCursor({ cwd, windowStart, windowEnd, existing, existingSources, notes, env, cursorConversationId }) {
   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)');
@@ -514,8 +684,16 @@ function collectCursor({ cwd, windowStart, windowEnd, existing, notes }) {
     notes.push('cursor: cannot read usage file');
     return [];
   }
+  const filterId = String((env && env.CURSOR_CONVERSATION_ID) || cursorConversationId || '').trim();
+  const existingFingerprints = new Set();
+  for (const src of existingSources || []) {
+    const fp = cursorSpendFingerprint(src);
+    if (fp) existingFingerprints.add(fp);
+  }
   // stop / afterAgentResponse / loop follow-ups may write the same generation_id
   // several times with cumulative turn totals; keep the largest record per id.
+  // Cursor sometimes omits generation_id, so stop + afterAgentResponse get two
+  // ids for one turn — collapse those by token fingerprint.
   const bestById = new Map();
   for (const line of text.split('\n')) {
     if (!line.trim()) continue;
@@ -529,10 +707,18 @@ function collectCursor({ cwd, windowStart, windowEnd, existing, notes }) {
     const id = row.id == null || row.id === '' ? null : String(row.id);
     if (!id) continue;
     if (existing.has(id)) continue;
+    if (filterId) {
+      const rowConversationId = row.conversationId == null || row.conversationId === ''
+        ? ''
+        : String(row.conversationId).trim();
+      if (rowConversationId !== filterId) 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 fp = cursorSpendFingerprint(row);
+    if (fp && existingFingerprints.has(fp)) continue;
     const model = row.model || row.modelId;
     const cacheReadTokens = numOrNull(row.cacheReadTokens);
     const described = describeCursorCostEstimate({
@@ -554,12 +740,18 @@ function collectCursor({ cwd, windowStart, windowEnd, existing, notes }) {
       costUsdEstimated: described?.usd ?? null,
       costSource: described?.costSource ?? null,
     });
+    record.event = row.event || null;
     const previous = bestById.get(id);
     if (!previous || (record.totalTokens ?? 0) >= (previous.totalTokens ?? 0)) {
       bestById.set(id, record);
     }
   }
-  return [...bestById.values()];
+  const bestByFingerprint = new Map();
+  for (const record of bestById.values()) {
+    const fp = cursorSpendFingerprint(record) || record.id;
+    bestByFingerprint.set(fp, preferCursorSource(bestByFingerprint.get(fp), record));
+  }
+  return [...bestByFingerprint.values()].map(stripCursorCollectMeta);
 }
 
 function aggregate(sources) {
@@ -622,15 +814,18 @@ export function collectSpend(options = {}) {
     ? options.platforms.filter((name) => PLATFORMS.includes(name))
     : PLATFORMS;
   const run = (name) => !wanted.length || wanted.includes(name);
+  const existingSources = Array.isArray(options.existingSources) ? options.existingSources : [];
   const ctx = {
     cwd,
     windowStart,
     windowEnd,
     existing,
+    existingSources,
     env,
     homedir,
     notes,
     ampThreadId: options.ampThreadId,
+    cursorConversationId: options.cursorConversationId,
     exportAmpThread: options.exportAmpThread,
     listAmpThreads: options.listAmpThreads,
     usageAmpThread: options.usageAmpThread,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-kit",
-  "version": "0.10.0",
+  "version": "0.11.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/rules/session-handoff.mdc

@@ -20,8 +20,8 @@ Agents (local or cloud) write session artifacts only to git-tracked paths — ne
 
 ## 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, 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`, `accounts/fireworks/models/glm-5p2`) — NEVER pass a Closed role, a subagent name, or an Amp **mode** (`low`, `medium`, `high`, `ultra`) as `--model`. The parent SHOULD still pass `--model`. The parent MUST NOT guess tokens. Persist collects spend for the client locked at restore (Amp: `amp threads export` + local threads; Cursor: hook file; Claude: JSONL). `--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` runs all three adapters, not only the locked client. The same `npx agent-orchestrator-kit handoff <name>` works in Cursor, Claude Code, and Amp. `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).
+2. Fill `## Metrics` before running persist. Required keys: `platform`, `model`, `input_tokens`, `output_tokens`, `cost_usd`, `amp_credits`, `spend_source`. Use `unknown` for unknown numbers — never invent `0`. Do not set `spend_source: self-report` when tokens are `unknown`. `--model` / `model` is the LLM product id (example `cursor-grok-4.6-xhigh-fast`); family `cursor-grok-4.6` is only a fallback; the CLI takes the product id from hook sources when they exist; Closed role MAY have a sentence after `—`; metrics stores the canonical token. `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-xhigh-fast`, `accounts/fireworks/models/glm-5p2`) — NEVER pass a Closed role, a subagent name, or an Amp **mode** (`low`, `medium`, `high`, `ultra`) as `--model`. The parent SHOULD still pass `--model`. The parent MUST NOT guess tokens. Persist collects spend for the client locked at restore (Amp: `amp threads export` + local threads; Cursor: hook file; Claude: JSONL). `--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` runs all three adapters, not only the locked client. The same `npx agent-orchestrator-kit handoff <name>` works in Cursor, Claude Code, and Amp. `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.

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

@@ -146,8 +146,8 @@ Archive is one deterministic CLI call — `npx agent-orchestrator-kit archive <n
 
 **End of each session (HARD STOP — you are NOT done):**
 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.
+2. Fill `## Metrics` (`platform`, `model`, `input_tokens`, `output_tokens`, `cost_usd`, `amp_credits`, `spend_source`) before persist. Use `unknown` for unknown numbers — never invent `0`. Do not set `spend_source: self-report` when tokens are `unknown`. `--model` / `model` is the LLM product id (example `cursor-grok-4.6-xhigh-fast`); family `cursor-grok-4.6` is only a fallback; the CLI takes the product id from hook sources when they exist; Closed role MAY have a sentence after `—`; metrics stores the canonical token.
+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-xhigh-fast`) — 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.
@@ -228,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 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.
+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`). Use `unknown` for unknown numbers — never invent `0`. Do not set `spend_source: self-report` when tokens are `unknown`. `--model` / `model` is the LLM product id (example `cursor-grok-4.6-xhigh-fast`); family `cursor-grok-4.6` is only a fallback; the CLI takes the product id from hook sources when they exist; Closed role MAY have a sentence after `—`; metrics stores the canonical token. (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

@@ -22,8 +22,8 @@ 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, 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`).
+2. Fill `## Metrics` (`platform`, `model`, `input_tokens`, `output_tokens`, `cost_usd`, `amp_credits`, `spend_source`) before persist. Use `unknown` for unknown numbers — never invent `0`. Do not set `spend_source: self-report` when tokens are `unknown`. `--model` / `model` is the LLM product id (example `cursor-grok-4.6-xhigh-fast`); family `cursor-grok-4.6` is only a fallback; the CLI takes the product id from hook sources when they exist; Closed role MAY have a sentence after `—`; metrics stores the canonical token. The CLI does not overwrite `## Metrics` with resolved values; `metrics.json` records what landed.
+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-xhigh-fast`) — 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`.

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

@@ -9,7 +9,7 @@ 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. Fill `## Metrics` in the change `handoff.md` only when reporting Archiver-specific numbers (use `unknown` when missing). Do not copy the previous apply session. The CLI auto-collects the locked client into the Archiver session.
+3. Fill `## Metrics` in the change `handoff.md` only when reporting Archiver-specific numbers. Use `unknown` for unknown numbers — never invent `0`. Do not set `spend_source: self-report` when tokens are `unknown`. `--model` / `model` is the LLM product id (example `cursor-grok-4.6-xhigh-fast`); family `cursor-grok-4.6` is only a fallback; the CLI takes the product id from hook sources when they exist; Closed role MAY have a sentence after `—`; metrics stores the canonical token. Do not copy the previous apply session. The CLI auto-collects the locked client into the Archiver session.
 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.