pan-wizard 3.28.0 → 3.30.0

package/hooks/dist/pan-stop-guard.js

@@ -39,6 +39,19 @@
 // per stop chain, so a user who genuinely wants to stop is delayed by exactly
 // one continuation, never trapped.
 //
+// Gemini CLI (R29, 2026-09-23): the guard is registered there on AfterAgent,
+// Gemini's end-of-turn event — until this date PAN registered it under Claude's
+// `Stop` key, which Gemini skips with an "Invalid hook event name" warning, so it
+// had never run. AfterAgent honours the same {decision: 'block', reason} output
+// (a block re-prompts the agent with the reason), but its stop_hook_active is only
+// true for the AfterAgent that evaluates a continuation the block started
+// directly: a continuation that used tools reports false again (gemini-cli
+// client.ts / useGeminiStream.ts, read 2026-09-23). The flag alone would let the
+// guard block every such turn. So on AfterAgent the one-shot promise is kept with
+// a marker per session, project and target phase in the per-user 0700 hook
+// directory: a second stop aimed at the same phase is allowed. No safe marker
+// directory, or no session id, means no block (fail open, as everywhere else).
+//
 // Escape hatch: set workflow.stop_guard to false in .planning/config.json to
 // disable the guard entirely without turning off auto_advance.
 //
