agent-orchestrator-kit 0.6.0 → 0.8.0

package/bin/session-client.js

@@ -0,0 +1,187 @@
+import { existsSync, readFileSync, readlinkSync } from 'fs';
+import { join } from 'path';
+import { homedir as osHomedir } from 'os';
+import { execFileSync } from 'child_process';
+
+const VALID_PLATFORMS = new Set(['cursor', 'claude', 'amp']);
+const AMP_TTY_MAX_AGE_MS = 2 * 60 * 60 * 1000;
+
+function trim(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function envFlagOn(value) {
+  if (value == null) return false;
+  const normalized = String(value).trim().toLowerCase();
+  return normalized !== '' && normalized !== '0' && normalized !== 'false';
+}
+
+export function ampDataRoot(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');
+}
+
+export function ampThreadIdFromEnv(env = {}) {
+  for (const key of ['AMP_CURRENT_THREAD', 'AMP_THREAD_ID']) {
+    const value = trim(env[key]);
+    if (value) return value;
+  }
+  return '';
+}
+
+export function isUsableTtyPath(raw) {
+  const path = String(raw || '').replace(/^tty:/, '').trim();
+  if (!path.startsWith('/dev/')) return false;
+  if (path === '/dev/null' || path.startsWith('/dev/null')) return false;
+  return true;
+}
+
+export function currentTtyKey(env = {}, readlink = null) {
+  const forced = trim(env.AOK_TTY);
+  if (forced) {
+    const path = forced.startsWith('tty:') ? forced.slice(4) : forced;
+    return isUsableTtyPath(path) ? (forced.startsWith('tty:') ? forced : `tty:${path}`) : '';
+  }
+  try {
+    const fn = readlink || readlinkSync;
+    const raw = String(fn('/proc/self/fd/0') || '').trim();
+    return isUsableTtyPath(raw) ? `tty:${raw}` : '';
+  } catch {
+    return '';
+  }
+}
+
+const AMP_THREAD_ID_RE = /\bT-[0-9a-fA-F-]{8,}\b/g;
+
+export function parseAmpThreadList(text) {
+  const ids = [];
+  for (const line of String(text || '').split('\n')) {
+    if (!line.trim() || /^Title\b/.test(line) || /^─/.test(line)) continue;
+    const matches = line.match(AMP_THREAD_ID_RE);
+    if (!matches || !matches.length) continue;
+    const id = matches[matches.length - 1];
+    if (!ids.includes(id)) ids.push(id);
+  }
+  return ids;
+}
+
+export function listRecentAmpThreadIds(options = {}) {
+  if (typeof options.listAmpThreads === 'function') {
+    try {
+      const out = options.listAmpThreads();
+      if (Array.isArray(out)) return out.map((id) => trim(id)).filter(Boolean);
+      return parseAmpThreadList(out);
+    } catch {
+      return [];
+    }
+  }
+  const env = options.env || {};
+  const bin = options.ampBin || trim(env.AOK_AMP_BIN) || 'amp';
+  if (bin !== 'amp' && !existsSync(bin)) return [];
+  try {
+    const text = execFileSync(bin, ['threads', 'list', '--limit', String(options.limit || 5)], {
+      encoding: 'utf-8',
+      timeout: options.timeoutMs != null ? Number(options.timeoutMs) : 15000,
+      env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return parseAmpThreadList(text);
+  } catch {
+    return [];
+  }
+}
+
+export function parentProcessComm(ppid = process.ppid, readFile = readFileSync) {
+  try {
+    return String(readFile(`/proc/${ppid}/comm`, 'utf-8')).trim();
+  } catch {
+    return '';
+  }
+}
+
+function looksLikeAmpProcess(comm) {
+  const name = String(comm || '').toLowerCase();
+  return name === 'amp' || name.startsWith('amp');
+}
+
+function isFreshTimestamp(value, now, maxAgeMs) {
+  if (value == null || value === '') return false;
+  const n = typeof value === 'number' ? (value < 1e12 ? value * 1000 : value) : Date.parse(String(value));
+  if (!Number.isFinite(n)) return false;
+  return now - n >= 0 && now - n <= maxAgeMs;
+}
+
+export function readAmpSessionHint(options = {}) {
+  const env = options.env || {};
+  const homedir = options.homedir || env.HOME;
+  const now = options.now != null ? Number(options.now) : Date.now();
+  const maxAgeMs = options.maxAgeMs != null ? Number(options.maxAgeMs) : AMP_TTY_MAX_AGE_MS;
+  const filePath = join(ampDataRoot(env, homedir), 'session.json');
+  if (!existsSync(filePath)) return { threadId: '', source: '' };
+  let data;
+  try {
+    data = JSON.parse(readFileSync(filePath, 'utf-8'));
+  } catch {
+    return { threadId: '', source: '' };
+  }
+  if (!data || typeof data !== 'object') return { threadId: '', source: '', lastThreadId: '' };
+  const lastThreadId = trim(data.lastThreadId);
+  const rawTty = options.ttyKey != null ? options.ttyKey : currentTtyKey(env, options.readlink);
+  const ttyKey = isUsableTtyPath(rawTty) ? (String(rawTty).startsWith('tty:') ? rawTty : `tty:${rawTty}`) : '';
+  const byTty = data.lastThreadByTerminal && ttyKey ? data.lastThreadByTerminal[ttyKey] : null;
+  if (byTty && trim(byTty.lastThreadId) && isFreshTimestamp(byTty.updatedAt, now, maxAgeMs)) {
+    return { threadId: trim(byTty.lastThreadId), source: 'amp-session-tty', lastThreadId };
+  }
+  return { threadId: '', source: '', lastThreadId };
+}
+
+export function detectSessionClient(options = {}) {
+  const env = options.env || {};
+  const ampId = ampThreadIdFromEnv(env);
+  if (ampId) {
+    return { platform: 'amp', threadId: ampId, source: 'amp-env' };
+  }
+
+  if (envFlagOn(env.CURSOR_AGENT) || trim(env.CURSOR_CONVERSATION_ID)) {
+    return { platform: 'cursor', threadId: null, source: 'cursor-env' };
+  }
+  if (envFlagOn(env.CLAUDECODE) || envFlagOn(env.CLAUDE_CODE) || trim(env.CLAUDE_CODE_ENTRYPOINT)) {
+    return { platform: 'claude', threadId: null, source: 'claude-env' };
+  }
+
+  const comm = options.parentComm != null ? options.parentComm : parentProcessComm();
+  const hint = readAmpSessionHint(options);
+  if (looksLikeAmpProcess(comm)) {
+    if (hint.threadId) {
+      return { platform: 'amp', threadId: hint.threadId, source: 'amp-parent' };
+    }
+    const listed = listRecentAmpThreadIds(options);
+    return {
+      platform: 'amp',
+      threadId: listed[0] || null,
+      source: listed[0] ? 'amp-threads-list' : 'amp-parent',
+    };
+  }
+  if (hint.threadId) {
+    return { platform: 'amp', threadId: hint.threadId, source: hint.source };
+  }
+
+  return { platform: null, threadId: null, source: 'none' };
+}
+
+export function resolveRestoreClient(options = {}) {
+  const env = options.env || {};
+  const detected = detectSessionClient(options);
+  const flag = trim(options.platform || env.AOK_PLATFORM).toLowerCase();
+  if (flag && VALID_PLATFORMS.has(flag)) {
+    return {
+      platform: flag,
+      threadId: detected.threadId,
+      source: options.platform ? 'flag' : 'aok-platform',
+    };
+  }
+  return detected;
+}

package/bin/spend-collect.js

@@ -1,6 +1,8 @@
 import { existsSync, readdirSync, readFileSync } from 'fs';
 import { join, basename } from 'path';
 import { homedir as osHomedir } from 'os';
+import { execFileSync } from 'child_process';
+import { listRecentAmpThreadIds } from './session-client.js';
 
 const PLATFORMS = ['cursor', 'claude', 'amp'];
 
@@ -43,6 +45,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 +203,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) {
@@ -237,6 +311,36 @@ function ampInputTokens(usage) {
   return has ? sum : null;
 }
 
+export function sourcesFromAmpThread(thread, ctx, fileName = '', via = null) {
+  const sources = [];
+  if (!thread || typeof thread !== 'object') return sources;
+  const { cwd, windowStart, windowEnd, existing, env } = ctx;
+  if (!ampThreadMatches(thread, cwd, env, fileName)) return sources;
+  const threadKey = thread.id ? String(thread.id) : basename(fileName || 'thread', '.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;
+    const record = sourceRecord({
+      id,
+      platform: 'amp',
+      model: usage.model,
+      inputTokens: ampInputTokens(usage),
+      outputTokens: usage.outputTokens,
+      costUsd: null,
+      ampCredits: null,
+      at: usage.timestamp,
+    });
+    if (via) record.via = via;
+    sources.push(record);
+  }
+  return sources;
+}
+
 function collectAmp({ cwd, windowStart, windowEnd, existing, env, homedir, notes }) {
   const root = ampRoot(env, homedir);
   const threadsDir = join(root, 'threads');
@@ -252,6 +356,7 @@ function collectAmp({ cwd, windowStart, windowEnd, existing, env, homedir, notes
     notes.push('amp: cannot read threads');
     return sources;
   }
+  const ctx = { cwd, windowStart, windowEnd, existing, env, homedir, notes };
   for (const file of files) {
     let thread;
     try {
@@ -259,30 +364,59 @@ function collectAmp({ cwd, windowStart, windowEnd, existing, env, homedir, notes
     } catch {
       continue;
     }
-    if (!thread || typeof thread !== 'object') continue;
-    if (!ampTreesMatch(thread, cwd)) 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,
-      }));
+    sources.push(...sourcesFromAmpThread(thread, ctx, file));
+  }
+  return sources;
+}
+
+export function exportAmpThread(threadId, options = {}) {
+  const id = threadId == null ? '' : String(threadId).trim();
+  if (!id) return null;
+  if (typeof options.exportAmpThread === 'function') {
+    try {
+      return options.exportAmpThread(id);
+    } catch {
+      return null;
+    }
+  }
+  const bin = options.ampBin || (options.env && options.env.AOK_AMP_BIN) || 'amp';
+  if (bin !== 'amp' && !existsSync(bin)) return null;
+  try {
+    const out = execFileSync(bin, ['threads', 'export', id], {
+      encoding: 'utf-8',
+      timeout: options.timeoutMs != null ? Number(options.timeoutMs) : 15000,
+      env: options.env || process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const parsed = JSON.parse(out);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function collectAmpCli(ctx) {
+  const { env, notes, ampThreadId } = ctx;
+  const ids = [];
+  const push = (value) => {
+    const id = value == null ? '' : String(value).trim();
+    if (id && !ids.includes(id)) ids.push(id);
+  };
+  push(ampThreadId);
+  push(ampCurrentThreadId(env));
+  if (!ids.length) {
+    for (const id of listRecentAmpThreadIds(ctx)) push(id);
+  }
+  const sources = [];
+  for (const id of ids) {
+    const thread = exportAmpThread(id, ctx);
+    if (!thread) {
+      notes.push(`amp: export failed for ${id}`);
+      continue;
     }
+    const extracted = sourcesFromAmpThread(thread, ctx, `${id}.json`, 'amp-cli');
+    if (!extracted.length) notes.push(`amp: export ${id} had no matching usage`);
+    sources.push(...extracted);
   }
   return sources;
 }
@@ -352,7 +486,7 @@ function aggregate(sources) {
       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 if (platform === 'amp') bucket.source = src.via === 'amp-cli' ? 'amp-cli' : 'amp-thread';
       else bucket.source = 'cursor-hook';
     }
     const model = src.model;
@@ -392,22 +526,52 @@ export function collectSpend(options = {}) {
   const windowStart = options.windowStart;
   const windowEnd = options.windowEnd;
   const notes = [];
-  const ctx = { cwd, windowStart, windowEnd, existing, env, homedir, notes };
+  const wanted = Array.isArray(options.platforms)
+    ? options.platforms.filter((name) => PLATFORMS.includes(name))
+    : PLATFORMS;
+  const run = (name) => !wanted.length || wanted.includes(name);
+  const ctx = {
+    cwd,
+    windowStart,
+    windowEnd,
+    existing,
+    env,
+    homedir,
+    notes,
+    ampThreadId: options.ampThreadId,
+    exportAmpThread: options.exportAmpThread,
+    listAmpThreads: options.listAmpThreads,
+    ampBin: options.ampBin,
+    timeoutMs: options.timeoutMs,
+  };
   let sources = [];
-  try {
-    sources = sources.concat(collectClaude(ctx));
-  } catch {
-    notes.push('claude: adapter failed');
+  if (run('claude')) {
+    try {
+      sources = sources.concat(collectClaude(ctx));
+    } catch {
+      notes.push('claude: adapter failed');
+    }
   }
-  try {
-    sources = sources.concat(collectAmp(ctx));
-  } catch {
-    notes.push('amp: adapter failed');
+  if (run('amp')) {
+    if (options.ampCli === true || typeof options.exportAmpThread === 'function') {
+      try {
+        sources = sources.concat(collectAmpCli(ctx));
+      } catch {
+        notes.push('amp: cli export 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');
+  if (run('cursor')) {
+    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.6.0",
+  "version": "0.8.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

@@ -12,20 +12,21 @@ Agents (local or cloud) write session artifacts only to git-tracked paths — ne
 ## Session Start (before any work)
 1. Honor pasted `/opsx:<phase> <name>` and announce the role.
 2. `npx agent-orchestrator-kit status`
-3. `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). The CLI briefing is canonical — it already reads memory.json and handoff.md; accumulated decisions print from git-tracked `openspec/changes/<name>/decisions.md`, not from Memory. No separate Memory MCP read step.
+3. `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). The CLI briefing is canonical — it already reads memory.json and handoff.md; accumulated decisions print from git-tracked `openspec/changes/<name>/decisions.md`, not from Memory. No separate Memory MCP read step. Restore also locks the session client (`cursor` / `claude` / `amp`) into `metrics.json` `pending` — persist will follow that client’s spend flow. Override with `--platform` when detection is wrong.
 4. If the restore CLI failed → read `openspec/changes/<name>/handoff.md` directly.
 5. Spawn `session-handoff` in restore mode ONLY if both the CLI and handoff.md are unavailable (Amp: isolated `subagent-session-handoff`). This is a fallback, never a routine step.
 6. Free-form continue/next/«далі» with one active change → execute `Handoff.next_command`.
 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`, `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.
+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: