pan-wizard 3.19.0 → 3.21.0

package/bin/install-lib.cjs

@@ -1324,105 +1324,21 @@ return { areas_mapped: maps.filter(Boolean).length, synthesis }
 
 // ─── AGENTS.md universal rules layer (ADR-0028 Phase 3) ─────────────────────
 //
-// AGENTS.md is the cross-runtime project-instructions standard; every PAN
-// target runtime (and Antigravity CLI) reads it natively. PAN contributes one
-// marker-fenced section so agents in any runtime understand the PAN context
-// when reading the repo. User content outside the markers is never touched.
+// The builders + markers live under pan-wizard-core/ (the single source of
+// truth, shipped into every install) so the installer and the installed
+// `pan-tools memory rebuild` regenerate byte-identical content. They are
+// re-exported here so all existing installer callers and tests keep importing
+// them from install-lib unchanged.
 
-const PAN_AGENTS_BEGIN = '<!-- BEGIN PAN WIZARD -->';
-const PAN_AGENTS_END = '<!-- END PAN WIZARD -->';
-
-/**
- * Build the PAN section for AGENTS.md (marker-fenced, runtime-neutral).
- * @returns {string} The fenced section, no leading/trailing blank lines.
- */
-function buildAgentsMdSection() {
-  return [
-    PAN_AGENTS_BEGIN,
-    '## PAN Wizard',
-    '',
-    'This project uses PAN Wizard for structured, phase-based planning and execution.',
-    '',
-    '- `.planning/` is PAN\'s state directory (state.md, roadmap.md, phase directories). Treat it as the source of truth for planning state and modify it through PAN commands, not by hand.',
-    '- PAN commands install as `pan-*` skills/commands (for example `/pan-help`, `/pan-new-project`, `/pan-exec-phase`). Start with `/pan-help`.',
-    '- The `pan-tools` dispatcher backs every command; it lives under `pan-wizard-core/` inside the runtime\'s config directory (or `.agents/` for unified installs).',
-    PAN_AGENTS_END,
-  ].join('\n');
-}
-
-/**
- * Insert or replace the PAN section in AGENTS.md content.
- * - No existing content (null/empty) → just the section.
- * - Markers present → replace exactly the fenced block, preserving everything
- *   around it.
- * - Markers absent → append with a separating blank line.
- * @param {string|null} existing - Current AGENTS.md content, or null if absent
- * @param {string} section - Output of buildAgentsMdSection()
- * @returns {string} New file content (always newline-terminated)
- */
-function upsertAgentsMdSection(existing, section) {
-  if (!existing || !existing.trim()) {
-    return section + '\n';
-  }
-  const beginIdx = existing.indexOf(PAN_AGENTS_BEGIN);
-  const endIdx = existing.indexOf(PAN_AGENTS_END);
-  if (beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx) {
-    const before = existing.slice(0, beginIdx);
-    const after = existing.slice(endIdx + PAN_AGENTS_END.length);
-    return before + section + after;
-  }
-  return existing.trimEnd() + '\n\n' + section + '\n';
-}
-
-/**
- * Remove the PAN section from AGENTS.md content.
- * @param {string} existing - Current AGENTS.md content
- * @returns {string|null} Content without the PAN block, or null when nothing
- *   meaningful remains (caller should delete the file).
- */
-function removeAgentsMdSection(existing) {
-  if (!existing) return null;
-  const beginIdx = existing.indexOf(PAN_AGENTS_BEGIN);
-  const endIdx = existing.indexOf(PAN_AGENTS_END);
-  if (beginIdx === -1 || endIdx === -1 || endIdx < beginIdx) {
-    return existing; // no PAN block — leave untouched
-  }
-  const before = existing.slice(0, beginIdx);
-  const after = existing.slice(endIdx + PAN_AGENTS_END.length);
-  const remaining = (before.trimEnd() + '\n\n' + after.trimStart()).trim();
-  return remaining ? remaining + '\n' : null;
-}
-
-/**
- * Ensure CLAUDE.md bridges to AGENTS.md via a marker-fenced @AGENTS.md import
- * (Claude Code's documented pattern for adopting the universal rules file).
- * Idempotent; preserves all user content.
- * @param {string|null} existing - Current CLAUDE.md content, or null if absent
- * @returns {string} New file content
- */
-function ensureClaudeMdImport(existing) {
-  const block = `${PAN_AGENTS_BEGIN}\n@AGENTS.md\n${PAN_AGENTS_END}`;
-  if (!existing || !existing.trim()) {
-    return block + '\n';
-  }
-  if (existing.includes(PAN_AGENTS_BEGIN)) {
-    return existing; // bridge (or another PAN block) already present
-  }
-  if (/^@AGENTS\.md\s*$/m.test(existing)) {
-    return existing; // user already imports AGENTS.md themselves
-  }
-  return existing.trimEnd() + '\n\n' + block + '\n';
-}
-
-/**
- * Remove the PAN bridge block from CLAUDE.md content.
- * @param {string} existing - Current CLAUDE.md content
- * @returns {string|null} Content without the bridge, or null when nothing
- *   meaningful remains (caller should delete the file).
- */
-function removeClaudeMdImport(existing) {
-  return removeAgentsMdSection(existing);
-}
+const {
+  PAN_AGENTS_BEGIN,
+  PAN_AGENTS_END,
+  buildAgentsMdSection,
+  upsertAgentsMdSection,
+  removeAgentsMdSection,
+  ensureClaudeMdImport,
+  removeClaudeMdImport,
+} = require('../pan-wizard-core/bin/lib/agents-md.cjs');
 
 // ─── Exports ────────────────────────────────────────────────────────────────
 

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

