pan-wizard 3.30.0 → 3.32.0

package/commands/pan/verify-phase.md

@@ -1,7 +1,7 @@
 ---
 name: pan:verify-phase
 group: Phase Lifecycle
-description: Validate built features through conversational UAT with test suite gate
+description: Re-run goal-backward verification of a phase with a test-suite gate and list its gaps
 argument-hint: "[phase number, e.g., '4']"
 allowed-tools:
   - Read
@@ -13,24 +13,23 @@ allowed-tools:
   - Task
 ---
 <objective>
-Validate built features through conversational testing with persistent state.
+Verify that the phase delivered what it promised, not just that its tasks completed.
 
-Purpose: Confirm what Claude built actually works from user's perspective. One test at a time, plain text responses, no interrogation. When issues are found, automatically diagnose, plan fixes, and prepare for execution.
+Purpose: goal-backward verification — what must be TRUE for the phase goal, what must EXIST for that, what must be WIRED — checked against the codebase, behind a test-suite gate.
 
-Output: {phase_num}-uat.md tracking all test results. If issues found: diagnosed gaps, verified fix plans ready for /pan:exec-phase
+Output: {phase_num}-verification.md with a status (passed, gaps_found or human_needed). Gaps found are listed for `/pan:plan-phase {phase_num} --gaps`.
 </objective>
 
 <execution_context>
 @~/.claude/pan-wizard-core/workflows/verify-phase.md
-@~/.claude/pan-wizard-core/templates/uat.md
 </execution_context>
 
 <context>
 Phase: $ARGUMENTS (optional)
 - If provided: Test specific phase (e.g., "4")
-- If not provided: Check for active sessions or prompt for phase
+- If not provided: prompt for the phase
 
-Context files are resolved inside the workflow (`init verify-work`) and delegated via `<files_to_read>` blocks.
+Context files are resolved inside the workflow (`init phase-op`).
 </context>
 
 <investigate_before_judging>
@@ -87,6 +86,6 @@ See [plan-phase.md](plan-phase.md) or [exec-phase.md](exec-phase.md) for the ful
 </cache_priming>
 
 <process>
-Execute the verify-work workflow from @~/.claude/pan-wizard-core/workflows/verify-phase.md end-to-end.
-Preserve all workflow gates (session management, test presentation, diagnosis, fix planning, routing).
+Execute the verify-phase workflow from @~/.claude/pan-wizard-core/workflows/verify-phase.md end-to-end.
+Preserve all workflow gates (the test-suite gate, the truth/artifact/wiring checks, status determination, the verification report).
 </process>

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

@@ -12,6 +12,45 @@
 
 const fs = require('fs');
 const path = require('path');
+
+// ─── R39: one run per hook when Claude and Copilot share a project ───────────
+// Copilot CLI also runs the hooks in a repository's .claude/settings.json and
+// .claude/settings.local.json. Measured 2026-09-26 (Copilot CLI 1.0.88, repository
+// hooks loaded): in a project with both the Claude and the Copilot install, every
+// PAN hook ran twice under Copilot — once from .github/hooks/pan.json, once from the
+// Claude settings. The Copilot project copy (this file under .github/hooks) steps
+// aside whenever the project's Claude settings register the same script, so the hook
+// runs once, and runs again from here the moment the Claude registration is gone.
+// Both files are repository hooks to Copilot and load under the same trust rule, so
+// deferring never leaves zero. Only this copy defers: Claude Code never reads
+// .github/hooks, Gemini and Codex never read .claude/settings.json, and a global
+// Copilot copy loads where repository hooks may not. Identical in every hook
+// Copilot registers — tests/copilot-hook-dedupe.test.cjs pins the copies.
+function deferToClaudeRegistration(projectDir, hookFile = __filename) {
+  // Assembled, not written as a literal: the installer rewrites every quoted .claude
+  // literal in a hook copy to that runtime's own directory, and this one must stay Claude's.
+  const claudeDir = ['.', 'claude'].join('');
+  try {
+    const hooksDir = path.dirname(hookFile);
+    if (path.basename(hooksDir) !== 'hooks' || path.basename(path.dirname(hooksDir)) !== '.github') return false;
+    if (typeof projectDir !== 'string' || !projectDir) return false;
+    const script = path.basename(hookFile);
+    for (const name of ['settings.json', 'settings.local.json']) {
+      let settings;
+      try { settings = JSON.parse(fs.readFileSync(path.join(projectDir, claudeDir, name), 'utf8')); } catch { continue; }
+      const events = settings && typeof settings.hooks === 'object' ? settings.hooks : null;
+      if (!events) continue;
+      for (const groups of Object.values(events)) {
+        if (!Array.isArray(groups)) continue;
+        for (const group of groups) {
+          const handlers = group && Array.isArray(group.hooks) ? group.hooks : [];
+          if (handlers.some((h) => h && typeof h.command === 'string' && h.command.includes(script))) return true;
+        }
+      }
+    }
+  } catch { /* fail open: run this copy */ }
+  return false;
+}
 const os = require('os');
 const { spawn } = require('child_process');
 
