agent-orchestrator-kit 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-08-31
+
+### Added
+- **Locked session client** — `handoff --restore` detects `cursor` / `claude` / `amp` (env, Amp parent process, or recent `session.json` tty mapping) and stores `pending.platform` + `pending.threadId`. Persist follows that client: Amp runs `amp threads export` plus local thread JSON; Cursor reads the spend hook; Claude reads `~/.claude/projects`. `--platform` / `AOK_PLATFORM` / `## Metrics` still override.
+- **Amp CLI export adapter** (`amp-cli`) — when the locked client is Amp (or `--collect`), the kit calls `amp threads export <id>` (override `AOK_AMP_BIN`). Fail-open if Amp CLI is missing. `agentMode` (`low`/`medium`) is never stored as `session.model`.
+- **Amp web / pipe restore** — if the parent process is `amp` and stdin is `/dev/null` (no pts), the kit takes the newest id from `amp threads list` instead of stale `session.json` `lastThreadId`.
+
+### Changed
+- Persist without `--collect` now collects **only the locked/resolved client**, not all three adapters. `--collect` still runs every adapter.
+
+## [0.7.0] - 2026-08-30
+
+### Breaking
+- **`--no-collect` removed** — persist and archive no longer collect local spend adapters by default. Pass `--collect` to run Claude JSONL, Amp thread, and Cursor hook adapters. Scripts that still pass `--no-collect` fail as an unknown option.
+
+### Added
+- **`## Metrics` in `handoff.md`** — Session Exit self-report (`platform`, `model`, `input_tokens`, `output_tokens`, `cost_usd`, `amp_credits`, `spend_source`). Persist and archive resolve spend from flags → self-report → optional `--collect` sources. The section stays the agent's declaration; `metrics.json` is the source of truth.
+- **`session.spendSource`** and **`session.ampCredits`** — origin of the numbers (`self-report` / `flag` / `adapter` / `unreported`, or a custom `spend_source`) and Amp credits kept out of USD totals.
+- **Archive summary** — after finalize, `archive` prints the same human tables as `metrics <name>` (by phase / platform / model, unreported count).
+
+### Changed
+- **Resolve chains** — `model`: `--model` → `## Metrics` → `AOK_MODEL` → sources (with `--collect`) → `null`. `platform`: `--platform` → `## Metrics` → `AOK_PLATFORM` → host env → sources.
+- **Cursor spend hook** — still installed by `init` / `update` / `sync` / `mcp-setup`; persist, restore, and `metrics` no longer self-heal `.cursor/hooks.json`.
+- **`spendByPlatform` / `spendByModel`** — include session-level self-report; matching `sources` are counted once; buckets without adapters keep `source: "none"`.
+
+### Fixed
+- **Spend collect window** — persist no longer starts the collect window at `pending.startedAt`. Window is `[last session.endedAt || createdAt, endedAt]`.
+- **Amp collect without trees** — a thread is no longer skipped solely because `env.initial.trees` is missing; cwd fields, `AMP_CURRENT_THREAD` / `AMP_THREAD_ID`, or an exact cwd mention still match.
+- **Amp leftover after persist/archive** — persist and archive run the same last-session backfill as `metrics --collect`.
+
 ## [0.6.0] - 2026-08-29
 
 ### Added
@@ -211,6 +241,8 @@ All notable changes to this project will be documented in this file.
 ### Added
 - Initial release: 5-role orchestration pipeline, `/opsx:*` commands, IDE sync
 
