agent-orchestrator-kit 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-08-31
+
+### Added
+- **`costUsdEstimated` first-class** in `metrics.json` (`spend`, platforms, models, sessions, sources). Cursor writes a labeled estimate whenever tokens exist: grok-4.5/4.6 keep xAI API rates (`costSource: "api-estimate"`); 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"`). This is **not** a Cursor invoice and is never mixed into billed `costUsd`. Self-report `cost_usd` stays billed and is not copied into `costUsdEstimated`. Amp without a `Cost:` line leaves `costUsd: null` (tokens are not converted to USD; credits stay separate). Archived `metrics.json` files are not backfilled.
+
+## [0.9.0] - 2026-08-31
+
+### Added
+- **UTC timestamps in `metrics.json`** — `createdAt` / `updatedAt` / `archivedAt` / session times / source `at` are stored as ISO-8601 UTC (`2026-08-31T07:08:17.563Z`). Broken Amp stamps like `2026-08-31T07:08:17.563464.000Z` are parsed and normalized to UTC. Human `metrics` output still prints Kyiv wall time (`31.08.2026 10:08:17 (Київ +03:00)`).
+- **Amp `threads usage`** — when the locked client is Amp, persist also runs `amp threads usage <id> --details` (fail-open) and writes the billed `costUsd`, per-model costs, and `agentMode` (`low` / `medium` / `high` / `ultra`) from `amp threads export`. Mode is never stored as `session.model`. Placeholder `amp-default` yields to the real LLM id from sources.
+- **Cursor API-equivalent estimate** — hook tokens for `cursor-grok-4.6` / `4.5` (including `-fast`, 200k long-context cliff, cache reads when present) fill `costUsdEstimated` with `costSource: "api-estimate"`. This is **not** the Cursor invoice and is never mixed into billed `costUsd`.
+- **Archive auto-collect** — `archive <name>` detects the current client (`resolveRestoreClient`) and records Archiver spend from that adapter (Cursor hook / Amp export+usage / Claude JSONL) in the window after the last session. Leftover apply `## Metrics` numbers are ignored when they match the previous session. `--collect` still runs all three adapters.
+
+### Changed
+- `metrics` / archive summary cost line shows `$1.30 billed + ~$8.98 est.` when both exist.
+
 ## [0.8.0] - 2026-08-31
 
 ### Added