@@ -128,9 +167,17 @@ function main() {
   const cacheDir = path.join(homeDir, '.claude', 'cache');
   const cacheFile = path.join(cacheDir, 'pan-update-check.json');
 
-  // VERSION file locations (check project first, then global)
+  // VERSION file locations: the project's own install first; then the core this
+  // hook copy ships with, which sits beside it in every layout (<config>/hooks next
+  // to <config>/pan-wizard-core, and the same under a plugin root); then the global
+  // install. The plugin case is why the middle one exists: the two config-dir paths
+  // only ever find an install, so under a plugin host the installed version read as
+  // 0.0.0 (3.28.0 review, LOW).
   const projectVersionFile = path.join(cwd, '.claude', 'pan-wizard-core', 'VERSION');
-  const globalVersionFile = path.join(homeDir, '.claude', 'pan-wizard-core', 'VERSION');
+  const ownVersionFile = path.join(__dirname, '..', 'pan-wizard-core', 'VERSION');
+  const globalVersionFile = fs.existsSync(ownVersionFile)
+    ? ownVersionFile
+    : path.join(homeDir, '.claude', 'pan-wizard-core', 'VERSION');
 
   // Ensure cache directory exists
   try {
@@ -153,6 +200,9 @@ function main() {
     return;
   }
 
+  // Copilot also runs the Claude registration of this hook in a two-runtime project.
+  if (deferToClaudeRegistration(cwd)) return;
+
   // Parent mode: run the check in a detached background child so the 10s
   // `npm view` never blocks SessionStart. windowsHide prevents a console flash.
   const child = spawn(process.execPath, [__filename, '--run-check'], {
@@ -168,6 +218,7 @@ if (require.main === module) {
 }
 
 module.exports = {
+  deferToClaudeRegistration,
   parseVersion,
   compareVersions,
   isUpdateAvailable,

package/hooks/dist/pan-context-monitor.js

@@ -5,7 +5,7 @@
 // context limits (the statusline only shows the user).
 //
 // How it works:
-// 1. The statusline hook writes metrics to /tmp/claude-ctx-{session_id}.json
+// 1. The statusline hook writes metrics to <os tmpdir>/pan-hooks-<uid>/claude-ctx-{session_id}.json
 // 2. This hook reads those metrics after each tool use
 // 3. When remaining context drops below thresholds, it injects a warning
 //    as additionalContext, which the agent sees in its conversation
@@ -25,6 +25,45 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
+// ─── R39: one run per hook when Claude and Copilot share a project ───────────
+// Copilot CLI also runs the hooks in a repository's .claude/settings.json and
+// .claude/settings.local.json. Measured 2026-09-26 (Copilot CLI 1.0.88, repository
+// hooks loaded): in a project with both the Claude and the Copilot install, every
+// PAN hook ran twice under Copilot — once from .github/hooks/pan.json, once from the
+// Claude settings. The Copilot project copy (this file under .github/hooks) steps
+// aside whenever the project's Claude settings register the same script, so the hook
+// runs once, and runs again from here the moment the Claude registration is gone.
+// Both files are repository hooks to Copilot and load under the same trust rule, so
+// deferring never leaves zero. Only this copy defers: Claude Code never reads
+// .github/hooks, Gemini and Codex never read .claude/settings.json, and a global
+// Copilot copy loads where repository hooks may not. Identical in every hook
+// Copilot registers — tests/copilot-hook-dedupe.test.cjs pins the copies.
+function deferToClaudeRegistration(projectDir, hookFile = __filename) {
+  // Assembled, not written as a literal: the installer rewrites every quoted .claude
+  // literal in a hook copy to that runtime's own directory, and this one must stay Claude's.
+  const claudeDir = ['.', 'claude'].join('');
+  try {
+    const hooksDir = path.dirname(hookFile);
+    if (path.basename(hooksDir) !== 'hooks' || path.basename(path.dirname(hooksDir)) !== '.github') return false;
+    if (typeof projectDir !== 'string' || !projectDir) return false;
+    const script = path.basename(hookFile);
+    for (const name of ['settings.json', 'settings.local.json']) {
+      let settings;
+      try { settings = JSON.parse(fs.readFileSync(path.join(projectDir, claudeDir, name), 'utf8')); } catch { continue; }
+      const events = settings && typeof settings.hooks === 'object' ? settings.hooks : null;
+      if (!events) continue;
+      for (const groups of Object.values(events)) {
+        if (!Array.isArray(groups)) continue;
+        for (const group of groups) {
+          const handlers = group && Array.isArray(group.hooks) ? group.hooks : [];
+          if (handlers.some((h) => h && typeof h.command === 'string' && h.command.includes(script))) return true;
+        }
+      }
+    }
+  } catch { /* fail open: run this copy */ }
+  return false;
+}
+
 // Per-user bridge directory inside tmpdir, created 0700 so another user on a
 // shared host can't pre-plant a symlink at a predictable session path or read
 // the bridge files. Both hooks derive the same dir from the same uid, so the
@@ -135,6 +174,7 @@ function main() {
   process.stdin.on('end', () => {
     try {
       const data = JSON.parse(input);
+      if (deferToClaudeRegistration(data.cwd || process.cwd())) process.exit(0);
       const sessionId = data.session_id;
 
       if (!sessionId) {
@@ -199,6 +239,7 @@ if (require.main === module) {
 }
 
 module.exports = {
+  deferToClaudeRegistration,
   buildContextWarning,
   bridgeDir,
   WARNING_THRESHOLD,

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

@@ -17,6 +17,45 @@
 
 const fs = require('fs');
 const path = require('path');
+
+// ─── R39: one run per hook when Claude and Copilot share a project ───────────
+// Copilot CLI also runs the hooks in a repository's .claude/settings.json and
+// .claude/settings.local.json. Measured 2026-09-26 (Copilot CLI 1.0.88, repository
+// hooks loaded): in a project with both the Claude and the Copilot install, every
+// PAN hook ran twice under Copilot — once from .github/hooks/pan.json, once from the
+// Claude settings. The Copilot project copy (this file under .github/hooks) steps
+// aside whenever the project's Claude settings register the same script, so the hook
+// runs once, and runs again from here the moment the Claude registration is gone.
+// Both files are repository hooks to Copilot and load under the same trust rule, so
+// deferring never leaves zero. Only this copy defers: Claude Code never reads
+// .github/hooks, Gemini and Codex never read .claude/settings.json, and a global
+// Copilot copy loads where repository hooks may not. Identical in every hook
+// Copilot registers — tests/copilot-hook-dedupe.test.cjs pins the copies.
+function deferToClaudeRegistration(projectDir, hookFile = __filename) {
+  // Assembled, not written as a literal: the installer rewrites every quoted .claude
+  // literal in a hook copy to that runtime's own directory, and this one must stay Claude's.
+  const claudeDir = ['.', 'claude'].join('');
+  try {
+    const hooksDir = path.dirname(hookFile);
+    if (path.basename(hooksDir) !== 'hooks' || path.basename(path.dirname(hooksDir)) !== '.github') return false;
+    if (typeof projectDir !== 'string' || !projectDir) return false;
+    const script = path.basename(hookFile);
+    for (const name of ['settings.json', 'settings.local.json']) {
+      let settings;
+      try { settings = JSON.parse(fs.readFileSync(path.join(projectDir, claudeDir, name), 'utf8')); } catch { continue; }
+      const events = settings && typeof settings.hooks === 'object' ? settings.hooks : null;
+      if (!events) continue;
+      for (const groups of Object.values(events)) {
+        if (!Array.isArray(groups)) continue;
+        for (const group of groups) {
+          const handlers = group && Array.isArray(group.hooks) ? group.hooks : [];
+          if (handlers.some((h) => h && typeof h.command === 'string' && h.command.includes(script))) return true;
+        }
+      }
+    }
+  } catch { /* fail open: run this copy */ }
+  return false;
+}
 const crypto = require('crypto');
 
 // Runtime config dirs a local PAN install lands in (mirrors installer getDirName).
@@ -107,9 +146,11 @@ const CURSOR_FILE = '.cost-cursor.json';
 // the per-invocation `event_sig` discriminator; v4 added `agent_id` and the
 // `agent-transcript` token source. Kept as a literal in each hook —
 // they are standalone zero-dep scripts that can't import from pan-wizard-core, so
-// the two hooks must stay in sync by hand. No constant in pan-wizard-core mirrors
-// it: the readers there take a row field by field rather than switching on its
-// version, so an added field is additive for them.
+// each hook's copy is kept by hand (in lockstep through v4; the trace logger's events
+// have since moved to 5 on their own). cost-rebuild.cjs in
+// pan-wizard-core mirrors it for the rows it rebuilds; 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 = 4;
 
 // Reverse-map a resolved model id to its cost tier so the "By tier" dashboard
@@ -417,10 +458,13 @@ const MAX_CURSOR_KEYS = 512;
 // 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).
+// (record, never mark). SHA-256 cut to the 40 hex characters the SHA-1 it replaced
+// produced, so persisted `event_sig` values keep their shape: a dedup key, not a
+// security boundary, but CodeQL rightly flags SHA-1 over a payload that carries a
+// session id (2026-09-29).
 function eventSignature(data) {
   try {
-    return crypto.createHash('sha1').update(JSON.stringify(data)).digest('hex');
+    return crypto.createHash('sha256').update(JSON.stringify(data)).digest('hex').slice(0, 40);
   } catch { return null; }
 }
 
@@ -520,6 +564,27 @@ function resolveAgentTranscript(data) {
   }
 }
 
+// Host-internal agents (measured 2026-09-28). Claude Code runs helper agents of its own:
+// the compaction summariser, and one at almost every turn end of an interactive session.
+// It fires SubagentStop for them with an `agent_id`, an EMPTY `agent_type`, and an
+// `agent_transcript_path` it never writes. That shape was captured from a real `/compact`
+// on Claude Code 2.1.280 (tests/fixtures/hooks/subagent-stop-internal-claude.json). Both
+// loggers booked each as an `unknown` zero-token spawn: 181 rows in three field projects
+// in eleven days, skewing optimize learn's agent stats and the ledger's spawn counts.
+// The host documents `agent_type` as present whenever a hook fires inside a subagent, so
+// a named instance with no type and no transcript is not a spawn anyone asked for, and
+// nothing is recorded. A NAMED spawn whose file is late or missing keeps its zero-token
+// row (N17/N25); a payload with no agent instance at all keeps the parent-slice path.
+// Identical in pan-cost-logger.js and pan-trace-logger.js (tests/trace-logger.test.cjs
+// pins the copies).
+function isHostInternalAgent(data, agentTranscript) {
+  if (!data || typeof data !== 'object' || agentTranscript) return false;
+  const typed = [data.agent_type, data.subagent_type].some((v) => typeof v === 'string' && v.trim() !== '');
+  if (typed) return false;
+  return (typeof data.agent_id === 'string' && AGENT_ID_SAFE.test(data.agent_id))
+    || (typeof data.agent_transcript_path === 'string' && data.agent_transcript_path !== '');
+}
+
 // A slice is a SUM over one subagent's conversation, so its ceiling sits above a
 // single call's (PLAUSIBLE_MAX): a long agent legitimately re-reads its cached
 // context on every turn. The cache_read and output ceilings are the absolute
@@ -537,6 +602,29 @@ function clampSlice(n, max) {
   return typeof n === 'number' && n >= 0 && n <= max ? n : 0;
 }
 
+// Copilot CLI's camelCase hook payload (docs.github.com/en/copilot/reference/hooks-reference,
+// read 2026-09-28; documented, not yet observed live) names every field differently from
+// Claude's snake_case one, so this hook read no session, transcript or agent from it and
+// booked every Copilot spawn as `unknown`. Its `agentType` is the KIND of agent (built-in
+// or custom); `agentName` is the configured name PAN's agents carry, so the name wins.
+// Claude payloads carry none of these keys and pass through unchanged. Identical in
+// pan-cost-logger.js and pan-trace-logger.js (tests/copilot-payload.test.cjs pins both).
+function normalizeHookPayload(data) {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return data;
+  const pick = (...keys) => {
+    for (const k of keys) if (typeof data[k] === 'string' && data[k]) return data[k];
+    return undefined;
+  };
+  const out = { ...data };
+  if (out.session_id === undefined && pick('sessionId')) out.session_id = pick('sessionId');
+  if (out.transcript_path === undefined && pick('transcriptPath')) out.transcript_path = pick('transcriptPath');
+  if (out.agent_id === undefined && pick('agentId')) out.agent_id = pick('agentId');
+  const name = pick('agent_name', 'agentName');
+  if (name) out.agent_type = name;
+  else if (out.agent_type === undefined && pick('agentType')) out.agent_type = pick('agentType');
+  return out;
+}
+
 /**
  * Extract what we can from the SubagentStop event payload.
  * Pure function — safe to test without stdin.
@@ -547,6 +635,7 @@ function clampSlice(n, max) {
  */
 function buildCostRecord(data, cwd) {
   if (!data || typeof data !== 'object') return null;
+  data = normalizeHookPayload(data);
 
   // Only log actual subagent stops; ignore other Stop variants.
   if (data.hook_event_name && data.hook_event_name !== 'SubagentStop') return null;
@@ -564,6 +653,8 @@ function buildCostRecord(data, cwd) {
   let outputTokens = 0;
   let cacheRead = 0;
   let cacheWrite = 0;
+  // { h1, m5 } when the source carried the cache-write lifetime split (M13).
+  let ttlSplit = null;
   let durationMs = null;
   // token_source records WHICH path produced the counts: `agent-transcript` (the
   // subagent's own conversation file — see resolveAgentTranscript), `transcript`
@@ -572,6 +663,7 @@ function buildCostRecord(data, cwd) {
   // a value dropped to 0 by a plausibility guard so a guarded zero is
   // distinguishable from a genuine zero-token run.
   const agentTranscript = resolveAgentTranscript(data);
+  if (isHostInternalAgent(data, agentTranscript)) return null; // the host's own helper, not a spawn
   const parentPath = typeof data.transcript_path === 'string' && data.transcript_path ? data.transcript_path : null;
   // The host NAMED an agent (a bare id, or an explicit agent transcript path) but
   // its file is not there — not flushed yet, or a host that sends ids without
@@ -621,6 +713,10 @@ function buildCostRecord(data, cwd) {
     cacheWrite = clampSlice(rawCw, SLICE_MAX.cache_write);
     clamped = rawIn > SLICE_MAX.input || rawOut > SLICE_MAX.output
       || rawCr > SLICE_MAX.cache_read || rawCw > SLICE_MAX.cache_write;
+    // A clamped write total no longer matches its split, so the split is dropped with it.
+    if (typeof fromTranscript.cache_write_1h_tokens === 'number' && rawCw <= SLICE_MAX.cache_write) {
+      ttlSplit = { h1: fromTranscript.cache_write_1h_tokens, m5: fromTranscript.cache_write_5m_tokens || 0 };
+    }
     durationMs = durationFromSpan(fromTranscript.first_ts, fromTranscript.last_ts); // as measured — see SLICE_MAX
     if (!model) model = fromTranscript.model;
     if (fromTranscript.lineCount > since) {
@@ -676,18 +772,24 @@ function buildCostRecord(data, cwd) {
     cacheRead = clampPlausible(rawCr);
     cacheWrite = clampPlausible(rawCw);
     clamped = [rawIn, rawOut, rawCr, rawCw].some((n) => n > PLAUSIBLE_MAX);
+    const split = {};
+    addCacheTtlSplit(split, data.usage);
+    if (typeof split.cache_write_1h_tokens === 'number' && cacheWrite === rawCw) {
+      ttlSplit = { h1: clampPlausible(split.cache_write_1h_tokens), m5: clampPlausible(split.cache_write_5m_tokens) };
+    }
   }
 
   // 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);
-  // The trace session only exists while the optimizer runs, so the parent transcript is
-  // the fallback that makes command attribution work outside focus mode — see
+  // The trace logger's day-scoped auto-session names no command (only a session opened
+  // by `optimize trace init` or focus mode does), so the parent transcript is the
+  // fallback that makes command attribution work in ordinary use — see
   // readCommandFromTranscript.
   const command = data.command || sessionMeta.command || readCommandFromTranscript(data.transcript_path) || null;
-  // The trace session is only present while the optimizer is running (off by
-  // default), so state.md is the fallback that makes phase attribution work in
-  // ordinary use instead of only under tracing.
+  // The day-scoped auto-session names no phase either, so state.md is the fallback
+  // that makes phase attribution work in ordinary use, not only in a session that
+  // was opened with one.
   const phase = data.phase || sessionMeta.phase || readCurrentPhase(cwd) || null;
 
   const record = {
@@ -705,6 +807,8 @@ function buildCostRecord(data, cwd) {
     output_tokens: outputTokens,
     cache_read_tokens: cacheRead,
     cache_write_tokens: cacheWrite,
+    // The lifetime split of cache_write_tokens, present only when measured (M13).
+    ...(ttlSplit ? { cache_write_1h_tokens: ttlSplit.h1, cache_write_5m_tokens: ttlSplit.m5 } : {}),
     cost_usd: null,
     duration_ms: durationMs,
     phase,
@@ -833,11 +937,27 @@ function readUsageFromTranscript(transcriptPath, sessionId, sinceLine = 0) {
     totals.output_tokens += extractNumber(usage, 'output_tokens');
     totals.cache_read_input_tokens += extractNumber(usage, 'cache_read_input_tokens');
     totals.cache_creation_input_tokens += extractNumber(usage, 'cache_creation_input_tokens');
+    addCacheTtlSplit(totals, usage);
   }
   totals.lineCount = seen;
   return totals;
 }
 
+/**
+ * Add a usage record's cache-write lifetime split to `totals` (M13). Claude Code
+ * transcripts carry `usage.cache_creation: { ephemeral_5m_input_tokens,
+ * ephemeral_1h_input_tokens }` beside the `cache_creation_input_tokens` total;
+ * one-hour writes bill at 2x base input against 1.25x for five-minute ones, so
+ * the ledger keeps the split. The totals gain the two fields only when some
+ * record carried the block — rows from hosts without it stay unchanged.
+ */
+function addCacheTtlSplit(totals, usage) {
+  const cc = usage && usage.cache_creation;
+  if (!cc || typeof cc !== 'object') return;
+  totals.cache_write_1h_tokens = (totals.cache_write_1h_tokens || 0) + extractNumber(cc, 'ephemeral_1h_input_tokens');
+  totals.cache_write_5m_tokens = (totals.cache_write_5m_tokens || 0) + extractNumber(cc, 'ephemeral_5m_input_tokens');
+}
+
 /**
  * Append record to .planning/metrics/tokens.jsonl. Silently succeeds
  * even if the file or directory can't be written — hook must not block.
@@ -922,6 +1042,7 @@ 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();
+      if (deferToClaudeRegistration(cwd)) return;
       // M62: a global-install hook fires in every repo; don't pollute non-PAN
       // projects with .planning/ metrics artifacts. The tree must already exist —
       // see hasPlanningTree (field sweep 2026-09-17).
@@ -934,4 +1055,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { buildCostRecord, appendRecord, readUsageFromTranscript, resolveAgentTranscript, readCursor, writeCursor, isPanProject, hasPlanningTree, readCommandFromTranscript, isSessionStale, PAN_RUNTIME_DIRS, METRICS_DIR, TOKENS_FILE, CURSOR_FILE, SLICE_MAX, MAX_CURSOR_KEYS };
+module.exports = { deferToClaudeRegistration, normalizeHookPayload, isHostInternalAgent, buildCostRecord, appendRecord, readUsageFromTranscript, addCacheTtlSplit, resolveAgentTranscript, readCursor, writeCursor, isPanProject, hasPlanningTree, readCommandFromTranscript, isSessionStale, PAN_RUNTIME_DIRS, METRICS_DIR, TOKENS_FILE, CURSOR_FILE, SLICE_MAX, MAX_CURSOR_KEYS };

package/hooks/dist/pan-state-reinject.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+// State Re-injection - SessionStart hook, `compact` matcher (market-ideas queue M10)
+//
+// Compaction replaces the conversation with a summary, and a summary can drop the
+// one line that mattered: which phase is in flight, which plan, where it stopped.
+// The PanLoop boundary-drop class (finding 0) is that failure — an agent that no
+// longer knows it is mid-chain ends the turn or re-plans finished work. This hook
+// runs when the session restarts after a compaction and hands the model PAN's
+// current position, read from the planning tree on disk, as `additionalContext`.
+//
+// Why SessionStart and not PostCompact: Claude Code's PostCompact has no decision
+// control and discards its output ("Used for side effects like logging"), while
+// SessionStart fires again after a compaction with `source: "compact"` and honours
+// `hookSpecificOutput.additionalContext` (code.claude.com/docs/en/hooks, read
+// 2026-09-26). Codex is the same: its PostCompact output schema has no
+// additionalContext, and SessionStart hooks matching `source: "compact"` deliver it
+// to the continuation (codex hooks docs, read 2026-09-26). Registered with the
+// `compact` matcher on both; the source is re-checked here so a registration
+// without the matcher stays inert on every other start.
+//
+// Inert unless the project is a PAN project with work in flight: `.planning/`
+// holds a state.md that names a current phase AND a roadmap.md with an unticked
+// phase. Everywhere else — no planning tree, a focus-only project, a finished
+// milestone — it prints nothing. It never writes a file (field finding: hooks
+// that scaffolded `.planning/` in projects that never ran PAN).
+//
+// Fail-open everywhere: bad stdin, unreadable files — exit 0 silently. A missing
+// reminder costs a re-read; a crashed hook is a failing hook at every start.
+//
+// The block is capped well under the host's 10,000-character limit for
+// additionalContext; each field is truncated on its own.
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Which planning tree this hook acts on.
+ *
+ * Mirrors pan-wizard-core/bin/lib/planning-root.cjs, which hooks cannot require
+ * (they are standalone and run inside the host runtime). Every PAN hook that
+ * reads the planning tree carries an identical copy — if the CLI is pointed at a track while a hook still writes to
+ * `.planning/`, that tree's telemetry lands in the wrong place.
+ *
+ * Env only — a hook gets no argv. A value that escapes the project root is
+ * ignored rather than honoured: a bad value degrades to the default, never
+ * writes outside the project.
+ */
+function planningDirName() {
+  const raw = process.env.PAN_PLANNING_DIR || '';
+  if (raw.trim()) {
+    const rel = raw.trim().replace(/\\/g, '/');
+    const bad = rel.startsWith('/') || rel.startsWith('\\') || /^[A-Za-z]:/.test(rel)
+      || rel.split('/').includes('..');
+    if (!bad) return rel;
+  }
+  const track = (process.env.PAN_TRACK || '').trim();
+  if (track && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(track)) {
+    return `.planning/tracks/${track}`;
+  }
+  return '.planning';
+}
+
+/** Absolute path inside the active planning tree. */
+function planningPath(cwd, ...segments) {
+  return path.join(cwd, ...planningDirName().split('/'), ...segments);
+}
+
+// Same unticked-phase shape the stop guard and the PanLoop harness use: the
+// checklist line templates/roadmap.md and pan-roadmapper.md emit.
+const UNTICKED_PHASE_RE = /^- \[ \] \*\*Phase (\d+(?:\.\d+)?):/m;
+
+const FIELD_MAX = 240;
+const BLOCK_MAX = 2000;
+
+/** A `**Name:** value` field from state.md — the shape state.cjs reads and writes. */
+function field(content, name) {
+  const m = content.match(new RegExp(`\\*\\*${name}:\\*\\*[ \\t]*(.+)`, 'i'));
+  if (!m) return null;
+  const v = m[1].trim();
+  // Template placeholders ("[X]", "[Phase name]") are not a position.
+  if (!v || /^\[.*\]$/.test(v) || /^none$/i.test(v)) return null;
+  return v.length > FIELD_MAX ? v.slice(0, FIELD_MAX - 1) + '…' : v;
+}
+
+/**
+ * Pure: the additionalContext block for this planning tree, or null when there is
+ * nothing in flight to restore.
+ * @param {object} args
+ * @param {string|null} args.stateContent   .planning/state.md, or null
+ * @param {string|null} args.roadmapContent .planning/roadmap.md, or null
+ * @param {string} [args.planningRel]       the planning directory, for the pointer line
+ * @returns {string|null}
+ */
+function buildReinjectContext({ stateContent, roadmapContent, planningRel = '.planning' }) {
+  if (typeof stateContent !== 'string' || typeof roadmapContent !== 'string') return null;
+  const phase = field(stateContent, 'Current Phase');
+  if (!phase) return null;
+  const unticked = roadmapContent.match(UNTICKED_PHASE_RE);
+  if (!unticked) return null; // every roadmap phase is built — nothing in flight
+
+  const name = field(stateContent, 'Current Phase Name');
+  const plan = field(stateContent, 'Current Plan');
+  const plans = field(stateContent, 'Total Plans in Phase');
+  const status = field(stateContent, 'Status');
+  const stoppedAt = field(stateContent, 'Stopped At');
+  const lastDesc = field(stateContent, 'Last Activity Description');
+  const resume = field(stateContent, 'Resume File');
+
+  const lines = ['PAN project state, re-read from disk after context compaction:'];
+  let position = `- Current phase: ${phase}${name ? ` (${name})` : ''}`;
+  if (plan) position += `, plan ${plan}${plans ? ` of ${plans}` : ''}`;
+  lines.push(position);
+  if (status) lines.push(`- Status: ${status}`);
+  if (stoppedAt) lines.push(`- Stopped at: ${stoppedAt}`);
+  else if (lastDesc) lines.push(`- Last activity: ${lastDesc}`);
+  if (resume) lines.push(`- Resume file: ${resume}`);
+  lines.push(`- First unbuilt roadmap phase: Phase ${unticked[1]}`);
+  lines.push(`Re-read ${planningRel}/state.md and the current phase's plan before the next step: continue the work in flight rather than re-planning finished work.`);
+  const block = lines.join('\n');
+  return block.length > BLOCK_MAX ? block.slice(0, BLOCK_MAX - 1) + '…' : block;
+}
+
+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 = {};
+      if (payload.source !== 'compact') { process.exit(0); return; }
+
+      const projectDir = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd();
+      const context = buildReinjectContext({
+        stateContent: readIfExists(planningPath(projectDir, 'state.md')),
+        roadmapContent: readIfExists(planningPath(projectDir, 'roadmap.md')),
+        planningRel: planningDirName(),
+      });
+      if (context) {
+        process.stdout.write(JSON.stringify({
+          hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: context },
+        }));
+      }
+    } catch { /* fail open — never break a session start */ }
+    process.exit(0);
+  });
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { buildReinjectContext, UNTICKED_PHASE_RE };