agent-orchestrator-kit 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-09-02
+
+### Fixed
+- **Cursor leftover race, multi-root, 4-decimal estimates, and per-phase clock.** `stop` / `afterAgentResponse` run leftover immediately after a successful jsonl append (fail-open, no stdout); `sessionEnd` leftover stays and stays idempotent. Leftover filters `last.threadId` when it is non-empty and stays time-only when it is `null` or `''`. Hook and collect resolve the consumer in a multi-root window (not the first cwd with `.agents` or `openspec`); leftover walks every candidate that has `openspec/changes`. Written `costUsdEstimated` aggregates are rounded to 4 decimals after sums (`2.3911 + 2.8153 + 1.355 === 6.5614`). Each `phases.<phase>` now stores `startedAt` / `endedAt` / `leadTimeMs` from that phase’s sessions (epoch ms); `durationMs` remains the work-time sum and does not clone `totals.leadTimeMs`.
+
+## [0.11.0] - 2026-09-02
+
+### Changed
+- **Session metrics attribution.** Persist collect is `[pending.startedAt, endedAt]`; a late hook goes to leftover of that session, not the next persist. Archive collect is `[pending.startedAt, now]` plus leftover of the previous session; `sessionEnd` reads the newest `openspec/changes/archive/*-<name>/metrics.json`. Source product id wins when sources have a model; `--model` / `## Metrics` / `AOK_MODEL` apply only when sources have none. Cursor collect filters by `conversationId` when a filter id is present. Canonical Closed role token is stored in `session.role`. Placeholder `unknown` plus `spend_source: self-report` does not freeze leftover totals.
+
+### Fixed
+- **Cursor `sessionEnd` collect writes `costUsdEstimated`.** `scripts/cursor-spend-collect.cjs` no longer copies tokens without an estimate: leftover hook rows keep `cacheReadTokens`, grok uses the xAI table (`costSource: api-estimate`, including `-fast` and the 200k cliff), other models use the `$3/$15` fallback, and aggregates (`spend`, platforms, models, phases) keep `costUsdEstimated`. Leftover rows after `pending.startedAt` stay off the last closed session. Persist / restore / `metrics --collect` also backfill estimates onto legacy cursor sources that already had tokens but `costUsdEstimated: null`. Amp credits stay self-report only; Amp billed USD still comes only from `amp threads usage` `Cost: $N`.
+- **Cursor `stop` + `afterAgentResponse` no longer double-count a turn.** When Cursor omits `generation_id`, the spend hook used `Date.now()` and wrote two ids for the same tokens. The hook now uses a stable fallback id; persist and `sessionEnd` collect also collapse rows that share model + input/output/cache, prefer `stop`, skip leftover after `endedAt + 120s` when no session is pending, and resync adapter session totals from the remaining sources.
+
 ## [0.10.0] - 2026-08-31
 
 ### Added