@@ -51,7 +64,9 @@
 // rather than only reachable via stdin (same pattern as the other PAN hooks).
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
+const crypto = require('crypto');
 /**
  * Which planning tree this hook acts on.
  *
@@ -155,6 +170,63 @@ function readIfExists(p) {
   try { return fs.readFileSync(p, 'utf8'); } catch { return null; }
 }
 
+// Per-user hook state directory inside tmpdir, created 0700 — the same directory
+// and the same checks as bridgeDir() in pan-context-monitor.js (hooks are
+// standalone files and cannot require one another). Fail CLOSED (null) when the
+// directory is not provably ours: a shared host must not be able to pre-plant a
+// marker that silences the guard, or a symlink it writes through (M60).
+function hookStateDir() {
+  const uid = (typeof process.getuid === 'function' ? process.getuid() : process.env.USERNAME || 'win');
+  const dir = path.join(os.tmpdir(), `pan-hooks-${uid}`);
+  try {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const st = fs.lstatSync(dir);
+    if (st.isSymbolicLink()) return null;
+    // POSIX-only ownership and mode checks: Windows fakes mode bits (N15).
+    if (typeof process.getuid === 'function') {
+      if (st.uid !== process.getuid()) return null;
+      if ((st.mode & 0o077) !== 0) return null;
+    }
+    return dir;
+  } catch { return null; }
+}
+
+/**
+ * The file name of the one-shot marker for an AfterAgent block (Gemini CLI).
+ * Keyed by session, project and the block's reason — the reason names the target
+ * phase, so a later drop at a DIFFERENT phase in the same session is still caught.
+ * Pure; null when there is no session id to key on.
+ */
+function onceMarkerName(sessionId, projectDir, reason) {
+  if (typeof sessionId !== 'string' || !sessionId) return null;
+  const key = crypto.createHash('sha256').update(`${sessionId}\0${projectDir}\0${reason}`).digest('hex').slice(0, 32);
+  return `stop-guard-${key}.json`;
+}
+
+const MARKER_MAX_AGE_MS = 7 * 24 * 3600 * 1000;
+
+/**
+ * Apply the AfterAgent one-shot rule: returns true when this block may be issued
+ * (and records it), false when the same session already got it or no safe place
+ * to remember it exists. Best-effort pruning keeps the directory from growing.
+ */
+function claimOnceMarker(dir, name, now = Date.now()) {
+  if (!dir || !name) return false;
+  const marker = path.join(dir, name);
+  try {
+    for (const f of fs.readdirSync(dir)) {
+      if (!/^stop-guard-[0-9a-f]{32}\.json$/.test(f)) continue;
+      try { if (now - fs.statSync(path.join(dir, f)).mtimeMs > MARKER_MAX_AGE_MS) fs.unlinkSync(path.join(dir, f)); } catch { /* keep */ }
+    }
+  } catch { /* unreadable dir — the exclusive create below still decides */ }
+  try {
+    // 'wx' fails when the marker exists: the create IS the check, so two hook
+    // processes racing on the same stop cannot both block.
+    fs.writeFileSync(marker, JSON.stringify({ at: new Date(now).toISOString() }), { flag: 'wx', mode: 0o600 });
+    return true;
+  } catch { return false; }
+}
+
 function main() {
   let input = '';
   process.stdin.setEncoding('utf8');
@@ -171,13 +243,20 @@ function main() {
       let config = null;
       try { config = JSON.parse(fs.readFileSync(path.join(planningDir, 'config.json'), 'utf8')); } catch { /* no project / bad config -> allow */ }
 
-      const decision = buildStopDecision({
+      let decision = buildStopDecision({
         stopHookActive: payload.stop_hook_active === true,
         config,
         stateContent: readIfExists(path.join(planningDir, 'state.md')),
         roadmapContent: readIfExists(path.join(planningDir, 'roadmap.md')),
       });
 
+      // Gemini CLI's end-of-turn event: its stop_hook_active cannot carry the
+      // one-shot promise on its own (see the header), so a marker does.
+      if (decision && payload.hook_event_name === 'AfterAgent') {
+        const name = onceMarkerName(payload.session_id, projectDir, decision.reason);
+        if (!claimOnceMarker(hookStateDir(), name)) decision = null;
+      }
+
       if (decision) process.stdout.write(JSON.stringify(decision));
     } catch { /* fail open — never break a stop */ }
     process.exit(0);
@@ -188,4 +267,4 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { buildStopDecision, UNTICKED_PHASE_RE };
+module.exports = { buildStopDecision, UNTICKED_PHASE_RE, onceMarkerName, claimOnceMarker };

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

@@ -51,7 +51,13 @@ function planningPath(cwd, ...segments) {
 }
 
 // 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}`);
 
 // M62: only instrument actual PAN projects. A global-install hook fires in EVERY
 // repo the user opens; without this gate it silently creates .planning/
@@ -77,6 +83,23 @@ function isPanProject(cwd) {
 // Resolved per call via planningDirName() so a track-scoped run traces into
 // its own tree; kept as a name for the code paths that only need the label.
 const PLANNING_DIR = planningDirName();
+
+// 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 OPTIMIZE_DIR = 'optimization';
 const TRACES_DIR = 'traces';
 const CURRENT_SESSION_FILE = 'current-session';
@@ -84,8 +107,9 @@ const TRACE_EVENT_FILE = 'trace.jsonl';
 
 // Trace event schema version — kept in sync by hand with pan-cost-logger.js
 // (standalone zero-dep hooks can't share a module). v3 added the per-invocation
-// `event_sig` discriminator to the completion event's context. See that file.
-const SCHEMA_V = 3;
+// `event_sig` discriminator to the completion event's context; v4 added
+// `agent_id` and the `agent-transcript` token source. See that file.
+const SCHEMA_V = 4;
 
 // YYYYMMDD stamp for a Date (the day-scope of an auto-session id).
 function dayStamp(d) {
@@ -145,6 +169,113 @@ function finalizeSession(cwd, sid) {
   } catch { /* best-effort */ }
 }
 
+// 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, and Claude Code after --unified-skills). 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;
+  }
+}
+
+// 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;
+}
+
 function getOptimizeDir(cwd) {
   return path.join(cwd, PLANNING_DIR, OPTIMIZE_DIR);
 }
@@ -290,14 +421,19 @@ function addSeenSig(cursor, transcriptPath, sig) {
   for (let i = 0; i < keys.length - MAX_SEEN_TRANSCRIPTS; i++) delete se[keys[i]];
 }
 
+// Cursor path keys: with per-agent transcripts every spawn adds a key that lives as
+// long as Claude Code keeps the file, so existence-pruning alone no longer bounds
+// the map (L40). Keep the most recently written keys (mirrors pan-cost-logger).
+const MAX_CURSOR_KEYS = 512;
+
 function writeTraceCursor(cwd, cursor) {
   try {
-    // Prune dead-transcript keys so the cursor map stays bounded (L40, ADR audit 2026-08).
+    // Prune dead-transcript keys, then keep only the newest MAX_CURSOR_KEYS so the
+    // cursor map stays bounded (L40, ADR audit 2026-08). Insertion order is write
+    // order — a key is re-inserted when advanced.
     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));
+    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 (N27); bounded by count instead (L40).
@@ -327,11 +463,15 @@ function ensureSessionId(cwd) {
   const stamp = dayStamp(now); // YYYYMMDD
   const existing = getCurrentSessionId(cwd);
   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.
+    // 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. An EXPLICIT session
+    // used to stay sticky with no bound at all, which is how a field project was still
+    // pointing at a 17 July session on 17 September; it now rolls over once it has been
+    // quiet for SESSION_STALE_MS, so "sticky while in use" no longer means "forever".
     const m = /^sess_auto_(\d{8})$/.exec(existing);
-    if (m && m[1] !== stamp) {
+    const dir = path.join(getTracesDir(cwd), existing);
+    const stale = isSessionStale(dir, readSessionMetaById(cwd, existing));
+    if ((m && m[1] !== stamp) || stale) {
       finalizeSession(cwd, existing);
       // fall through to mint a new day-scoped session below
     } else {
@@ -375,6 +515,54 @@ function clampPlausible(n) {
   return typeof n === 'number' && n >= 0 && n <= PLAUSIBLE_MAX ? n : 0;
 }
 
+// Per-agent transcript resolution — mirrors pan-cost-logger.js (the hooks are
+// standalone and cannot share a module; keep the two in sync by hand). On
+// SubagentStop the host hands over the PARENT session transcript plus the
+// subagent's `agent_id`; the subagent's own conversation lives beside it as
+// `<parent dir>/<session_id>/subagents/agent-<agent_id>.jsonl`. Slicing the
+// parent per event attributed the session's usage to whichever subagent stopped
+// next, so the agent file is preferred whenever it exists. 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');
+    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;
+    // Workflow-tool subagents live one level down: subagents/workflows/<wf_id>/.
+    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;
+  }
+}
+
+// Slice ceilings — a sum over one subagent's conversation, so above a single
+// call's PLAUSIBLE_MAX; cache_read and output mirror cost.cjs isSuspectRecord's
+// absolute limits, input is a hook-only sanity ceiling (same values as
+// pan-cost-logger's SLICE_MAX). A value past its ceiling is a session's cumulative
+// usage that leaked into the slice — drop it to 0 and flag the event. The span
+// is recorded as measured; the reader's six-hour rule judges it.
+const SLICE_MAX = { input: 2e7, output: 1e7, cache_read: 5e8 };
+function clampSlice(n, max) {
+  return typeof n === 'number' && n >= 0 && n <= 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
@@ -413,6 +601,12 @@ function readUsageFromTranscript(transcriptPath, sessionId, sinceLine = 0) {
     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 record
+  // per content block, each repeating the turn's `message.id` with a usage
+  // snapshot (the last block's holds the final counts). Key by id, last wins;
+  // records without an id are summed as they come. Mirrors pan-cost-logger.
+  const byMessage = new Map();
+  let unkeyed = 0;
   for (const line of raw.split('\n')) {
     if (!line) continue;
     seen++;
@@ -425,7 +619,14 @@ 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;
+    // 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) 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;
@@ -442,6 +643,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');
@@ -487,23 +694,47 @@ function buildTraceEvents(data, sessionId, cwd) {
   let outputTokens = 0;
   let cacheRead = 0;
   let durationMs = null;
-  let tokenSource = data.transcript_path ? 'transcript' : 'usage-fallback';
+  // `agent-transcript` when the subagent's own conversation file was sliced,
+  // `transcript` for a slice of the shared parent transcript (the fallback when
+  // the host names no agent), `usage-fallback` for the payload's own counters.
+  const agentTranscript = resolveAgentTranscript(data);
+  const parentPath = typeof data.transcript_path === 'string' && data.transcript_path ? data.transcript_path : null;
+  // A named agent whose file is not there consumes nothing (see pan-cost-logger:
+  // the parent slice would be the whole session booked to one spawn).
+  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';
+  const agentId = typeof data.agent_id === 'string' && data.agent_id ? data.agent_id : null;
   let clamped = false;
-  if (data.transcript_path) {
+  if (sliceSource || agentFileMissing) {
+    const keyPath = sliceSource || parentPath;
     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);
+    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;
+    inputTokens = clampSlice(rawIn, SLICE_MAX.input);
+    outputTokens = clampSlice(rawOut, SLICE_MAX.output);
+    cacheRead = clampSlice(rawCr, SLICE_MAX.cache_read);
+    clamped = rawIn > SLICE_MAX.input || rawOut > SLICE_MAX.output || rawCr > SLICE_MAX.cache_read;
+    durationMs = durationFromSpan(fromTranscript.first_ts, fromTranscript.last_ts); // as measured
     if (!model) model = fromTranscript.model;
     if (cwd && fromTranscript.lineCount > since) {
       // A real slice. Advance the cursor and 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);
+      // Re-insert so insertion order tracks write order (writeTraceCursor keeps
+      // the newest keys).
+      delete cursor[keyPath];
+      cursor[keyPath] = fromTranscript.lineCount;
+      addSeenSig(cursor, keyPath, eventSig);
       writeTraceCursor(cwd, cursor);
     } else if (cwd && fromTranscript.lineCount <= since) {
       // No transcript records past the cursor: this event consumed NO slice of its
@@ -522,12 +753,13 @@ function buildTraceEvents(data, sessionId, cwd) {
       // The full-payload signature distinguishes them (N25/N26): emit nothing
       // ONLY when this exact payload was already seen for this transcript;
       // otherwise fall through and emit the completion.
-      if (eventSig && getSeenSigs(cursor, data.transcript_path).includes(eventSig)) {
+      if (eventSig && getSeenSigs(cursor, keyPath).includes(eventSig)) {
         return []; // already-seen event → re-fire; emit nothing (M61)
       }
-      // Sibling / first-fire: remember this event's signature so its own re-fire
-      // is subsequently dropped, then fall through to emit the completion.
-      addSeenSig(cursor, data.transcript_path, eventSig);
+      // Sibling / first-fire / named-but-missing agent file: remember this
+      // event's signature so its own re-fire is subsequently dropped, then fall
+      // through to emit the completion.
+      addSeenSig(cursor, keyPath, eventSig);
       writeTraceCursor(cwd, cursor);
     }
   } else {
@@ -561,7 +793,10 @@ function buildTraceEvents(data, sessionId, cwd) {
     description: `${agent} completed`,
     context: {
       model,
-      command: data.command || sessionMeta.command || null,
+      // Outside focus mode the trace session carries no command; the parent transcript
+      // names it instead (see readCommandFromTranscript).
+      command: data.command || sessionMeta.command || readCommandFromTranscript(data.transcript_path) || null,
+      agent_id: agentId,
       input_tokens: inputTokens,
       output_tokens: outputTokens,
       cache_read_tokens: cacheRead,
@@ -593,8 +828,10 @@ function buildTraceEvents(data, sessionId, cwd) {
   });
 
   // Heuristic: if output tokens > 3000 and no cache hits, flag as potential redundancy
-  // (expensive agent run that wasn't cached — may be repeated research)
-  if (outputTokens > 3000 && cacheRead === 0) {
+  // (expensive agent run that wasn't cached — may be repeated research). A zero
+  // the plausibility guard produced is not a cache miss, so a clamped event never
+  // trips it.
+  if (outputTokens > 3000 && cacheRead === 0 && !clamped) {
     events.push({
       v: SCHEMA_V,
       ts,
@@ -696,8 +933,9 @@ if (require.main === module) {
       const data = JSON.parse(input);
       const cwd = data.cwd || data.workspace?.current_dir || process.cwd();
       // M62: a global-install hook fires in every repo; skip non-PAN projects so
-      // we don't create .planning/ optimization + trace artifacts in them.
-      if (!isPanProject(cwd)) return;
+      // we don't create .planning/ optimization + trace artifacts in them. The tree
+      // must already exist — see hasPlanningTree (field sweep 2026-09-17).
+      if (!hasPlanningTree(cwd)) return;
       // In a PAN project, ensure a session exists — creates a day-scoped
       // auto-session if needed.
       const sessionId = ensureSessionId(cwd);
@@ -712,9 +950,14 @@ if (require.main === module) {
 module.exports = {
   buildTraceEvents,
   appendTraceEvents,
+  resolveAgentTranscript,
   getCurrentSessionId,
   ensureSessionId,
   isPanProject,
+  hasPlanningTree,
+  PAN_RUNTIME_DIRS,
+  readCommandFromTranscript,
+  isSessionStale,
   PLANNING_DIR,
   OPTIMIZE_DIR,
   TRACES_DIR,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pan-wizard",
-  "version": "3.28.0",
+  "version": "3.30.0",
   "description": "Command a bot army for your codebase: a reasoning-tier 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"
@@ -70,6 +70,9 @@
     "test:e2e": "node scripts/run-tests.cjs tests/scenarios",
     "test:vscode": "npx playwright test --config tests/e2e/playwright.config.mjs",
     "test:watch": "node scripts/run-tests.cjs --watch tests tests/scenarios",
+    "test:coverage": "node scripts/coverage-gate.cjs",
+    "test:surface": "node scripts/test-surface.cjs --check",
+    "test:mutate": "node scripts/mutation-probe.cjs",
     "build:plugin": "node scripts/build-plugin.js",
     "build:agent-plugin": "node scripts/build-agent-plugin.js",
     "harness": "node harness/src/run.cjs --tier 0",

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

@@ -2,8 +2,9 @@
 
 // ─── 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
+// AGENTS.md is the cross-runtime project-instructions standard; Codex,
+// OpenCode and Copilot CLI read it natively, Claude Code only through the @AGENTS.md
+// import in CLAUDE.md; Gemini CLI reads GEMINI.md by default, not this file. 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.
 //

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

@@ -428,7 +428,9 @@ function cmdCommit(cwd, message, files, raw, amend, opts) {
   const commitArgs = amend ? ['commit', '--amend', '--no-edit'] : ['commit', '-m', finalMessage];
   const commitResult = execGit(cwd, commitArgs);
   if (commitResult.exitCode !== 0) {
-    if (commitResult.stdout.includes('nothing to commit') || commitResult.stderr.includes('nothing to commit')) {
+    // Both of git's phrasings — see the matching guard in git.cjs cmdGitCommit.
+    if ((commitResult.stdout + commitResult.stderr).includes('nothing to commit')
+      || (commitResult.stdout + commitResult.stderr).includes('nothing added to commit')) {
       output({ committed: false, hash: null, reason: 'nothing_to_commit' }, raw, 'nothing');
       return;
     }

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

@@ -670,6 +670,22 @@ const CACHEABLE_CONTEXT_FILES = [
   'state.md',
   'standards.md',
 ];
+/**
+ * Which workflow model a `.planning/` tree is running, by the entries only that model
+ * creates. PAN has three: the PHASE model (`/pan:new-project` → project/roadmap/state
+ * → phases), the FOCUS model (`/pan:focus` → .planning/focus/, no phase spine), and an
+ * orchestration CAMPAIGN. A tree with none of these holds only generated artifacts
+ * (metrics, traces, codebase maps) — a fragment, typically scaffolded by a hook.
+ * Checks that belong to one model must not be run against another: a focus-model
+ * project has no project.md by design, and reporting that as an error called eight of
+ * fourteen field projects broken (field sweep 2026-09-17).
+ */
+const PLANNING_MODEL_MARKERS = {
+  phase: ['project.md', 'roadmap.md', 'state.md', 'requirements.md', 'phases', 'milestones'],
+  focus: ['focus', 'quick'],
+  campaign: ['orchestration'],
+};
+
 /** Default thinking budget (tokens) for verification-heavy agents */
 const THINKING_BUDGETS = {
   'pan-plan-checker': 8000,
@@ -796,6 +812,7 @@ module.exports = {
   LARGE_CONTEXT_TOKEN_THRESHOLD,
   SMALL_CONTEXT_TOKEN_THRESHOLD,
   CACHEABLE_CONTEXT_FILES,
+  PLANNING_MODEL_MARKERS,
   THINKING_BUDGETS,
   REFLECTION_THRESHOLD,
   CONTEXT_WINDOW,