agent-orchestrator-kit 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-08-31
+
+### Added
+- **Locked session client** — `handoff --restore` detects `cursor` / `claude` / `amp` (env, Amp parent process, or recent `session.json` tty mapping) and stores `pending.platform` + `pending.threadId`. Persist follows that client: Amp runs `amp threads export` plus local thread JSON; Cursor reads the spend hook; Claude reads `~/.claude/projects`. `--platform` / `AOK_PLATFORM` / `## Metrics` still override.
+- **Amp CLI export adapter** (`amp-cli`) — when the locked client is Amp (or `--collect`), the kit calls `amp threads export <id>` (override `AOK_AMP_BIN`). Fail-open if Amp CLI is missing. `agentMode` (`low`/`medium`) is never stored as `session.model`.
+- **Amp web / pipe restore** — if the parent process is `amp` and stdin is `/dev/null` (no pts), the kit takes the newest id from `amp threads list` instead of stale `session.json` `lastThreadId`.
+
+### Changed
+- Persist without `--collect` now collects **only the locked/resolved client**, not all three adapters. `--collect` still runs every adapter.
+
 ## [0.7.0] - 2026-08-30
 
 ### Breaking
@@ -231,6 +241,8 @@ All notable changes to this project will be documented in this file.
 ### Added
 - Initial release: 5-role orchestration pipeline, `/opsx:*` commands, IDE sync
 
