pan-wizard 3.20.0 → 3.21.0

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
@@ -69,6 +111,12 @@ function buildCostRecord(data, cwd) {
   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;
@@ -77,6 +125,7 @@ function buildCostRecord(data, cwd) {
     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 so the next subagent's record starts fresh — the slices
     // partition the transcript, so it is never re-summed on every event.
@@ -86,27 +135,43 @@ function buildCostRecord(data, cwd) {
     }
   } 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.
-    inputTokens = clampPlausible(extractNumber(data.usage, 'input_tokens'));
-    outputTokens = clampPlausible(extractNumber(data.usage, 'output_tokens'));
-    cacheRead = clampPlausible(extractNumber(data.usage, 'cache_read_input_tokens'));
-    cacheWrite = clampPlausible(extractNumber(data.usage, 'cache_creation_input_tokens'));
+    // 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;
@@ -148,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;
@@ -161,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;

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);
@@ -131,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;
@@ -154,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
@@ -196,9 +281,13 @@ function buildTraceEvents(data, sessionId, cwd) {
   // 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;
@@ -206,35 +295,52 @@ function buildTraceEvents(data, sessionId, cwd) {
     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 {
-    inputTokens = clampPlausible(extractNumber(data.usage, 'input_tokens'));
-    outputTokens = clampPlausible(extractNumber(data.usage, 'output_tokens'));
-    cacheRead = clampPlausible(extractNumber(data.usage, 'cache_read_input_tokens'));
+    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,
@@ -245,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`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pan-wizard",
-  "version": "3.20.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"

package/pan-wizard-core/bin/lib/campaign.cjs

@@ -13,7 +13,7 @@
 const fs = require('fs');
 const path = require('path');
 const { output, error } = require('./core.cjs');
-const { PLANNING_DIR } = require('./constants.cjs');
+const { PLANNING_DIR, VERIFY_RESERVE_FRACTION } = require('./constants.cjs');
 
 const ORCH_DIR = 'orchestration';
 const SCHEDULE_FILE = 'schedule.json';
@@ -169,12 +169,19 @@ function cmdCampaignStatus(cwd, raw) {
   if (!schedule) return output({ scheduled: false }, raw, 'No campaign scheduled');
   const at = new Date();
   const d = isRunDue(schedule, at);
+  // Advisory verify-reserve indicators (status only — does not move the isRunDue
+  // trip threshold): how much of the daily budget is held back for re-verification
+  // and whether today's spend has crossed into it.
+  const fraction = typeof schedule.verify_reserve === 'number' ? schedule.verify_reserve : VERIFY_RESERVE_FRACTION;
+  const verifyReserve = schedule.daily_budget != null && fraction > 0 ? Math.ceil(schedule.daily_budget * fraction) : 0;
+  const intoReserve = verifyReserve > 0 && schedule.daily_budget != null && d.spent_today >= schedule.daily_budget - verifyReserve;
   const result = {
     scheduled: true, enabled: schedule.enabled, paused: schedule.paused,
     cadence: schedule.cadence, daily_budget: schedule.daily_budget,
     next_due: schedule.next_due, last_run: schedule.last_run,
     spent_today: d.spent_today, runs: (schedule.history || []).length,
     due: d.due, reason: d.reason,
+    verify_reserve: verifyReserve, into_verify_reserve: intoReserve,
   };
   const human = `Campaign ${schedule.enabled ? (schedule.paused ? 'paused' : 'active') : 'disabled'} · ${schedule.cadence} · spent ${d.spent_today}/${schedule.daily_budget} today · next ${schedule.next_due} · ${d.due ? 'DUE NOW' : d.reason}`;
   output(result, raw, human);

package/pan-wizard-core/bin/lib/config.cjs

@@ -66,6 +66,9 @@ function buildConfigDefaults(hasBraveSearch, userDefaults) {
       // (HUD, telemetry) but never STOP a run. Set enforce:true (or pass
       // --enforce-budget) to make the cap a hard stop again.
       enforce: false,
+      // Fraction of the spawn budget held back for re-verification (0..0.5).
+      // Surfaced as an indicator always; a hard early stop only under enforce.
+      verify_reserve: 0.15,
     },
     commit: {
       safety_checks: true,

package/pan-wizard-core/bin/lib/constants.cjs

@@ -183,6 +183,12 @@ const DEFAULT_MAX_CYCLES = 10;
 
 /** Default cumulative budget cap for auto-runner */
 const DEFAULT_TOTAL_BUDGET = 500;
+// Fraction of the spawn budget held back for re-verification so a run can't
+// exhaust its points on Build/Execute before the quality gate re-checks the
+// work. Advisory by default (an indicator); a hard early stop only under
+// --enforce-budget. FLOOR guards tiny budgets from a zero reserve.
+const VERIFY_RESERVE_FRACTION = 0.15;
+const VERIFY_RESERVE_FLOOR = 1;
 
 // ─── Standards ──────────────────────────────────────────────────────────────
 
@@ -717,6 +723,8 @@ module.exports = {
   CATEGORY_DEFAULTS,
   DEFAULT_MAX_CYCLES,
   DEFAULT_TOTAL_BUDGET,
+  VERIFY_RESERVE_FRACTION,
+  VERIFY_RESERVE_FLOOR,
   // Standards
   STANDARDS_FILE,
   STANDARDS_CATEGORIES,

package/pan-wizard-core/bin/lib/core.cjs

@@ -296,6 +296,9 @@ function loadConfig(cwd) {
       model_overrides: parsed.model_overrides || {},
       effort_overrides: parsed.effort_overrides || {},
       routing: parsed.routing || { strategy: 'static', provider: 'auto' },
+      // Cost dashboard config: `cost.rates` per-model overrides (surfaced so the
+      // documented override actually reaches cost.cjs — it was dropped before).
+      cost: parsed.cost || {},
       // ADR-0031: project build/verification commands. null = not configured
       // (focus-auto --clean-seal then asks or skips rather than guessing).
       build: parsed.build || null,
@@ -312,6 +315,7 @@ function loadConfig(cwd) {
       model_overrides: {},
       effort_overrides: {},
       routing: { strategy: 'static', provider: 'auto' },
+      cost: {},
       build: null,
       verification: null,
       concurrency: { serial_build: false },

package/pan-wizard-core/bin/lib/cost.cjs

@@ -148,10 +148,13 @@ function appendRecord(cwd, rec) {
     phase: rec.phase || null,
     session: rec.session || null,
   };
-  // Allow caller-supplied cost override; otherwise compute.
+  // Allow caller-supplied cost override; otherwise compute at the user's
+  // configured rates (config.cost.rates) — without this, CLI-appended rows froze
+  // at DEFAULT_RATES while hook rows (cost_usd:null) got config rates at read
+  // time, so the two producers priced identical tokens differently.
   normalized.cost_usd = typeof rec.cost_usd === 'number'
     ? rec.cost_usd
-    : computeCost(normalized);
+    : computeCost(normalized, loadConfig(cwd)?.cost?.rates);
 
   try {
     fs.mkdirSync(metricsDir(cwd), { recursive: true });
@@ -167,7 +170,16 @@ function appendRecord(cwd, rec) {
  * @param {string} cwd
  * @returns {Array<Object>}
  */
+// Count of malformed (unparseable) rows dropped by the most recent readRecords
+// call. A crash mid-append or interleaved concurrent appends can leave a torn
+// row; surfacing the count (rather than swallowing it) mirrors the existing
+// suspect_excluded contract. Module-level so aggregate() can read it without a
+// breaking change to readRecords' bare-array return (consumed as an array by
+// aggregate, memory.cjs, and hygiene.cjs).
+let _lastReadMalformed = 0;
+
 function readRecords(cwd) {
+  _lastReadMalformed = 0;
   const raw = safeReadFile(tokensFile(cwd));
   if (!raw) return [];
   const records = [];
@@ -175,7 +187,7 @@ function readRecords(cwd) {
     if (!line.trim()) continue;
     try {
       records.push(JSON.parse(line));
-    } catch { /* skip malformed line */ }
+    } catch { _lastReadMalformed += 1; }
   }
   return records;
 }
@@ -207,6 +219,7 @@ function isSuspectRecord(r) {
 
 function aggregate(cwd, opts) {
   const records = readRecords(cwd);
+  const malformedSkipped = _lastReadMalformed; // captured before any later read
   const since = opts?.since ? new Date(opts.since).getTime() : null;
   const until = opts?.until ? new Date(opts.until).getTime() : null;
   const config = loadConfig(cwd);
@@ -229,6 +242,7 @@ function aggregate(cwd, opts) {
     cost_usd: 0,
     cost_unknown: 0,
     suspect_excluded: 0,
+    malformed_skipped: malformedSkipped,
   };
 
   const byAgent = {};
@@ -305,7 +319,7 @@ function renderTable(agg) {
   lines.push(window);
   lines.push('');
   lines.push('Totals');
-  lines.push(`  Calls              : ${agg.totals.calls}`);
+  lines.push(`  Calls              : ${agg.totals.calls}${agg.totals.malformed_skipped > 0 ? ` (+${agg.totals.malformed_skipped} malformed)` : ''}`);
   lines.push(`  Input tokens       : ${agg.totals.input_tokens.toLocaleString()}`);
   lines.push(`  Output tokens      : ${agg.totals.output_tokens.toLocaleString()}`);
   lines.push(`  Cache read         : ${agg.totals.cache_read_tokens.toLocaleString()}`);

package/pan-wizard-core/bin/lib/focus.cjs

@@ -15,7 +15,7 @@ const {
   BUDGET_LIMIT_BUGFIX, BUDGET_LIMIT_FULL, STABILITY_RATIO, FEATURE_RATIO,
   DIMINISHING_RETURNS_THRESHOLD,
   AUTO_RUN_FILE, FOCUS_CATEGORIES, FOCUS_SOURCES, CATEGORY_PRIORITY_RANGE, CATEGORY_DEFAULTS,
-  DEFAULT_MAX_CYCLES, DEFAULT_TOTAL_BUDGET,
+  DEFAULT_MAX_CYCLES, DEFAULT_TOTAL_BUDGET, VERIFY_RESERVE_FRACTION, VERIFY_RESERVE_FLOOR,
   BUDGET_MIN, BUDGET_MAX, MAX_CYCLES_MIN, MAX_CYCLES_MAX, TOTAL_BUDGET_MIN, TOTAL_BUDGET_MAX,
   AUTORUN_STATUSES, DOC_SYNC_FILES, COMMAND_RENAME_MAP,
 } = require('./constants.cjs');
@@ -693,12 +693,28 @@ function generateRunId(cwd) {
  * @param {boolean} raw - Raw output mode
  * @param {...string} args - CLI arguments
  */
+/**
+ * Advisory budget indicators for a run: raw remaining, the verify reserve, the
+ * remaining budget for NEW work (excludes the reserve), and whether spend has
+ * crossed into the reserved headroom. Pure — no behavior change; surfaced so the
+ * human/HUD can see the reserve even when it isn't being enforced.
+ */
+function budgetIndicators(run) {
+  const used = run.totals ? run.totals.points_used : 0;
+  const reserve = run.verify_reserve || 0;
+  return {
+    budget_remaining: run.total_budget - used,
+    verify_reserve: reserve,
+    new_work_budget_remaining: run.total_budget - reserve - used,
+    into_verify_reserve: reserve > 0 && used >= run.total_budget - reserve,
+  };
+}
+
 function focusAutoStatus(cwd, raw) {
   const run = readAutoRun(cwd);
   if (!run) return error('No auto-run found. Start with: focus auto --category <name>');
-  const budgetRemaining = run.total_budget - (run.totals ? run.totals.points_used : 0);
   const cyclesRemaining = run.max_cycles - (run.totals ? run.totals.cycles_completed : 0);
-  return output({ ...run, budget_remaining: budgetRemaining, cycles_remaining: cyclesRemaining }, raw);
+  return output({ ...run, ...budgetIndicators(run), cycles_remaining: cyclesRemaining }, raw);
 }
 
 function focusAutoStop(cwd, raw) {
@@ -781,6 +797,30 @@ function focusAutoUpdate(cwd, raw, getVal) {
   cycle.tests_verified = tv.verified;
 
   if (!run.cycles) run.cycles = [];
+
+  // Attribution: anchor this cycle to a start, measure its wall-clock duration,
+  // name the driving command, and JOIN to the authoritative cost ledger so the
+  // cycle carries the agents + dollars behind its item counts (not just a
+  // self-reported points estimate). windowStart = the prior cycle's end, or the
+  // run start for cycle 1. Server-side join — no fakeable CLI arg.
+  const windowStart = run.cycles.length ? run.cycles[run.cycles.length - 1].timestamp : run.started_at;
+  cycle.started_at = windowStart || null;
+  const durMs = windowStart ? (new Date(cycle.timestamp) - new Date(windowStart)) : NaN;
+  cycle.duration_ms = Number.isFinite(durMs) ? durMs : null;
+  cycle.command = getVal('--command', run.category || run.source || null);
+  cycle.cost_usd = null;
+  cycle.tokens = null;
+  cycle.agents = [];
+  if (windowStart) {
+    try {
+      const agg = require('./cost.cjs').aggregate(cwd, { since: windowStart, until: cycle.timestamp });
+      if (agg && agg.totals) {
+        cycle.cost_usd = agg.totals.calls > 0 ? agg.totals.cost_usd : null;
+        cycle.tokens = { input: agg.totals.input_tokens, output: agg.totals.output_tokens, cache_read: agg.totals.cache_read_tokens };
+        cycle.agents = agg.by_agent ? Object.keys(agg.by_agent) : [];
+      }
+    } catch { /* cost is observability, never the critical path */ }
+  }
   run.cycles.push(cycle);
 
   if (!run.totals) {
@@ -868,7 +908,13 @@ function determineStopReason(cycle, run) {
   if (cycle.tests_after < cycle.tests_before) return 'regression';
   // Budget is advisory by default — it only STOPS the run when explicitly enforced.
   // Otherwise the overage is tracked/surfaced (indication) and the loop continues.
+  // Hard cap (full budget) is evaluated FIRST so it remains the absolute boundary;
+  // the softer verify-reserve stop only fires in the band below it.
   if (run.budget_enforce && run.totals.points_used >= run.total_budget) return 'budget_cap';
+  // Verify-reserve: under enforcement, stop once new-work spend crosses into the
+  // reserved headroom so re-verification still has points. Advisory mode never trips.
+  const reserve = run.verify_reserve || 0;
+  if (run.budget_enforce && reserve > 0 && run.totals.points_used >= run.total_budget - reserve) return 'budget_reserve_reached';
   if (run.totals.cycles_completed >= run.max_cycles) return 'max_cycles';
   if (cycle.items_completed === 0) {
     // Security category gets a descriptive stop reason rather than generic zero_completed
@@ -905,9 +951,8 @@ function focusAutoContinue(cwd, raw) {
   run.status = run.totals && run.totals.cycles_completed > 0 ? AUTORUN_STATUSES.IN_PROGRESS : AUTORUN_STATUSES.INITIALIZED;
   run.stop_reason = null;
   writeAutoRun(cwd, run);
-  const budgetRemaining = run.total_budget - (run.totals ? run.totals.points_used : 0);
   const cyclesRemaining = run.max_cycles - (run.totals ? run.totals.cycles_completed : 0);
-  return output({ ...run, budget_remaining: budgetRemaining, cycles_remaining: cyclesRemaining }, raw);
+  return output({ ...run, ...budgetIndicators(run), cycles_remaining: cyclesRemaining }, raw);
 }
 
 function focusAutoInit(cwd, raw, getVal, hasFlag) {
@@ -938,6 +983,15 @@ function focusAutoInit(cwd, raw, getVal, hasFlag) {
   // only when the user opts in via config `budget.enforce` or `--enforce-budget`.
   const budgetConfig = loadConfig(cwd).budget || {};
   const budgetEnforce = hasFlag('--enforce-budget') || budgetConfig.enforce === true;
+  // Verify-reserve: hold back a fraction of the spawn budget so re-verification
+  // isn't starved of points. Advisory by default (surfaced as an indicator);
+  // only a hard early stop under --enforce-budget. Clamp the fraction to 0..0.5.
+  const reserveRaw = getVal('--verify-reserve', null);
+  let reserveFraction = reserveRaw != null ? Number(reserveRaw)
+    : (typeof budgetConfig.verify_reserve === 'number' ? budgetConfig.verify_reserve : VERIFY_RESERVE_FRACTION);
+  if (!Number.isFinite(reserveFraction) || reserveFraction < 0) reserveFraction = 0;
+  if (reserveFraction > 0.5) reserveFraction = 0.5;
+  const verifyReserve = reserveFraction > 0 ? Math.max(VERIFY_RESERVE_FLOOR, Math.ceil(totalBudget * reserveFraction)) : 0;
 
   if (!FOCUS_MODES.includes(mode)) return error(`Mode must be one of: ${FOCUS_MODES.join(', ')}`);
   if (budget < BUDGET_MIN || budget > BUDGET_MAX) return error(`Budget must be between ${BUDGET_MIN} and ${BUDGET_MAX}`);
@@ -947,6 +1001,7 @@ function focusAutoInit(cwd, raw, getVal, hasFlag) {
   const runData = {
     run_id: generateRunId(cwd),
     status: AUTORUN_STATUSES.INITIALIZED,
+    started_at: new Date().toISOString(),
     source: source,
     category: category,
     mode: mode,
@@ -957,6 +1012,7 @@ function focusAutoInit(cwd, raw, getVal, hasFlag) {
     max_cycles: maxCycles,
     total_budget: totalBudget,
     budget_enforce: budgetEnforce,
+    verify_reserve: verifyReserve,
     priority_range: category ? CATEGORY_PRIORITY_RANGE[category] : { min: 0, max: 6 },
     deep_review_enabled: hasFlag('--deep-review'),
     tests_baseline: null,

package/pan-wizard-core/bin/lib/optimize.cjs

@@ -8,7 +8,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { output, escapeRegex } = require('./core.cjs');
+const { output, escapeRegex, execGit } = require('./core.cjs');
 const { PLANNING_DIR } = require('./constants.cjs');
 
 // ─── Storage layout ──────────────────────────────────────────────────────────
@@ -172,6 +172,65 @@ function logTraceEvent(cwd, event, sessionId) {
   }
 }
 
+/**
+ * Recompute a session's counters straight from its trace.jsonl — the single
+ * source of truth for event_count/agent_count/agents/type_counts, plus a count
+ * of malformed (unparseable) rows that would otherwise vanish silently. Pure
+ * read; never writes. Used by endTraceSession, the reconcile subcommand, and the
+ * reconcile-on-read overlay so the counting logic lives in exactly one place.
+ */
+function reconcileSessionMeta(cwd, sessionId) {
+  const sessionDir = path.join(getTracesDir(cwd), sessionId);
+  let eventCount = 0;
+  let malformed = 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 => {
+      let e;
+      try { e = JSON.parse(line); } catch { malformed++; return; }
+      eventCount++;
+      if (e.agent) agentNames.add(e.agent);
+      typeCounts[e.type] = (typeCounts[e.type] || 0) + 1;
+    });
+  } catch { /* no trace.jsonl yet */ }
+  return {
+    event_count: eventCount,
+    agent_count: agentNames.size,
+    agents: Array.from(agentNames),
+    type_counts: typeCounts,
+    malformed_count: malformed,
+  };
+}
+
+/**
+ * Compute the measured dollar cost + commit count for a session's [started_at,
+ * ended_at||now] window, folding the authoritative per-agent cost ledger
+ * (tokens.jsonl, suspect rows already quarantined) into the session so the
+ * autonomous-overhead metrics work. cost_usd is null when the ledger has no
+ * in-window rows; commit_count is null when git is unavailable — never a
+ * fabricated 0 (0 would make minutes_per_commit Infinity). Best-effort.
+ */
+function computeSessionCostAndCommits(cwd, meta) {
+  const out = { cost_usd: null, commit_count: null };
+  if (!meta || !meta.started_at) return out;
+  const since = meta.started_at;
+  const until = meta.ended_at || new Date().toISOString();
+  try {
+    const cost = require('./cost.cjs');
+    const agg = cost.aggregate(cwd, { since, until });
+    if (agg && agg.totals && agg.totals.calls > 0) out.cost_usd = agg.totals.cost_usd;
+  } catch { /* cost is observability, never the critical path */ }
+  try {
+    const r = execGit(cwd, ['log', '--oneline', '--since', since, '--until', until]);
+    if (r && r.exitCode === 0) {
+      out.commit_count = r.stdout ? r.stdout.split('\n').filter(Boolean).length : 0;
+    }
+  } catch { /* non-repo / git absent → leave null */ }
+  return out;
+}
+
 function endTraceSession(cwd, sessionId) {
   const sid = sessionId || getCurrentSessionId(cwd);
   if (!sid) return { error: 'No active session' };
@@ -183,35 +242,39 @@ function endTraceSession(cwd, sessionId) {
     let meta = {};
     try { meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8')); } catch {}
 
-    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 {}
-      });
-    } catch {}
-
+    const counts = reconcileSessionMeta(cwd, sid);
     meta.ended_at = new Date().toISOString();
-    meta.event_count = eventCount;
-    meta.agent_count = agentNames.size;
-    meta.agents = Array.from(agentNames);
-    meta.type_counts = typeCounts;
+    meta.event_count = counts.event_count;
+    meta.agent_count = counts.agent_count;
+    meta.agents = counts.agents;
+    meta.type_counts = counts.type_counts;
+    if (counts.malformed_count) meta.malformed_count = counts.malformed_count;
+
+    // Fold measured cost + commit count into the session so overhead.* metrics
+    // and `optimize stats` carry real dollars, not perpetual nulls.
+    const cc = computeSessionCostAndCommits(cwd, meta);
+    if (cc.cost_usd != null) meta.cost_usd = cc.cost_usd;
+    if (cc.commit_count != null) meta.commit_count = cc.commit_count;
 
     fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2) + '\n');
 
+    // Clear the active-session pointer so the next SubagentStop opens a fresh
+    // session — but ONLY when we ended the session it points at (ending session
+    // A explicitly must not orphan a different active session B).
+    try {
+      if (getCurrentSessionId(cwd) === sid) {
+        fs.unlinkSync(path.join(getOptimizeDir(cwd), CURRENT_SESSION_FILE));
+      }
+    } catch { /* best-effort */ }
+
     return {
       session_id: sid,
-      event_count: eventCount,
-      agent_count: agentNames.size,
-      type_counts: typeCounts,
+      event_count: counts.event_count,
+      agent_count: counts.agent_count,
+      type_counts: counts.type_counts,
+      malformed_count: counts.malformed_count,
+      cost_usd: meta.cost_usd != null ? meta.cost_usd : null,
+      commit_count: meta.commit_count != null ? meta.commit_count : null,
       ended_at: meta.ended_at,
     };
   } catch (e) {
@@ -219,6 +282,43 @@ function endTraceSession(cwd, sessionId) {
   }
 }
 
+/**
+ * Rewrite session.json from trace.jsonl WITHOUT ending the session (ended_at is
+ * left untouched). Powers `optimize trace reconcile`, so hook-driven auto-sessions
+ * that never call `end` still get accurate counters.
+ */
+function reconcileTraceSession(cwd, sessionId) {
+  const sid = sessionId || getCurrentSessionId(cwd);
+  if (!sid) return { error: 'No session to reconcile' };
+  try {
+    const metaPath = path.join(getTracesDir(cwd), sid, OPT_SESSION_FILE);
+    let meta = {};
+    try { meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8')); } catch {}
+    const counts = reconcileSessionMeta(cwd, sid);
+    meta.event_count = counts.event_count;
+    meta.agent_count = counts.agent_count;
+    meta.agents = counts.agents;
+    meta.type_counts = counts.type_counts;
+    if (counts.malformed_count) meta.malformed_count = counts.malformed_count;
+    fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2) + '\n');
+    return { session_id: sid, reconciled: true, event_count: counts.event_count, malformed_count: counts.malformed_count };
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+
+/** Reconcile every session dir (used by `optimize trace reconcile --all`). */
+function reconcileAllTraceSessions(cwd) {
+  const results = [];
+  try {
+    const tracesDir = getTracesDir(cwd);
+    for (const e of fs.readdirSync(tracesDir, { withFileTypes: true })) {
+      if (e.isDirectory() && e.name.startsWith('sess_')) results.push(reconcileTraceSession(cwd, e.name));
+    }
+  } catch { /* no traces dir */ }
+  return { reconciled: results.length, sessions: results };
+}
+
 function readTraceSession(cwd, sessionId) {
   try {
     const sessionDir = path.join(getTracesDir(cwd), sessionId);
@@ -229,14 +329,25 @@ function readTraceSession(cwd, sessionId) {
     } catch {}
 
     const events = [];
+    let malformed = 0;
     try {
       const raw = fs.readFileSync(path.join(sessionDir, TRACE_EVENT_FILE), 'utf-8');
       raw.trim().split('\n').filter(Boolean).forEach(line => {
-        try { events.push(JSON.parse(line)); } catch {}
+        try { events.push(JSON.parse(line)); } catch { malformed++; }
       });
     } catch {}
 
-    return { session_id: sessionId, metadata, events, event_count: events.length };
+    // Reconcile-on-read: an unfinalized meta (no ended_at) or a stale zero
+    // event_count is overlaid with the live counts derived from the events just
+    // read, so consumers of metadata (e.g. optimize stats) never see a stale 0.
+    if (!metadata.ended_at || !metadata.event_count) {
+      const typeCounts = {};
+      const agents = new Set();
+      for (const e of events) { typeCounts[e.type] = (typeCounts[e.type] || 0) + 1; if (e.agent) agents.add(e.agent); }
+      metadata = { ...metadata, event_count: events.length, agent_count: agents.size, agents: Array.from(agents), type_counts: typeCounts };
+    }
+
+    return { session_id: sessionId, metadata, events, event_count: events.length, malformed_count: malformed };
   } catch (e) {
     return { error: e.message };
   }
@@ -256,6 +367,14 @@ function listTraceSessions(cwd) {
       try {
         meta = JSON.parse(fs.readFileSync(path.join(sessionDir, OPT_SESSION_FILE), 'utf-8'));
       } catch {}
+      // Reconcile-on-read: unfinalized (no ended_at) or stale-zero sessions —
+      // every hook-driven auto-session — get live counts from trace.jsonl so
+      // getOptimizeStats doesn't sum perpetual zeros. Finalized sessions with a
+      // real count stay cheap (session.json read only).
+      if (!meta.ended_at || !meta.event_count) {
+        const counts = reconcileSessionMeta(cwd, e.name);
+        meta = { ...meta, event_count: counts.event_count, agent_count: counts.agent_count, agents: counts.agents, type_counts: counts.type_counts };
+      }
       return meta;
     }).sort((a, b) => (b.started_at || '').localeCompare(a.started_at || ''));
 
@@ -291,11 +410,18 @@ function analyzeEvents(events, sessionMeta) {
   const agentStats = {};
   events.forEach(e => {
     if (!e.agent) return;
-    if (!agentStats[e.agent]) agentStats[e.agent] = { total: 0, errors: 0, gaps: 0, corrections: 0 };
+    if (!agentStats[e.agent]) agentStats[e.agent] = { total: 0, errors: 0, gaps: 0, corrections: 0, input_tokens: 0, output_tokens: 0, total_tokens: 0 };
     agentStats[e.agent].total++;
     if (e.type === 'error') agentStats[e.agent].errors++;
     if (e.type === 'gap') agentStats[e.agent].gaps++;
     if (e.type === 'correction') agentStats[e.agent].corrections++;
+    // Sum the per-call tokens the trace logger now writes — ONLY on completion
+    // events, so the redundancy event that mirrors output_tokens isn't counted twice.
+    if (e.category === 'agent_completion' && e.context) {
+      agentStats[e.agent].input_tokens += e.context.input_tokens || 0;
+      agentStats[e.agent].output_tokens += e.context.output_tokens || 0;
+      agentStats[e.agent].total_tokens += e.context.total_tokens || ((e.context.input_tokens || 0) + (e.context.output_tokens || 0));
+    }
   });
 
   Object.keys(agentStats).forEach(a => {
@@ -305,9 +431,20 @@ function analyzeEvents(events, sessionMeta) {
 
   const wastedTokens = redundancies.reduce((sum, e) => sum + (e.tokens_wasted || 0), 0);
 
-  // ── Timing analysis from wall-clock timestamps ────────────────────────────
-  // Token data is unavailable (Claude Code SubagentStop doesn't populate usage).
-  // Use event timestamps + session start/end for meaningful timing analysis.
+  // Sum the authoritative per-call tokens (written by the SubagentStop hooks
+  // since v3.20.0) across completion events — the redundancy events mirror
+  // output_tokens, so restrict to agent_completion to avoid double-counting.
+  const completions = events.filter(e => e.category === 'agent_completion' && e.context);
+  const tokenTotals = completions.reduce((acc, e) => {
+    acc.input += e.context.input_tokens || 0;
+    acc.output += e.context.output_tokens || 0;
+    acc.cache_read += e.context.cache_read_tokens || 0;
+    return acc;
+  }, { input: 0, output: 0, cache_read: 0 });
+
+  // ── Timing analysis ───────────────────────────────────────────────────────
+  // Prefer measured per-agent duration_ms (hooks derive it from the transcript
+  // slice); fall back to the inter-event wall-clock gap when it's absent.
   const timing = {};
 
   // Session total duration
@@ -381,6 +518,10 @@ function analyzeEvents(events, sessionMeta) {
       wasted_tokens: wastedTokens,
       reviewer_corrections: reviewerCorrections.length,
       memory_primed_count: memoryPrimed.length,
+      total_input_tokens: tokenTotals.input,
+      total_output_tokens: tokenTotals.output,
+      total_cache_read_tokens: tokenTotals.cache_read,
+      total_tokens: tokenTotals.input + tokenTotals.output,
     },
     timing,
     overhead,
@@ -405,11 +546,21 @@ function generateLocalReport(cwd, sessionId) {
   const session = readTraceSession(cwd, sessionId);
   if (session.error) return session;
 
+  // Fold measured cost + commit count into the metadata before analysis so the
+  // autonomous-overhead metrics populate even for hook-driven auto-sessions that
+  // never call `optimize trace end`. Only fill fields a producer didn't set.
+  const metadata = session.metadata || {};
+  if (typeof metadata.cost_usd !== 'number' || typeof metadata.commit_count !== 'number') {
+    const cc = computeSessionCostAndCommits(cwd, metadata);
+    if (typeof metadata.cost_usd !== 'number' && cc.cost_usd != null) metadata.cost_usd = cc.cost_usd;
+    if (typeof metadata.commit_count !== 'number' && cc.commit_count != null) metadata.commit_count = cc.commit_count;
+  }
+
   return {
     session_id: sessionId,
     generated_at: new Date().toISOString(),
-    metadata: session.metadata,
-    ...analyzeEvents(session.events, session.metadata),
+    metadata,
+    ...analyzeEvents(session.events, metadata),
     raw_events: session.events,
   };
 }
@@ -622,8 +773,12 @@ function cmdOptimizeTrace(cwd, sub, opts, raw) {
   } else if (sub === 'show') {
     if (!opts.sessionId) { output({ error: 'Session ID required (--session <id>)' }, raw); return; }
     output(readTraceSession(cwd, opts.sessionId), raw);
+  } else if (sub === 'reconcile') {
+    // Rewrite session.json counters from trace.jsonl without ending the session,
+    // so hook-driven auto-sessions that never call `end` still report real numbers.
+    output(opts.all ? reconcileAllTraceSessions(cwd) : reconcileTraceSession(cwd, opts.sessionId), raw);
   } else {
-    output({ error: 'Unknown trace subcommand. Available: init, log, end, current, list, show' }, raw);
+    output({ error: 'Unknown trace subcommand. Available: init, log, end, current, list, show, reconcile' }, raw);
   }
 }
 
@@ -1087,6 +1242,10 @@ module.exports = {
   endTraceSession,
   readTraceSession,
   listTraceSessions,
+  reconcileSessionMeta,
+  reconcileTraceSession,
+  reconcileAllTraceSessions,
+  computeSessionCostAndCommits,
   // Analysis
   analyzeEvents,
   generateLocalReport,

package/pan-wizard-core/bin/pan-tools.cjs

@@ -1297,6 +1297,7 @@ async function main() {
         const traceSub = args[2];
         optimize.cmdOptimizeTrace(cwd, traceSub, {
           sessionId: getArgValue(args, '--session'),
+          all: args.includes('--all'),
           description: getArgValue(args, '--description'),
           command: getArgValue(args, '--command'),
           phase: getArgValue(args, '--phase'),