agent-orchestrator-kit 0.6.0 → 0.7.0

package/bin/spend-collect.js

@@ -43,6 +43,19 @@ function stripFileUri(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)) {
@@ -188,10 +201,69 @@ function ampRoot(env, homedir) {
   return join(homedir || env.HOME || osHomedir(), '.local', 'share', 'amp');
 }
 
-function ampTreesMatch(thread, cwd) {
+function ampTrees(thread) {
   const trees = thread && thread.env && thread.env.initial && thread.env.initial.trees;
-  if (!Array.isArray(trees) || trees.length === 0) return false;
-  return trees.some((tree) => tree && stripFileUri(tree.uri) === cwd);
+  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) {
@@ -260,7 +332,7 @@ function collectAmp({ cwd, windowStart, windowEnd, existing, env, homedir, notes
       continue;
     }
     if (!thread || typeof thread !== 'object') continue;
-    if (!ampTreesMatch(thread, cwd)) 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');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-kit",
-  "version": "0.6.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

@@ -21,7 +21,7 @@ Archive is one CLI call, no phase subagents.
    npx agent-orchestrator-kit archive <name> [--sync | --no-sync --force]
    ```
 
-   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 runs collect unless `--no-collect`; if `spend.costUsd` is `null` — stderr warning, not a gate.
+   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 stdout as-is.** On exit ≠ 0, report the gate from stderr and stop — no manual merge/move.
 

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> --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`. Persist auto-collects local usage from Claude JSONL, Amp threads, and the Cursor spend hook file (.agents/spend/cursor-usage.jsonl). 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`. 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).
-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> --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`. Persist auto-collects local usage from Claude JSONL, Amp threads, and the Cursor spend hook file (.agents/spend/cursor-usage.jsonl). 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`. 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.
-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> --model <llm-product-id>` (exit 0) — NEVER pass a Closed role or subagent name as `--model`; persist auto-collects local usage from Claude JSONL, Amp threads, and the Cursor spend hook file (.agents/spend/cursor-usage.jsonl); the parent SHOULD still pass `--model` and MUST NOT guess tokens; spend flags override session totals only; optional `--platform`; 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`; `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> --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`. Persist auto-collects local usage from Claude JSONL, Amp threads, and the Cursor spend hook file (.agents/spend/cursor-usage.jsonl). 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`. 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`).
-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.
 

package/templates/CLAUDE.md

@@ -10,6 +10,6 @@ See `AGENTS.md` and `.agents/rules/` for routing, HARD STOP, and CLI (`npx` only
 
 Lean delegation: explore/design/propose/review spawn a mandatory specialist; apply is parent-driven from `tasks.md` + `apply-notes.md` (subagents optional for independent tasks); archive runs `npx agent-orchestrator-kit archive <name> [--sync]` — no subagent. Review is two-tiered: `gate-check --review` (deterministic) before `spec-reviewer`; `gate-check --tasks` lints the Files/Do/Done-when task contract.
 
-Session Start/Exit are parent-driven (canonical: `.agents/rules/session-handoff.mdc`): restore with `npx agent-orchestrator-kit handoff --restore`; exit — write `handoff.md`, run `npx agent-orchestrator-kit handoff <name>` (exit 0), paste the CLI prompt. `session-handoff` subagent is a fallback only. Do not start the next phase in this chat.
+Session Start/Exit are parent-driven (canonical: `.agents/rules/session-handoff.mdc`): restore with `npx agent-orchestrator-kit handoff --restore`; exit — write `handoff.md` including `## Metrics` (`unknown` when missing), run `npx agent-orchestrator-kit handoff <name>` (exit 0; optional `--collect`), paste the CLI prompt. `session-handoff` subagent is a fallback only. Do not start the next phase in this chat.
 
 One active change. No `src/` in explore/design/review. After apply: build/lint. Skills: `.claude/skills/` (synced from `.agents/skills/`).

package/templates/scripts/cursor-spend-collect.cjs

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+// Cursor hook (sessionEnd): merge leftover hook rows into the last metrics
+// session after `stop` has written `.agents/spend/cursor-usage.jsonl`.
+// Fail-open and silent — never block the agent loop.
+'use strict';
+
+const { existsSync, readdirSync, readFileSync, writeFileSync, statSync } = require('fs');
+const { join } = require('path');
+
+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 resolveBaseDir(payload) {
+  const cwd = process.cwd();
+  if (existsSync(join(cwd, 'openspec', 'changes'))) return cwd;
+  const roots = Array.isArray(payload.workspace_roots) ? payload.workspace_roots : [];
+  for (const root of roots) {
+    if (root && existsSync(join(String(root), 'openspec', 'changes'))) return String(root);
+  }
+  return cwd;
+}
+
+function existingIds(metrics) {
+  const ids = new Set();
+  for (const session of metrics.sessions || []) {
+    for (const src of session.sources || []) {
+      if (src && src.id != null && src.id !== '') ids.add(String(src.id));
+    }
+  }
+  return ids;
+}
+
+function sourceTotals(sources) {
+  let inputTokens = null;
+  let outputTokens = null;
+  let totalTokens = null;
+  let costUsd = null;
+  for (const src of sources || []) {
+    inputTokens = addNullable(inputTokens, numOrNull(src.inputTokens));
+    outputTokens = addNullable(outputTokens, numOrNull(src.outputTokens));
+    totalTokens = addNullable(totalTokens, numOrNull(src.totalTokens));
+    if (src.costUsd != null) costUsd = addNullable(costUsd, numOrNull(src.costUsd));
+  }
+  return { inputTokens, outputTokens, totalTokens, costUsd };
+}
+
+function looksOverridden(session) {
+  const fromSources = sourceTotals(session.sources || []);
+  return ['inputTokens', 'outputTokens', 'totalTokens', 'costUsd'].some((key) => {
+    const sessionVal = numOrNull(session[key]);
+    const sourceVal = numOrNull(fromSources[key]);
+    if (sessionVal == null) return false;
+    if (sourceVal == null) return true;
+    return sessionVal !== sourceVal;
+  });
+}
+
+function emptyPlatform(source = 'none') {
+  return {
+    inputTokens: null,
+    outputTokens: null,
+    totalTokens: null,
+    costUsd: null,
+    ampCredits: null,
+    source,
+  };
+}
+
+function recompute(metrics) {
+  const phases = {};
+  const totals = { sessions: 0, durationMs: null, leadTimeMs: null, cloudSessions: 0 };
+  const spend = { inputTokens: null, outputTokens: null, totalTokens: null, costUsd: null };
+  const byPlatform = {
+    cursor: emptyPlatform(),
+    claude: emptyPlatform(),
+    amp: emptyPlatform(),
+  };
+  const byModel = new Map();
+  let firstStart = null;
+  let lastEnd = null;
+
+  for (const session of metrics.sessions || []) {
+    totals.sessions += 1;
+    if (session.runtime === 'cloud') totals.cloudSessions += 1;
+    totals.durationMs = addNullable(totals.durationMs, numOrNull(session.durationMs));
+    if (session.startedAt && (firstStart == null || session.startedAt < firstStart)) firstStart = session.startedAt;
+    if (session.endedAt && (lastEnd == null || session.endedAt > lastEnd)) lastEnd = session.endedAt;
+
+    const key = session.phase || 'other';
+    const phase = phases[key] || {
+      sessions: 0,
+      durationMs: null,
+      inputTokens: null,
+      outputTokens: null,
+      totalTokens: null,
+      costUsd: null,
+      agents: [],
+      models: [],
+    };
+    phase.sessions += 1;
+    phase.durationMs = addNullable(phase.durationMs, numOrNull(session.durationMs));
+    for (const spendKey of ['inputTokens', 'outputTokens', 'totalTokens', 'costUsd']) {
+      const fromSession = numOrNull(session[spendKey]);
+      let value = fromSession;
+      if (value == null) {
+        let sum = null;
+        for (const src of session.sources || []) sum = addNullable(sum, numOrNull(src[spendKey]));
+        value = sum;
+      }
+      phase[spendKey] = addNullable(phase[spendKey], value);
+      spend[spendKey] = addNullable(spend[spendKey], value);
+    }
+    if (session.role && !phase.agents.includes(session.role)) phase.agents.push(session.role);
+    if (session.model && !phase.models.includes(session.model)) phase.models.push(session.model);
+    if (Array.isArray(session.models)) {
+      for (const model of session.models) {
+        if (model && !phase.models.includes(model)) phase.models.push(model);
+      }
+    }
+    phases[key] = phase;
+
+    for (const src of session.sources || []) {
+      const platform = src.platform;
+      if (platform && byPlatform[platform]) {
+        const bucket = byPlatform[platform];
+        bucket.inputTokens = addNullable(bucket.inputTokens, numOrNull(src.inputTokens));
+        bucket.outputTokens = addNullable(bucket.outputTokens, numOrNull(src.outputTokens));
+        bucket.totalTokens = addNullable(bucket.totalTokens, numOrNull(src.totalTokens));
+        bucket.costUsd = addNullable(bucket.costUsd, numOrNull(src.costUsd));
+        if (platform === 'claude') bucket.source = 'claude-jsonl';
+        else if (platform === 'amp') bucket.source = 'amp-thread';
+        else if (platform === 'cursor') bucket.source = 'cursor-hook';
+      }
+      if (src.model) {
+        const modelKey = `${src.model}::${src.platform || ''}`;
+        const row = byModel.get(modelKey) || {
+          model: src.model,
+          platform: src.platform || null,
+          inputTokens: null,
+          outputTokens: null,
+          totalTokens: null,
+          costUsd: null,
+          ampCredits: null,
+        };
+        row.inputTokens = addNullable(row.inputTokens, numOrNull(src.inputTokens));
+        row.outputTokens = addNullable(row.outputTokens, numOrNull(src.outputTokens));
+        row.totalTokens = addNullable(row.totalTokens, numOrNull(src.totalTokens));
+        row.costUsd = addNullable(row.costUsd, numOrNull(src.costUsd));
+        byModel.set(modelKey, row);
+      }
+    }
+  }
+
+  if (firstStart && lastEnd) {
+    totals.leadTimeMs = Math.max(0, Date.parse(lastEnd) - Date.parse(firstStart));
+  }
+  metrics.phases = phases;
+  metrics.totals = totals;
+  metrics.spend = spend;
+  metrics.spendByPlatform = byPlatform;
+  metrics.spendByModel = [...byModel.values()];
+}
+
+function incomingCursorSources(cwd, existing, windowStart) {
+  const filePath = join(cwd, '.agents', 'spend', 'cursor-usage.jsonl');
+  if (!existsSync(filePath)) return [];
+  const startMs = windowStart ? Date.parse(windowStart) : NaN;
+  const bestById = new Map();
+  for (const line of readFileSync(filePath, 'utf-8').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 || existing.has(id)) continue;
+    const atMs = Date.parse(row.at);
+    if (Number.isFinite(startMs) && Number.isFinite(atMs) && atMs < startMs) continue;
+    const inputTokens = numOrNull(row.inputTokens);
+    const outputTokens = numOrNull(row.outputTokens);
+    if (inputTokens == null && outputTokens == null) continue;
+    const totalTokens = (inputTokens ?? 0) + (outputTokens ?? 0);
+    const record = {
+      id,
+      platform: 'cursor',
+      model: row.model || row.modelId || null,
+      inputTokens,
+      outputTokens,
+      totalTokens,
+      costUsd: null,
+      ampCredits: null,
+      at: row.at == null ? null : String(row.at),
+    };
+    const previous = bestById.get(id);
+    if (!previous || (record.totalTokens ?? 0) >= (previous.totalTokens ?? 0)) {
+      bestById.set(id, record);
+    }
+  }
+  return [...bestById.values()];
+}
+
+function backfillChange(cwd, changeName) {
+  const filePath = join(cwd, 'openspec', 'changes', changeName, 'metrics.json');
+  if (!existsSync(filePath)) return;
+  let metrics;
+  try {
+    metrics = JSON.parse(readFileSync(filePath, 'utf-8'));
+  } catch {
+    return;
+  }
+  if (!metrics || typeof metrics !== 'object') return;
+  const sessions = Array.isArray(metrics.sessions) ? metrics.sessions : [];
+  if (!sessions.length) return;
+  const last = sessions[sessions.length - 1];
+  const incoming = incomingCursorSources(
+    cwd,
+    existingIds(metrics),
+    last.startedAt || last.endedAt || metrics.createdAt,
+  );
+  if (!incoming.length) return;
+  const overridden = looksOverridden(last);
+  last.sources = [...(last.sources || []), ...incoming];
+  if (!overridden) {
+    const totals = sourceTotals(last.sources);
+    last.inputTokens = totals.inputTokens;
+    last.outputTokens = totals.outputTokens;
+    last.totalTokens = totals.totalTokens;
+    last.costUsd = totals.costUsd;
+  }
+  metrics.updatedAt = new Date().toISOString();
+  recompute(metrics);
+  writeFileSync(filePath, `${JSON.stringify(metrics, null, 2)}\n`);
+}
+
+function main(raw) {
+  let payload = {};
+  try {
+    payload = raw ? JSON.parse(raw) : {};
+  } catch {
+    payload = {};
+  }
+  const cwd = resolveBaseDir(payload && typeof payload === 'object' ? payload : {});
+  const changesDir = join(cwd, 'openspec', 'changes');
+  if (!existsSync(changesDir)) return;
+  for (const name of readdirSync(changesDir)) {
+    if (name === 'archive') continue;
+    const full = join(changesDir, name);
+    try {
+      if (!statSync(full).isDirectory()) continue;
+    } catch {
+      continue;
+    }
+    backfillChange(cwd, name);
+  }
+}
+
+if (process.stdin.isTTY) {
+  try {
+    main('');
+  } catch {}
+  process.exit(0);
+}
+
+let input = '';
+process.stdin.on('data', (chunk) => {
+  input += chunk;
+});
+process.stdin.on('end', () => {
+  try {
+    main(input);
+  } catch {}
+  process.exit(0);
+});
+process.stdin.on('error', () => process.exit(0));

package/templates/scripts/cursor-spend-hook.cjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Cursor hook (stop / subagentStop): appends per-turn token usage from the hook
+// Cursor hook (stop / subagentStop / afterAgentResponse): appends per-turn token usage from the hook
 // payload to .agents/spend/cursor-usage.jsonl so `agent-orchestrator-kit handoff`
 // can collect real Cursor spend offline. Silent and fail-open by design: a hook
 // must never block the agent loop, so every failure path exits 0 with no output.