+[0.8.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.7.0...v0.8.0
+[0.7.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.3.0...v0.4.0

package/README.md

@@ -74,7 +74,7 @@ npx agent-orchestrator-kit@latest init --profile generic --ci gitlab --spec-veri
 
 See [Installation](#installation) for profile/CI options.
 
-**🔄 Already have the kit installed? Upgrade to latest (`## Metrics` self-report + opt-in `--collect` in v0.7.0 — **BREAKING:** `--no-collect` is gone; change metrics in v0.5.0+, factory phases 1–3 in v0.4.0+, lean pipeline / archive CLI in v0.3.0+, handoff CLI in v0.1.14+, Figma PAT in v0.1.11+):**
+**🔄 Already have the kit installed? Upgrade to latest (locked Amp/Cursor client + `amp threads export` in v0.8.0; `## Metrics` self-report + opt-in `--collect` in v0.7.0 — **BREAKING:** `--no-collect` is gone; change metrics in v0.5.0+, factory phases 1–3 in v0.4.0+, lean pipeline / archive CLI in v0.3.0+, handoff CLI in v0.1.14+, Figma PAT in v0.1.11+):**
 
 ```bash
 npx agent-orchestrator-kit@latest update
@@ -806,8 +806,9 @@ Every change accumulates git-tracked `openspec/changes/<name>/metrics.json` —
 - **Session start** — `handoff --restore` writes a `pending` marker (`startedAt`, expected role).
 - **Session end** — `handoff <name>` closes the pending session: duration, closed role, mapped phase (`explore` / `design` / `spec` / `review` / `apply` / `archive`), runtime (local/cloud), tasks snapshot (`n/m`), and spend from flags → self-report → optional `--collect` adapters. `--input-tokens` / `--output-tokens` / `--total-tokens` / `--cost-usd` override session totals only and do not wipe `spendByPlatform` / `spendByModel`. Never guess. Never invent USD from Amp credits. Never Cursor SDK / npm sqlite / a pricing table. No restore marker? Pass `--started-at <iso>` or the duration stays honestly `null`.
 - **Archive** — successful `archive <name>` always creates or finalizes `metrics.json`, sets `archivedAt`, appends an Archiver session from the archived `## Metrics` (or archive flags), prints the same human summary as `metrics <name>`, and collects adapters only with `--collect`.
-- **Platform** — `--platform` → `## Metrics: platform` → `AOK_PLATFORM` → host env (Amp / Cursor / Claude Code) → collected sources (`cursor|claude|amp` only). Invalid `--platform` fails before persist/move.
-- **Cursor spend hook (optional)** — Cursor never writes token usage to disk, so the kit can install `scripts/cursor-spend-hook.cjs` plus `.cursor/hooks.json` entries (`stop` / `subagentStop` / `afterAgentResponse`) in `init` / `update` / `sync` / `mcp-setup`: the hook appends each turn's tokens to gitignored `.agents/spend/cursor-usage.jsonl`. Collect is opt-in (`handoff`/`archive`/`metrics --collect`). Persist and restore do not self-heal the hook. `sessionEnd` still runs `scripts/cursor-spend-collect.cjs`. Restart Cursor once after the first install. `status` shows a `Spend capture` section. Claude (`~/.claude/projects/*.jsonl`) and Amp (`~/.local/share/amp/threads/*.json`) already persist usage locally and need no hook.
+- **Platform** — `--platform` → `## Metrics: platform` → `AOK_PLATFORM` → **pending client from `--restore`** → host env (Amp / Cursor / Claude Code) → collected sources (`cursor|claude|amp` only). Invalid `--platform` fails before persist/move.
+- **Locked client** — `--restore` records `pending.platform` and Amp `pending.threadId` before phase work. Persist follows that client’s flow even if persist runs in another shell (no `AMP_*` / `CURSOR_*`). Amp: `amp threads export` (`AOK_AMP_BIN`) plus local `threads/*.json`. If Amp runs tools over a pipe (`/dev/null`), thread id comes from `amp threads list`, not stale `session.json` `lastThreadId`. Cursor: spend hook file. Claude: `~/.claude/projects`. `--collect` still runs all three adapters.
+- **Cursor spend hook (optional)** — Cursor never writes token usage to disk, so the kit can install `scripts/cursor-spend-hook.cjs` plus `.cursor/hooks.json` entries (`stop` / `subagentStop` / `afterAgentResponse`) in `init` / `update` / `sync` / `mcp-setup`: the hook appends each turn's tokens to gitignored `.agents/spend/cursor-usage.jsonl`. Persist auto-reads that file when the locked client is Cursor. Persist and restore do not self-heal the hook. `sessionEnd` still runs `scripts/cursor-spend-collect.cjs`. Restart Cursor once after the first install. `status` shows a `Spend capture` section. Claude JSONL and Amp disk threads remain fallbacks; Amp web/CLI spend is taken from `amp threads export`.
 
 Aggregates are recomputed on every write: per-phase totals (`durationMs`, tokens, `costUsd`, `sessions`, `roles`, `models`) plus overall `totals` (`sessions`, `cloudSessions`, `durationMs` = sum of session work time, `leadTimeMs` = wall clock from first session start to last session end), `spend` (USD only), and separate **by platform** / **by model** tables. Numbers are null-honest: a metric nobody reported stays `null`, never a fake `0`. No single total that adds Amp credits to USD.
 

package/bin/agent-orchestrator.js

@@ -6,6 +6,7 @@ import { join, dirname, basename, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
 import { collectSpend } from './spend-collect.js';
+import { resolveRestoreClient, ampThreadIdFromEnv } from './session-client.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const KIT_ROOT = join(__dirname, '..');
@@ -484,7 +485,7 @@ function printSpendHealth(projectDir) {
     ? String(process.env.AMP_DATA_DIR).trim()
     : join(home, '.local', 'share', 'amp');
   const ampOk = existsSync(join(ampDir, 'threads'));
-  console.log(`  amp      ${ampOk ? 'ok (threads found)' : 'no local Amp data'}`);
+  console.log(`  amp      ${ampOk ? 'ok (threads found)' : 'no local Amp data'}; locked client + amp threads export`);
   console.log('');
 }
 
@@ -1151,7 +1152,7 @@ function inferPlatformFromHost(env) {
   return null;
 }
 
-function resolvePlatform(opts, env, reported) {
+function resolvePlatform(opts, env, reported, pending) {
   const flag = opts && opts.platform != null ? String(opts.platform).trim() : '';
   if (flag) {
     const lower = flag.toLowerCase();
@@ -1172,6 +1173,10 @@ function resolvePlatform(opts, env, reported) {
     if (VALID_PLATFORMS.has(lower)) return { value: lower };
     return { value: null, warn: 'invalid AOK_PLATFORM (use cursor, claude, or amp)' };
   }
+  const pendingPlatform = pending && pending.platform != null ? String(pending.platform).trim() : '';
+  if (pendingPlatform && VALID_PLATFORMS.has(pendingPlatform)) {
+    return { value: pendingPlatform };
+  }
   return { value: inferPlatformFromHost(env) };
 }
 
@@ -1856,7 +1861,7 @@ function sessionTotalsFromSources(sources) {
   return { inputTokens, outputTokens, totalTokens, costUsd };
 }
 
-function runCollectSpend(metrics, windowStart, windowEnd) {
+function runCollectSpend(metrics, windowStart, windowEnd, extra = {}) {
   try {
     return collectSpend({
       cwd: process.cwd(),
@@ -1865,6 +1870,10 @@ function runCollectSpend(metrics, windowStart, windowEnd) {
       existingSourceIds: existingSourceIdSet(metrics),
       env: process.env,
       homedir: process.env.HOME,
+      platforms: extra.platforms,
+      ampThreadId: extra.ampThreadId,
+      ampCli: extra.ampCli === true,
+      exportAmpThread: extra.exportAmpThread,
     });
   } catch {
     return { sources: [], byPlatform: defaultSpendByPlatform(), byModel: [], notes: [] };
@@ -1910,7 +1919,11 @@ function metricsBackfillFile(filePath, changeName) {
   if (!sessions.length) return { filePath, added: 0, empty: true };
   const last = sessions[sessions.length - 1];
   const windowStart = last.startedAt || collectWindowStart(metrics);
-  const collected = runCollectSpend(metrics, windowStart, nowIso);
+  const lastPlatform = last && last.platform;
+  const collected = runCollectSpend(metrics, windowStart, nowIso, {
+    ampThreadId: last && last.threadId || ampThreadIdFromEnv(process.env) || null,
+    ampCli: lastPlatform === 'amp',
+  });
   const incoming = collected.sources || [];
   if (!incoming.length) return { filePath, added: 0 };
   const overridden = sessionTotalsLookOverridden(last);
@@ -1935,9 +1948,9 @@ function metricsBackfillFile(filePath, changeName) {
   return { filePath, added: incoming.length };
 }
 
-function adapterSourceName(platform) {
+function adapterSourceName(platform, via) {
   if (platform === 'claude') return 'claude-jsonl';
-  if (platform === 'amp') return 'amp-thread';
+  if (platform === 'amp') return via === 'amp-cli' ? 'amp-cli' : 'amp-thread';
   if (platform === 'cursor') return 'cursor-hook';
   return null;
 }
@@ -2060,11 +2073,17 @@ function recomputeMetricsAggregates(metrics) {
   recomputeSpendMaps(metrics);
 }
 
-function metricsRecordSessionStart(projectDir, changeName, role) {
+function metricsRecordSessionStart(projectDir, changeName, role, client = {}) {
   const filePath = metricsFilePath(projectDir, changeName);
   const nowIso = new Date().toISOString();
   const metrics = loadMetricsFile(filePath, changeName, nowIso);
-  metrics.pending = { startedAt: nowIso, role: role || '' };
+  metrics.pending = {
+    startedAt: nowIso,
+    role: role || '',
+    platform: client.platform || null,
+    threadId: client.threadId || null,
+    clientSource: client.source || null,
+  };
   metrics.updatedAt = nowIso;
   saveMetricsFile(filePath, metrics);
   return filePath;
@@ -2079,8 +2098,17 @@ function metricsRecordSessionEnd(projectDir, fields, opts = {}) {
   const reported = opts.reported || fields.metrics || emptyMetricsFields();
   const resolvedModel = opts.model === undefined ? resolveModel(opts, process.env, reported) : opts.model;
   const windowStart = collectWindowStart(metrics);
-  const collected = opts.collect === true
-    ? runCollectSpend(metrics, windowStart, nowIso)
+  const pending = metrics.pending || {};
+  const platform = opts.platform || pending.platform || null;
+  const collectAll = opts.collect === true;
+  const platforms = collectAll ? undefined : (platform ? [platform] : []);
+  const shouldCollect = collectAll || (Array.isArray(platforms) && platforms.length > 0);
+  const collected = shouldCollect
+    ? runCollectSpend(metrics, windowStart, nowIso, {
+      platforms,
+      ampThreadId: opts.ampThreadId || pending.threadId || ampThreadIdFromEnv(process.env) || null,
+      ampCli: collectAll || platform === 'amp',
+    })
     : { sources: [] };
   const session = {
     startedAt,
@@ -2091,7 +2119,8 @@ function metricsRecordSessionEnd(projectDir, fields, opts = {}) {
     runtime: fields.runtime || 'local',
     agentId: fields.agentId || 'none',
     model: resolvedModel || null,
-    platform: opts.platform || null,
+    platform: opts.platform || pending.platform || null,
+    threadId: opts.ampThreadId || pending.threadId || null,
     tasks: fields.tasks || null,
     sources: [],
     inputTokens: null,
@@ -2120,8 +2149,16 @@ function metricsFinalizeArchive(targetDir, changeName, opts = {}) {
   const nowIso = new Date().toISOString();
   const metrics = loadMetricsFile(filePath, changeName, nowIso);
   const windowStart = lastSessionEndedAt(metrics) || metrics.createdAt;
-  const collected = opts.collect === true
-    ? runCollectSpend(metrics, windowStart, nowIso)
+  const collectAll = opts.collect === true;
+  const platform = opts.platform || null;
+  const platforms = collectAll ? undefined : (platform ? [platform] : []);
+  const shouldCollect = collectAll || (Array.isArray(platforms) && platforms.length > 0);
+  const collected = shouldCollect
+    ? runCollectSpend(metrics, windowStart, nowIso, {
+      platforms,
+      ampThreadId: opts.ampThreadId || ampThreadIdFromEnv(process.env) || null,
+      ampCli: collectAll || platform === 'amp',
+    })
     : { sources: [] };
   const reported = opts.reported || emptyMetricsFields();
   const resolvedModel = opts.model === undefined ? resolveModel(opts, process.env, reported) : opts.model;
@@ -2197,7 +2234,10 @@ function renderMetricsSummary(metrics) {
   lines.push(`unreported: ${unreported}`);
   if (metrics.archivedAt) lines.push(`archived:  ${metrics.archivedAt}`);
   if (metrics.pending) {
-    lines.push(`open session since ${metrics.pending.startedAt} (${metrics.pending.role || 'unknown role'})`);
+    const pendingClient = metrics.pending.platform
+      ? ` ${metrics.pending.platform}${metrics.pending.threadId ? ` ${metrics.pending.threadId}` : ''}`
+      : '';
+    lines.push(`open session since ${metrics.pending.startedAt} (${metrics.pending.role || 'unknown role'}${pendingClient})`);
   }
 
   const phaseOrder = ['explore', 'design', 'spec', 'review', 'apply', 'archive', 'other'];
@@ -3877,8 +3917,18 @@ program
         log.warn(`Memory JSON empty or missing at ${memoryPath}`);
       }
       if (opts.metrics !== false && existsSync(changeDir)) {
-        const metricsPath = metricsRecordSessionStart(projectDir, name, fields ? fields.nextRole : '');
+        const client = resolveRestoreClient({
+          env: process.env,
+          cwd: projectDir,
+          homedir: process.env.HOME,
+          platform: opts.platform,
+        });
+        const metricsPath = metricsRecordSessionStart(projectDir, name, fields ? fields.nextRole : '', client);
+        const clientLabel = client.platform
+          ? `${client.platform}${client.threadId ? ` ${client.threadId}` : ''} (${client.source})`
+          : 'unknown — pass --platform or fill ## Metrics';
         log.ok(`metrics: session start recorded (${metricsPath.replace(`${projectDir}/`, '')})`);
+        log.info(`metrics: client ${clientLabel}`);
       }
       return;
     }
@@ -3948,7 +3998,8 @@ program
     }
 
     const reported = fields.metrics || emptyMetricsFields();
-    const platformResult = resolvePlatform(opts, process.env, reported);
+    const metricsPreview = loadMetricsFile(metricsFilePath(projectDir, name), name, new Date().toISOString());
+    const platformResult = resolvePlatform(opts, process.env, reported, metricsPreview.pending);
     if (platformResult.error) {
       log.err(platformResult.error);
       process.exitCode = 1;
@@ -3977,6 +4028,7 @@ program
         totalTokens: opts.totalTokens,
         costUsd: opts.costUsd,
         collect: opts.collect === true,
+        ampThreadId: (metricsPreview.pending && metricsPreview.pending.threadId) || ampThreadIdFromEnv(process.env) || null,
         reported,
       });
       console.error(pc.green('  ✓'), `metrics.json updated: ${metricsPath.replace(`${projectDir}/`, '')}`);

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'];
 
@@ -309,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');
@@ -324,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 {
@@ -331,31 +364,60 @@ function collectAmp({ cwd, windowStart, windowEnd, existing, env, homedir, notes
     } catch {
       continue;
     }
-    if (!thread || typeof thread !== 'object') continue;
-    if (!ampThreadMatches(thread, cwd, env, file)) continue;
-    // messageId values are thread-local counters (1, 3, 5, ...), so a bare id
-    // collides across threads; namespace with the thread id for global dedup.
-    const threadKey = thread.id ? String(thread.id) : basename(file, '.json');
-    for (const message of ampMessages(thread)) {
-      const usage = ampUsage(message);
-      if (!usage) continue;
-      const rawId = ampId(message);
-      if (rawId == null || rawId === '') continue;
-      const id = `${threadKey}:${rawId}`;
-      if (existing.has(id)) continue;
-      if (!inWindow(usage.timestamp, windowStart, windowEnd)) continue;
-      sources.push(sourceRecord({
-        id,
-        platform: 'amp',
-        model: usage.model,
-        inputTokens: ampInputTokens(usage),
-        outputTokens: usage.outputTokens,
-        costUsd: null,
-        ampCredits: null,
-        at: usage.timestamp,
-      }));
+    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;
 }
 
@@ -424,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;
@@ -464,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.7.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/rules/session-handoff.mdc

@@ -12,7 +12,7 @@ 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`.
@@ -21,7 +21,7 @@ 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`) — 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).
+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.