pan-wizard 3.21.1 → 3.24.0

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

@@ -15,16 +15,44 @@
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
+
+// Runtime config dirs a local PAN install lands in (mirrors installer getDirName).
+const PAN_RUNTIME_DIRS = ['.claude', '.codex', '.gemini', '.opencode', '.github'];
+
+// M62: only instrument actual PAN projects. A global-install hook fires in EVERY
+// repo the user opens; without this gate it silently creates .planning/ metrics
+// artifacts in non-PAN repos. A project counts as PAN if it already has a
+// .planning/ tree (a /pan command created it) OR carries a local PAN install
+// (a manifest / core payload under a runtime config dir — covers a fresh local
+// install before any .planning/ exists). Global installs in a plain repo match
+// neither, so the hook no-ops. Best-effort — never throws.
+function isPanProject(cwd) {
+  try {
+    if (!cwd) return false;
+    if (fs.existsSync(path.join(cwd, '.planning'))) return true;
+    for (const d of PAN_RUNTIME_DIRS) {
+      if (fs.existsSync(path.join(cwd, d, 'pan-file-manifest.json'))) return true;
+      if (fs.existsSync(path.join(cwd, d, 'pan-wizard-core'))) return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
 
 const METRICS_DIR = 'metrics';
 const TOKENS_FILE = 'tokens.jsonl';
 const CURSOR_FILE = '.cost-cursor.json';
 
 // Ledger row schema version. Bump when the record shape changes so readers can
-// tell which shape a row was written in (pre-versioned rows read as v1). 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;
+// tell which shape a row was written in (pre-versioned rows read as v1); v3 added
+// the per-invocation `event_sig` discriminator. Kept as a literal in each hook —
+// they are standalone zero-dep scripts that can't import from pan-wizard-core, so
+// the two hooks must stay in sync by hand. No constant in pan-wizard-core mirrors
+// it: the readers there take a row field by field rather than switching on its
+// version, so an added field is additive for them.
+const SCHEMA_V = 3;
 
 // 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
@@ -77,10 +105,161 @@ function readCursor(cwd) {
     return c && typeof c === 'object' ? c : {};
   } catch { return {}; }
 }
+
+// N17/N25-N27: reserved key in the cursor map recording, per transcript, the
+// SIGNATURES of recently-seen SubagentStop events. An empty-slice event is a
+// true re-fire / dual-registration ONLY when its full-payload signature was
+// already seen for that transcript; a PARALLEL SIBLING (any payload difference)
+// or a FIRST FIRE (missing/unreadable transcript, since===0) carries a new
+// signature and must be recorded, not dropped. A bounded FIFO SET rather than a
+// single slot (N25): a sibling recorded in between can no longer evict the
+// signature that identifies an earlier event's re-fire. Bounded by COUNT, not
+// by transcript existence, so the L40 dead-transcript prune can no longer erase
+// the live marker of a missing-transcript first fire in the very write meant to
+// persist it (N27). The name can never collide with a transcript path (an
+// absolute file path).
+const SEEN_EVENTS = '__seenEvents';
+// Pre-N25 single-slot marker — no longer read; dropped on the next write
+// (self-migrating, no reader of the old shape exists outside this hook).
+const LEGACY_CONSUME_KEYS = '__consumeKeys';
+// Bounds (L40): at most MAX_SEEN_TRANSCRIPTS transcripts x MAX_SEEN_SIGS
+// signatures (~40 chars each) — a few KB worst-case. FIFO eviction on both axes.
+// This window is the ONLY layer that recognizes a re-fire which is no longer
+// ADJACENT to the row it duplicates: the ledger dedup below compares against the
+// immediately preceding row and nothing further. A sibling wave wider than
+// MAX_SEEN_SIGS on one transcript therefore evicts the earliest sibling's
+// signature, and a late re-fire of THAT sibling is admitted as a phantom row.
+// That residual is accepted deliberately, not overlooked — see eventSignature
+// below for what widening either window was measured to cost.
+const MAX_SEEN_SIGS = 8;
+const MAX_SEEN_TRANSCRIPTS = 16;
+
+// Signature of a SubagentStop event: a hash of the FULL payload as delivered.
+// A dual-registration re-fire is byte-identical on stdin (the host pipes the
+// same JSON to every registration of one event), so its signature matches. A
+// parallel sibling is distinguished by ANY differing payload field, without
+// hardcoding which field a given runtime provides (N26).
+//
+// WHICH fields actually differ on real payloads is only partly established, so
+// the sibling-admission benefit is CONDITIONAL. What this repo has observed:
+//   • `agent_type` / `subagent_type` is supplied and does vary between siblings
+//     of DIFFERENT type — the trace rows recorded under
+//     experiments/*/.planning/optimization/traces/ were written by the sibling
+//     hook from real payloads and carry real agent names. Different-type
+//     siblings are therefore always separable.
+//   • `session_id` is SHARED with the parent, and so is the session transcript
+//     (docs/FIELD-REPORT-army-2026-06.md, root cause 1) — neither is
+//     per-invocation.
+//   • `model` and `phase` came out null in those recorded rows: the payload
+//     carried neither.
+//   • `usage` is absent entirely in headless mode (docs/HOOKS.md, P-1805).
+//   • No recorded payload in this repo carries an `agent_id` or any other
+//     per-invocation id. `grep -rn agent_id hooks/ pan-wizard-core/ tests/`
+//     finds only PAN's own agent-tracking artifacts (written by workflows) and
+//     the hook tests, which inject one as a stand-in.
+// So for two CONCURRENT SAME-TYPE siblings no varying payload field is
+// confirmed on any host. Where the host supplies one, both spawns are admitted;
+// where it supplies none the two payloads are the same bytes, hence
+// informationally indistinguishable from a re-fire, and the second stays
+// suppressed.
+//
+// What the guards promise, stated as narrowly as they hold: a re-fire is
+// suppressed while it is still RECOGNIZABLE — its signature is in this
+// transcript's seen-event window (MAX_SEEN_SIGS), or it is byte-identical modulo
+// `ts` to the row IMMEDIATELY PRECEDING it in the ledger. Nothing further. A
+// re-fire arriving after its signature has been evicted from the marker window,
+// and not adjacent to the row it duplicates, IS admitted as a phantom row. That
+// is the residual; it is documented rather than engineered away.
+//
+// It was engineered away once, and the cure destroyed data. The ledger dedup was
+// widened to scan a tail of recent rows, with a second prong matching on a
+// repeated signature alone for rows carrying no tokens. Both prongs delete real
+// spawns. Five genuine spawns X,Y,X,Y,X on one shared transcript — the ordinary
+// shared-session topology of docs/FIELD-REPORT-army-2026-06.md, where sequential
+// same-type subagents deliver byte-identical payloads and therefore one
+// signature — collapsed to TWO rows; when their slices carried real usage the
+// collapsed rows' token counts vanished with them. Deleting real cost data is
+// strictly worse than the occasional phantom row it prevents. The invariant that
+// justified the contentless prong ("an event that consumed a real transcript
+// slice never looks contentless") is also false: a slice of records that carry
+// no `usage` and no `timestamp` yields zero on every axis and a null duration.
+// So the dedup stays adjacent-only, and this comment states the residual instead
+// of an invariant the code does not hold. Pinned in
+// tests/cost-logger-hook.test.cjs — `grep -n 'no genuine spawn' tests/cost-logger-hook.test.cjs`.
+//
+// The NO-transcript path carries a wider residual: it never consults the marker
+// layer at all (there is no transcript to key it by), so an INTERLEAVED dual
+// registration there — A, B, A′, B′ — puts A′ and B′ out of adjacency reach and
+// both are admitted as phantom rows. Closing that needs a lookback, and a
+// lookback is the window whose failure mode is the data loss above, so it stays
+// open.
+//
+// Where the guards CAN distinguish two events (their payloads differ, so their
+// signatures differ) both are recorded — that is what the row's `event_sig`
+// exists for. Where they CANNOT (identical bytes), the second is suppressed.
+// So the bias falls on the indistinguishable case only, and it is deliberate:
+// an undercounted spawn beats a phantom row for cost reporting (N29).
+//
+// The cost of that bias, stated plainly because no other comment admits it:
+// two SEQUENTIAL genuine spawns whose rows coincide in every field but `ts` —
+// same agent, same tokens, same span — collapse to one row, and the second
+// spawn's real tokens are lost. This is inherent to an adjacent whole-row
+// dedup, predates `event_sig`, and is identical in the pre-`event_sig` code;
+// removing the dedup instead reinstates the duplicate-row field bug it was
+// added for. It is the one UNDER-count residual, distinct from the evicted-
+// marker phantom (an over-count) and from N29 (concurrent same-type siblings).
+//
+// Returns null when the payload cannot be serialized — callers then fail OPEN
+// (record, never mark).
+function eventSignature(data) {
+  try {
+    return crypto.createHash('sha1').update(JSON.stringify(data)).digest('hex');
+  } catch { return null; }
+}
+
+function getSeenSigs(cursor, transcriptPath) {
+  const se = cursor && cursor[SEEN_EVENTS];
+  const arr = se && typeof se === 'object' ? se[transcriptPath] : null;
+  return Array.isArray(arr) ? arr : [];
+}
+function addSeenSig(cursor, transcriptPath, sig) {
+  if (!sig) return; // unhashable payload → never mark (fail open to recording)
+  if (!cursor[SEEN_EVENTS] || typeof cursor[SEEN_EVENTS] !== 'object') cursor[SEEN_EVENTS] = {};
+  const se = cursor[SEEN_EVENTS];
+  const arr = Array.isArray(se[transcriptPath]) ? se[transcriptPath].filter((s) => s !== sig) : [];
+  arr.push(sig);
+  while (arr.length > MAX_SEEN_SIGS) arr.shift(); // FIFO — evict the oldest signature
+  delete se[transcriptPath]; // re-insert so key order tracks recency for the transcript cap
+  se[transcriptPath] = arr;
+  const keys = Object.keys(se);
+  for (let i = 0; i < keys.length - MAX_SEEN_TRANSCRIPTS; i++) delete se[keys[i]];
+}
+
 function writeCursor(cwd, cursor) {
   try {
+    // Prune cursor keys for transcripts that no longer exist so the map can't
+    // grow without bound over a long-lived project (L40, ADR audit 2026-08).
+    const pruned = {};
+    for (const [tp, v] of Object.entries(cursor)) {
+      if (tp === SEEN_EVENTS || tp === LEGACY_CONSUME_KEYS) continue; // reserved markers — not paths
+      if (tp && fs.existsSync(tp)) pruned[tp] = v;
+    }
+    // Preserve the seen-event marker (N17/N25-N27). Deliberately NOT pruned by
+    // transcript existence — a missing-transcript first fire's marker must
+    // survive this very write, or its re-fire is re-admitted as a phantom row
+    // (N27). Bounded by count instead (FIFO on both axes), which keeps the file
+    // strictly bounded per L40.
+    const se = cursor[SEEN_EVENTS];
+    if (se && typeof se === 'object') {
+      const bounded = {};
+      for (const tp of Object.keys(se).slice(-MAX_SEEN_TRANSCRIPTS)) {
+        const arr = se[tp];
+        if (Array.isArray(arr) && arr.length) bounded[tp] = arr.slice(-MAX_SEEN_SIGS);
+      }
+      if (Object.keys(bounded).length) pruned[SEEN_EVENTS] = bounded;
+    }
     fs.mkdirSync(path.dirname(cursorFilePath(cwd)), { recursive: true });
-    fs.writeFileSync(cursorFilePath(cwd), JSON.stringify(cursor), 'utf-8');
+    fs.writeFileSync(cursorFilePath(cwd), JSON.stringify(pruned), 'utf-8');
   } catch { /* best-effort — never block the agent loop */ }
 }
 
@@ -117,6 +296,17 @@ function buildCostRecord(data, cwd) {
   // from a genuine zero-token run.
   let tokenSource = data.transcript_path ? 'transcript' : 'usage-fallback';
   let clamped = false;
+  // Set when a transcript-sourced event consumed no new records AND is an
+  // identical re-fire / dual-registration. Carried on the returned record as a
+  // transient flag so appendRecord can drop the phantom row; never written to
+  // the ledger (M61).
+  let emptySlice = false;
+  const agent = data.agent_type || data.subagent_type || null;
+  // This event's per-invocation identity, hashed once and used by BOTH layers:
+  // the seen-event marker below and the `event_sig` row field further down.
+  // buildCostRecord never mutates `data`, so hoisting the hash here yields the
+  // same value the marker calls used when they each computed it themselves.
+  const eventSig = eventSignature(data);
   if (data.transcript_path) {
     const cursor = readCursor(cwd);
     const since = cursor[data.transcript_path] || 0;
@@ -127,11 +317,42 @@ function buildCostRecord(data, cwd) {
     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.
     if (fromTranscript.lineCount > since) {
+      // A real slice. Advance the cursor so the next subagent's record starts
+      // fresh — the slices partition the transcript, so it is never re-summed on
+      // every event. Remember this event's signature (N17/N25) so a later
+      // empty-slice event can tell its re-fire from a parallel sibling — even
+      // when other siblings are recorded in between (N25).
       cursor[data.transcript_path] = fromTranscript.lineCount;
+      addSeenSig(cursor, data.transcript_path, eventSig);
       writeCursor(cwd, cursor);
+    } else {
+      // No transcript records past the cursor: this event consumed NO slice of
+      // its own. Two very different situations land here (N17):
+      //   • A re-fire / dual global+local hook registration — the SAME event
+      //     delivered again (byte-identical payload). Its all-zero row is a
+      //     phantom the ledger dedup cannot catch — the zeros differ from the
+      //     real row the re-fire follows — so flag it and let appendRecord drop
+      //     it (M61). This marker is the ONLY layer that catches that case; there
+      //     is no signature-matching backstop below it, by design (see
+      //     eventSignature).
+      //   • A PARALLEL SIBLING (another subagent — same or different type — whose
+      //     sibling already consumed the shared transcript to EOF and advanced
+      //     this shared cursor) or a FIRST FIRE whose transcript_path is
+      //     missing/unreadable (lineCount=0, since=0). These are legitimate
+      //     spawns that must be RECORDED with zero tokens, not dropped —
+      //     dropping them undercounts /pan:cost.
+      // The full-payload signature distinguishes them (N25/N26): DROP only when
+      // this exact payload was already seen for this transcript (true re-fire);
+      // otherwise record the spawn.
+      if (eventSig && getSeenSigs(cursor, data.transcript_path).includes(eventSig)) {
+        emptySlice = true; // already-seen event → re-fire; appendRecord drops the phantom row (M61)
+      } else {
+        // Sibling / first-fire: record the spawn (zero tokens) and remember its
+        // signature so a subsequent re-fire of THIS event is dropped.
+        addSeenSig(cursor, data.transcript_path, eventSig);
+        writeCursor(cwd, cursor);
+      }
     }
   } else {
     // No transcript to slice — best-effort from data.usage, plausibility-guarded
@@ -157,7 +378,7 @@ function buildCostRecord(data, cwd) {
   const record = {
     v: SCHEMA_V,
     ts: new Date().toISOString(),
-    agent: data.agent_type || data.subagent_type || null,
+    agent,
     command,
     model,
     tier: tierForModel(model),
@@ -172,8 +393,29 @@ function buildCostRecord(data, cwd) {
     source: 'hook',
     token_source: tokenSource,
     clamped,
+    // This spawn's per-invocation discriminator: the event signature, persisted.
+    // The signature was already hashed for the seen-event marker but never
+    // written into the row, so two parallel same-type siblings produced rows
+    // that were byte-identical modulo `ts` and the dedup ate the second one even
+    // though the marker layer had correctly admitted it (N26). Persisting it
+    // gives both layers ONE notion of event identity: siblings differ here even
+    // when every other field matches, while a re-fire carries the same signature
+    // and still matches the row it duplicates.
+    // It is a field the dedup COMPARES as part of whole-row identity — never a
+    // key the dedup searches the ledger by. Two sequential subagents on a shared
+    // growing transcript share one payload and therefore one signature while
+    // holding different real token counts, so matching on the signature alone
+    // deletes genuine rows (see eventSignature). null when the payload could not
+    // be hashed.
+    event_sig: eventSig,
   };
 
+  // Non-enumerable transient flag: it must NOT be serialized into the ledger,
+  // but appendRecord needs to read it to drop a phantom re-fire row (M61).
+  if (emptySlice) {
+    Object.defineProperty(record, '__emptySlice', { value: true, enumerable: false });
+  }
+
   return record;
 }
 
@@ -264,6 +506,12 @@ function readUsageFromTranscript(transcriptPath, sessionId, sinceLine = 0) {
  */
 function appendRecord(cwd, record) {
   if (!record) return false;
+  // M61 re-fire guard: a transcript-sourced event that consumed no new records
+  // (buildCostRecord flags it via __emptySlice) is a re-fired / dual-registered
+  // SubagentStop with nothing of its own to attribute. Dropping it here is the
+  // real guard the last-row dedup could not be — the phantom all-zero row
+  // differs from the real row it follows, so the dedup never fired (M61).
+  if (record.__emptySlice) return false;
   try {
     const dir = path.join(cwd, '.planning', METRICS_DIR);
     fs.mkdirSync(dir, { recursive: true });
@@ -271,7 +519,8 @@ function appendRecord(cwd, record) {
     // 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.
+    // field (2026-07). Adjacent-only on purpose; see isDuplicateOfLastRecord.
+    // 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;
@@ -280,12 +529,35 @@ function appendRecord(cwd, record) {
   }
 }
 
-/** True when `record` equals the last JSONL row of `file`, ignoring `ts`. */
+/**
+ * True when `record` equals the LAST JSONL row of `file`, ignoring `ts`.
+ *
+ * Adjacent-only, and that is the design rather than an oversight. The comparison
+ * covers every field including the `event_sig` discriminator, so a true re-fire
+ * (same payload → same signature → same row) still matches the row it follows,
+ * while two siblings the payload can distinguish both survive (N26).
+ *
+ * It deliberately does NOT scan back over a tail of recent rows, and does not
+ * match on a repeated signature. Both of those were tried and both delete real
+ * spawns: an identity scan over a window collapses genuine repeat spawns whose
+ * rows coincide, and a signature prong collapses genuine spawns that share a
+ * payload — the ordinary shared-transcript topology. eventSignature carries the
+ * measured reproduction and the residual this leaves standing;
+ * tests/cost-logger-hook.test.cjs pins both
+ * (`grep -n 'no genuine spawn' tests/cost-logger-hook.test.cjs`).
+ *
+ * Rows written before the discriminator existed carry no `event_sig` and an
+ * older `v`, so a row written now never equals one of them. The bounded
+ * consequence: the first append after a schema bump can land beside a pre-bump
+ * row without matching it, and the guard resumes on the following same-shape
+ * pair. Those older rows still parse and still report — the readers in
+ * pan-wizard-core take a row field by field and require no particular version
+ * or field to be present.
+ */
 function isDuplicateOfLastRecord(file, record) {
   let prev;
   try {
-    const raw = fs.readFileSync(file, 'utf-8');
-    const lines = raw.split('\n').filter(Boolean);
+    const lines = fs.readFileSync(file, 'utf-8').split('\n').filter(Boolean);
     if (!lines.length) return false;
     prev = JSON.parse(lines[lines.length - 1]);
   } catch {
@@ -308,6 +580,9 @@ if (require.main === module) {
       // fall back to process.cwd() which is the project root when Claude Code
       // invokes the hook.
       const cwd = data.cwd || data.workspace?.current_dir || process.cwd();
+      // M62: a global-install hook fires in every repo; don't pollute non-PAN
+      // projects with .planning/ metrics artifacts.
+      if (!isPanProject(cwd)) return;
       const record = buildCostRecord(data, cwd);
       appendRecord(cwd, record);
     } catch {
@@ -316,4 +591,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { buildCostRecord, appendRecord, readUsageFromTranscript, readCursor, writeCursor, METRICS_DIR, TOKENS_FILE, CURSOR_FILE };
+module.exports = { buildCostRecord, appendRecord, readUsageFromTranscript, readCursor, writeCursor, isPanProject, METRICS_DIR, TOKENS_FILE, CURSOR_FILE };

package/hooks/dist/pan-statusline.js

@@ -44,14 +44,30 @@ function buildStatuslineOutput(data, deps) {
         // Mirrors bridgeDir() in pan-context-monitor.js (the reader).
         const uid = (typeof process.getuid === 'function' ? process.getuid() : process.env.USERNAME || 'win');
         const bridgeSubdir = pathMod.join(tmpDir, `pan-hooks-${uid}`);
-        try { fsMod.mkdirSync(bridgeSubdir, { recursive: true, mode: 0o700 }); } catch { /* best-effort */ }
-        const bridgePath = pathMod.join(bridgeSubdir, `claude-ctx-${session}.json`);
-        fsMod.writeFileSync(bridgePath, JSON.stringify({
-          session_id: session,
-          remaining_percentage: remaining,
-          used_pct: used,
-          timestamp: Math.floor(Date.now() / 1000),
-        }));
+        // Fail CLOSED if the per-user dir is pre-planted/symlinked/owned by
+        // someone else — mkdirSync{recursive} silently no-ops on an existing dir,
+        // so verify ownership+mode before writing the session bridge (M60).
+        let secure = false;
+        try {
+          fsMod.mkdirSync(bridgeSubdir, { recursive: true, mode: 0o700 });
+          const st = fsMod.lstatSync(bridgeSubdir);
+          // Symlink check is cross-platform; POSIX ownership/mode checks apply
+          // only where getuid exists (Windows fakes mode bits — gating on them
+          // there disabled the bridge entirely, N15).
+          secure = !st.isSymbolicLink();
+          if (secure && typeof process.getuid === 'function') {
+            secure = st.uid === process.getuid() && (st.mode & 0o077) === 0;
+          }
+        } catch { secure = false; }
+        if (secure) {
+          const bridgePath = pathMod.join(bridgeSubdir, `claude-ctx-${session}.json`);
+          fsMod.writeFileSync(bridgePath, JSON.stringify({
+            session_id: session,
+            remaining_percentage: remaining,
+            used_pct: used,
+            timestamp: Math.floor(Date.now() / 1000),
+          }));
+        }
       } catch { /* bridge is best-effort */ }
     }
 

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

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+// Auto-Advance Stop Guard - Stop hook (P-1809)
+//
+// Catches the P-1801/P-1807 boundary drop mechanically. Field data (PanLoop,
+// 2026-08): with the gate-parity fix and prose hardening in place, autonomous
+// builds still stopped at a phase boundary at a low, nondeterministic rate —
+// the orchestrator finishes transition.md's state bookkeeping and ends its turn
+// without issuing the Route A Task spawn. Prose cannot bind that tail reliably;
+// a Stop hook can, because it runs as code when the session tries to end.
+//
+// When the session stops, this hook blocks ONCE — with a reason telling the
+// agent to spawn the next phase — if and only if the disk shows the exact
+// boundary-drop fingerprint:
+//   1. .planning/config.json shows an autonomy signal: workflow.auto_advance
+//      === true OR mode === 'yolo'. P-1810 (PanLoop finding 7): the guard
+//      originally armed on auto_advance alone — narrower than the composite
+//      trigger it guards (flag OR config OR yolo) — and stayed dark on the
+//      exact base64url drop it was built for (mode yolo, auto_advance false).
+//      A Stop hook cannot see the --auto flag, so the chain's entry hops
+//      (discuss/plan/exec-phase) persist the flag into config, and yolo is
+//      accepted directly. transition.md Route B clears auto_advance at the
+//      milestone boundary, which disarms the config half at the true end.
+//   2. .planning/state.md does NOT show a legitimate-stop marker (gaps found,
+//      verification failed, blocked). P-1812 (PanLoop finding 9): this
+//      condition was originally "status begins 'Ready to plan'" — one batch
+//      produced four different status phrasings for the same situation, and a
+//      run with BOTH arming conditions satisfied was disarmed by wording
+//      alone. The condition is now inverted: an unrecognised phrasing ARMS
+//      the guard (fail-safe — at worst one extra continuation, bounded by the
+//      one-shot design) instead of disarming it (fail-open — the build
+//      silently stops). Never re-introduce a required phrasing here; the
+//      model does not reliably write canonical wording and nothing forces it.
+//   3. .planning/roadmap.md still has unticked `- [ ] **Phase N:` lines
+//      (the shipped template/roadmapper checklist shape — same detector the
+//      PanLoop harness uses to call a build incomplete)
+//
+// Loop safety: the host sets stop_hook_active on stop attempts that follow a
+// stop-hook block, and this guard always allows those — it fires at most once
+// per stop chain, so a user who genuinely wants to stop is delayed by exactly
+// one continuation, never trapped.
+//
+// Escape hatch: set workflow.stop_guard to false in .planning/config.json to
+// disable the guard entirely without turning off auto_advance.
+//
+// Fail-open everywhere: no .planning, unparseable config/state/roadmap, bad
+// stdin — exit 0 silently. This guard must never block a stop on uncertainty;
+// a missed catch is a re-run, a wrong block is a trapped session.
+//
+// The decision logic lives in the pure, exported buildStopDecision() so the
+// full condition matrix is unit-tested (tests/stop-guard-hook.test.cjs)
+// rather than only reachable via stdin (same pattern as the other PAN hooks).
+
+const fs = require('fs');
+const path = require('path');
+
+// Unticked phase line, exactly as templates/roadmap.md and pan-roadmapper.md
+// emit it. Fixture doctrine: this shape is pinned against the shipped template
+// by the tests — never widen it from imagination, re-derive it from the files.
+const UNTICKED_PHASE_RE = /^- \[ \] \*\*Phase (\d+(?:\.\d+)?):/m;
+
+// Legitimate-stop markers in state.md (P-1812). Condition 2 exists only to
+// let a REAL stop through — a verification failure, gaps, or a recorded
+// blocker. Matching those (a short, high-precision list) is robust; matching
+// the "chain should continue" wording was not: PAN wrote "Ready to plan",
+// "Ready to execute", "Phase 2 planning pending" and two milestone phrasings
+// for the same boundary within one field batch. Anything NOT matching this
+// list arms the guard.
+const LEGIT_STOP_RE = /gaps?\s+found|verification\s+(?:failed|found\s+gaps)|failed\s+verification|\bblocked\b|\bblocker\b/i;
+
+// The stopped_at "ready to plan Phase N" phrasing, when present, names the
+// next phase more precisely than the first-unticked roadmap line (a
+// completed-but-unticked earlier phase would misdirect it — finding 8).
+const READY_STOPPED_AT_RE = /ready to plan phase\s*(\d+(?:\.\d+)?)/i;
+
+/**
+ * Pure decision: should this stop be blocked?
+ * @param {object} args
+ * @param {boolean} args.stopHookActive  stop_hook_active from the payload
+ * @param {object|null} args.config      parsed .planning/config.json, or null
+ * @param {string|null} args.stateContent    .planning/state.md, or null
+ * @param {string|null} args.roadmapContent  .planning/roadmap.md, or null
+ * @returns {{decision: 'block', reason: string}|null} null = allow the stop
+ */
+function buildStopDecision({ stopHookActive, config, stateContent, roadmapContent }) {
+  if (stopHookActive) return null; // one-shot: never block a post-block stop
+  if (!config || typeof config !== 'object') return null;
+  const wf = (config.workflow && typeof config.workflow === 'object') ? config.workflow : {};
+  if (wf.stop_guard === false) return null; // explicit escape hatch beats every arming signal
+  // P-1810: arm on EITHER disk-visible autonomy signal — auto_advance alone
+  // was narrower than the trigger it guards and missed a real drop (finding 7).
+  const armed = wf.auto_advance === true || config.mode === 'yolo';
+  if (!armed) return null;
+  if (typeof stateContent !== 'string' || typeof roadmapContent !== 'string') return null;
+
+  // P-1812: inverted condition — allow the stop only when state records a
+  // legitimate reason to stop. Unrecognised status phrasings arm the guard.
+  if (LEGIT_STOP_RE.test(stateContent)) return null;
+
+  const unticked = roadmapContent.match(UNTICKED_PHASE_RE);
+  if (!unticked) return null; // every phase built — nothing to continue
+
+  // Prefer the phase state.md says is next: a COMPLETED phase left unticked
+  // (finding 8) would otherwise make the first-unticked line name a phase that
+  // is already built. The roadmap match still gates arming; state names the
+  // target when it can.
+  const stateNext = stateContent.match(READY_STOPPED_AT_RE);
+  const nextPhase = (stateNext && stateNext[1]) || unticked[1];
+  return {
+    decision: 'block',
+    reason:
+      `PAN auto-advance chain incomplete: autonomy is armed in .planning/config.json, ` +
+      `state.md records no failure/gaps/blocker, and roadmap.md still has unbuilt phases ` +
+      `(next: Phase ${nextPhase}). Ending the turn here is the P-1801/P-1807 boundary drop. ` +
+      `Continue the chain now: if the current phase is finished, follow transition.md's ` +
+      `offer_next_phase Route A and spawn Phase ${nextPhase} as a Task subagent ` +
+      `(plan-phase orchestrator, ARGUMENTS='${nextPhase} --auto'); if the current phase is ` +
+      `mid-flight, resume it instead. If the user explicitly asked to stop, first run: ` +
+      `pan-tools config-set workflow.auto_advance false — then stop. ` +
+      `(Disable this guard permanently with workflow.stop_guard: false.)`
+  };
+}
+
+function readIfExists(p) {
+  try { return fs.readFileSync(p, 'utf8'); } catch { return null; }
+}
+
+function main() {
+  let input = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => { input += chunk; });
+  process.stdin.on('end', () => {
+    try {
+      let payload = {};
+      try { payload = JSON.parse(input); } catch { /* fail open on bad stdin */ }
+      if (!payload || typeof payload !== 'object') payload = {};
+
+      const projectDir = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd();
+      const planningDir = path.join(projectDir, '.planning');
+
+      let config = null;
+      try { config = JSON.parse(fs.readFileSync(path.join(planningDir, 'config.json'), 'utf8')); } catch { /* no project / bad config -> allow */ }
+
+      const decision = buildStopDecision({
+        stopHookActive: payload.stop_hook_active === true,
+        config,
+        stateContent: readIfExists(path.join(planningDir, 'state.md')),
+        roadmapContent: readIfExists(path.join(planningDir, 'roadmap.md')),
+      });
+
+      if (decision) process.stdout.write(JSON.stringify(decision));
+    } catch { /* fail open — never break a stop */ }
+    process.exit(0);
+  });
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { buildStopDecision, UNTICKED_PHASE_RE };