+[0.8.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.7.0...v0.8.0
+[0.7.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.3.0...v0.4.0

package/README.md

@@ -74,7 +74,7 @@ npx agent-orchestrator-kit@latest init --profile generic --ci gitlab --spec-veri
 
 See [Installation](#installation) for profile/CI options.
 
-**🔄 Already have the kit installed? Upgrade to latest (auto-collect spend + Cursor hook in v0.6.0+, change metrics in v0.5.0+, factory phases 1–3 in v0.4.0+, lean pipeline / archive CLI in v0.3.0+, handoff CLI in v0.1.14+, Figma PAT in v0.1.11+):**
+**🔄 Already have the kit installed? Upgrade to latest (locked Amp/Cursor client + `amp threads export` in v0.8.0; `## Metrics` self-report + opt-in `--collect` in v0.7.0 — **BREAKING:** `--no-collect` is gone; change metrics in v0.5.0+, factory phases 1–3 in v0.4.0+, lean pipeline / archive CLI in v0.3.0+, handoff CLI in v0.1.14+, Figma PAT in v0.1.11+):**
 
 ```bash
 npx agent-orchestrator-kit@latest update
@@ -597,10 +597,10 @@ After PR merged + CI green:
 Archive is a **deterministic CLI**, not an agent workflow:
 
 ```bash
-npx agent-orchestrator-kit archive <name> [--sync | --no-sync --force]
+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`) and updating memory. 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, 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.
 
 ## Configuration
 
@@ -801,22 +801,39 @@ 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.
 
-- **`session.model`** — LLM product id. Primary from collected sources, otherwise `--model` → `AOK_MODEL` → `null` (stderr warning). Never a Closed role.
+- **`## 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 persist/archive auto-collect local usage from Claude JSONL, Amp threads, and the Cursor spend hook file (.agents/spend/cursor-usage.jsonl). `--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, and runs collect unless `--no-collect`.
-- **Platform** — optional `--platform` / `AOK_PLATFORM` (`cursor|claude|amp` only). Invalid `--platform` fails before persist/move.
-- **Cursor spend hook (mandatory)** — Cursor never writes token usage to disk, so the kit installs `scripts/cursor-spend-hook.cjs` plus a `.cursor/hooks.json` entry (`stop` + `subagentStop`) in every project: the hook appends each turn's `input_tokens` / `output_tokens` / model from the hook payload to gitignored `.agents/spend/cursor-usage.jsonl`, and collect reads it (`source: "cursor-hook"`). Installed by `init` / `update` / `sync` / `mcp-setup` and self-healed on every `handoff` restore/persist — no manual step, no flags. Restart Cursor once after the first install. `status` shows a `Spend capture` section. Claude (`~/.claude/projects/*.jsonl`) and Amp (`~/.local/share/amp/threads/*.json`) already persist usage locally and need no hook.
+- **Session end** — `handoff <name>` closes the pending session: duration, closed role, mapped phase (`explore` / `design` / `spec` / `review` / `apply` / `archive`), runtime (local/cloud), tasks snapshot (`n/m`), and spend from flags → self-report → optional `--collect` adapters. `--input-tokens` / `--output-tokens` / `--total-tokens` / `--cost-usd` override session totals only and do not wipe `spendByPlatform` / `spendByModel`. Never guess. Never invent USD from Amp credits. Never Cursor SDK / npm sqlite / a pricing table. No restore marker? Pass `--started-at <iso>` or the duration stays honestly `null`.
+- **Archive** — successful `archive <name>` always creates or finalizes `metrics.json`, sets `archivedAt`, appends an Archiver session from the archived `## Metrics` (or archive flags), prints the same human summary as `metrics <name>`, and collects adapters only with `--collect`.
+- **Platform** — `--platform` → `## Metrics: platform` → `AOK_PLATFORM` → **pending client from `--restore`** → host env (Amp / Cursor / Claude Code) → collected sources (`cursor|claude|amp` only). Invalid `--platform` fails before persist/move.
+- **Locked client** — `--restore` records `pending.platform` and Amp `pending.threadId` before phase work. Persist follows that client’s flow even if persist runs in another shell (no `AMP_*` / `CURSOR_*`). Amp: `amp threads export` (`AOK_AMP_BIN`) plus local `threads/*.json`. If Amp runs tools over a pipe (`/dev/null`), thread id comes from `amp threads list`, not stale `session.json` `lastThreadId`. Cursor: spend hook file. Claude: `~/.claude/projects`. `--collect` still runs all three adapters.
+- **Cursor spend hook (optional)** — Cursor never writes token usage to disk, so the kit can install `scripts/cursor-spend-hook.cjs` plus `.cursor/hooks.json` entries (`stop` / `subagentStop` / `afterAgentResponse`) in `init` / `update` / `sync` / `mcp-setup`: the hook appends each turn's tokens to gitignored `.agents/spend/cursor-usage.jsonl`. Persist auto-reads that file when the locked client is Cursor. Persist and restore do not self-heal the hook. `sessionEnd` still runs `scripts/cursor-spend-collect.cjs`. Restart Cursor once after the first install. `status` shows a `Spend capture` section. Claude JSONL and Amp disk threads remain fallbacks; Amp web/CLI spend is taken from `amp threads export`.
 
 Aggregates are recomputed on every write: per-phase totals (`durationMs`, tokens, `costUsd`, `sessions`, `roles`, `models`) plus overall `totals` (`sessions`, `cloudSessions`, `durationMs` = sum of session work time, `leadTimeMs` = wall clock from first session start to last session end), `spend` (USD only), and separate **by platform** / **by model** tables. Numbers are null-honest: a metric nobody reported stays `null`, never a fake `0`. No single total that adds Amp credits to USD.
 
+Fill `## Metrics` in `handoff.md` **before** persist (unknown is fine; do not invent `0`):
+
+```markdown
+## Metrics
+- platform: cursor
+- model: cursor-grok-4.6
+- input_tokens: 128000
+- output_tokens: 9400
+- cost_usd: unknown
+- amp_credits: unknown
+- spend_source: self-report
+```
+
 ```bash
-npx agent-orchestrator-kit handoff add-thing --input-tokens 12000 --output-tokens 3000 --cost-usd 0.42 --model claude-sonnet
-npx agent-orchestrator-kit metrics add-thing          # human summary: phases, tokens, cost, roles / models
-npx agent-orchestrator-kit metrics add-thing --json   # raw metrics.json (works for archived changes too)
+npx agent-orchestrator-kit handoff add-thing
+npx agent-orchestrator-kit handoff add-thing --collect   # optional: Claude JSONL / Amp threads / Cursor hook
+npx agent-orchestrator-kit metrics add-thing             # human summary: phases, tokens, cost, roles / models
+npx agent-orchestrator-kit metrics add-thing --json      # raw metrics.json (works for archived changes too)
+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`. `--no-collect` skips adapters only.
+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.
 
 ### Skill inventory
 
@@ -915,9 +932,10 @@ npx agent-orchestrator-kit hooks-setup
 npx agent-orchestrator-kit mcp-setup [--vcs github|gitlab] [--no-browser]
   Install GitHub/GitLab (from origin) and browser MCP launchers
 
-npx agent-orchestrator-kit archive <name> [--sync | --no-sync --force]
+npx agent-orchestrator-kit archive <name> [--sync | --no-sync --force] [--collect]
   Gate-check a completed change, optionally merge delta specs, move to
-  openspec/changes/archive/YYYY-MM-DD-<name>, validate, write final handoff
+  openspec/changes/archive/YYYY-MM-DD-<name>, validate, write final handoff,
+  and print the change-wide metrics summary. --collect also runs adapters.
 
 npx agent-orchestrator-kit handoff [change-name] [options]
   --restore          Print the restore briefing instead of persisting
@@ -927,15 +945,18 @@ npx agent-orchestrator-kit handoff [change-name] [options]
   --cloud-check      Verify change artifacts are committed and pushed
                      (cloud: non-zero on failure; local: warning, exit 0)
   --started-at <iso> Session start override when --restore was not run
-  --model <name>     Model used in this session (metrics.json)
+  --model <name>     LLM product id (metrics.json); never a Closed role
+  --platform <id>    cursor | claude | amp
   --input-tokens <n> / --output-tokens <n> / --total-tokens <n>
                      Token spend for this session (total defaults to in+out)
   --cost-usd <usd>   Session cost in USD
+  --collect          Also run local spend adapters (off by default)
   --no-metrics       Skip recording this session into metrics.json
 
-npx agent-orchestrator-kit metrics [change-name] [--json]
+npx agent-orchestrator-kit metrics [change-name] [--json] [--collect]
   Show recorded session metrics for a change (active or archived):
-  time per phase, sessions, tokens, cost, roles, models, lead time
+  time per phase, sessions, tokens, cost, roles, models, lead time.
+  --collect backfills the last session from adapters without adding a session.
 ```
 
 ## Directory Reference
@@ -982,8 +1003,14 @@ Phase bounds and non-goals: [`openspec/specs/agentic-factory-roadmap/spec.md`](o
 
 ## Changelog
 
+### 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`
+- Archive prints the same human summary as `metrics <name>` (by phase / platform / model, `spendSource`, unreported count)
+- Cursor spend hook is optional setup (`init` / `update` / `sync` / `mcp-setup`); persist and restore no longer self-heal `.cursor/hooks.json`
+
 ### 0.6.0
-- **Mandatory Cursor spend hook** — `scripts/cursor-spend-hook.cjs` + `.cursor/hooks.json` (`stop` / `subagentStop`) write `.agents/spend/cursor-usage.jsonl`; installed by `init` / `update` / `sync` / `mcp-setup` and self-healed on `handoff`
+- **Mandatory Cursor spend hook** — `scripts/cursor-spend-hook.cjs` + `.cursor/hooks.json` (`stop` / `subagentStop` / `afterAgentResponse`) write `.agents/spend/cursor-usage.jsonl`; `sessionEnd` + `metrics --collect` backfill the last session; installed by `init` / `update` / `sync` / `mcp-setup` and self-healed on `handoff`
 - Persist/archive auto-collect local usage from Claude JSONL, Amp threads, and the Cursor hook file into `spendByPlatform` / `spendByModel`
 - Amp source ids namespaced as `<threadId>:<messageId>` so thread-local counters do not collide
 - `status` prints a `Spend capture` section