@@ -20,6 +20,48 @@ 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). Kept as
+// a literal in both hooks + cost.cjs — the hooks are standalone zero-dep scripts
+// that can't import from pan-wizard-core, so this MUST stay in sync by hand.
+const SCHEMA_V = 2;
+
+// 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
+// resolves); unknown models stay null rather than guess.
+function tierForModel(model) {
+  if (typeof model !== 'string' || !model) return null;
+  if (/opus|fable|mythos/i.test(model)) return 'reasoning';
+  if (/sonnet/i.test(model)) return 'mid';
+  if (/haiku/i.test(model)) return 'fast';
+  return null;
+}
+
+// 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).
+// Never throws — returns {} on any miss.
+function readActiveSessionMeta(cwd) {
+  try {
+    const optDir = path.join(cwd, '.planning', '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 : {};
+  } catch {
+    return {};
+  }
+}
+
+// Duration of a transcript slice from its first→last record timestamp. Returns
+// null when either bound is absent/unparseable — never a fabricated 0.
+function durationFromSpan(firstTs, lastTs) {
+  if (!firstTs || !lastTs) return null;
+  const a = Date.parse(firstTs);
+  const b = Date.parse(lastTs);
+  return Number.isFinite(a) && Number.isFinite(b) ? b - a : null;
+}
+
 // Per-transcript high-water mark: the count of JSONL records already attributed
 // to earlier SubagentStop events, keyed by transcript path. Each event then sums
 // ONLY its own slice (records past the cursor) instead of re-summing the whole
@@ -56,57 +98,80 @@ function buildCostRecord(data, cwd) {
   // Only log actual subagent stops; ignore other Stop variants.
   if (data.hook_event_name && data.hook_event_name !== 'SubagentStop') return null;
 
-  // P-1805 (v3.7.8): if data.usage is missing/empty (Claude Code headless mode
-  // doesn't include it in the SubagentStop payload), fall back to reading the
-  // transcript_path JSONL and summing usage across the subagent's messages.
-  // Same approach as pan-trace-logger.js for consistency.
-  //
-  // 2026-06: the SubagentStop payload carries no model id either, which left
-  // every hook record with model:null and /pan:cost unable to price it. The
-  // transcript's assistant messages carry message.model right next to the
-  // usage we already read — capture it whenever data.model is absent.
-  let inputTokens = extractNumber(data.usage, 'input_tokens');
-  let outputTokens = extractNumber(data.usage, 'output_tokens');
-  let cacheRead = extractNumber(data.usage, 'cache_read_input_tokens');
-  let cacheWrite = extractNumber(data.usage, 'cache_creation_input_tokens');
+  // Per-call token counts come from the transcript SLICE — the records since
+  // this transcript's previous SubagentStop cursor. The SubagentStop `data.usage`,
+  // when Claude Code supplies it, is a CUMULATIVE session counter, NOT this
+  // subagent's delta, so logging it verbatim stamped impossible per-row magnitudes
+  // (tens of millions of output tokens, billions of cache-read) onto every record
+  // and made /pan:cost and the optimizer unusable (field reports 2026-06 / 2026-07).
+  // The transcript slice is the authoritative per-invocation delta; `data.usage`
+  // is a guarded fallback used only when no transcript is available.
   let model = typeof data.model === 'string' && data.model ? data.model : null;
-  const needUsage = (inputTokens + outputTokens + cacheRead + cacheWrite) === 0;
-  if ((needUsage || !model) && data.transcript_path) {
-    // Attribute only the transcript slice since the previous SubagentStop for
-    // this transcript, so a shared-session transcript is never re-summed on
-    // every event (field report 2026-06 — the billion-token cache-read bug).
+  let inputTokens = 0;
+  let outputTokens = 0;
+  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';
+  let clamped = false;
+  if (data.transcript_path) {
     const cursor = readCursor(cwd);
     const since = cursor[data.transcript_path] || 0;
     const fromTranscript = readUsageFromTranscript(data.transcript_path, data.session_id, since);
-    if (needUsage) {
-      inputTokens = fromTranscript.input_tokens;
-      outputTokens = fromTranscript.output_tokens;
-      cacheRead = fromTranscript.cache_read_input_tokens;
-      cacheWrite = fromTranscript.cache_creation_input_tokens;
-    }
+    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);
     if (!model) model = fromTranscript.model;
-    // Advance the cursor to the end of the transcript so the next subagent's
-    // record starts fresh (these slices partition the transcript — no overlap).
+    // 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.
     if (fromTranscript.lineCount > since) {
       cursor[data.transcript_path] = fromTranscript.lineCount;
       writeCursor(cwd, cursor);
     }
+  } else {
+    // No transcript to slice — best-effort from data.usage, plausibility-guarded
+    // so a cumulative counter can never slip through as a per-call value. Flag
+    // when the guard actually fired so a dropped value isn't read as a real zero.
+    const rawIn = extractNumber(data.usage, 'input_tokens');
+    const rawOut = extractNumber(data.usage, 'output_tokens');
+    const rawCr = extractNumber(data.usage, 'cache_read_input_tokens');
+    const rawCw = extractNumber(data.usage, 'cache_creation_input_tokens');
+    inputTokens = clampPlausible(rawIn);
+    outputTokens = clampPlausible(rawOut);
+    cacheRead = clampPlausible(rawCr);
+    cacheWrite = clampPlausible(rawCw);
+    clamped = [rawIn, rawOut, rawCr, rawCw].some((n) => n > PLAUSIBLE_MAX);
   }
 
+  // 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;
+  const phase = data.phase || sessionMeta.phase || null;
+
   const record = {
+    v: SCHEMA_V,
     ts: new Date().toISOString(),
     agent: data.agent_type || data.subagent_type || null,
-    command: null,
+    command,
     model,
-    tier: null,
+    tier: tierForModel(model),
     input_tokens: inputTokens,
     output_tokens: outputTokens,
     cache_read_tokens: cacheRead,
     cache_write_tokens: cacheWrite,
     cost_usd: null,
-    phase: data.phase || null,
+    duration_ms: durationMs,
+    phase,
     session: data.session_id || null,
     source: 'hook',
+    token_source: tokenSource,
+    clamped,
   };
 
   return record;
@@ -118,6 +183,15 @@ function extractNumber(obj, key) {
   return typeof v === 'number' ? v : 0;
 }
 
+// A single subagent call's token counts never realistically exceed this; a value
+// above it is a cumulative session counter that leaked in, so we drop it to 0
+// rather than poison the ledger. Generous vs. any real call, tiny vs. the
+// billions/tens-of-millions the cumulative bug produced.
+const PLAUSIBLE_MAX = 20000000;
+function clampPlausible(n) {
+  return typeof n === 'number' && n >= 0 && n <= PLAUSIBLE_MAX ? n : 0;
+}
+
 /**
  * P-1805 (v3.7.8): read transcript JSONL and sum usage across assistant messages.
  *
@@ -139,6 +213,8 @@ function readUsageFromTranscript(transcriptPath, sessionId, sinceLine = 0) {
     cache_read_input_tokens: 0,
     cache_creation_input_tokens: 0,
     model: null,
+    first_ts: null,
+    last_ts: null,
     lineCount: 0,
   };
   if (!transcriptPath || typeof transcriptPath !== 'string') return totals;
@@ -152,6 +228,13 @@ function readUsageFromTranscript(transcriptPath, sessionId, sinceLine = 0) {
     let entry;
     try { entry = JSON.parse(line); } catch { continue; }
     if (sessionId && entry.session_id && entry.session_id !== 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;
+    if (entryTs) {
+      if (!totals.first_ts) totals.first_ts = entryTs;
+      totals.last_ts = entryTs;
+    }
     // Assistant messages carry the model id alongside their usage — keep the
     // last one seen (mid-session model switches resolve to the final model).
     const entryModel = entry.message?.model || entry.model || null;
@@ -184,13 +267,34 @@ function appendRecord(cwd, record) {
   try {
     const dir = path.join(cwd, '.planning', METRICS_DIR);
     fs.mkdirSync(dir, { recursive: true });
-    fs.appendFileSync(path.join(dir, TOKENS_FILE), JSON.stringify(record) + '\n', 'utf-8');
+    const file = path.join(dir, TOKENS_FILE);
+    // Idempotency guard: a re-fired SubagentStop must not double-log. Skip the
+    // append when this record is identical (every field but the timestamp) to
+    // the immediately-preceding row — the source of ~57% duplicate rows in the
+    // field (2026-07). Best-effort: any read error just proceeds with the append.
+    if (isDuplicateOfLastRecord(file, record)) return false;
+    fs.appendFileSync(file, JSON.stringify(record) + '\n', 'utf-8');
     return true;
   } catch {
     return false;
   }
 }
 
+/** True when `record` equals the last JSONL row of `file`, ignoring `ts`. */
+function isDuplicateOfLastRecord(file, record) {
+  let prev;
+  try {
+    const raw = fs.readFileSync(file, 'utf-8');
+    const lines = raw.split('\n').filter(Boolean);
+    if (!lines.length) return false;
+    prev = JSON.parse(lines[lines.length - 1]);
+  } catch {
+    return false; // no file / unreadable / bad JSON → not a duplicate
+  }
+  const strip = (r) => { const { ts, ...rest } = r; return JSON.stringify(rest); };
+  return strip(prev) === strip(record);
+}
+
 // ─── Stdin driver ───────────────────────────────────────────────────────────
 
 if (require.main === module) {

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

@@ -23,6 +23,68 @@ const TRACES_DIR = 'traces';
 const CURRENT_SESSION_FILE = 'current-session';
 const TRACE_EVENT_FILE = 'trace.jsonl';
 
+// Trace event schema version — kept in sync by hand with pan-cost-logger.js +
+// cost.cjs (standalone zero-dep hooks can't share a module). See that file.
+const SCHEMA_V = 2;
+
+// YYYYMMDD stamp for a Date (the day-scope of an auto-session id).
+function dayStamp(d) {
+  return d.toISOString().replace(/[-:T]/g, '').slice(0, 8);
+}
+
+// Duration of a transcript slice from its first→last record timestamp; null when
+// either bound is missing/unparseable (never a fabricated 0).
+function durationFromSpan(firstTs, lastTs) {
+  if (!firstTs || !lastTs) return null;
+  const a = Date.parse(firstTs);
+  const b = Date.parse(lastTs);
+  return Number.isFinite(a) && Number.isFinite(b) ? b - a : null;
+}
+
+// Read a session's persisted command/phase (written by optimize.cjs
+// initTraceSession) so hook events can inherit them. Best-effort → {} on miss.
+function readSessionMetaById(cwd, sid) {
+  try {
+    const meta = JSON.parse(fs.readFileSync(path.join(getTracesDir(cwd), sid, 'session.json'), 'utf-8'));
+    return meta && typeof meta === 'object' ? meta : {};
+  } catch {
+    return {};
+  }
+}
+
+// Finalize a session in place: recompute event_count / type_counts / agents from
+// its trace.jsonl and stamp ended_at. Inlined (the hook can't import optimize.cjs)
+// and mirrors optimize.cjs endTraceSession's count loop so day-rollover leaves a
+// properly-closed session behind. Best-effort; never throws.
+function finalizeSession(cwd, sid) {
+  try {
+    const sessionDir = path.join(getTracesDir(cwd), sid);
+    const metaPath = path.join(sessionDir, 'session.json');
+    let meta = {};
+    try { meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8')); } catch { return; }
+    let eventCount = 0;
+    const agentNames = new Set();
+    const typeCounts = {};
+    try {
+      const raw = fs.readFileSync(path.join(sessionDir, TRACE_EVENT_FILE), 'utf-8');
+      raw.trim().split('\n').filter(Boolean).forEach((line) => {
+        try {
+          const e = JSON.parse(line);
+          eventCount++;
+          if (e.agent) agentNames.add(e.agent);
+          typeCounts[e.type] = (typeCounts[e.type] || 0) + 1;
+        } catch { /* skip malformed */ }
+      });
+    } catch { /* no trace.jsonl */ }
+    meta.ended_at = new Date().toISOString();
+    meta.event_count = eventCount;
+    meta.agent_count = agentNames.size;
+    meta.agents = Array.from(agentNames);
+    meta.type_counts = typeCounts;
+    fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2) + '\n');
+  } catch { /* best-effort */ }
+}
+
 function getOptimizeDir(cwd) {
   return path.join(cwd, PLANNING_DIR, OPTIMIZE_DIR);
 }
@@ -65,12 +127,23 @@ function writeTraceCursor(cwd, cursor) {
  * @returns {string} The active session ID
  */
 function ensureSessionId(cwd) {
+  const now = new Date();
+  const stamp = dayStamp(now); // YYYYMMDD
   const existing = getCurrentSessionId(cwd);
-  if (existing) return existing;
+  if (existing) {
+    // Day-rollover: a stale day-scoped auto-session from a previous day must not
+    // keep accumulating today's rows. Finalize it and mint a fresh one. Explicit
+    // (non-auto) sessions stay sticky — only auto-sessions roll over.
+    const m = /^sess_auto_(\d{8})$/.exec(existing);
+    if (m && m[1] !== stamp) {
+      finalizeSession(cwd, existing);
+      // fall through to mint a new day-scoped session below
+    } else {
+      return existing;
+    }
+  }
 
   // Create a day-scoped auto session
-  const now = new Date();
-  const stamp = now.toISOString().replace(/[-:T]/g, '').slice(0, 8); // YYYYMMDD
   const sessionId = `sess_auto_${stamp}`;
   try {
     const sessionDir = path.join(getTracesDir(cwd), sessionId);
@@ -98,6 +171,14 @@ function extractNumber(obj, key) {
   return typeof v === 'number' ? v : 0;
 }
 
+// Drop implausibly large per-call token counts (a cumulative counter that leaked
+// through the no-transcript fallback) to 0 rather than record them. Mirrors
+// pan-cost-logger's guard.
+const PLAUSIBLE_MAX = 20000000;
+function clampPlausible(n) {
+  return typeof n === 'number' && n >= 0 && n <= PLAUSIBLE_MAX ? n : 0;
+}
+
 /**
  * P-1805 (v3.7.8): extract usage totals by reading the SubagentStop transcript.
  * The hook payload from Claude Code in headless mode does NOT include
@@ -123,6 +204,9 @@ function readUsageFromTranscript(transcriptPath, sessionId, sinceLine = 0) {
     output_tokens: 0,
     cache_read_input_tokens: 0,
     cache_creation_input_tokens: 0,
+    model: null,
+    first_ts: null,
+    last_ts: null,
     lineCount: 0,
   };
   if (!transcriptPath || typeof transcriptPath !== 'string') return totals;
@@ -146,6 +230,15 @@ function readUsageFromTranscript(transcriptPath, sessionId, sinceLine = 0) {
     // Filter to entries from this subagent if a session_id is provided.
     // The transcript may include parent + child traffic; session_id discriminates.
     if (sessionId && entry.session_id && entry.session_id !== sessionId) continue;
+    // Span of this subagent's slice (after the session filter) for duration_ms,
+    // and the model id (mirrors pan-cost-logger — keep the last model seen).
+    const entryTs = typeof entry.timestamp === 'string' ? entry.timestamp : null;
+    if (entryTs) {
+      if (!totals.first_ts) totals.first_ts = entryTs;
+      totals.last_ts = entryTs;
+    }
+    const entryModel = entry.message?.model || entry.model || null;
+    if (typeof entryModel === 'string' && entryModel) totals.model = entryModel;
     // Usage typically lives on assistant message records.
     const usage = entry.usage
       || entry.message?.usage
@@ -183,44 +276,71 @@ function buildTraceEvents(data, sessionId, cwd) {
   const ts = new Date().toISOString();
   const agent = data.agent_type || data.subagent_type || 'unknown';
 
-  // P-1805: prefer usage from data.usage when present (interactive Claude Code path).
-  // Fall back to reading the transcript file (headless `claude -p` path — usage
-  // not in payload but discoverable via transcript_path).
-  let inputTokens = extractNumber(data.usage, 'input_tokens');
-  let outputTokens = extractNumber(data.usage, 'output_tokens');
-  let cacheRead = extractNumber(data.usage, 'cache_read_input_tokens');
-  if ((inputTokens + outputTokens + cacheRead) === 0 && data.transcript_path) {
+  // Per-call tokens come from the transcript SLICE. The SubagentStop `data.usage`,
+  // when present, is a CUMULATIVE session counter — not this subagent's delta — so
+  // logging it verbatim produced impossible per-row magnitudes (see pan-cost-logger
+  // for the full rationale). The slice is authoritative; data.usage is only a
+  // plausibility-guarded fallback when no transcript is available.
+  let model = typeof data.model === 'string' && data.model ? data.model : null;
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let cacheRead = 0;
+  let durationMs = null;
+  let tokenSource = data.transcript_path ? 'transcript' : 'usage-fallback';
+  let clamped = false;
+  if (data.transcript_path) {
     const cursor = readTraceCursor(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;
+    durationMs = durationFromSpan(fromTranscript.first_ts, fromTranscript.last_ts);
+    if (!model) model = fromTranscript.model;
     if (cwd && fromTranscript.lineCount > since) {
       cursor[data.transcript_path] = fromTranscript.lineCount;
       writeTraceCursor(cwd, cursor);
     }
+  } else {
+    const rawIn = extractNumber(data.usage, 'input_tokens');
+    const rawOut = extractNumber(data.usage, 'output_tokens');
+    const rawCr = extractNumber(data.usage, 'cache_read_input_tokens');
+    inputTokens = clampPlausible(rawIn);
+    outputTokens = clampPlausible(rawOut);
+    cacheRead = clampPlausible(rawCr);
+    clamped = [rawIn, rawOut, rawCr].some((n) => n > PLAUSIBLE_MAX);
   }
   const totalTokens = inputTokens + outputTokens;
 
+  // Inherit command/phase from the active session when the payload omits them
+  // (mirrors optimize.cjs logTraceEvent's W3 phase-inheritance, which the hook
+  // path otherwise bypasses).
+  const sessionMeta = cwd ? readSessionMetaById(cwd, sessionId) : {};
+  const phase = data.phase || sessionMeta.phase || null;
+
   const events = [];
 
   // Core completion event
   events.push({
+    v: SCHEMA_V,
     ts,
     session: sessionId,
     agent,
-    phase: data.phase || null,
+    phase,
     type: 'decision',
     category: 'agent_completion',
     description: `${agent} completed`,
     context: {
-      model: data.model || null,
+      model,
+      command: data.command || sessionMeta.command || null,
       input_tokens: inputTokens,
       output_tokens: outputTokens,
       cache_read_tokens: cacheRead,
       total_tokens: totalTokens,
+      duration_ms: durationMs,
       exit_code: data.exit_code || 0,
+      token_source: tokenSource,
+      clamped,
     },
     impact: 'trivial',
     correction: null,
@@ -231,10 +351,11 @@ function buildTraceEvents(data, sessionId, cwd) {
   // (expensive agent run that wasn't cached — may be repeated research)
   if (outputTokens > 3000 && cacheRead === 0) {
     events.push({
+      v: SCHEMA_V,
       ts,
       session: sessionId,
       agent,
-      phase: data.phase || null,
+      phase,
       type: 'redundancy',
       category: 'uncached_heavy_run',
       description: `${agent} produced ${outputTokens} output tokens with zero cache hits — possible repeated research`,
@@ -261,14 +382,39 @@ function appendTraceEvents(cwd, events, sessionId) {
   try {
     const sessionDir = path.join(getTracesDir(cwd), sessionId);
     fs.mkdirSync(sessionDir, { recursive: true });
+    const file = path.join(sessionDir, TRACE_EVENT_FILE);
+    // Idempotency guard: a re-fired SubagentStop must not double-log. If this
+    // batch's completion event duplicates the last agent_completion already in
+    // the file (every field but ts), skip the whole batch — the source of the
+    // ~57% duplicate completion rows in the field (2026-07).
+    const completion = events.find(e => e && e.category === 'agent_completion');
+    if (completion && isDuplicateCompletion(file, completion)) return false;
     const lines = events.map(e => JSON.stringify(e)).join('\n') + '\n';
-    fs.appendFileSync(path.join(sessionDir, TRACE_EVENT_FILE), lines, 'utf-8');
+    fs.appendFileSync(file, lines, 'utf-8');
     return true;
   } catch {
     return false;
   }
 }
 
+/** True when `completion` matches the file's last agent_completion row, ignoring ts. */
+function isDuplicateCompletion(file, completion) {
+  let last;
+  try {
+    const raw = fs.readFileSync(file, 'utf-8');
+    for (const line of raw.split('\n')) {
+      if (!line) continue;
+      let e; try { e = JSON.parse(line); } catch { continue; }
+      if (e && e.category === 'agent_completion') last = e;
+    }
+  } catch {
+    return false;
+  }
+  if (!last) return false;
+  const strip = (e) => { const { ts, ...rest } = e; return JSON.stringify(rest); };
+  return strip(last) === strip(completion);
+}
+
 // ─── Stdin driver ────────────────────────────────────────────────────────────
 
 if (require.main === module) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pan-wizard",
-  "version": "3.19.0",
+  "version": "3.21.0",
   "description": "Command a bot army for your codebase: an Opus Mission Control delegates whole-project goals to specialist squads and ships behind a human merge gate. Five AI CLIs, zero context rot.",
   "bin": {
     "pan-wizard": "bin/install.js"