@@ -257,6 +271,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.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
 [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

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 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 (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
@@ -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, 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.
+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 `[pending.startedAt, now]` plus leftover of the previous session — the same leftover-then-collect 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
 
@@ -802,15 +802,18 @@ Persist with `runtime: cloud` prints those four steps on stderr; stdout stays th
 Every change accumulates git-tracked `openspec/changes/<name>/metrics.json` — the data source for planning the next feature: how long each phase took, how many sessions it needed, what it cost.
 
 - **`## 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.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. `--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.
+- **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`.
+- **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`.
+- **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 `—`.
 - **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.
-- **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).
+- **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 (`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.
+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.
 
 Fill `## Metrics` in `handoff.md` **before** persist (unknown is fine; do not invent `0`):
 
@@ -1003,6 +1006,16 @@ Phase bounds and non-goals: [`openspec/specs/agentic-factory-roadmap/spec.md`](o
 
 ## Changelog
 
+### 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`
+- `costUsdEstimated` aggregates write 4 decimals; `phases.<phase>` stores `startedAt` / `endedAt` / `leadTimeMs` (work-time `durationMs` is not `totals.leadTimeMs`)
+
+### 0.11.0
+- Session metrics attribution: persist collect is `[pending.startedAt, endedAt]`; a late hook stays leftover of that session; archive is `[pending.startedAt, now]` plus leftover of the previous session
+- Source product id wins for `session.model`; `--model` / `## Metrics` / `AOK_MODEL` apply only when sources have none
+- Cursor `sessionEnd` writes `costUsdEstimated`; `stop` + `afterAgentResponse` no longer double-count a turn
+
 ### 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.
 

package/bin/agent-orchestrator.js

@@ -5,7 +5,7 @@ import { readFileSync, existsSync, mkdirSync, copyFileSync, readdirSync, statSyn
 import { join, dirname, basename, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
-import { collectSpend } from './spend-collect.js';
+import { collectSpend, enrichMetricsCursorEstimates } from './spend-collect.js';
 import { resolveRestoreClient, ampThreadIdFromEnv } from './session-client.js';
 import {
   earlierTimestamp,
@@ -1613,6 +1613,12 @@ function readHandoffFields(projectDir, changeName) {
 
 const METRICS_VERSION = 1;
 const METRICS_SPEND_KEYS = ['inputTokens', 'outputTokens', 'totalTokens', 'costUsd', 'costUsdEstimated'];
+const LEFTOVER_GRACE_MS = 120000;
+
+function roundUsd4(x) {
+  if (x == null) return null;
+  return Math.round(Number(x) * 10000) / 10000;
+}
 
 function metricsFilePath(projectDir, changeName) {
   return join(projectDir, 'openspec', 'changes', changeName, 'metrics.json');
@@ -1713,12 +1719,29 @@ function addNullable(a, b) {
   return (a ?? 0) + (b ?? 0);
 }
 
+function canonicalRole(role) {
+  const raw = String(role || '').trim();
+  if (!raw) return '';
+  const segment = raw.split(/[—,]/)[0].trim();
+  const known = (text) => {
+    const value = String(text || '').trim();
+    if (/^spec\s+reviewer\b/i.test(value)) return 'Spec Reviewer';
+    if (/^design\s+intake\b/i.test(value)) return 'Design Intake';
+    if (/^explorer\b/i.test(value)) return 'Explorer';
+    if (/^architect\b/i.test(value)) return 'Architect';
+    if (/^implementer\b/i.test(value)) return 'Implementer';
+    if (/^archiver\b/i.test(value)) return 'Archiver';
+    return '';
+  };
+  return known(segment) || known(raw) || segment;
+}
+
 function phaseForRole(role) {
   const value = String(role || '').toLowerCase();
   if (/explor/.test(value)) return 'explore';
+  if (/architect|propose/.test(value)) return 'spec';
   if (/review/.test(value)) return 'review';
   if (/implement|apply|code-writer|test-writer/.test(value)) return 'apply';
-  if (/architect|propose/.test(value)) return 'spec';
   if (/design/.test(value)) return 'design';
   if (/archiv/.test(value)) return 'archive';
   return 'other';
@@ -1741,8 +1764,46 @@ function lastSessionEndedAt(metrics) {
   return last;
 }
 
-function collectWindowStart(metrics) {
-  return lastSessionEndedAt(metrics) || metrics.createdAt;
+function collectWindowStart(metrics, extra) {
+  return (extra && extra.startedAt) || (metrics.pending && metrics.pending.startedAt) || null;
+}
+
+function leftoverGraceEnd(endedAt) {
+  const ms = parseFlexibleIso(endedAt);
+  if (!Number.isFinite(ms)) return null;
+  return new Date(ms + LEFTOVER_GRACE_MS).toISOString();
+}
+
+function leftoverTimestampInWindow(at, windowStart, leftoverEnd, exclusiveEnd) {
+  const t = parseFlexibleIso(at);
+  if (!Number.isFinite(t)) return false;
+  const start = parseFlexibleIso(windowStart);
+  if (Number.isFinite(start) && t < start) return false;
+  const end = parseFlexibleIso(leftoverEnd);
+  if (Number.isFinite(end)) {
+    if (exclusiveEnd) {
+      if (t >= end) return false;
+    } else if (t > end) return false;
+  }
+  return true;
+}
+
+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;
+}
+
+function existingSourceRecords(metrics) {
+  const out = [];
+  for (const session of metrics.sessions || []) {
+    for (const src of session.sources || []) {
+      if (src) out.push(src);
+    }
+  }
+  return out;
 }
 
 function existingSourceIdSet(metrics) {
@@ -1802,8 +1863,9 @@ function rankSources(sources) {
 }
 
 function primaryModelFromSources(sources) {
-  if (!sources || !sources.length) return null;
-  const top = rankSources(sources)[0];
+  const withModel = (sources || []).filter((src) => src && src.model);
+  if (!withModel.length) return null;
+  const top = rankSources(withModel)[0];
   const model = top && top.model;
   return model == null || model === '' ? null : String(model);
 }
@@ -1845,7 +1907,7 @@ function sourceEstimatedUsd(sources) {
   for (const src of sources || []) {
     sum = addNullable(sum, numOrNull(src.costUsdEstimated));
   }
-  return sum;
+  return roundUsd4(sum);
 }
 
 function ampThreadTotals(threads) {
@@ -1884,7 +1946,7 @@ function resolveSessionSpend(opts, reported, sources, extra = {}) {
   const ampCredits = firstNonNull(flagCredits, self.ampCredits, sourceCredits);
   const costUsdEstimated = sourceEstimatedUsd(sources || []);
   let spendSource = 'unreported';
-  if (self.spendSource) spendSource = String(self.spendSource);
+  if (self.spendSource && reportedHasSpendNumbers(self)) 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';
@@ -1936,11 +1998,13 @@ function runCollectSpend(metrics, windowStart, windowEnd, extra = {}) {
       windowStart,
       windowEnd,
       existingSourceIds: existingSourceIdSet(metrics),
+      existingSources: existingSourceRecords(metrics),
       env: process.env,
       homedir: process.env.HOME,
       platforms: extra.platforms,
       ampThreadId: extra.ampThreadId,
       ampCli: extra.ampCli === true,
+      cursorConversationId: extra.cursorConversationId,
       exportAmpThread: extra.exportAmpThread,
       usageAmpThread: extra.usageAmpThread,
     });
@@ -1949,6 +2013,37 @@ function runCollectSpend(metrics, windowStart, windowEnd, extra = {}) {
   }
 }
 
+function attachLeftoverSources(metrics, session, leftoverEnd, extra = {}) {
+  if (!session || !session.endedAt || !leftoverEnd) return 0;
+  const exclusiveEnd = extra.exclusiveEnd === true;
+  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',
+    cursorConversationId: extra.cursorConversationId
+      || (session.platform === 'cursor' ? session.threadId : undefined),
+  });
+  const incoming = (collected.sources || []).filter((src) => leftoverTimestampInWindow(
+    src.at,
+    session.endedAt,
+    leftoverEnd,
+    exclusiveEnd,
+  ));
+  if (!incoming.length) return 0;
+  const merged = [...(session.sources || []), ...incoming];
+  if (sessionSpendIsFrozen(session)) {
+    session.sources = merged;
+    const uniqueModels = uniqueSourceModels(merged);
+    if (uniqueModels.length > 1) session.models = uniqueModels;
+  } else {
+    applyCollectedSessionFields(session, merged, session.model, {}, {
+      model: session.model,
+      platform: session.platform,
+    }, { ampThreads: collected.ampThreads });
+  }
+  return incoming.length;
+}
+
 function applyCollectedSessionFields(session, sources, resolvedModel, opts, reported, extra = {}) {
   session.sources = sources || [];
   const uniqueModels = uniqueSourceModels(session.sources);
@@ -1956,14 +2051,16 @@ function applyCollectedSessionFields(session, sources, resolvedModel, opts, repo
   for (const model of fromAmp.models) {
     if (model && !uniqueModels.includes(model)) uniqueModels.push(model);
   }
-  if (!session.model || isPlaceholderModel(session.model)) {
+  if (uniqueModels.length > 1) session.models = uniqueModels;
+  const sourceModel = primaryModelFromSources(session.sources);
+  if (sourceModel) {
+    session.model = sourceModel;
+  } else {
     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, extra);
   session.inputTokens = spend.inputTokens;
   session.outputTokens = spend.outputTokens;
@@ -2005,21 +2102,17 @@ function metricsBackfillFile(filePath, changeName) {
   const sessions = metrics.sessions || [];
   if (!sessions.length) return { filePath, added: 0, empty: true };
   const last = sessions[sessions.length - 1];
-  const windowStart = last.startedAt || collectWindowStart(metrics);
+  const windowStart = last.startedAt || last.endedAt || metrics.createdAt;
   const lastPlatform = last && last.platform;
   const collected = runCollectSpend(metrics, windowStart, nowIso, {
     ampThreadId: last && last.threadId || ampThreadIdFromEnv(process.env) || null,
     ampCli: lastPlatform === 'amp',
+    cursorConversationId: lastPlatform === 'cursor' ? last.threadId : undefined,
   });
   const incoming = collected.sources || [];
   if (!incoming.length) return { filePath, added: 0 };
-  const overridden = sessionTotalsLookOverridden(last);
   const merged = [...(last.sources || []), ...incoming];
-  const keepReportedTotals = overridden
-    || last.spendSource === 'flag'
-    || last.spendSource === 'self-report'
-    || (last.spendSource && last.spendSource !== 'adapter' && last.spendSource !== 'unreported');
-  if (keepReportedTotals) {
+  if (sessionSpendIsFrozen(last)) {
     last.sources = merged;
     const uniqueModels = uniqueSourceModels(merged);
     if (uniqueModels.length > 1) last.models = uniqueModels;
@@ -2103,58 +2196,77 @@ function recomputeSpendMaps(metrics) {
   }
 
   for (const session of metrics.sessions || []) {
-    const sessionNums = spendTuple(session);
-    const sourceTotals = sessionTotalsFromSources(session.sources || []);
-    sourceTotals.ampCredits = sourceAmpCredits(session.sources || []);
     const sources = session.sources || [];
-    const sourcesMatchSession = sources.length > 0 && spendTuplesMatch(sessionNums, sourceTotals);
-
-    if (sourcesMatchSession) {
+    if (sources.length > 0) {
       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;
     }
-
+    const sessionNums = spendTuple(session);
     if (session.platform && byPlatform[session.platform]) {
       addSpendNums(byPlatform[session.platform], sessionNums);
     }
     addModelRow(session.model, session.platform, sessionNums);
-    for (const src of sources) addSourceRow(src);
+  }
+  for (const key of Object.keys(byPlatform)) {
+    byPlatform[key].costUsdEstimated = roundUsd4(byPlatform[key].costUsdEstimated);
+  }
+  for (const row of byModel.values()) {
+    row.costUsdEstimated = roundUsd4(row.costUsdEstimated);
   }
   metrics.spendByPlatform = byPlatform;
   metrics.spendByModel = [...byModel.values()];
 }
 
 function recomputeMetricsAggregates(metrics) {
+  enrichMetricsCursorEstimates(metrics, process.cwd());
   const phases = {};
   const totals = { sessions: 0, durationMs: null, leadTimeMs: null, cloudSessions: 0 };
   const spend = emptySpendTotals();
   let firstStart = null;
   let lastEnd = null;
   for (const session of metrics.sessions) {
+    session.costUsdEstimated = roundUsd4(session.costUsdEstimated);
     totals.sessions += 1;
     if (session.runtime === 'cloud') totals.cloudSessions += 1;
     totals.durationMs = addNullable(totals.durationMs, numOrNull(session.durationMs));
-    if (session.startedAt) firstStart = firstStart == null ? session.startedAt : earlierTimestamp(firstStart, session.startedAt);
-    if (session.endedAt) lastEnd = lastEnd == null ? session.endedAt : laterTimestamp(lastEnd, session.endedAt);
+    if (Number.isFinite(parseFlexibleIso(session.startedAt))) {
+      firstStart = firstStart == null ? session.startedAt : earlierTimestamp(firstStart, session.startedAt);
+    }
+    if (Number.isFinite(parseFlexibleIso(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: [] };
+    const phase = phases[key] || {
+      sessions: 0,
+      durationMs: null,
+      startedAt: null,
+      endedAt: null,
+      leadTimeMs: null,
+      ...emptySpendTotals(),
+      agents: [],
+      models: [],
+    };
     phase.sessions += 1;
     phase.durationMs = addNullable(phase.durationMs, numOrNull(session.durationMs));
+    if (Number.isFinite(parseFlexibleIso(session.startedAt))) {
+      phase.startedAt = phase.startedAt == null
+        ? session.startedAt
+        : earlierTimestamp(phase.startedAt, session.startedAt);
+    }
+    if (Number.isFinite(parseFlexibleIso(session.endedAt))) {
+      phase.endedAt = phase.endedAt == null
+        ? session.endedAt
+        : laterTimestamp(phase.endedAt, session.endedAt);
+    }
     for (const spendKey of METRICS_SPEND_KEYS) {
-      const value = sessionFieldOrSources(session, spendKey);
+      let value = null;
+      if ((session.sources || []).length > 0) {
+        for (const src of session.sources) {
+          value = addNullable(value, numOrNull(src[spendKey]));
+        }
+      } else {
+        value = sessionFieldOrSources(session, spendKey);
+      }
       phase[spendKey] = addNullable(phase[spendKey], value);
       spend[spendKey] = addNullable(spend[spendKey], value);
     }
@@ -2170,6 +2282,15 @@ function recomputeMetricsAggregates(metrics) {
   if (firstStart && lastEnd) {
     totals.leadTimeMs = Math.max(0, parseFlexibleIso(lastEnd) - parseFlexibleIso(firstStart));
   }
+  for (const phase of Object.values(phases)) {
+    const startMs = parseFlexibleIso(phase.startedAt);
+    const endMs = parseFlexibleIso(phase.endedAt);
+    phase.leadTimeMs = Number.isFinite(startMs) && Number.isFinite(endMs)
+      ? Math.max(0, endMs - startMs)
+      : null;
+    phase.costUsdEstimated = roundUsd4(phase.costUsdEstimated);
+  }
+  spend.costUsdEstimated = roundUsd4(spend.costUsdEstimated);
   metrics.phases = phases;
   metrics.totals = totals;
   metrics.spend = spend;
@@ -2188,6 +2309,7 @@ function metricsRecordSessionStart(projectDir, changeName, role, client = {}) {
     clientSource: client.source || null,
   };
   metrics.updatedAt = nowIso;
+  recomputeMetricsAggregates(metrics);
   saveMetricsFile(filePath, metrics);
   return filePath;
 }
@@ -2196,33 +2318,43 @@ function metricsRecordSessionEnd(projectDir, fields, opts = {}) {
   const filePath = metricsFilePath(projectDir, fields.changeName);
   const nowIso = nowUtcIso();
   const metrics = loadMetricsFile(filePath, fields.changeName, nowIso);
-  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 lastClosed = (metrics.sessions || [])[(metrics.sessions || []).length - 1];
+  const leftoverEnd = (metrics.pending && metrics.pending.startedAt)
+    ? metrics.pending.startedAt
+    : leftoverGraceEnd(lastClosed && lastClosed.endedAt);
+  attachLeftoverSources(metrics, lastClosed, leftoverEnd, {
+    exclusiveEnd: Boolean(metrics.pending && metrics.pending.startedAt),
+  });
+  let startedAt = isoOrNull(opts.startedAt) || isoOrNull(metrics.pending && metrics.pending.startedAt) || null;
   const reported = opts.reported || fields.metrics || emptyMetricsFields();
   const resolvedModel = opts.model === undefined ? resolveModel(opts, process.env, reported) : opts.model;
-  const windowStart = collectWindowStart(metrics);
+  const windowStart = collectWindowStart(metrics, { startedAt });
   const pending = metrics.pending || {};
   const platform = opts.platform || pending.platform || null;
   const collectAll = opts.collect === true;
   const platforms = collectAll ? undefined : (platform ? [platform] : []);
   const shouldCollect = collectAll || (Array.isArray(platforms) && platforms.length > 0);
+  const endedAt = nowIso;
   const collected = shouldCollect
-    ? runCollectSpend(metrics, windowStart, nowIso, {
+    ? runCollectSpend(metrics, windowStart, endedAt, {
       platforms,
       ampThreadId: opts.ampThreadId || pending.threadId || ampThreadIdFromEnv(process.env) || null,
       ampCli: collectAll || platform === 'amp',
+      cursorConversationId: platform === 'cursor' ? pending.threadId : undefined,
     })
     : { sources: [] };
+  const startedMs = parseFlexibleIso(startedAt);
+  const endedMs = parseFlexibleIso(endedAt);
+  let durationMs = Number.isFinite(startedMs) && Number.isFinite(endedMs)
+    ? Math.max(0, endedMs - startedMs)
+    : null;
+  const closedRole = canonicalRole(fields.closedRole) || fields.closedRole || '';
   const session = {
     startedAt,
-    endedAt: nowIso,
+    endedAt,
     durationMs,
-    role: fields.closedRole || '',
-    phase: phaseForRole(fields.closedRole),
+    role: closedRole,
+    phase: phaseForRole(closedRole),
     runtime: fields.runtime || 'local',
     agentId: fields.agentId || 'none',
     model: resolvedModel || null,
@@ -2239,6 +2371,22 @@ function metricsRecordSessionEnd(projectDir, fields, opts = {}) {
     spendSource: 'unreported',
   };
   applyCollectedSessionFields(session, collected.sources || [], resolvedModel, opts, reported, collected);
+  if (!session.startedAt) {
+    let earliest = null;
+    for (const src of session.sources || []) {
+      const at = isoOrNull(src.at);
+      if (!at) continue;
+      earliest = earliest == null ? at : earlierTimestamp(earliest, at);
+    }
+    if (earliest) {
+      session.startedAt = earliest;
+      const fromMs = parseFlexibleIso(session.startedAt);
+      const toMs = parseFlexibleIso(session.endedAt);
+      session.durationMs = Number.isFinite(fromMs) && Number.isFinite(toMs)
+        ? Math.max(0, toMs - fromMs)
+        : null;
+    }
+  }
   metrics.sessions.push(session);
   metrics.pending = null;
   metrics.updatedAt = nowIso;
@@ -2256,25 +2404,33 @@ function metricsFinalizeArchive(targetDir, changeName, opts = {}) {
   const filePath = join(targetDir, 'metrics.json');
   const nowIso = nowUtcIso();
   const metrics = loadMetricsFile(filePath, changeName, nowIso);
-  const windowStart = lastSessionEndedAt(metrics) || metrics.createdAt;
+  const pending = metrics.pending || {};
+  const startedAt = isoOrNull(pending.startedAt) || nowIso;
+  const endedAt = nowIso;
+  const startedMs = parseFlexibleIso(startedAt);
+  const endedMs = parseFlexibleIso(endedAt);
+  const durationMs = Number.isFinite(startedMs) && Number.isFinite(endedMs)
+    ? Math.max(0, endedMs - startedMs)
+    : 0;
   const collectAll = opts.collect === true;
-  const platform = opts.platform || null;
+  const platform = opts.platform || pending.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 ampThreadId = opts.ampThreadId || pending.threadId || ampThreadIdFromEnv(process.env) || null;
   const collected = shouldCollect
-    ? runCollectSpend(metrics, windowStart, nowIso, {
+    ? runCollectSpend(metrics, startedAt, endedAt, {
       platforms,
       ampThreadId,
       ampCli: collectAll || platform === 'amp',
+      cursorConversationId: platform === 'cursor' ? (pending.threadId || ampThreadId) : undefined,
     })
     : { sources: [] };
   const reported = dropStaleArchiveSelfReport(opts.reported, metrics.sessions);
   const resolvedModel = opts.model === undefined ? resolveModel(opts, process.env, reported) : opts.model;
   const session = {
-    startedAt: nowIso,
-    endedAt: nowIso,
-    durationMs: null,
+    startedAt,
+    endedAt,
+    durationMs,
     role: 'Archiver',
     phase: phaseForRole('Archiver'),
     runtime: opts.runtime || 'local',
@@ -2308,6 +2464,29 @@ function metricsFinalizeArchive(targetDir, changeName, opts = {}) {
   return filePath;
 }
 
+function metricsPrepareArchiveStart(changeRoot, changeName, client = {}) {
+  const filePath = join(changeRoot, 'metrics.json');
+  if (!existsSync(filePath)) return;
+  const nowIso = nowUtcIso();
+  const metrics = loadMetricsFile(filePath, changeName, nowIso);
+  if (metrics.pending == null) {
+    metrics.pending = {
+      startedAt: nowIso,
+      role: 'Archiver',
+      platform: client.platform || null,
+      threadId: client.threadId || null,
+      clientSource: client.source || null,
+    };
+  }
+  const leftoverEnd = metrics.pending && metrics.pending.startedAt;
+  attachLeftoverSources(metrics, lastNonArchiverSession(metrics.sessions), leftoverEnd, {
+    exclusiveEnd: true,
+  });
+  metrics.updatedAt = nowIso;
+  recomputeMetricsAggregates(metrics);
+  saveMetricsFile(filePath, metrics);
+}
+
 function formatMetricsDuration(durationMs) {
   if (durationMs == null || !Number.isFinite(durationMs)) return '—';
   const totalSeconds = Math.max(0, Math.round(durationMs / 1000));
@@ -3691,7 +3870,13 @@ program
       }
     }
 
-    // Move change into the dated archive
+    const archiveClient = resolveRestoreClient({
+      env: process.env,
+      cwd: projectDir,
+      homedir: process.env.HOME,
+      platform: opts.platform,
+    });
+    metricsPrepareArchiveStart(changeRoot, name, archiveClient);
     mkdirSync(dirname(targetDir), { recursive: true });
     renameSync(changeRoot, targetDir);
 
@@ -4262,4 +4447,4 @@ if (isDirectCliRun()) {
   program.parse();
 }
 
-export { formatMetricsCostLine, resolveSessionSpend };
+export { formatMetricsCostLine, resolveSessionSpend, canonicalRole, phaseForRole };

package/bin/session-client.js

@@ -146,7 +146,7 @@ export function detectSessionClient(options = {}) {
   }
 
   if (envFlagOn(env.CURSOR_AGENT) || trim(env.CURSOR_CONVERSATION_ID)) {
-    return { platform: 'cursor', threadId: null, source: 'cursor-env' };
+    return { platform: 'cursor', threadId: trim(env.CURSOR_CONVERSATION_ID) || null, source: 'cursor-env' };
   }
   if (envFlagOn(env.CLAUDECODE) || envFlagOn(env.CLAUDE_CODE) || trim(env.CLAUDE_CODE_ENTRYPOINT)) {
     return { platform: 'claude', threadId: null, source: 'claude-env' };