agent-orchestrator-kit 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-09-04
+
+### Fixed
+- **Amp Cost-once rollup, restore `amp-session-last`, leftover thread-scope.** After persist/recompute, Amp `Cost: $N` is added once **per qualifying session** into `spend.costUsd`, `spendByPlatform.amp.costUsd`, and `phases.*.costUsd` when that session’s `sources[].costUsd` are all null — never copied onto each source (not ×N); several Amp sessions accumulate. Restore without Amp parent locks a fresh `session.json` `lastThreadId` as `amp-session-last` (Amp parent without tty still uses `amp threads list`). Leftover without `--collect` scopes to `last.platform` and the Amp thread id / `T-…` prefix; an explicit `ampThreadId` does not add the env thread. Leftover after `amp-usage` resyncs tokens from sources and keeps billed Cost; `usageModels` stay unique to that thread; `pending.role` is the canonical token.
+
 ## [0.12.0] - 2026-09-02
 
 ### Fixed
@@ -271,6 +276,7 @@ All notable changes to this project will be documented in this file.
 ### Added
 - Initial release: 5-role orchestration pipeline, `/opsx:*` commands, IDE sync
 
+[0.13.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.12.0...v0.13.0
 [0.12.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.9.0...v0.10.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 (Cursor leftover race + multi-root + per-phase clock in v0.12.0; session attribution + Cursor estimate/dedup in v0.11.0; Cursor fallback estimate + first-class `costUsdEstimated` in v0.10.0; UTC timestamps + Amp stamp parse, Amp billed `$`, Cursor API estimate, archive auto-collect in v0.9.0; locked Amp/Cursor client 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+):**
+**🔄 Already have the kit installed? Upgrade to latest (Amp Cost-once rollup + `amp-session-last` + leftover thread-scope in v0.13.0; Cursor leftover race + multi-root + per-phase clock in v0.12.0; session attribution + Cursor estimate/dedup in v0.11.0; Cursor fallback estimate + first-class `costUsdEstimated` in v0.10.0; UTC timestamps + Amp stamp parse, Amp billed `$`, Cursor API estimate, archive auto-collect in v0.9.0; locked Amp/Cursor client 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
@@ -804,13 +804,14 @@ Every change accumulates git-tracked `openspec/changes/<name>/metrics.json` —
 - **`## Metrics` self-report** — Session Exit fills `handoff.md` with `platform`, `model`, `input_tokens`, `output_tokens`, `cost_usd`, `amp_credits`, `spend_source` (`unknown` when missing). Persist reads that section; `metrics.json` is the source of truth for what landed. CLI flags do not rewrite the section.
 - **`session.model`** — source product id wins when any collected source has a model; `--model` / `## Metrics: model` / `AOK_MODEL` apply only when sources have no model. Never a Closed role.
 - **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 → adapters. Persist collect window is `[pending.startedAt, endedAt]`; a late hook after persist goes to leftover of that session, not the next persist. `--input-tokens` / `--output-tokens` / `--total-tokens` / `--cost-usd` override session totals only and do not wipe `spendByPlatform` / `spendByModel`. Amp billed USD comes from `amp threads usage --details` (`Cost: $N` only; missing line → `costUsd: null`), not from converting credits. Cursor always writes a labeled `costUsdEstimated` when tokens exist: grok-4.6/4.5 use xAI API rates (`costSource: api-estimate`, including `-fast` and the 200k cliff); other models use a versioned fallback of $3/1M input + $15/1M output (or $3.50/1M when only `totalTokens` is present, `costSource: api-estimate-fallback`). That estimate is **not** the Cursor invoice and is never added into billed `costUsd`. Timestamps are ISO-8601 UTC (`…Z`). No restore marker? Pass `--started-at <iso>` or the duration stays honestly `null`.
+- **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 → adapters. Persist collect window is `[pending.startedAt, endedAt]`; a late hook after persist goes to leftover of that session, not the next persist. `--input-tokens` / `--output-tokens` / `--total-tokens` / `--cost-usd` override session totals only and do not wipe `spendByPlatform` / `spendByModel`. Amp billed USD comes from `amp threads usage --details` (`Cost: $N` only; missing line → `costUsd: null`), not from converting credits. After persist/recompute, that Cost is a **Cost-once rollup**: once **per qualifying session** into `spend.costUsd` / `spendByPlatform.amp.costUsd` / `phases.*.costUsd` when that session’s `sources[].costUsd` are all null — never copied onto each source (not ×N); several Amp sessions accumulate. Cursor always writes a labeled `costUsdEstimated` when tokens exist: grok-4.6/4.5 use xAI API rates (`costSource: api-estimate`, including `-fast` and the 200k cliff); other models use a versioned fallback of $3/1M input + $15/1M output (or $3.50/1M when only `totalTokens` is present, `costSource: api-estimate-fallback`). That estimate is **not** the Cursor invoice and is never added into billed `costUsd`. Timestamps are ISO-8601 UTC (`…Z`). 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, collects the locked client (Cursor hook / Amp export+usage / Claude JSONL) in `[pending.startedAt, now]` plus leftover of the previous session, and prints the same human summary as `metrics <name>`. `--collect` still runs all three adapters. Leftover apply `## Metrics` that repeats the previous session is ignored so those tokens are not counted twice.
 - **`sessionEnd` leftover** — `scripts/cursor-spend-collect.cjs` also reads the newest `openspec/changes/archive/*-<name>/metrics.json` when the active change folder is gone, so a late hook after archive still attaches. `stop` / `afterAgentResponse` run the same leftover after a successful jsonl append. When `last.threadId` is non-empty, leftover keeps only rows whose `conversationId` matches that id (empty/`null` threadId stays time-only). In a multi-root window leftover walks every candidate that has `openspec/changes`, reading that root’s jsonl. Aggregates write `costUsdEstimated` with 4 decimal places. Each `phases.<phase>` stores `startedAt` / `endedAt` / `leadTimeMs` from that phase’s sessions; `durationMs` stays the work-time sum and does not clone `totals.leadTimeMs`.
+- **Leftover without `--collect`** — Scopes to `last.platform` and, for Amp, leftover **thread-scope**: the session thread id or the `T-…` prefix from `sources[].id` (`T-apply:8` → `T-apply`). An explicit `ampThreadId` does not also add the env thread. After `amp-usage`, leftover **token resync** sums tokens from all sources and keeps billed Cost (`spendSource: amp-usage`). `usageModels` stay unique to that thread.
 - **Cursor `conversationId`** — restore writes `CURSOR_CONVERSATION_ID` into `pending.threadId`; Cursor collect and sessionEnd leftover skip rows whose `conversationId` does not match when a filter id is present (`last.threadId` on leftover).
-- **Canonical role** — `session.role` stores the first known token (`Explorer`, `Architect`, `Spec Reviewer`, `Implementer`, `Archiver`, `Design Intake`); Closed role in `handoff.md` MAY keep a sentence after `—`.
+- **Canonical role** — `session.role` and `pending.role` store the first known token (`Explorer`, `Architect`, `Spec Reviewer`, `Implementer`, `Archiver`, `Design Intake`); Closed role in `handoff.md` MAY keep a sentence after `—`.
 - **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` plus `amp threads usage --details` (`AOK_AMP_BIN`) and local `threads/*.json`. Export supplies `model` / tokens / `agentMode`; usage supplies billed `$`. 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.
+- **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` plus `amp threads usage --details` (`AOK_AMP_BIN`) and local `threads/*.json`. Export supplies `model` / tokens / `agentMode`; usage supplies billed `$`. If Amp runs tools over a pipe (`/dev/null`), thread id comes from `amp threads list`, not stale `session.json` `lastThreadId`. When env and Amp parent do not win, restore locks a fresh `session.json` `lastThreadId` as `amp-session-last`. 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`. After a successful `stop` / `afterAgentResponse` append the hook runs leftover (fail-open, no stdout). Hook and collect resolve the consumer in a multi-root window (not the first cwd with `.agents` or `openspec`). 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 remains a fallback. Amp web/CLI spend is taken from `amp threads export` (tokens, model, `agentMode`) and `amp threads usage` (billed USD).
 
 Aggregates are recomputed on every write: per-phase totals (`startedAt`, `endedAt`, `leadTimeMs` from that phase’s sessions, `durationMs` = sum of session work time — not `totals.leadTimeMs` and not `endedAt − startedAt`, tokens, `costUsd`, `costUsdEstimated` to 4 decimals, `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.
@@ -1006,6 +1007,11 @@ Phase bounds and non-goals: [`openspec/specs/agentic-factory-roadmap/spec.md`](o
 
 ## Changelog
 
+### 0.13.0
+- Amp Cost-once rollup: `Cost: $N` once per qualifying session into `spend` / `spendByPlatform.amp` / `phases` (not ×N sources; several sessions accumulate)
+- Restore without Amp parent locks a fresh `session.json` `lastThreadId` as `amp-session-last`
+- Leftover without `--collect` scopes to `last.platform` and Amp thread / `T-…` prefix; leftover after `amp-usage` resyncs tokens and keeps billed Cost
+
 ### 0.12.0
 - Cursor leftover after `stop` / `afterAgentResponse` (fail-open, idempotent `sessionEnd`); leftover filters `last.threadId` when it is set
 - Multi-root hook/collect resolve the consumer window; leftover walks every candidate with `openspec/changes`

package/bin/agent-orchestrator.js

@@ -1788,12 +1788,64 @@ function leftoverTimestampInWindow(at, windowStart, leftoverEnd, exclusiveEnd) {
   return true;
 }
 
+function uniqueAmpSourceThreadPrefix(sources) {
+  const prefixes = [];
+  for (const src of sources || []) {
+    const id = src && src.id != null ? String(src.id) : '';
+    if (!id.startsWith('T-')) continue;
+    const prefix = id.split(':')[0];
+    if (!prefix) continue;
+    if (!prefixes.includes(prefix)) prefixes.push(prefix);
+  }
+  return prefixes.length === 1 ? prefixes[0] : null;
+}
+
+function leftoverAmpThreadId(session) {
+  if (!session) return null;
+  if (session.threadId) return String(session.threadId);
+  return uniqueAmpSourceThreadPrefix(session.sources);
+}
+
+function sessionAmpThreadKeys(session) {
+  const keys = new Set();
+  if (session && session.threadId) keys.add(String(session.threadId));
+  for (const src of (session && session.sources) || []) {
+    const id = src && src.id != null ? String(src.id) : '';
+    if (!id.startsWith('T-')) continue;
+    const prefix = id.split(':')[0];
+    if (prefix) keys.add(prefix);
+  }
+  return keys;
+}
+
+function usageModelTokenCount(row) {
+  const total = numOrNull(row && row.totalTokens);
+  if (total != null) return total;
+  return (numOrNull(row && row.inputTokens) ?? 0) + (numOrNull(row && row.outputTokens) ?? 0);
+}
+
+function usageModelsForSession(session, ampThreads) {
+  const allowed = sessionAmpThreadKeys(session);
+  const byModel = new Map();
+  for (const thread of ampThreads || []) {
+    const id = thread && thread.id != null ? String(thread.id) : '';
+    if (!allowed.has(id)) continue;
+    for (const row of (thread && thread.models) || []) {
+      if (!row || !row.model) continue;
+      const key = String(row.model);
+      const prev = byModel.get(key);
+      if (!prev || usageModelTokenCount(row) >= usageModelTokenCount(prev)) {
+        byModel.set(key, row);
+      }
+    }
+  }
+  return [...byModel.values()];
+}
+
 function sessionSpendIsFrozen(session) {
   if (!session) return false;
   if (session.spendSource === 'flag') return true;
-  if (!reportedHasSpendNumbers(session)) return false;
-  if (!session.spendSource || session.spendSource === 'adapter' || session.spendSource === 'unreported') return false;
-  return true;
+  return session.spendSource === 'self-report' && reportedHasSpendNumbers(session);
 }
 
 function existingSourceRecords(metrics) {
@@ -1994,41 +2046,90 @@ function sessionTotalsFromSources(sources) {
 function runCollectSpend(metrics, windowStart, windowEnd, extra = {}) {
   try {
     return collectSpend({
-      cwd: process.cwd(),
+      cwd: extra.cwd || process.cwd(),
       windowStart,
       windowEnd,
       existingSourceIds: existingSourceIdSet(metrics),
       existingSources: existingSourceRecords(metrics),
-      env: process.env,
-      homedir: process.env.HOME,
+      env: extra.env || process.env,
+      homedir: extra.homedir || process.env.HOME,
       platforms: extra.platforms,
       ampThreadId: extra.ampThreadId,
       ampCli: extra.ampCli === true,
       cursorConversationId: extra.cursorConversationId,
       exportAmpThread: extra.exportAmpThread,
       usageAmpThread: extra.usageAmpThread,
+      listRecentAmpThreads: extra.listRecentAmpThreads,
+      listAmpThreads: extra.listAmpThreads,
     });
   } catch {
     return { sources: [], byPlatform: defaultSpendByPlatform(), byModel: [], notes: [] };
   }
 }
 
+function leftoverCollectPlatforms(session, collectAll, ampThreadId) {
+  if (collectAll) return undefined;
+  if (session.platform === 'amp' || session.platform === 'cursor' || session.platform === 'claude') {
+    if (session.platform === 'amp' && !ampThreadId) return [];
+    return [session.platform];
+  }
+  if (session.platform == null && ampThreadId) return ['amp'];
+  return [];
+}
+
+function resyncLeftoverSessionSpend(session, priorCost, priorSource) {
+  const fromSources = sessionTotalsFromSources(session.sources || []);
+  session.inputTokens = fromSources.inputTokens;
+  session.outputTokens = fromSources.outputTokens;
+  let totalTokens = fromSources.totalTokens;
+  if (totalTokens == null && (fromSources.inputTokens != null || fromSources.outputTokens != null)) {
+    totalTokens = (fromSources.inputTokens ?? 0) + (fromSources.outputTokens ?? 0);
+  }
+  session.totalTokens = totalTokens;
+  if (fromSources.costUsd == null && priorCost != null) {
+    session.costUsd = priorCost;
+  }
+  if (priorSource === 'amp-usage' && numOrNull(session.costUsd) != null) {
+    session.spendSource = 'amp-usage';
+  }
+}
+
 function attachLeftoverSources(metrics, session, leftoverEnd, extra = {}) {
   if (!session || !session.endedAt || !leftoverEnd) return 0;
   const exclusiveEnd = extra.exclusiveEnd === true;
+  const collectAll = extra.collect === true;
+  const ampThreadId = leftoverAmpThreadId(session);
+  const platforms = leftoverCollectPlatforms(session, collectAll, ampThreadId);
+  if (!collectAll && (!Array.isArray(platforms) || platforms.length === 0)) return 0;
+  const collectAmp = collectAll || (Array.isArray(platforms) && platforms.includes('amp'));
+  const collectCursor = collectAll || (Array.isArray(platforms) && platforms.includes('cursor'));
   const collected = runCollectSpend(metrics, session.endedAt, leftoverEnd, {
-    platforms: extra.platforms,
-    ampThreadId: session.threadId || extra.ampThreadId || ampThreadIdFromEnv(process.env) || null,
-    ampCli: extra.ampCli === true || session.platform === 'amp',
+    platforms,
+    ...(ampThreadId ? { ampThreadId } : {}),
+    listRecentAmpThreads: false,
+    ampCli: extra.ampCli === true || collectAmp,
     cursorConversationId: extra.cursorConversationId
-      || (session.platform === 'cursor' ? session.threadId : undefined),
+      || (collectCursor && session.platform === 'cursor' ? session.threadId : undefined),
+    exportAmpThread: extra.exportAmpThread,
+    usageAmpThread: extra.usageAmpThread,
+    listAmpThreads: extra.listAmpThreads,
+    env: extra.env,
+    cwd: extra.cwd,
+    homedir: extra.homedir,
   });
-  const incoming = (collected.sources || []).filter((src) => leftoverTimestampInWindow(
+  let incoming = (collected.sources || []).filter((src) => leftoverTimestampInWindow(
     src.at,
     session.endedAt,
     leftoverEnd,
     exclusiveEnd,
   ));
+  if (ampThreadId) {
+    const prefix = `${ampThreadId}:`;
+    incoming = incoming.filter((src) => {
+      if (src && src.platform === 'amp') return String(src.id || '').startsWith(prefix);
+      return true;
+    });
+  }
   if (!incoming.length) return 0;
   const merged = [...(session.sources || []), ...incoming];
   if (sessionSpendIsFrozen(session)) {
@@ -2036,10 +2137,13 @@ function attachLeftoverSources(metrics, session, leftoverEnd, extra = {}) {
     const uniqueModels = uniqueSourceModels(merged);
     if (uniqueModels.length > 1) session.models = uniqueModels;
   } else {
+    const priorCost = numOrNull(session.costUsd);
+    const priorSource = session.spendSource;
     applyCollectedSessionFields(session, merged, session.model, {}, {
       model: session.model,
       platform: session.platform,
-    }, { ampThreads: collected.ampThreads });
+    }, { ampThreads: Array.isArray(extra.ampThreads) ? extra.ampThreads : collected.ampThreads });
+    resyncLeftoverSessionSpend(session, priorCost, priorSource);
   }
   return incoming.length;
 }
@@ -2070,13 +2174,10 @@ function applyCollectedSessionFields(session, sources, resolvedModel, opts, repo
   session.costUsdEstimated = spend.costUsdEstimated;
   session.spendSource = spend.spendSource;
   if (spend.agentMode) session.agentMode = spend.agentMode;
-  const usageModels = [];
-  for (const thread of extra.ampThreads || []) {
-    for (const row of thread.models || []) {
-      if (row && row.model) usageModels.push(row);
-    }
+  const usageModels = usageModelsForSession(session, extra.ampThreads);
+  if (usageModels.length || Array.isArray(session.usageModels)) {
+    session.usageModels = usageModels;
   }
-  if (usageModels.length) session.usageModels = usageModels;
 }
 
 function sessionTotalsLookOverridden(session) {
@@ -2199,6 +2300,14 @@ function recomputeSpendMaps(metrics) {
     const sources = session.sources || [];
     if (sources.length > 0) {
       for (const src of sources) addSourceRow(src);
+      let sourceCost = null;
+      for (const src of sources) sourceCost = addNullable(sourceCost, numOrNull(src.costUsd));
+      if (sourceCost == null && session.platform && byPlatform[session.platform]) {
+        byPlatform[session.platform].costUsd = addNullable(
+          byPlatform[session.platform].costUsd,
+          numOrNull(session.costUsd),
+        );
+      }
       continue;
     }
     const sessionNums = spendTuple(session);
@@ -2258,11 +2367,18 @@ function recomputeMetricsAggregates(metrics) {
         ? session.endedAt
         : laterTimestamp(phase.endedAt, session.endedAt);
     }
+    const sources = session.sources || [];
+    let sourceCost = null;
+    for (const src of sources) sourceCost = addNullable(sourceCost, numOrNull(src.costUsd));
     for (const spendKey of METRICS_SPEND_KEYS) {
       let value = null;
-      if ((session.sources || []).length > 0) {
-        for (const src of session.sources) {
-          value = addNullable(value, numOrNull(src[spendKey]));
+      if (sources.length > 0) {
+        if (spendKey === 'costUsd') {
+          value = sourceCost == null ? numOrNull(session.costUsd) : sourceCost;
+        } else {
+          for (const src of sources) {
+            value = addNullable(value, numOrNull(src[spendKey]));
+          }
         }
       } else {
         value = sessionFieldOrSources(session, spendKey);
@@ -2303,7 +2419,7 @@ function metricsRecordSessionStart(projectDir, changeName, role, client = {}) {
   const metrics = loadMetricsFile(filePath, changeName, nowIso);
   metrics.pending = {
     startedAt: nowIso,
-    role: role || '',
+    role: canonicalRole(role) || role || '',
     platform: client.platform || null,
     threadId: client.threadId || null,
     clientSource: client.source || null,
@@ -2324,6 +2440,7 @@ function metricsRecordSessionEnd(projectDir, fields, opts = {}) {
     : leftoverGraceEnd(lastClosed && lastClosed.endedAt);
   attachLeftoverSources(metrics, lastClosed, leftoverEnd, {
     exclusiveEnd: Boolean(metrics.pending && metrics.pending.startedAt),
+    collect: opts.collect === true,
   });
   let startedAt = isoOrNull(opts.startedAt) || isoOrNull(metrics.pending && metrics.pending.startedAt) || null;
   const reported = opts.reported || fields.metrics || emptyMetricsFields();
@@ -2464,7 +2581,7 @@ function metricsFinalizeArchive(targetDir, changeName, opts = {}) {
   return filePath;
 }
 
-function metricsPrepareArchiveStart(changeRoot, changeName, client = {}) {
+function metricsPrepareArchiveStart(changeRoot, changeName, client = {}, extra = {}) {
   const filePath = join(changeRoot, 'metrics.json');
   if (!existsSync(filePath)) return;
   const nowIso = nowUtcIso();
@@ -2481,6 +2598,7 @@ function metricsPrepareArchiveStart(changeRoot, changeName, client = {}) {
   const leftoverEnd = metrics.pending && metrics.pending.startedAt;
   attachLeftoverSources(metrics, lastNonArchiverSession(metrics.sessions), leftoverEnd, {
     exclusiveEnd: true,
+    collect: extra.collect === true,
   });
   metrics.updatedAt = nowIso;
   recomputeMetricsAggregates(metrics);
@@ -3876,7 +3994,7 @@ program
       homedir: process.env.HOME,
       platform: opts.platform,
     });
-    metricsPrepareArchiveStart(changeRoot, name, archiveClient);
+    metricsPrepareArchiveStart(changeRoot, name, archiveClient, { collect: opts.collect === true });
     mkdirSync(dirname(targetDir), { recursive: true });
     renameSync(changeRoot, targetDir);
 
@@ -4447,4 +4565,13 @@ if (isDirectCliRun()) {
   program.parse();
 }
 
-export { formatMetricsCostLine, resolveSessionSpend, canonicalRole, phaseForRole };
+export {
+  formatMetricsCostLine,
+  resolveSessionSpend,
+  canonicalRole,
+  phaseForRole,
+  recomputeMetricsAggregates,
+  sessionSpendIsFrozen,
+  attachLeftoverSources,
+  runCollectSpend,
+};

package/bin/session-client.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, readlinkSync } from 'fs';
+import { existsSync, readFileSync, readlinkSync, statSync } from 'fs';
 import { join } from 'path';
 import { homedir as osHomedir } from 'os';
 import { execFileSync } from 'child_process';
@@ -114,28 +114,68 @@ function isFreshTimestamp(value, now, maxAgeMs) {
   return now - n >= 0 && now - n <= maxAgeMs;
 }
 
+function isSessionFileFresh(updatedAt, filePath, now, maxAgeMs) {
+  if (updatedAt != null && updatedAt !== '') {
+    return isFreshTimestamp(updatedAt, now, maxAgeMs);
+  }
+  try {
+    return isFreshTimestamp(statSync(filePath).mtimeMs, now, maxAgeMs);
+  } catch {
+    return false;
+  }
+}
+
+function emptyAmpSessionHint(filePath, fileFresh, updatedAt) {
+  return {
+    threadId: '',
+    source: '',
+    lastThreadId: '',
+    filePath: filePath || '',
+    fileFresh: Boolean(fileFresh),
+    updatedAt: updatedAt == null ? '' : updatedAt,
+  };
+}
+
 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: '' };
+  if (!existsSync(filePath)) return emptyAmpSessionHint(filePath, false, '');
   let data;
   try {
     data = JSON.parse(readFileSync(filePath, 'utf-8'));
   } catch {
-    return { threadId: '', source: '' };
+    return emptyAmpSessionHint(filePath, isSessionFileFresh('', filePath, now, maxAgeMs), '');
+  }
+  if (!data || typeof data !== 'object') {
+    return emptyAmpSessionHint(filePath, isSessionFileFresh('', filePath, now, maxAgeMs), '');
   }
-  if (!data || typeof data !== 'object') return { threadId: '', source: '', lastThreadId: '' };
   const lastThreadId = trim(data.lastThreadId);
+  const updatedAt = data.updatedAt;
+  const fileFresh = isSessionFileFresh(updatedAt, filePath, now, maxAgeMs);
   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: trim(byTty.lastThreadId),
+      source: 'amp-session-tty',
+      lastThreadId,
+      filePath,
+      fileFresh,
+      updatedAt,
+    };
   }
-  return { threadId: '', source: '', lastThreadId };
+  return {
+    threadId: '',
+    source: '',
+    lastThreadId,
+    filePath,
+    fileFresh,
+    updatedAt,
+  };
 }
 
 export function detectSessionClient(options = {}) {
@@ -168,6 +208,15 @@ export function detectSessionClient(options = {}) {
   if (hint.threadId) {
     return { platform: 'amp', threadId: hint.threadId, source: hint.source };
   }
+  if (hint.lastThreadId && hint.fileFresh) {
+    return { platform: 'amp', threadId: hint.lastThreadId, source: 'amp-session-last' };
+  }
+  if (hint.fileFresh) {
+    const listed = listRecentAmpThreadIds(options);
+    if (listed[0]) {
+      return { platform: 'amp', threadId: listed[0], source: 'amp-session-list' };
+    }
+  }
 
   return { platform: null, threadId: null, source: 'none' };
 }

package/bin/spend-collect.js

@@ -504,8 +504,10 @@ function collectAmpCli(ctx) {
     if (id && !ids.includes(id)) ids.push(id);
   };
   push(ampThreadId);
-  push(ampCurrentThreadId(env));
-  if (!ids.length) {
+  if (ctx.listRecentAmpThreads !== false) {
+    push(ampCurrentThreadId(env));
+  }
+  if (!ids.length && ctx.listRecentAmpThreads !== false) {
     for (const id of listRecentAmpThreadIds(ctx)) push(id);
   }
   const sources = [];
@@ -825,6 +827,7 @@ export function collectSpend(options = {}) {
     homedir,
     notes,
     ampThreadId: options.ampThreadId,
+    listRecentAmpThreads: options.listRecentAmpThreads,
     cursorConversationId: options.cursorConversationId,
     exportAmpThread: options.exportAmpThread,
     listAmpThreads: options.listAmpThreads,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-kit",
-  "version": "0.12.0",
+  "version": "0.13.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/scripts/cursor-spend-collect.cjs

@@ -508,7 +508,9 @@ function recompute(metrics) {
     }
     phases[key] = phase;
 
+    let sessionSourceCostUsd = null;
     for (const src of session.sources || []) {
+      sessionSourceCostUsd = addNullable(sessionSourceCostUsd, numOrNull(src.costUsd));
       const platform = src.platform;
       if (platform && byPlatform[platform]) {
         const bucket = byPlatform[platform];
@@ -543,6 +545,11 @@ function recompute(metrics) {
         byModel.set(modelKey, row);
       }
     }
+    const sessionCostUsd = numOrNull(session.costUsd);
+    if (sessionSourceCostUsd == null && sessionCostUsd != null) {
+      const billedBucket = session.platform && byPlatform[session.platform];
+      if (billedBucket) billedBucket.costUsd = addNullable(billedBucket.costUsd, sessionCostUsd);
+    }
   }
 
   if (firstStart && lastEnd) {