pan-wizard 3.28.0 → 3.29.0

package/commands/pan/cost.md

@@ -2,7 +2,7 @@
 name: pan:cost
 group: Observability
 description: Show token usage and estimated cost across PAN commands and agents
-argument-hint: "[report|append|clear] [--format json|table|chart] [--since YYYY-MM-DD] [--until YYYY-MM-DD]"
+argument-hint: "[report|append|clear|rebuild] [--format json|table|chart] [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--apply] [--no-main-thread]"
 allowed-tools:
   - Read
   - Bash
@@ -45,7 +45,10 @@ pan-tools cost report [--format json|table|chart] [--since YYYY-MM-DD] [--until
     "cache_read_tokens": 50000,
     "cache_write_tokens": 5000,
     "cost_usd": 2.1234,
-    "cost_unknown": 0
+    "cost_unknown": 0,
+    "suspect_excluded": 0,
+    "empty_excluded": 0,
+    "malformed_skipped": 0
   },
   "cache_hit_rate_pct": 40.5,
   "by_agent": { "pan-planner": { "calls": 8, "input": 50000, ... } },
@@ -78,6 +81,15 @@ Delete the cost log. Useful at the start of a billing cycle.
 pan-tools cost clear
 ```
 
+### `rebuild`
+
+Rebuild the ledger from Claude Code's own transcripts (session file plus the per-agent files under `<session>/subagents/`, Workflow-tool subagents one level down). Rows written by hooks before v3.29 booked a slice of the parent session to whichever subagent stopped and counted turns once per content block; the rebuild replaces them with one exact row per agent transcript, typed from the main thread's `Agent` calls, plus one row per session for the main thread's own usage (`--no-main-thread` omits it). Rows whose session transcript is gone, and caller-appended rows, are kept. Dry-run by default — show the user the per-session before → after (and any `warnings`), then apply only on their say-so; the previous ledger is kept beside the new one as `tokens.jsonl.rebuilt-<date>` (a later copy never overwrites an earlier one). Run it **before** `/pan:hygiene --apply` on a poisoned ledger: quarantine moves the whole file aside, and a rebuild afterwards has no rows left to keep. The main-thread row is dated to the session's last record, so `--since`/`--until` windows and the per-day view see a session's own usage on its final day.
+
+```
+pan-tools cost rebuild              # dry run
+pan-tools cost rebuild --apply      # write the rebuilt ledger
+```
+
 </subcommands>
 
 <rate_table>

package/hooks/dist/pan-check-update.js

@@ -113,6 +113,10 @@ function defaultFetchLatest() {
     encoding: 'utf8',
     timeout: 10000,
     windowsHide: true,
+    // Own the silence here rather than relying on the caller's stdio: 'ignore'. npm
+    // writes registry and PATH failures to stderr, and a hook that lets them through
+    // puts its own diagnostics in front of the user mid-session.
+    stdio: ['ignore', 'pipe', 'ignore'],
   }).trim();
 }
 

package/hooks/dist/pan-cost-logger.js

@@ -7,9 +7,11 @@
 //
 // We append a minimal record to .planning/metrics/tokens.jsonl so
 // `/pan:cost` reports reflect real agent spawns, not just manually-appended
-// entries. Token counts are best-effort: if the hook input doesn't carry
-// them, we log a record with zeros + a `source: "hook"` flag so the
-// aggregator distinguishes these from fully-instrumented records.
+// entries. Token counts come from the subagent's OWN transcript when the host
+// names one (`agent_id` → `<session>/subagents/agent-<id>.jsonl`, see
+// resolveAgentTranscript), else from a slice of the parent session transcript,
+// else from the payload's plausibility-guarded counters. A `source: "hook"`
+// flag distinguishes these rows from fully-instrumented records.
 //
 // This hook NEVER blocks the main agent loop — all errors are swallowed.
 
@@ -18,7 +20,13 @@ const path = require('path');
 const crypto = require('crypto');
 
 // Runtime config dirs a local PAN install lands in (mirrors installer getDirName).
-const PAN_RUNTIME_DIRS = ['.claude', '.codex', '.gemini', '.opencode', '.github'];
+// Every runtime PAN installs into, by config-directory name. Built from the runtime
+// names rather than written as literals on purpose: the installer templates a hook by
+// rewriting the string `'.claude'`, including a catch-all for unanchored occurrences,
+// which rewrote this list too — a Codex install shipped `.codex` twice and no `.claude`
+// at all, so this predicate stopped recognising a Claude-only project (2026-09-17).
+// This list is runtime-AGNOSTIC and must survive the install byte for byte.
+const PAN_RUNTIME_DIRS = ['claude', 'codex', 'gemini', 'opencode', 'github'].map((r) => `.${r}`);
 
 /**
  * Which planning tree this hook writes to.
@@ -73,18 +81,36 @@ function isPanProject(cwd) {
   }
 }
 
+
+// Telemetry FILLS a planning tree; it never brings one into existence. isPanProject
+// above also accepts a bare install marker, which is right for "is PAN here" but wrong
+// as a licence to write: a global-install hook fires in every repo the user opens, and
+// scaffolding `.planning/` on the marker alone made repos that had merely installed PAN
+// look like half-built projects to `validate health` and `hygiene scan` — five of the
+// fourteen field projects swept on 2026-09-17 had a planning tree no /pan command ever
+// created. Before the first /pan command there is no project to attribute a run to, so
+// the honest record is no record. Best-effort — never throws.
+function hasPlanningTree(cwd) {
+  try {
+    return !!cwd && fs.existsSync(planningPath(cwd));
+  } catch {
+    return false;
+  }
+}
+
 const METRICS_DIR = 'metrics';
 const TOKENS_FILE = 'tokens.jsonl';
 const CURSOR_FILE = '.cost-cursor.json';
 
 // Ledger row schema version. Bump when the record shape changes so readers can
 // tell which shape a row was written in (pre-versioned rows read as v1); v3 added
-// the per-invocation `event_sig` discriminator. Kept as a literal in each hook —
+// the per-invocation `event_sig` discriminator; v4 added `agent_id` and the
+// `agent-transcript` token source. Kept as a literal in each hook —
 // they are standalone zero-dep scripts that can't import from pan-wizard-core, so
 // the two hooks must stay in sync by hand. No constant in pan-wizard-core mirrors
 // it: the readers there take a row field by field rather than switching on its
 // version, so an added field is additive for them.
-const SCHEMA_V = 3;
+const SCHEMA_V = 4;
 
 // Reverse-map a resolved model id to its cost tier so the "By tier" dashboard
 // section isn't blind on the hook path. Anthropic families only (the tiers PAN
@@ -97,6 +123,37 @@ function tierForModel(model) {
   return null;
 }
 
+// How long a `current-session` pointer is evidence of a live session. An explicit
+// (non-auto) session used to stay "current" indefinitely: a field project still pointed
+// at a session started on 17 July when it was swept on 17 September, so every ledger row
+// since had inherited that session's command and phase. Mirrors SESSION_STALE_MS in
+// optimize.cjs — the hooks cannot import it.
+const SESSION_STALE_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Last write to a session — its event log, else the moment it started, else null.
+ * Best-effort; never throws.
+ */
+function sessionLastActivityMs(dir) {
+  try {
+    return fs.statSync(path.join(dir, 'trace.jsonl')).mtimeMs;
+  } catch { /* no events yet */ }
+  try {
+    const meta = JSON.parse(fs.readFileSync(path.join(dir, 'session.json'), 'utf-8'));
+    const t = new Date(meta.started_at).getTime();
+    return Number.isFinite(t) ? t : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Finished, or too old to be the session running now. */
+function isSessionStale(dir, meta, now = Date.now()) {
+  if (meta && meta.ended_at) return true;
+  const last = sessionLastActivityMs(dir);
+  return last === null || now - last > SESSION_STALE_MS;
+}
+
 // Best-effort read of the active trace session's command/phase so hook rows can
 // be attributed to the command that spawned them. current-session →
 // traces/<sid>/session.json (both written by the trace logger / optimize.cjs).
@@ -106,13 +163,94 @@ function readActiveSessionMeta(cwd) {
     const optDir = planningPath(cwd, 'optimization');
     const sid = fs.readFileSync(path.join(optDir, 'current-session'), 'utf-8').trim();
     if (!sid) return {};
-    const meta = JSON.parse(fs.readFileSync(path.join(optDir, 'traces', sid, 'session.json'), 'utf-8'));
-    return meta && typeof meta === 'object' ? meta : {};
+    const dir = path.join(optDir, 'traces', sid);
+    const meta = JSON.parse(fs.readFileSync(path.join(dir, 'session.json'), 'utf-8'));
+    if (!meta || typeof meta !== 'object') return {};
+    // A pointer at a finished or long-dead session describes nothing that is running
+    // now; its command/phase must not be copied onto this row.
+    if (isSessionStale(dir, meta)) return {};
+    return meta;
   } catch {
     return {};
   }
 }
 
+
+// How much of a session transcript's tail to read when looking for the command that
+// spawned this agent. A long session file runs to hundreds of megabytes, and the answer
+// is always in the most recent turns, so the read is bounded.
+const COMMAND_TAIL_BYTES = 262144;
+
+// PAN's own command namespace, as a runtime writes it: `/pan:exec-phase` (Claude Code,
+// Gemini) or `/pan-exec-phase` (Codex, OpenCode, Copilot). Only these spawn PAN agents,
+// so only these are attributed — a host UI command (`/model`, `/compact`) and a plain
+// typed prompt leave the row honestly unattributed instead of borrowing a name.
+const PAN_COMMAND_RE = /<command-name>\s*\/?pan[:-]([a-z0-9][a-z0-9-]*)\s*<\/command-name>/i;
+
+/**
+ * The PAN command in whose turn this agent ran, read from the PARENT session transcript.
+ *
+ * `command` used to come only from the optimizer's trace session, and tracing is off by
+ * default, so outside focus mode every field row carried `command: null` and "which
+ * command got expensive" was unanswerable from PAN's own telemetry (field sweep
+ * 2026-09-17, 976 rows). A runtime records a slash-command invocation as a TYPED user
+ * turn carrying `<command-name>`, so the tail's most recent such turn names this work.
+ *
+ * Only typed user turns count. A tool_result record is the host replying to a tool call,
+ * and its payload may quote a command tag verbatim — a transcript that had grepped another
+ * project's history reported that project's command as its own until this was record-scoped
+ * rather than text-scoped. Turns without a command (plain prose, an injected reminder) are
+ * skipped rather than treated as clearing the attribution, so a mid-run "continue" does not
+ * erase it.
+ *
+ * This is attribution by recency, not by proof: an agent spawned from a plain prompt long
+ * after a PAN command still reads as that command while it remains in the window. Scoping
+ * the match to PAN's namespace is what keeps that bounded — a session that has run no PAN
+ * command reports null rather than naming whatever the user last typed.
+ *
+ * Returns the bare command name (`/pan:exec-phase` → `exec-phase`) or null. Never throws.
+ */
+function readCommandFromTranscript(transcriptPath) {
+  try {
+    if (typeof transcriptPath !== 'string' || !transcriptPath) return null;
+    const fd = fs.openSync(transcriptPath, 'r');
+    let text;
+    let partial = false;
+    try {
+      const size = fs.fstatSync(fd).size;
+      const start = Math.max(0, size - COMMAND_TAIL_BYTES);
+      partial = start > 0;
+      const len = size - start;
+      if (len <= 0) return null;
+      const buf = Buffer.allocUnsafe(len);
+      const read = fs.readSync(fd, buf, 0, len, start);
+      text = buf.toString('utf-8', 0, read);
+    } finally {
+      fs.closeSync(fd);
+    }
+    const lines = text.split(/\r?\n/);
+    if (partial) lines.shift(); // a mid-record first line
+    for (let i = lines.length - 1; i >= 0; i--) {
+      if (!lines[i]) continue;
+      let rec;
+      try { rec = JSON.parse(lines[i]); } catch { continue; }
+      if (!rec || rec.type !== 'user' || !rec.message) continue;
+      const content = rec.message.content;
+      let typed = null;
+      if (typeof content === 'string') typed = content;
+      else if (Array.isArray(content)) {
+        if (content.some((b) => b && b.type === 'tool_result')) continue; // host reply, not a typed turn
+        typed = content.filter((b) => b && b.type === 'text' && typeof b.text === 'string').map((b) => b.text).join('\n');
+      }
+      if (!typed) continue;
+      const m = typed.match(PAN_COMMAND_RE);
+      if (m) return m[1].toLowerCase();
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
 /**
  * Current phase from state.md — the fallback when no optimizer trace is running.
  *
@@ -194,6 +332,12 @@ const LEGACY_CONSUME_KEYS = '__consumeKeys';
 // below for what widening either window was measured to cost.
 const MAX_SEEN_SIGS = 8;
 const MAX_SEEN_TRANSCRIPTS = 16;
+// Cursor path keys. With per-agent transcripts every spawn adds a key that lives
+// as long as Claude Code keeps the file (weeks), so existence-pruning alone no
+// longer bounds the map (L40). Keep the most recently written keys only; a
+// spawn's transcript is sliced once, so an evicted key costs nothing but a
+// re-sum if that agent is ever resumed weeks later.
+const MAX_CURSOR_KEYS = 512;
 
 // Signature of a SubagentStop event: a hash of the FULL payload as delivered.
 // A dual-registration re-fire is byte-identical on stdin (the host pipes the
@@ -214,13 +358,15 @@ const MAX_SEEN_TRANSCRIPTS = 16;
 //   • `model` and `phase` came out null in those recorded rows: the payload
 //     carried neither.
 //   • `usage` is absent entirely in headless mode (docs/HOOKS.md, P-1805).
-//   • No recorded payload in this repo carries an `agent_id` or any other
-//     per-invocation id. `grep -rn agent_id hooks/ pan-wizard-core/ tests/`
-//     finds only PAN's own agent-tracking artifacts (written by workflows) and
-//     the hook tests, which inject one as a stand-in.
-// So for two CONCURRENT SAME-TYPE siblings no varying payload field is
-// confirmed on any host. Where the host supplies one, both spawns are admitted;
-// where it supplies none the two payloads are the same bytes, hence
+//   • Claude Code's hook reference documents `agent_id` as a common input field
+//     "present only when the hook fires inside a subagent call", and the
+//     matching per-agent transcript files exist on disk beside the session
+//     transcript (resolveAgentTranscript). Where it is present, the slice comes
+//     from the agent's own transcript and two concurrent same-type siblings are
+//     separable by that field alone.
+// So on a host that omits `agent_id`, two CONCURRENT SAME-TYPE siblings have no
+// confirmed varying payload field. Where the host supplies one, both spawns are
+// admitted; where it supplies none the two payloads are the same bytes, hence
 // informationally indistinguishable from a re-fire, and the second stays
 // suppressed.
 //
@@ -301,10 +447,10 @@ function writeCursor(cwd, cursor) {
     // Prune cursor keys for transcripts that no longer exist so the map can't
     // grow without bound over a long-lived project (L40, ADR audit 2026-08).
     const pruned = {};
-    for (const [tp, v] of Object.entries(cursor)) {
-      if (tp === SEEN_EVENTS || tp === LEGACY_CONSUME_KEYS) continue; // reserved markers — not paths
-      if (tp && fs.existsSync(tp)) pruned[tp] = v;
-    }
+    const live = Object.entries(cursor).filter(([tp]) => tp !== SEEN_EVENTS && tp !== LEGACY_CONSUME_KEYS && tp && fs.existsSync(tp));
+    // Insertion order is write order (a key is re-inserted when advanced), so
+    // the tail of the list is the most recently sliced transcripts.
+    for (const [tp, v] of live.slice(-MAX_CURSOR_KEYS)) pruned[tp] = v;
     // Preserve the seen-event marker (N17/N25-N27). Deliberately NOT pruned by
     // transcript existence — a missing-transcript first fire's marker must
     // survive this very write, or its re-fire is re-admitted as a phantom row
@@ -324,6 +470,73 @@ function writeCursor(cwd, cursor) {
   } catch { /* best-effort — never block the agent loop */ }
 }
 
+// ─── Per-agent transcript resolution ────────────────────────────────────────
+//
+// On SubagentStop Claude Code hands the hook the PARENT session's transcript
+// (`transcript_path`) plus the subagent's `agent_id`; the subagent's own
+// conversation is written beside the parent transcript as
+// `<parent dir>/<session_id>/subagents/agent-<agent_id>.jsonl`. Slicing the
+// parent transcript per event booked whatever the session had done since the
+// previous stop to whichever subagent happened to stop next — and the FIRST stop
+// on a long-lived session (cursor 0, or a cursor a ledger quarantine had reset)
+// booked the session's entire history to one row: 7.5 billion cache-read tokens
+// over a ten-day "duration" was observed in the field (2026-09). Sibling stops
+// arriving before the parent transcript grew produced the complementary all-zero
+// rows — 63% of one ledger. The agent transcript is the subagent's usage and
+// nothing else, so it is preferred whenever it exists; the parent-slice path
+// remains the fallback for hosts that supply no agent id. An explicit
+// `agent_transcript_path` in the payload wins over the derivation.
+const AGENT_ID_SAFE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+function resolveAgentTranscript(data) {
+  try {
+    const explicit = data.agent_transcript_path;
+    if (typeof explicit === 'string' && explicit && fs.existsSync(explicit)) return explicit;
+    const agentId = data.agent_id;
+    if (typeof agentId !== 'string' || !AGENT_ID_SAFE.test(agentId)) return null;
+    if (typeof data.transcript_path !== 'string' || !data.transcript_path) return null;
+    if (typeof data.session_id !== 'string' || !AGENT_ID_SAFE.test(data.session_id)) return null;
+    const base = path.dirname(data.transcript_path);
+    const subagentsDir = path.join(base, data.session_id, 'subagents');
+    // Containment: every derived path must stay under the parent transcript's directory.
+    const resolvedBase = path.resolve(base);
+    const contained = (p) => path.resolve(p).startsWith(resolvedBase + path.sep);
+    const direct = path.join(subagentsDir, `agent-${agentId}.jsonl`);
+    if (contained(direct) && fs.existsSync(direct)) return direct;
+    // Subagents spawned by the Workflow tool (the native `/pan-*` workflow
+    // scripts) are written one level down, under the run that spawned them:
+    // `subagents/workflows/<wf_id>/agent-<agent_id>.jsonl`. In the field those
+    // were the majority of spawns (269 of 331 rows in one ledger), so missing
+    // this level would have recorded them as unmeasured.
+    const workflowsDir = path.join(subagentsDir, 'workflows');
+    let runs = [];
+    try { runs = fs.readdirSync(workflowsDir); } catch { return null; }
+    for (const run of runs) {
+      const nested = path.join(workflowsDir, run, `agent-${agentId}.jsonl`);
+      if (contained(nested) && fs.existsSync(nested)) return nested;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// A slice is a SUM over one subagent's conversation, so its ceiling sits above a
+// single call's (PLAUSIBLE_MAX): a long agent legitimately re-reads its cached
+// context on every turn. The cache_read and output ceilings are the absolute
+// limits cost.cjs isSuspectRecord quarantines on; input and cache_write are
+// hook-only sanity ceilings (the reader has no rule for them). A value past its
+// ceiling is a session's cumulative usage that leaked into the slice, never one
+// subagent's own — drop it to 0 and flag the row. The parent-slice path had NO
+// guard before v3.29: every oversum row in the field carried `clamped: false`.
+// The slice's SPAN is not clamped: it is recorded as measured, and the reader's
+// six-hour rule (cost.cjs SUSPECT_MAX_DURATION_MS) quarantines a slice that ran
+// longer. Nulling the span here instead would hand the row to the reader's
+// untimed cache-ratio rule and lose a legitimate long agent with it.
+const SLICE_MAX = { input: 2e7, output: 1e7, cache_read: 5e8, cache_write: 1e8 };
+function clampSlice(n, max) {
+  return typeof n === 'number' && n >= 0 && n <= max ? n : 0;
+}
+
 /**
  * Extract what we can from the SubagentStop event payload.
  * Pure function — safe to test without stdin.
@@ -352,10 +565,27 @@ function buildCostRecord(data, cwd) {
   let cacheRead = 0;
   let cacheWrite = 0;
   let durationMs = null;
-  // token_source records WHICH path produced the counts; clamped marks a value
-  // dropped to 0 by the plausibility guard so a guarded zero is distinguishable
-  // from a genuine zero-token run.
-  let tokenSource = data.transcript_path ? 'transcript' : 'usage-fallback';
+  // token_source records WHICH path produced the counts: `agent-transcript` (the
+  // subagent's own conversation file — see resolveAgentTranscript), `transcript`
+  // (a slice of the parent session transcript, the fallback when the host names
+  // no agent) or `usage-fallback` (the payload's own counters). `clamped` marks
+  // a value dropped to 0 by a plausibility guard so a guarded zero is
+  // distinguishable from a genuine zero-token run.
+  const agentTranscript = resolveAgentTranscript(data);
+  const parentPath = typeof data.transcript_path === 'string' && data.transcript_path ? data.transcript_path : null;
+  // The host NAMED an agent (a bare id, or an explicit agent transcript path) but
+  // its file is not there — not flushed yet, or a host that sends ids without
+  // per-agent files. The parent slice is the wrong answer for that spawn: it is
+  // the whole session since the last parent-slice stop, booked to one agent. So
+  // this event consumes nothing and records an unmeasured spawn (zeros, a
+  // distinct token_source), which the reader excludes from calls.
+  const agentNamed = (typeof data.agent_id === 'string' && AGENT_ID_SAFE.test(data.agent_id))
+    || (typeof data.agent_transcript_path === 'string' && data.agent_transcript_path !== '');
+  const agentFileMissing = !agentTranscript && agentNamed && parentPath !== null;
+  const sliceSource = agentTranscript || (agentFileMissing ? null : parentPath);
+  const tokenSource = agentTranscript ? 'agent-transcript'
+    : agentFileMissing ? 'agent-transcript-missing'
+      : sliceSource ? 'transcript' : 'usage-fallback';
   let clamped = false;
   // Set when a transcript-sourced event consumed no new records AND is an
   // identical re-fire / dual-registration. Carried on the returned record as a
@@ -363,29 +593,46 @@ function buildCostRecord(data, cwd) {
   // the ledger (M61).
   let emptySlice = false;
   const agent = data.agent_type || data.subagent_type || null;
+  const agentId = typeof data.agent_id === 'string' && data.agent_id ? data.agent_id : null;
   // This event's per-invocation identity, hashed once and used by BOTH layers:
   // the seen-event marker below and the `event_sig` row field further down.
   // buildCostRecord never mutates `data`, so hoisting the hash here yields the
   // same value the marker calls used when they each computed it themselves.
   const eventSig = eventSignature(data);
-  if (data.transcript_path) {
+  if (sliceSource || agentFileMissing) {
+    // The cursor and the seen-event marker are keyed by whichever file is being
+    // sliced: the agent transcript (one file per spawn, so a re-fire is the only
+    // way to see an empty slice) or the shared parent transcript. A named-but-
+    // missing agent file consumes nothing and is keyed by the parent, so the
+    // re-fire / sibling marker logic below applies to it unchanged.
+    const keyPath = sliceSource || parentPath;
     const cursor = readCursor(cwd);
-    const since = cursor[data.transcript_path] || 0;
-    const fromTranscript = readUsageFromTranscript(data.transcript_path, data.session_id, since);
-    inputTokens = fromTranscript.input_tokens;
-    outputTokens = fromTranscript.output_tokens;
-    cacheRead = fromTranscript.cache_read_input_tokens;
-    cacheWrite = fromTranscript.cache_creation_input_tokens;
-    durationMs = durationFromSpan(fromTranscript.first_ts, fromTranscript.last_ts);
+    const since = cursor[keyPath] || 0;
+    const fromTranscript = sliceSource
+      ? readUsageFromTranscript(sliceSource, data.session_id, since)
+      : { input_tokens: 0, output_tokens: 0, cache_read_input_tokens: 0, cache_creation_input_tokens: 0, model: null, first_ts: null, last_ts: null, lineCount: since };
+    const rawIn = fromTranscript.input_tokens;
+    const rawOut = fromTranscript.output_tokens;
+    const rawCr = fromTranscript.cache_read_input_tokens;
+    const rawCw = fromTranscript.cache_creation_input_tokens;
+    inputTokens = clampSlice(rawIn, SLICE_MAX.input);
+    outputTokens = clampSlice(rawOut, SLICE_MAX.output);
+    cacheRead = clampSlice(rawCr, SLICE_MAX.cache_read);
+    cacheWrite = clampSlice(rawCw, SLICE_MAX.cache_write);
+    clamped = rawIn > SLICE_MAX.input || rawOut > SLICE_MAX.output
+      || rawCr > SLICE_MAX.cache_read || rawCw > SLICE_MAX.cache_write;
+    durationMs = durationFromSpan(fromTranscript.first_ts, fromTranscript.last_ts); // as measured — see SLICE_MAX
     if (!model) model = fromTranscript.model;
     if (fromTranscript.lineCount > since) {
       // A real slice. Advance the cursor so the next subagent's record starts
       // fresh — the slices partition the transcript, so it is never re-summed on
       // every event. Remember this event's signature (N17/N25) so a later
       // empty-slice event can tell its re-fire from a parallel sibling — even
-      // when other siblings are recorded in between (N25).
-      cursor[data.transcript_path] = fromTranscript.lineCount;
-      addSeenSig(cursor, data.transcript_path, eventSig);
+      // when other siblings are recorded in between (N25). Re-insert the key so
+      // insertion order tracks write order (writeCursor keeps the newest keys).
+      delete cursor[keyPath];
+      cursor[keyPath] = fromTranscript.lineCount;
+      addSeenSig(cursor, keyPath, eventSig);
       writeCursor(cwd, cursor);
     } else {
       // No transcript records past the cursor: this event consumed NO slice of
@@ -406,12 +653,13 @@ function buildCostRecord(data, cwd) {
       // The full-payload signature distinguishes them (N25/N26): DROP only when
       // this exact payload was already seen for this transcript (true re-fire);
       // otherwise record the spawn.
-      if (eventSig && getSeenSigs(cursor, data.transcript_path).includes(eventSig)) {
+      if (eventSig && getSeenSigs(cursor, keyPath).includes(eventSig)) {
         emptySlice = true; // already-seen event → re-fire; appendRecord drops the phantom row (M61)
       } else {
-        // Sibling / first-fire: record the spawn (zero tokens) and remember its
-        // signature so a subsequent re-fire of THIS event is dropped.
-        addSeenSig(cursor, data.transcript_path, eventSig);
+        // Sibling / first-fire / named-but-missing agent file: record the spawn
+        // (zero tokens) and remember its signature so a subsequent re-fire of
+        // THIS event is dropped.
+        addSeenSig(cursor, keyPath, eventSig);
         writeCursor(cwd, cursor);
       }
     }
@@ -433,7 +681,10 @@ function buildCostRecord(data, cwd) {
   // Backfill command/phase from the active trace session when the payload omits
   // them (real SubagentStop payloads carry neither); tier is derived from the model.
   const sessionMeta = readActiveSessionMeta(cwd);
-  const command = data.command || sessionMeta.command || null;
+  // The trace session only exists while the optimizer runs, so the parent transcript is
+  // the fallback that makes command attribution work outside focus mode — see
+  // readCommandFromTranscript.
+  const command = data.command || sessionMeta.command || readCommandFromTranscript(data.transcript_path) || null;
   // The trace session is only present while the optimizer is running (off by
   // default), so state.md is the fallback that makes phase attribution work in
   // ordinary use instead of only under tracing.
@@ -443,6 +694,10 @@ function buildCostRecord(data, cwd) {
     v: SCHEMA_V,
     ts: new Date().toISOString(),
     agent,
+    // The host's per-spawn id (null where the host supplies none). What made
+    // the agent's own transcript addressable; persisted so a reader can tell
+    // two same-type siblings apart without hashing the payload.
+    agent_id: agentId,
     command,
     model,
     tier: tierForModel(model),
@@ -527,13 +782,30 @@ function readUsageFromTranscript(transcriptPath, sessionId, sinceLine = 0) {
   let raw;
   try { raw = fs.readFileSync(transcriptPath, 'utf-8'); } catch { return totals; }
   let seen = 0; // count of non-empty JSONL records (the cursor unit)
+  // One API turn, one usage. Claude Code writes an assistant turn as one JSONL
+  // record PER CONTENT BLOCK (text, tool_use, …), each carrying that turn's
+  // `message.id` and a usage snapshot; the last block's snapshot holds the
+  // turn's final counts. Summing every record therefore counted a three-block
+  // turn three times — a real 65-turn agent transcript summed to 14.8M
+  // cache-read tokens against 8.5M actual (2026-09). Keyed by `message.id`,
+  // last snapshot wins; records with no id (older transcripts, other hosts)
+  // are summed as they come.
+  const byMessage = new Map();
+  let unkeyed = 0;
   for (const line of raw.split('\n')) {
     if (!line) continue;
     seen++;
     if (seen <= sinceLine) continue; // already attributed to an earlier event
     let entry;
     try { entry = JSON.parse(line); } catch { continue; }
-    if (sessionId && entry.session_id && entry.session_id !== sessionId) continue;
+    // Claude Code names this field `sessionId`; the guard read `session_id` only, so it
+    // was inert — 199 of 200 records in a real local transcript carry the camelCase
+    // spelling and none carry the snake_case one (measured 2026-09-17). Harmless on the
+    // per-agent path, where every record in the file belongs to the one agent, but the
+    // scoping it claims to do never happened on the parent-slice fallback. Both
+    // spellings are accepted rather than one guessed at.
+    const entrySession = entry.sessionId || entry.session_id;
+    if (sessionId && entrySession && entrySession !== sessionId) continue;
     // Span of THIS subagent's slice (after the session filter) — first→last
     // record timestamp gives a measured runtime rather than an idle-gap proxy.
     const entryTs = typeof entry.timestamp === 'string' ? entry.timestamp : null;
@@ -551,6 +823,12 @@ function readUsageFromTranscript(transcriptPath, sessionId, sinceLine = 0) {
       || (entry.type === 'assistant' && entry.message?.usage)
       || null;
     if (!usage || typeof usage !== 'object') continue;
+    const messageId = entry.message && typeof entry.message.id === 'string' && entry.message.id
+      ? entry.message.id
+      : `__unkeyed_${unkeyed++}`;
+    byMessage.set(messageId, usage);
+  }
+  for (const usage of byMessage.values()) {
     totals.input_tokens += extractNumber(usage, 'input_tokens');
     totals.output_tokens += extractNumber(usage, 'output_tokens');
     totals.cache_read_input_tokens += extractNumber(usage, 'cache_read_input_tokens');
@@ -645,8 +923,9 @@ if (require.main === module) {
       // invokes the hook.
       const cwd = data.cwd || data.workspace?.current_dir || process.cwd();
       // M62: a global-install hook fires in every repo; don't pollute non-PAN
-      // projects with .planning/ metrics artifacts.
-      if (!isPanProject(cwd)) return;
+      // projects with .planning/ metrics artifacts. The tree must already exist —
+      // see hasPlanningTree (field sweep 2026-09-17).
+      if (!hasPlanningTree(cwd)) return;
       const record = buildCostRecord(data, cwd);
       appendRecord(cwd, record);
     } catch {
@@ -655,4 +934,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { buildCostRecord, appendRecord, readUsageFromTranscript, readCursor, writeCursor, isPanProject, METRICS_DIR, TOKENS_FILE, CURSOR_FILE };
+module.exports = { buildCostRecord, appendRecord, readUsageFromTranscript, resolveAgentTranscript, readCursor, writeCursor, isPanProject, hasPlanningTree, readCommandFromTranscript, isSessionStale, PAN_RUNTIME_DIRS, METRICS_DIR, TOKENS_FILE, CURSOR_FILE, SLICE_MAX, MAX_CURSOR_KEYS };