@@ -241,6 +257,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.10.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.9.0...v0.10.0
+[0.9.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.8.0...v0.9.0
 [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

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 (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+):**
+**🔄 Already have the kit installed? Upgrade to latest (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
@@ -600,7 +600,7 @@ Archive is a **deterministic CLI**, not an agent workflow:
 npx agent-orchestrator-kit archive <name> [--sync | --no-sync --force] [--collect]
 ```
 
-It checks the gates (APPROVE in `review.md` when required, all tasks `[x]`, target folder free), merges delta specs into `openspec/specs/` (`--sync`: ADDED append, MODIFIED replace, REMOVED delete), moves the change to `openspec/changes/archive/YYYY-MM-DD-<name>`, and runs `npx openspec validate --all --strict` with a full rollback on failure (main specs restored, new spec files deleted, move reverted). With delta specs present you must decide: `--sync` merges, `--no-sync --force` archives without merging, and no flag refuses with exit 1. It finishes by writing the final `handoff.md` (`next_command: none`), updating memory, and printing the same human metrics summary as `metrics <name>`. Fill `## Metrics` in the change `handoff.md` before archive so the Archiver session can resolve platform / model / spend. `--collect` is optional. The `/opsx:archive` command is a thin wrapper that calls this CLI; the `spec-archiver` subagent remains only as a fallback when the CLI is unavailable.
+It checks the gates (APPROVE in `review.md` when required, all tasks `[x]`, target folder free), merges delta specs into `openspec/specs/` (`--sync`: ADDED append, MODIFIED replace, REMOVED delete), moves the change to `openspec/changes/archive/YYYY-MM-DD-<name>`, and runs `npx openspec validate --all --strict` with a full rollback on failure (main specs restored, new spec files deleted, move reverted). With delta specs present you must decide: `--sync` merges, `--no-sync --force` archives without merging, and no flag refuses with exit 1. It finishes by writing the final `handoff.md` (`next_command: none`), updating memory, appending an Archiver session, and printing the same human metrics summary as `metrics <name>`. Archive collects the locked client (Cursor hook / Amp threads / Claude JSONL) in the window after the last session — the same flow as persist. `--collect` still runs every adapter. Unique `## Metrics` in the change `handoff.md` still counts as Archiver self-report; leftover apply numbers that match the previous session are ignored. The `/opsx:archive` command is a thin wrapper that calls this CLI; the `spec-archiver` subagent remains only as a fallback when the CLI is unavailable.
 
 ## Configuration
 
@@ -804,11 +804,11 @@ 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`** — `--model` → `## Metrics: model` → `AOK_MODEL` → collected sources (only with `--collect`) → `null` (stderr warning). 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 → 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`.
+- **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. `--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`.
+- **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 `[last session.endedAt, now]`, 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.
 - **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`.
+- **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.
+- **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 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 (`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.
 
@@ -833,7 +833,7 @@ npx agent-orchestrator-kit metrics add-thing --json      # raw metrics.json (wor
 npx agent-orchestrator-kit archive add-thing --sync      # finalize + the same tables as metrics
 ```
 
-Recording is on by default and never a persist/archive/`gate-check` gate; opt out per persist with `--no-metrics`. Adapters run only with `--collect`. Flags (`--model`, `--platform`, `--input-tokens`, …) override session totals in `metrics.json` and do not rewrite the `## Metrics` section.
+Recording is on by default and never a persist/archive/`gate-check` gate; opt out per persist with `--no-metrics`. Persist and archive collect the locked client without `--collect`; `--collect` runs every adapter. Flags (`--model`, `--platform`, `--input-tokens`, …) override session totals in `metrics.json` and do not rewrite the `## Metrics` section.
 
 ### Skill inventory
 
@@ -1003,6 +1003,19 @@ Phase bounds and non-goals: [`openspec/specs/agentic-factory-roadmap/spec.md`](o
 
 ## Changelog
 
+### 0.10.0
+- `costUsdEstimated` is first-class on `metrics.json`; Cursor writes a labeled estimate whenever tokens exist — grok via xAI API (`costSource: api-estimate`), other models via versioned fallback $3/1M in + $15/1M out (or $3.50/1M when only `totalTokens`, `costSource: api-estimate-fallback`). The estimate is **not** an invoice and is never mixed into billed `costUsd`. Amp without a `Cost:` line leaves `costUsd: null`; self-report `cost_usd` stays billed.
+
+### 0.9.0
+- **UTC timestamps** in `metrics.json` (`…Z`; broken Amp stamps parsed and normalized)
+- Amp `threads usage --details` billed `$` + `agentMode` (never stored as `session.model`)
+- Cursor `costUsdEstimated` from xAI API rates for grok-4.6/4.5 — labeled, not mixed into billed `costUsd`
+- **Archive auto-collect** — Archiver session picks up the locked client after the last session; leftover apply `## Metrics` is not double-counted
+
+### 0.8.0
+- Locked session client on `--restore`; persist collects only that client without `--collect`
+- Amp CLI `threads export` + `threads list` when Amp runs over a pipe
+
 ### 0.7.0
 - **`## Metrics` self-report** — persist reads the session section in `handoff.md`; `metrics.json` is the source of truth; CLI flags do not rewrite the section
 - **BREAKING** — `--no-collect` removed; `handoff` and `archive` collect local adapters only with opt-in `--collect`

package/bin/agent-orchestrator.js

@@ -1,12 +1,20 @@
 #!/usr/bin/env node
 import { program } from 'commander';
 import pc from 'picocolors';
-import { readFileSync, existsSync, mkdirSync, copyFileSync, readdirSync, statSync, writeFileSync, rmSync, renameSync, chmodSync } from 'fs';
+import { readFileSync, existsSync, mkdirSync, copyFileSync, readdirSync, statSync, writeFileSync, rmSync, renameSync, chmodSync, realpathSync } from 'fs';
 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';
+import {
+  earlierTimestamp,
+  formatKyivDisplay,
+  isoOrNull,
+  laterTimestamp,
+  nowUtcIso,
+  parseFlexibleIso,
+} from './metrics-time.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const KIT_ROOT = join(__dirname, '..');
@@ -1123,12 +1131,22 @@ function firstNonNull(...values) {
   return null;
 }
 
+function isPlaceholderModel(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  return !normalized || ['unknown', 'none', 'n/a', '-', '—', 'null', 'amp-default'].includes(normalized);
+}
+
 function resolveModel(opts, env, reported) {
-  const flag = opts && opts.model != null ? String(opts.model).trim() : '';
+  const pick = (value) => {
+    const text = value == null ? '' : String(value).trim();
+    if (!text || isPlaceholderModel(text)) return '';
+    return text;
+  };
+  const flag = pick(opts && opts.model);
   if (flag) return flag;
-  const fromReport = reported && reported.model != null ? String(reported.model).trim() : '';
+  const fromReport = pick(reported && reported.model);
   if (fromReport) return fromReport;
-  const fromEnv = env && env.AOK_MODEL != null ? String(env.AOK_MODEL).trim() : '';
+  const fromEnv = pick(env && env.AOK_MODEL);
   if (fromEnv) return fromEnv;
   return null;
 }
@@ -1594,14 +1612,14 @@ function readHandoffFields(projectDir, changeName) {
 }
 
 const METRICS_VERSION = 1;
-const METRICS_SPEND_KEYS = ['inputTokens', 'outputTokens', 'totalTokens', 'costUsd'];
+const METRICS_SPEND_KEYS = ['inputTokens', 'outputTokens', 'totalTokens', 'costUsd', 'costUsdEstimated'];
 
 function metricsFilePath(projectDir, changeName) {
   return join(projectDir, 'openspec', 'changes', changeName, 'metrics.json');
 }
 
 function emptySpendTotals() {
-  return { inputTokens: null, outputTokens: null, totalTokens: null, costUsd: null };
+  return { inputTokens: null, outputTokens: null, totalTokens: null, costUsd: null, costUsdEstimated: null };
 }
 
 function emptyPlatformSpend(source = 'none') {
@@ -1611,6 +1629,7 @@ function emptyPlatformSpend(source = 'none') {
     totalTokens: null,
     costUsd: null,
     ampCredits: null,
+    costUsdEstimated: null,
     source,
   };
 }
@@ -1678,7 +1697,9 @@ function loadMetricsFile(filePath, changeName, nowIso) {
 
 function saveMetricsFile(filePath, metrics) {
   mkdirSync(dirname(filePath), { recursive: true });
-  writeFileSync(filePath, `${JSON.stringify(metrics, null, 2)}\n`);
+  const out = { ...metrics };
+  delete out.timezone;
+  writeFileSync(filePath, `${JSON.stringify(out, null, 2)}\n`);
 }
 
 function numOrNull(value) {
@@ -1703,12 +1724,6 @@ function phaseForRole(role) {
   return 'other';
 }
 
-function isoOrNull(value) {
-  if (!value) return null;
-  const ms = Date.parse(String(value));
-  return Number.isFinite(ms) ? new Date(ms).toISOString() : null;
-}
-
 function sessionFieldOrSources(session, key) {
   if (session[key] != null && session[key] !== '') return numOrNull(session[key]);
   let sum = null;
@@ -1721,7 +1736,7 @@ function sessionFieldOrSources(session, key) {
 function lastSessionEndedAt(metrics) {
   let last = null;
   for (const session of metrics.sessions || []) {
-    if (session.endedAt && (last == null || session.endedAt > last)) last = session.endedAt;
+    if (session.endedAt) last = last == null ? session.endedAt : laterTimestamp(last, session.endedAt);
   }
   return last;
 }
@@ -1740,6 +1755,33 @@ function existingSourceIdSet(metrics) {
   return ids;
 }
 
+function lastNonArchiverSession(sessions) {
+  const list = Array.isArray(sessions) ? sessions : [];
+  for (let i = list.length - 1; i >= 0; i -= 1) {
+    if (list[i] && list[i].role !== 'Archiver') return list[i];
+  }
+  return null;
+}
+
+function dropStaleArchiveSelfReport(reported, sessions) {
+  const base = reported && typeof reported === 'object' ? { ...reported } : emptyMetricsFields();
+  const last = lastNonArchiverSession(sessions);
+  if (!last) return base;
+  const sameInput = numOrNull(base.inputTokens) != null && numOrNull(base.inputTokens) === numOrNull(last.inputTokens);
+  const sameOutput = numOrNull(base.outputTokens) === numOrNull(last.outputTokens);
+  if (sameInput && sameOutput) {
+    base.inputTokens = null;
+    base.outputTokens = null;
+    base.totalTokens = null;
+    base.costUsd = null;
+    base.ampCredits = null;
+    if (!base.spendSource || base.spendSource === 'self-report') base.spendSource = null;
+  }
+  if (base.model && last.model && base.model === last.model) base.model = null;
+  if (base.platform && last.platform && base.platform === last.platform) base.platform = null;
+  return base;
+}
+
 function uniqueSourceModels(sources) {
   const seen = [];
   for (const src of sources || []) {
@@ -1798,11 +1840,35 @@ function sourceAmpCredits(sources) {
   return sum;
 }
 
-function resolveSessionSpend(opts, reported, sources) {
+function sourceEstimatedUsd(sources) {
+  let sum = null;
+  for (const src of sources || []) {
+    sum = addNullable(sum, numOrNull(src.costUsdEstimated));
+  }
+  return sum;
+}
+
+function ampThreadTotals(threads) {
+  const list = Array.isArray(threads) ? threads : [];
+  let costUsd = null;
+  let agentMode = null;
+  const models = [];
+  for (const thread of list) {
+    costUsd = addNullable(costUsd, numOrNull(thread && thread.costUsd));
+    if (!agentMode && thread && thread.agentMode) agentMode = String(thread.agentMode);
+    for (const row of (thread && thread.models) || []) {
+      if (row && row.model && !models.includes(row.model)) models.push(row.model);
+    }
+  }
+  return { costUsd, agentMode, models };
+}
+
+function resolveSessionSpend(opts, reported, sources, extra = {}) {
   const flags = opts || {};
   const self = reported || emptyMetricsFields();
   const fromSources = sessionTotalsFromSources(sources || []);
   const sourceCredits = sourceAmpCredits(sources || []);
+  const fromAmp = ampThreadTotals(extra.ampThreads);
   const flagInput = numOrNull(flags.inputTokens);
   const flagOutput = numOrNull(flags.outputTokens);
   const flagTotal = numOrNull(flags.totalTokens);
@@ -1814,12 +1880,14 @@ function resolveSessionSpend(opts, reported, sources) {
   if (totalTokens == null && (inputTokens != null || outputTokens != null)) {
     totalTokens = (inputTokens ?? 0) + (outputTokens ?? 0);
   }
-  const costUsd = firstNonNull(flagCost, self.costUsd, fromSources.costUsd);
+  const costUsd = firstNonNull(flagCost, self.costUsd, fromAmp.costUsd, fromSources.costUsd);
   const ampCredits = firstNonNull(flagCredits, self.ampCredits, sourceCredits);
+  const costUsdEstimated = sourceEstimatedUsd(sources || []);
   let spendSource = 'unreported';
   if (self.spendSource) spendSource = String(self.spendSource);
   else if (hasSpendOverride(flags)) spendSource = 'flag';
   else if (reportedHasSpendNumbers(self)) spendSource = 'self-report';
+  else if (fromAmp.costUsd != null) spendSource = 'amp-usage';
   else if (
     fromSources.inputTokens != null
     || fromSources.outputTokens != null
@@ -1829,7 +1897,7 @@ function resolveSessionSpend(opts, reported, sources) {
   ) {
     spendSource = 'adapter';
   }
-  return { inputTokens, outputTokens, totalTokens, costUsd, ampCredits, spendSource };
+  return { inputTokens, outputTokens, totalTokens, costUsd, ampCredits, costUsdEstimated, spendSource, agentMode: fromAmp.agentMode };
 }
 
 function sessionTotalsFromFlags(opts) {
@@ -1874,25 +1942,44 @@ function runCollectSpend(metrics, windowStart, windowEnd, extra = {}) {
       ampThreadId: extra.ampThreadId,
       ampCli: extra.ampCli === true,
       exportAmpThread: extra.exportAmpThread,
+      usageAmpThread: extra.usageAmpThread,
     });
   } catch {
     return { sources: [], byPlatform: defaultSpendByPlatform(), byModel: [], notes: [] };
   }
 }
 
-function applyCollectedSessionFields(session, sources, resolvedModel, opts, reported) {
+function applyCollectedSessionFields(session, sources, resolvedModel, opts, reported, extra = {}) {
   session.sources = sources || [];
   const uniqueModels = uniqueSourceModels(session.sources);
-  if (!session.model) session.model = resolvedModel || primaryModelFromSources(session.sources) || null;
+  const fromAmp = ampThreadTotals(extra.ampThreads);
+  for (const model of fromAmp.models) {
+    if (model && !uniqueModels.includes(model)) uniqueModels.push(model);
+  }
+  if (!session.model || isPlaceholderModel(session.model)) {
+    session.model = (resolvedModel && !isPlaceholderModel(resolvedModel) ? resolvedModel : null)
+      || primaryModelFromSources(session.sources)
+      || fromAmp.models[0]
+      || null;
+  }
   if (!session.platform) session.platform = primaryPlatformFromSources(session.sources) || null;
   if (uniqueModels.length > 1) session.models = uniqueModels;
-  const spend = resolveSessionSpend(opts, reported, session.sources);
+  const spend = resolveSessionSpend(opts, reported, session.sources, extra);
   session.inputTokens = spend.inputTokens;
   session.outputTokens = spend.outputTokens;
   session.totalTokens = spend.totalTokens;
   session.costUsd = spend.costUsd;
   session.ampCredits = spend.ampCredits;
+  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);
+    }
+  }
+  if (usageModels.length) session.usageModels = usageModels;
 }
 
 function sessionTotalsLookOverridden(session) {
@@ -1913,7 +2000,7 @@ function metricsBackfillLastSession(projectDir, changeName) {
 }
 
 function metricsBackfillFile(filePath, changeName) {
-  const nowIso = new Date().toISOString();
+  const nowIso = nowUtcIso();
   const metrics = loadMetricsFile(filePath, changeName, nowIso);
   const sessions = metrics.sessions || [];
   if (!sessions.length) return { filePath, added: 0, empty: true };
@@ -1940,7 +2027,7 @@ function metricsBackfillFile(filePath, changeName) {
     applyCollectedSessionFields(last, merged, last.model, {}, {
       model: last.model,
       platform: last.platform,
-    });
+    }, { ampThreads: collected.ampThreads });
   }
   metrics.updatedAt = nowIso;
   recomputeMetricsAggregates(metrics);
@@ -1962,11 +2049,12 @@ function spendTuple(obj) {
     totalTokens: numOrNull(obj && obj.totalTokens),
     costUsd: numOrNull(obj && obj.costUsd),
     ampCredits: numOrNull(obj && obj.ampCredits),
+    costUsdEstimated: numOrNull(obj && obj.costUsdEstimated),
   };
 }
 
 function spendTuplesMatch(a, b) {
-  return ['inputTokens', 'outputTokens', 'totalTokens', 'costUsd'].every((key) => {
+  return ['inputTokens', 'outputTokens', 'totalTokens'].every((key) => {
     const left = a[key];
     const right = b[key];
     if (left == null && right == null) return true;
@@ -1980,6 +2068,7 @@ function addSpendNums(target, nums) {
   target.totalTokens = addNullable(target.totalTokens, nums.totalTokens);
   target.costUsd = addNullable(target.costUsd, nums.costUsd);
   target.ampCredits = addNullable(target.ampCredits, nums.ampCredits);
+  target.costUsdEstimated = addNullable(target.costUsdEstimated, nums.costUsdEstimated);
 }
 
 function recomputeSpendMaps(metrics) {
@@ -1997,6 +2086,7 @@ function recomputeSpendMaps(metrics) {
       totalTokens: null,
       costUsd: null,
       ampCredits: null,
+      costUsdEstimated: null,
     };
     addSpendNums(row, nums);
     byModel.set(key, row);
@@ -2006,7 +2096,7 @@ function recomputeSpendMaps(metrics) {
     const nums = spendTuple(src);
     if (src.platform && byPlatform[src.platform]) {
       addSpendNums(byPlatform[src.platform], nums);
-      const label = adapterSourceName(src.platform);
+      const label = adapterSourceName(src.platform, src.via);
       if (label) byPlatform[src.platform].source = label;
     }
     addModelRow(src.model, src.platform, nums);
@@ -2021,6 +2111,19 @@ function recomputeSpendMaps(metrics) {
 
     if (sourcesMatchSession) {
       for (const src of sources) addSourceRow(src);
+      if (session.costUsd != null && sourceTotals.costUsd == null && session.platform && byPlatform[session.platform]) {
+        byPlatform[session.platform].costUsd = addNullable(byPlatform[session.platform].costUsd, session.costUsd);
+      }
+      for (const row of session.usageModels || []) {
+        addModelRow(row.model, session.platform || 'amp', {
+          inputTokens: null,
+          outputTokens: null,
+          totalTokens: null,
+          costUsd: numOrNull(row.costUsd),
+          ampCredits: null,
+          costUsdEstimated: null,
+        });
+      }
       continue;
     }
 
@@ -2044,8 +2147,8 @@ function recomputeMetricsAggregates(metrics) {
     totals.sessions += 1;
     if (session.runtime === 'cloud') totals.cloudSessions += 1;
     totals.durationMs = addNullable(totals.durationMs, numOrNull(session.durationMs));
-    if (session.startedAt && (firstStart == null || session.startedAt < firstStart)) firstStart = session.startedAt;
-    if (session.endedAt && (lastEnd == null || session.endedAt > lastEnd)) lastEnd = session.endedAt;
+    if (session.startedAt) firstStart = firstStart == null ? session.startedAt : earlierTimestamp(firstStart, session.startedAt);
+    if (session.endedAt) lastEnd = lastEnd == null ? session.endedAt : laterTimestamp(lastEnd, session.endedAt);
     const key = session.phase || 'other';
     const phase = phases[key] || { sessions: 0, durationMs: null, ...emptySpendTotals(), agents: [], models: [] };
     phase.sessions += 1;
@@ -2065,7 +2168,7 @@ function recomputeMetricsAggregates(metrics) {
     phases[key] = phase;
   }
   if (firstStart && lastEnd) {
-    totals.leadTimeMs = Math.max(0, Date.parse(lastEnd) - Date.parse(firstStart));
+    totals.leadTimeMs = Math.max(0, parseFlexibleIso(lastEnd) - parseFlexibleIso(firstStart));
   }
   metrics.phases = phases;
   metrics.totals = totals;
@@ -2075,7 +2178,7 @@ function recomputeMetricsAggregates(metrics) {
 
 function metricsRecordSessionStart(projectDir, changeName, role, client = {}) {
   const filePath = metricsFilePath(projectDir, changeName);
-  const nowIso = new Date().toISOString();
+  const nowIso = nowUtcIso();
   const metrics = loadMetricsFile(filePath, changeName, nowIso);
   metrics.pending = {
     startedAt: nowIso,
@@ -2091,10 +2194,14 @@ function metricsRecordSessionStart(projectDir, changeName, role, client = {}) {
 
 function metricsRecordSessionEnd(projectDir, fields, opts = {}) {
   const filePath = metricsFilePath(projectDir, fields.changeName);
-  const nowIso = new Date().toISOString();
+  const nowIso = nowUtcIso();
   const metrics = loadMetricsFile(filePath, fields.changeName, nowIso);
-  const startedAt = isoOrNull(opts.startedAt) || (metrics.pending && metrics.pending.startedAt) || null;
-  const durationMs = startedAt ? Math.max(0, Date.parse(nowIso) - Date.parse(startedAt)) : null;
+  const startedAt = isoOrNull(opts.startedAt) || isoOrNull(metrics.pending && metrics.pending.startedAt) || null;
+  const startedMs = parseFlexibleIso(startedAt);
+  const endedMs = parseFlexibleIso(nowIso);
+  const durationMs = Number.isFinite(startedMs) && Number.isFinite(endedMs)
+    ? Math.max(0, endedMs - startedMs)
+    : null;
   const reported = opts.reported || fields.metrics || emptyMetricsFields();
   const resolvedModel = opts.model === undefined ? resolveModel(opts, process.env, reported) : opts.model;
   const windowStart = collectWindowStart(metrics);
@@ -2128,9 +2235,10 @@ function metricsRecordSessionEnd(projectDir, fields, opts = {}) {
     totalTokens: null,
     costUsd: null,
     ampCredits: null,
+    costUsdEstimated: null,
     spendSource: 'unreported',
   };
-  applyCollectedSessionFields(session, collected.sources || [], resolvedModel, opts, reported);
+  applyCollectedSessionFields(session, collected.sources || [], resolvedModel, opts, reported, collected);
   metrics.sessions.push(session);
   metrics.pending = null;
   metrics.updatedAt = nowIso;
@@ -2146,21 +2254,22 @@ function metricsRecordSessionEnd(projectDir, fields, opts = {}) {
 
 function metricsFinalizeArchive(targetDir, changeName, opts = {}) {
   const filePath = join(targetDir, 'metrics.json');
-  const nowIso = new Date().toISOString();
+  const nowIso = nowUtcIso();
   const metrics = loadMetricsFile(filePath, changeName, nowIso);
   const windowStart = lastSessionEndedAt(metrics) || metrics.createdAt;
   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 ampThreadId = opts.ampThreadId || ampThreadIdFromEnv(process.env) || null;
   const collected = shouldCollect
     ? runCollectSpend(metrics, windowStart, nowIso, {
       platforms,
-      ampThreadId: opts.ampThreadId || ampThreadIdFromEnv(process.env) || null,
+      ampThreadId,
       ampCli: collectAll || platform === 'amp',
     })
     : { sources: [] };
-  const reported = opts.reported || emptyMetricsFields();
+  const reported = dropStaleArchiveSelfReport(opts.reported, metrics.sessions);
   const resolvedModel = opts.model === undefined ? resolveModel(opts, process.env, reported) : opts.model;
   const session = {
     startedAt: nowIso,
@@ -2171,7 +2280,8 @@ function metricsFinalizeArchive(targetDir, changeName, opts = {}) {
     runtime: opts.runtime || 'local',
     agentId: opts.agentId || 'none',
     model: resolvedModel || null,
-    platform: opts.platform || null,
+    platform,
+    threadId: ampThreadId || null,
     tasks: opts.tasks || null,
     sources: [],
     inputTokens: null,
@@ -2179,9 +2289,10 @@ function metricsFinalizeArchive(targetDir, changeName, opts = {}) {
     totalTokens: null,
     costUsd: null,
     ampCredits: null,
+    costUsdEstimated: null,
     spendSource: 'unreported',
   };
-  applyCollectedSessionFields(session, collected.sources || [], resolvedModel, opts, reported);
+  applyCollectedSessionFields(session, collected.sources || [], resolvedModel, opts, reported, collected);
   metrics.sessions.push(session);
   metrics.archivedAt = nowIso;
   metrics.pending = null;
@@ -2216,6 +2327,17 @@ function formatMetricsCost(value) {
   return value == null ? '—' : `$${Number(value).toFixed(2)}`;
 }
 
+function formatMetricsCostLine(spend) {
+  const billed = spend && spend.costUsd;
+  const estimated = spend && spend.costUsdEstimated;
+  if (billed == null && estimated == null) return '—';
+  if (billed != null && estimated != null) {
+    return `${formatMetricsCost(billed)} billed + ~${formatMetricsCost(estimated)} est.`;
+  }
+  if (billed != null) return formatMetricsCost(billed);
+  return `~${formatMetricsCost(estimated)} est.`;
+}
+
 function sessionSpendSourceLabel(session) {
   const raw = session && session.spendSource;
   if (raw == null || String(raw).trim() === '') return 'unreported';
@@ -2230,9 +2352,9 @@ function renderMetricsSummary(metrics) {
   lines.push(`work time: ${formatMetricsDuration(metrics.totals.durationMs)}`);
   lines.push(`lead time: ${formatMetricsDuration(metrics.totals.leadTimeMs)}`);
   lines.push(`tokens:    ${formatMetricsNumber(metrics.spend.totalTokens)} (in: ${formatMetricsNumber(metrics.spend.inputTokens)}, out: ${formatMetricsNumber(metrics.spend.outputTokens)})`);
-  lines.push(`cost:      ${formatMetricsCost(metrics.spend.costUsd)}`);
+  lines.push(`cost:      ${formatMetricsCostLine(metrics.spend)}`);
   lines.push(`unreported: ${unreported}`);
-  if (metrics.archivedAt) lines.push(`archived:  ${metrics.archivedAt}`);
+  if (metrics.archivedAt) lines.push(`archived:  ${formatKyivDisplay(metrics.archivedAt)}`);
   if (metrics.pending) {
     const pendingClient = metrics.pending.platform
       ? ` ${metrics.pending.platform}${metrics.pending.threadId ? ` ${metrics.pending.threadId}` : ''}`
@@ -2252,7 +2374,7 @@ function renderMetricsSummary(metrics) {
         String(phase.sessions).padEnd(9),
         formatMetricsDuration(phase.durationMs).padEnd(9),
         formatMetricsNumber(phase.totalTokens).padEnd(9),
-        formatMetricsCost(phase.costUsd).padEnd(9),
+        formatMetricsCostLine(phase).padEnd(9),
         (phase.agents.join(', ') || '—').padEnd(20),
         phase.models.join(', ') || '—',
       ].join(' '));
@@ -2268,7 +2390,7 @@ function renderMetricsSummary(metrics) {
     lines.push([
       key.padEnd(10),
       formatMetricsNumber(row.totalTokens).padEnd(9),
-      formatMetricsCost(row.costUsd).padEnd(9),
+      formatMetricsCostLine(row).padEnd(9),
       formatMetricsNumber(row.ampCredits).padEnd(9),
       row.source || 'none',
     ].join(' '));
@@ -2286,7 +2408,7 @@ function renderMetricsSummary(metrics) {
         String(row.model || '—').padEnd(20),
         String(row.platform || '—').padEnd(10),
         formatMetricsNumber(row.totalTokens).padEnd(9),
-        formatMetricsCost(row.costUsd).padEnd(9),
+        formatMetricsCostLine(row).padEnd(9),
         formatMetricsNumber(row.ampCredits),
       ].join(' '));
     }
@@ -2296,10 +2418,11 @@ function renderMetricsSummary(metrics) {
     lines.push('');
     lines.push('recent sessions:');
     for (const session of sessions.slice(-5)) {
-      const spendLabel = session.totalTokens != null || session.costUsd != null
-        ? ` — ${formatMetricsNumber(session.totalTokens)} tok, ${formatMetricsCost(session.costUsd)}`
+      const spendLabel = session.totalTokens != null || session.costUsd != null || session.costUsdEstimated != null
+        ? ` — ${formatMetricsNumber(session.totalTokens)} tok, ${formatMetricsCostLine(session)}`
         : '';
-      lines.push(`- ${session.endedAt}  ${String(session.phase || '').padEnd(7)} ${formatMetricsDuration(session.durationMs).padEnd(9)} ${session.role || '(no role)'}${session.model ? ` [${session.model}]` : ''} (${sessionSpendSourceLabel(session)})${spendLabel}`);
+      const modeLabel = session.agentMode ? ` mode:${session.agentMode}` : '';
+      lines.push(`- ${formatKyivDisplay(session.endedAt)}  ${String(session.phase || '').padEnd(7)} ${formatMetricsDuration(session.durationMs).padEnd(9)} ${session.role || '(no role)'}${session.model ? ` [${session.model}]` : ''}${modeLabel} (${sessionSpendSourceLabel(session)})${spendLabel}`);
     }
   }
   return lines;
@@ -3478,7 +3601,7 @@ program
   .option('--output-tokens <n>', 'Output tokens spent in the Archiver session')
   .option('--total-tokens <n>', 'Total tokens spent in the Archiver session (default: input + output)')
   .option('--cost-usd <usd>', 'Cost of the Archiver session in USD')
-  .option('--collect', 'Additionally collect local spend adapters', false)
+  .option('--collect', 'Collect all spend adapters (default: locked Cursor/Amp/Claude client only)', false)
   .action((name, opts) => {
     const projectDir = process.cwd();
     const fail = (msg) => {
@@ -3598,11 +3721,25 @@ program
     if (existsSync(archivedHandoffPath)) {
       priorFields = fieldsFromSections(name, parseHandoffMarkdown(readFileSync(archivedHandoffPath, 'utf-8')));
     }
-    const reported = priorFields.metrics || emptyMetricsFields();
-    const archivePlatform = resolvePlatform(opts, process.env, reported);
+    const metricsPreview = loadMetricsFile(join(targetDir, 'metrics.json'), name, nowUtcIso());
+    const reported = dropStaleArchiveSelfReport(priorFields.metrics, metricsPreview.sessions);
+    const client = resolveRestoreClient({
+      env: process.env,
+      cwd: projectDir,
+      homedir: process.env.HOME,
+      platform: opts.platform,
+    });
+    const archivePlatform = resolvePlatform(opts, process.env, reported, {
+      platform: client.platform,
+      threadId: client.threadId,
+    });
     const archiveModel = resolveModel(opts, process.env, reported);
     if (archivePlatform.warn) console.error(archivePlatform.warn);
     printMetricsSectionWarnings(reported, Boolean(archivePlatform.warn));
+    const clientLabel = archivePlatform.value || client.platform
+      ? `${archivePlatform.value || client.platform}${client.threadId ? ` ${client.threadId}` : ''}${client.source ? ` (${client.source})` : ''}`
+      : 'unknown — pass --platform or run archive from Cursor/Amp/Claude';
+    console.error(`metrics: archive client ${clientLabel}`);
     const runtimeResult = resolveRuntime({}, process.env, priorFields);
     const progress = parseTasksProgress(targetDir);
     const fields = {
@@ -3629,7 +3766,8 @@ program
     const memoryPath = persistMemoryFromHandoff(projectDir, fields);
     const metricsPath = metricsFinalizeArchive(targetDir, name, {
       model: archiveModel,
-      platform: archivePlatform.value || null,
+      platform: archivePlatform.value || client.platform || null,
+      ampThreadId: client.threadId || ampThreadIdFromEnv(process.env) || null,
       runtime: fields.runtime,
       agentId: fields.agentId,
       tasks: fields.tasks,
@@ -3649,7 +3787,7 @@ program
     console.log(`memory:   ${memoryPath.replace(`${projectDir}/`, '')}`);
     console.log(`metrics:  ${metricsPath.replace(`${projectDir}/`, '')} (archived_at set)`);
     try {
-      const archivedMetrics = loadMetricsFile(metricsPath, name, new Date().toISOString());
+      const archivedMetrics = loadMetricsFile(metricsPath, name, nowUtcIso());
       for (const line of renderMetricsSummary(archivedMetrics)) console.log(line);
     } catch {}
     log.ok(`archived ${name}`);
@@ -3998,7 +4136,7 @@ program
     }
 
     const reported = fields.metrics || emptyMetricsFields();
-    const metricsPreview = loadMetricsFile(metricsFilePath(projectDir, name), name, new Date().toISOString());
+    const metricsPreview = loadMetricsFile(metricsFilePath(projectDir, name), name, nowUtcIso());
     const platformResult = resolvePlatform(opts, process.env, reported, metricsPreview.pending);
     if (platformResult.error) {
       log.err(platformResult.error);
@@ -4099,7 +4237,7 @@ program
       return;
     }
 
-    const metrics = loadMetricsFile(filePath, name, new Date().toISOString());
+    const metrics = loadMetricsFile(filePath, name, nowUtcIso());
     if (opts.json) {
       process.stdout.write(`${JSON.stringify(metrics, null, 2)}\n`);
       return;
@@ -4110,4 +4248,18 @@ program
     for (const line of renderMetricsSummary(metrics)) console.log(line);
   });
 
-program.parse();
+function isDirectCliRun() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return resolve(entry) === fileURLToPath(import.meta.url);
+  }
+}
+
+if (isDirectCliRun()) {
+  program.parse();
+}
+
+export { formatMetricsCostLine, resolveSessionSpend };

package/bin/amp-usage.js

@@ -0,0 +1,63 @@
+function numOrNull(value) {
+  if (value == null || value === '') return null;
+  const n = Number(String(value).replace(/,/g, ''));
+  return Number.isFinite(n) ? n : null;
+}
+
+export function parseAmpUsageDetails(text) {
+  const raw = String(text || '');
+  const costMatch = /(?:^|\n)Cost:\s*\$([0-9]+(?:\.[0-9]+)?)/.exec(raw);
+  const totalMatch = /Total tokens:\s*([\d,]+)/i.exec(raw);
+  const inputMatch = /Input tokens:\s*([\d,]+)(?:\s*\(([\d,]+)\s*cache reads\))?/i.exec(raw);
+  const outputMatch = /Output tokens:\s*([\d,]+)/i.exec(raw);
+  const models = [];
+  const tableStart = raw.search(/##\s*Models\b/i);
+  if (tableStart >= 0) {
+    const section = raw.slice(tableStart);
+    const rowRe = /^\|\s*(?!Model\b|[-: ]+)([^|]+?)\s*\|\s*([\d,]+)\s*\|\s*([\d,]+)\s*\|\s*([\d,]+)\s*\|\s*\$([0-9]+(?:\.[0-9]+)?)\s*\|/gim;
+    let row;
+    while ((row = rowRe.exec(section))) {
+      models.push({
+        model: row[1].trim(),
+        requests: numOrNull(row[2]),
+        inputTokens: numOrNull(row[3]),
+        outputTokens: numOrNull(row[4]),
+        costUsd: numOrNull(row[5]),
+      });
+    }
+  }
+  return {
+    costUsd: costMatch ? numOrNull(costMatch[1]) : null,
+    totalTokens: totalMatch ? numOrNull(totalMatch[1]) : null,
+    inputTokens: inputMatch ? numOrNull(inputMatch[1]) : null,
+    cacheReadTokens: inputMatch && inputMatch[2] ? numOrNull(inputMatch[2]) : null,
+    outputTokens: outputMatch ? numOrNull(outputMatch[1]) : null,
+    models,
+  };
+}
+
+export function ampAgentMode(thread) {
+  if (!thread || typeof thread !== 'object') return null;
+  const direct = thread.agentMode || (thread.meta && thread.meta.agentMode);
+  if (direct == null || String(direct).trim() === '') return null;
+  return String(direct).trim();
+}
+
+function compactModel(value) {
+  return String(value || '').toLowerCase().replace(/[^a-z0-9]+/g, '').replace(/(\d)p(\d)/g, '$1$2');
+}
+
+export function matchAmpUsageModel(displayName, sourceModels) {
+  const wanted = compactModel(displayName);
+  if (!wanted) return displayName;
+  let best = null;
+  for (const id of sourceModels || []) {
+    const compact = compactModel(id);
+    if (!compact) continue;
+    if (compact === wanted || compact.includes(wanted) || wanted.includes(compact.replace(/^accountsfireworkmodels/, ''))) {
+      best = id;
+      break;
+    }
+  }
+  return best || displayName;
+}

package/bin/cursor-cost-estimate.js

@@ -0,0 +1,76 @@
+function numOrNull(value) {
+  if (value == null || value === '') return null;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+const GROK_46 = {
+  inputPerM: 2,
+  cachedPerM: 0.5,
+  outputPerM: 6,
+  longInputPerM: 4,
+  longCachedPerM: 1,
+  longOutputPerM: 12,
+  longAt: 200000,
+};
+
+const FALLBACK_INPUT_PER_M = 3;
+const FALLBACK_OUTPUT_PER_M = 15;
+const FALLBACK_TOTAL_PER_M = 3.5;
+
+function ratesForModel(model) {
+  const id = String(model || '').toLowerCase();
+  if (!id) return null;
+  let rates = null;
+  if (id.includes('grok-4.6') || id.includes('grok-4-6')) rates = { ...GROK_46 };
+  else if (id.includes('grok-4.5') || id.includes('grok-4-5')) {
+    rates = { ...GROK_46, cachedPerM: 0.3, longCachedPerM: 0.6 };
+  } else {
+    return null;
+  }
+  if (id.includes('fast')) {
+    for (const key of ['inputPerM', 'cachedPerM', 'outputPerM', 'longInputPerM', 'longCachedPerM', 'longOutputPerM']) {
+      rates[key] *= 2;
+    }
+  }
+  return rates;
+}
+
+export function estimateCursorCostUsd({ model, inputTokens, outputTokens, cacheReadTokens, totalTokens } = {}) {
+  const rates = ratesForModel(model);
+  if (rates) {
+    const input = numOrNull(inputTokens);
+    const output = numOrNull(outputTokens) ?? 0;
+    if (input == null && output == 0) return null;
+    const totalInput = input ?? 0;
+    const cached = Math.min(numOrNull(cacheReadTokens) ?? 0, totalInput);
+    const fresh = Math.max(0, totalInput - cached);
+    const long = totalInput >= rates.longAt;
+    const inputRate = long ? rates.longInputPerM : rates.inputPerM;
+    const cachedRate = long ? rates.longCachedPerM : rates.cachedPerM;
+    const outputRate = long ? rates.longOutputPerM : rates.outputPerM;
+    const usd = (fresh * inputRate + cached * cachedRate + output * outputRate) / 1e6;
+    return Math.round(usd * 10000) / 10000;
+  }
+  const input = numOrNull(inputTokens);
+  const output = numOrNull(outputTokens);
+  if (input != null || output != null) {
+    const usd = ((input ?? 0) * FALLBACK_INPUT_PER_M + (output ?? 0) * FALLBACK_OUTPUT_PER_M) / 1e6;
+    return Math.round(usd * 10000) / 10000;
+  }
+  const total = numOrNull(totalTokens);
+  if (total != null) {
+    const usd = total * FALLBACK_TOTAL_PER_M / 1e6;
+    return Math.round(usd * 10000) / 10000;
+  }
+  return null;
+}
+
+export function describeCursorCostEstimate(args) {
+  const usd = estimateCursorCostUsd(args);
+  if (usd == null) return null;
+  return {
+    usd,
+    costSource: ratesForModel(args && args.model) != null ? 'api-estimate' : 'api-estimate-fallback',
+  };
+}

package/bin/metrics-time.js

@@ -0,0 +1,99 @@
+const DISPLAY_TIMEZONE = 'Europe/Kyiv';
+
+function pad2(value) {
+  return String(value).padStart(2, '0');
+}
+
+export function parseFlexibleIso(value) {
+  if (value == null || value === '') return NaN;
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return value < 1e12 ? value * 1000 : value;
+  }
+  let raw = String(value).trim();
+  if (!raw) return NaN;
+  raw = raw.replace(/^(\d{4}-\d{2}-\d{2})[ ]+(\d{2}:)/, '$1T$2');
+  raw = raw.replace(/(\.\d{3})\d*\.000(?=Z$|[+-]\d{2}:?\d{2}$)/i, '$1');
+  raw = raw.replace(/(\.\d{3})\d+(?=Z$|[+-]\d{2}:?\d{2}$)/i, '$1');
+  raw = raw.replace(/([+-]\d{2})(\d{2})$/, '$1:$2');
+  if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?$/.test(raw)) raw += 'Z';
+  const ms = Date.parse(raw);
+  return Number.isFinite(ms) ? ms : NaN;
+}
+
+export function formatUtcIso(value) {
+  const ms = parseFlexibleIso(value);
+  if (!Number.isFinite(ms)) return null;
+  return new Date(ms).toISOString();
+}
+
+export function nowUtcIso(now = Date.now()) {
+  return formatUtcIso(now);
+}
+
+function kyivOffset(ms) {
+  const d = new Date(ms);
+  const fmt = new Intl.DateTimeFormat('en-US', {
+    timeZone: DISPLAY_TIMEZONE,
+    timeZoneName: 'longOffset',
+    hour: '2-digit',
+  });
+  const name = fmt.formatToParts(d).find((part) => part.type === 'timeZoneName')?.value || '';
+  const match = /GMT([+-])(\d{1,2})(?::(\d{2}))?/.exec(name);
+  if (match) {
+    return `${match[1]}${pad2(match[2])}:${match[3] || '00'}`;
+  }
+  const utc = new Date(d.toLocaleString('en-US', { timeZone: 'UTC' })).getTime();
+  const kyiv = new Date(d.toLocaleString('en-US', { timeZone: DISPLAY_TIMEZONE })).getTime();
+  const minutes = Math.round((kyiv - utc) / 60000);
+  const sign = minutes >= 0 ? '+' : '-';
+  const abs = Math.abs(minutes);
+  return `${sign}${pad2(Math.floor(abs / 60))}:${pad2(abs % 60)}`;
+}
+
+function formatKyivIso(value) {
+  const ms = parseFlexibleIso(value);
+  if (!Number.isFinite(ms)) return null;
+  const d = new Date(ms);
+  const parts = Object.fromEntries(
+    new Intl.DateTimeFormat('en-US', {
+      timeZone: DISPLAY_TIMEZONE,
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+      hourCycle: 'h23',
+    }).formatToParts(d).map((part) => [part.type, part.value]),
+  );
+  return `${parts.year}-${parts.month}-${parts.day}T${parts.hour}:${parts.minute}:${parts.second}.${String(ms % 1000).padStart(3, '0')}${kyivOffset(ms)}`;
+}
+
+export function formatKyivDisplay(value) {
+  const iso = formatKyivIso(value);
+  if (!iso) return '—';
+  const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?([+-]\d{2}:\d{2})$/.exec(iso);
+  if (!match) return iso;
+  return `${match[3]}.${match[2]}.${match[1]} ${match[4]}:${match[5]}:${match[6]} (Київ ${match[7]})`;
+}
+
+export function isoOrNull(value) {
+  if (value == null || value === '') return null;
+  return formatUtcIso(value);
+}
+
+export function laterTimestamp(a, b) {
+  const left = parseFlexibleIso(a);
+  const right = parseFlexibleIso(b);
+  if (!Number.isFinite(left)) return b;
+  if (!Number.isFinite(right)) return a;
+  return left >= right ? a : b;
+}
+
+export function earlierTimestamp(a, b) {
+  const left = parseFlexibleIso(a);
+  const right = parseFlexibleIso(b);
+  if (!Number.isFinite(left)) return b;
+  if (!Number.isFinite(right)) return a;
+  return left <= right ? a : b;
+}

package/bin/spend-collect.js

@@ -3,6 +3,9 @@ import { join, basename } from 'path';
 import { homedir as osHomedir } from 'os';
 import { execFileSync } from 'child_process';
 import { listRecentAmpThreadIds } from './session-client.js';
+import { formatUtcIso, parseFlexibleIso } from './metrics-time.js';
+import { describeCursorCostEstimate } from './cursor-cost-estimate.js';
+import { ampAgentMode, matchAmpUsageModel, parseAmpUsageDetails } from './amp-usage.js';
 
 const PLATFORMS = ['cursor', 'claude', 'amp'];
 
@@ -24,6 +27,7 @@ function emptyPlatform(source = 'none') {
     totalTokens: null,
     costUsd: null,
     ampCredits: null,
+    costUsdEstimated: null,
     source,
   };
 }
@@ -59,11 +63,7 @@ function pathsEqual(a, b) {
 }
 
 function parseTime(value) {
-  if (value == null || value === '') return NaN;
-  if (typeof value === 'number' && Number.isFinite(value)) {
-    return value < 1e12 ? value * 1000 : value;
-  }
-  return Date.parse(String(value));
+  return parseFlexibleIso(value);
 }
 
 function inWindow(timestamp, windowStart, windowEnd) {
@@ -80,12 +80,25 @@ function inWindow(timestamp, windowStart, windowEnd) {
   return true;
 }
 
-function sourceRecord({ id, platform, model, inputTokens, outputTokens, costUsd, ampCredits, at }) {
+function sourceRecord({
+  id,
+  platform,
+  model,
+  inputTokens,
+  outputTokens,
+  costUsd,
+  ampCredits,
+  at,
+  cacheReadTokens,
+  costUsdEstimated,
+  costSource,
+  agentMode,
+}) {
   const input = numOrNull(inputTokens);
   const output = numOrNull(outputTokens);
   let total = null;
   if (input != null || output != null) total = (input ?? 0) + (output ?? 0);
-  return {
+  const record = {
     id: String(id),
     platform,
     model: model == null || model === '' ? null : String(model),
@@ -94,8 +107,15 @@ function sourceRecord({ id, platform, model, inputTokens, outputTokens, costUsd,
     totalTokens: total,
     costUsd: numOrNull(costUsd),
     ampCredits: numOrNull(ampCredits),
-    at: at == null ? null : String(at),
+    at: at == null || at === '' ? null : (formatUtcIso(at) || String(at)),
   };
+  const cache = numOrNull(cacheReadTokens);
+  if (cache != null) record.cacheReadTokens = cache;
+  const estimated = numOrNull(costUsdEstimated);
+  if (estimated != null) record.costUsdEstimated = estimated;
+  if (costSource) record.costSource = String(costSource);
+  if (agentMode) record.agentMode = String(agentMode);
+  return record;
 }
 
 function claudeInputTokens(usage) {
@@ -334,6 +354,7 @@ export function sourcesFromAmpThread(thread, ctx, fileName = '', via = null) {
       costUsd: null,
       ampCredits: null,
       at: usage.timestamp,
+      agentMode: ampAgentMode(thread),
     });
     if (via) record.via = via;
     sources.push(record);
@@ -395,6 +416,39 @@ export function exportAmpThread(threadId, options = {}) {
   }
 }
 
+export function fetchAmpThreadUsage(threadId, options = {}) {
+  const id = threadId == null ? '' : String(threadId).trim();
+  if (!id) return null;
+  if (typeof options.usageAmpThread === 'function') {
+    try {
+      const injected = options.usageAmpThread(id);
+      if (injected == null) return null;
+      if (typeof injected === 'string') return parseAmpUsageDetails(injected);
+      if (typeof injected === 'object') {
+        if (injected.text && injected.costUsd == null) return { ...parseAmpUsageDetails(injected.text), ...injected };
+        return injected;
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+  if (typeof options.exportAmpThread === 'function') 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', 'usage', id, '--details'], {
+      encoding: 'utf-8',
+      timeout: options.timeoutMs != null ? Number(options.timeoutMs) : 25000,
+      env: options.env || process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return parseAmpUsageDetails(out);
+  } catch {
+    return null;
+  }
+}
+
 function collectAmpCli(ctx) {
   const { env, notes, ampThreadId } = ctx;
   const ids = [];
@@ -408,17 +462,41 @@ function collectAmpCli(ctx) {
     for (const id of listRecentAmpThreadIds(ctx)) push(id);
   }
   const sources = [];
+  const threads = [];
   for (const id of ids) {
     const thread = exportAmpThread(id, ctx);
     if (!thread) {
       notes.push(`amp: export failed for ${id}`);
       continue;
     }
+    const agentMode = ampAgentMode(thread);
     const extracted = sourcesFromAmpThread(thread, ctx, `${id}.json`, 'amp-cli');
     if (!extracted.length) notes.push(`amp: export ${id} had no matching usage`);
     sources.push(...extracted);
+    const usage = fetchAmpThreadUsage(id, ctx);
+    if (!usage) notes.push(`amp: usage failed for ${id}`);
+    const sourceModels = extracted.map((src) => src.model).filter(Boolean);
+    const usageModels = (usage && Array.isArray(usage.models) ? usage.models : []).map((row) => ({
+      ...row,
+      model: matchAmpUsageModel(row.model, sourceModels),
+    }));
+    if (usage && usage.costUsd != null) {
+      for (const src of extracted) {
+        src.costSource = 'amp-usage';
+      }
+    }
+    threads.push({
+      id,
+      agentMode,
+      costUsd: usage ? numOrNull(usage.costUsd) : null,
+      inputTokens: usage ? numOrNull(usage.inputTokens) : null,
+      outputTokens: usage ? numOrNull(usage.outputTokens) : null,
+      totalTokens: usage ? numOrNull(usage.totalTokens) : null,
+      cacheReadTokens: usage ? numOrNull(usage.cacheReadTokens) : null,
+      models: usageModels,
+    });
   }
-  return sources;
+  return { sources, threads };
 }
 
 export const CURSOR_USAGE_FILE_REL = join('.agents', 'spend', 'cursor-usage.jsonl');
@@ -455,15 +533,26 @@ function collectCursor({ cwd, windowStart, windowEnd, existing, notes }) {
     const inputTokens = numOrNull(row.inputTokens);
     const outputTokens = numOrNull(row.outputTokens);
     if (inputTokens == null && outputTokens == null) continue;
+    const model = row.model || row.modelId;
+    const cacheReadTokens = numOrNull(row.cacheReadTokens);
+    const described = describeCursorCostEstimate({
+      model,
+      inputTokens,
+      outputTokens,
+      cacheReadTokens,
+    });
     const record = sourceRecord({
       id,
       platform: 'cursor',
-      model: row.model || row.modelId,
+      model,
       inputTokens,
       outputTokens,
       costUsd: null,
       ampCredits: null,
       at: row.at,
+      cacheReadTokens,
+      costUsdEstimated: described?.usd ?? null,
+      costSource: described?.costSource ?? null,
     });
     const previous = bestById.get(id);
     if (!previous || (record.totalTokens ?? 0) >= (previous.totalTokens ?? 0)) {
@@ -485,6 +574,7 @@ function aggregate(sources) {
       bucket.totalTokens = addNullable(bucket.totalTokens, src.totalTokens);
       bucket.costUsd = addNullable(bucket.costUsd, src.costUsd);
       bucket.ampCredits = addNullable(bucket.ampCredits, src.ampCredits);
+      bucket.costUsdEstimated = addNullable(bucket.costUsdEstimated, src.costUsdEstimated);
       if (platform === 'claude') bucket.source = 'claude-jsonl';
       else if (platform === 'amp') bucket.source = src.via === 'amp-cli' ? 'amp-cli' : 'amp-thread';
       else bucket.source = 'cursor-hook';
@@ -500,12 +590,14 @@ function aggregate(sources) {
         totalTokens: null,
         costUsd: null,
         ampCredits: null,
+        costUsdEstimated: null,
       };
       row.inputTokens = addNullable(row.inputTokens, src.inputTokens);
       row.outputTokens = addNullable(row.outputTokens, src.outputTokens);
       row.totalTokens = addNullable(row.totalTokens, src.totalTokens);
       row.costUsd = addNullable(row.costUsd, src.costUsd);
       row.ampCredits = addNullable(row.ampCredits, src.ampCredits);
+      row.costUsdEstimated = addNullable(row.costUsdEstimated, src.costUsdEstimated);
       byModel.set(key, row);
     }
   }
@@ -541,10 +633,12 @@ export function collectSpend(options = {}) {
     ampThreadId: options.ampThreadId,
     exportAmpThread: options.exportAmpThread,
     listAmpThreads: options.listAmpThreads,
+    usageAmpThread: options.usageAmpThread,
     ampBin: options.ampBin,
     timeoutMs: options.timeoutMs,
   };
   let sources = [];
+  const ampThreads = [];
   if (run('claude')) {
     try {
       sources = sources.concat(collectClaude(ctx));
@@ -555,7 +649,9 @@ export function collectSpend(options = {}) {
   if (run('amp')) {
     if (options.ampCli === true || typeof options.exportAmpThread === 'function') {
       try {
-        sources = sources.concat(collectAmpCli(ctx));
+        const cli = collectAmpCli(ctx);
+        sources = sources.concat(cli.sources || []);
+        if (Array.isArray(cli.threads)) ampThreads.push(...cli.threads);
       } catch {
         notes.push('amp: cli export failed');
       }
@@ -574,5 +670,22 @@ export function collectSpend(options = {}) {
     }
   }
   const { byPlatform, byModel } = aggregate(sources);
-  return { sources, byPlatform, byModel, notes };
+  applyAmpThreadSpend(byPlatform, byModel, ampThreads);
+  return { sources, byPlatform, byModel, notes, ampThreads };
+}
+
+function applyAmpThreadSpend(byPlatform, byModel, threads) {
+  if (!threads || !threads.length) return;
+  let cost = null;
+  for (const thread of threads) {
+    cost = addNullable(cost, numOrNull(thread.costUsd));
+    for (const row of thread.models || []) {
+      if (!row.model) continue;
+      const key = `${row.model}::amp`;
+      const existing = byModel.find((item) => `${item.model}::${item.platform || ''}` === key)
+        || byModel.find((item) => item.platform === 'amp' && item.model === row.model);
+      if (existing && row.costUsd != null) existing.costUsd = addNullable(existing.costUsd, row.costUsd);
+    }
+  }
+  if (cost != null) byPlatform.amp.costUsd = addNullable(byPlatform.amp.costUsd, cost);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-kit",
-  "version": "0.8.0",
+  "version": "0.10.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 prints the change-wide metrics summary. Collect runs only with `--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), collects the locked client into that session (Cursor hook / Amp usage / Claude JSONL; `--collect` = all adapters), and prints the change-wide metrics summary. 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/subagents/spec-archiver.md

@@ -9,7 +9,7 @@ Workflow:
 
 1. Read `.agents/orchestrator.yaml`, the complete change, review verdict, task state, and verification/merge evidence supplied by the conductor.
 2. Refuse to archive unless required review is approved, all tasks are complete, and the configured merge/CI gate is satisfied.
-3. Fill `## Metrics` in the change `handoff.md` (Archiver self-report: platform, model, tokens, cost_usd, amp_credits, spend_source; use `unknown` when missing) before running archive.
+3. Fill `## Metrics` in the change `handoff.md` only when reporting Archiver-specific numbers (use `unknown` when missing). Do not copy the previous apply session. The CLI auto-collects the locked client into the Archiver session.
 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.