pan-wizard 3.30.0 → 3.31.0

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

@@ -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).
@@ -564,6 +603,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`
@@ -621,6 +662,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,6 +721,11 @@ 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
@@ -705,6 +755,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 +885,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 +990,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 +1003,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, 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). All PAN hooks carry 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 };

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

@@ -52,6 +52,12 @@
 // 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).
 //
+// Codex and Copilot CLI (M14, 2026-09-26): registered on Codex's `Stop` and
+// Copilot's `agentStop`. Both payloads carry `cwd` and `stop_hook_active` (Copilot
+// keeps that one field snake_case inside its camelCase payload) and both honour the
+// same {decision: 'block', reason} output, so the logic above applies unchanged.
+// Copilot also ends the turn itself after eight consecutive blocks.
+//
 // Escape hatch: set workflow.stop_guard to false in .planning/config.json to
 // disable the guard entirely without turning off auto_advance.
 //
@@ -66,6 +72,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;
+}
 const crypto = require('crypto');
 /**
  * Which planning tree this hook acts on.
@@ -238,6 +283,7 @@ function main() {
       if (!payload || typeof payload !== 'object') payload = {};
 
       const projectDir = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd();
+      if (deferToClaudeRegistration(projectDir)) process.exit(0);
       const planningDir = planningPath(projectDir);
 
       let config = null;
@@ -253,7 +299,7 @@ function main() {
       // 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);
+        const name = onceMarkerName(payload.session_id || payload.sessionId, projectDir, decision.reason);
         if (!claimOnceMarker(hookStateDir(), name)) decision = null;
       }
 
@@ -267,4 +313,4 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { buildStopDecision, UNTICKED_PHASE_RE, onceMarkerName, claimOnceMarker };
+module.exports = { deferToClaudeRegistration, buildStopDecision, UNTICKED_PHASE_RE, onceMarkerName, claimOnceMarker };

package/hooks/dist/pan-trace-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');
 /**
  * Which planning tree this hook acts on.
@@ -932,6 +971,7 @@ if (require.main === module) {
     try {
       const data = JSON.parse(input);
       const cwd = data.cwd || data.workspace?.current_dir || process.cwd();
+      if (deferToClaudeRegistration(cwd)) return;
       // M62: a global-install hook fires in every repo; skip non-PAN projects so
       // we don't create .planning/ optimization + trace artifacts in them. The tree
       // must already exist — see hasPlanningTree (field sweep 2026-09-17).
@@ -948,6 +988,7 @@ if (require.main === module) {
 }
 
 module.exports = {
+  deferToClaudeRegistration,
   buildTraceEvents,
   appendTraceEvents,
   resolveAgentTranscript,

package/package.json

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

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

@@ -3,7 +3,7 @@
  */
 const fs = require('fs');
 const path = require('path');
-const { safeReadFile, loadConfig, isGitIgnored, isGitRepo, execGit, normalizePhaseName, comparePhaseNum, getArchivedPhaseDirs, generateSlugInternal, getMilestoneInfo, resolveModelInternal, resolveEffortInternal, detectProvider, resolveTierToModel, estimateCostMultiplier, MODEL_PROFILES, output, error, findPhaseInternal, scanPendingTodos, toPosix } = require('./core.cjs');
+const { safeReadFile, loadConfig, isGitIgnored, isGitRepo, execGit, normalizePhaseName, comparePhaseNum, getArchivedPhaseDirs, generateSlugInternal, getMilestoneInfo, resolveModelInternal, resolveModelDetailed, resolveEffortInternal, detectProvider, resolveTierToModel, estimateCostMultiplier, MODEL_PROFILES, output, error, findPhaseInternal, scanPendingTodos, toPosix } = require('./core.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
 const { PHASES_DIR, MILESTONES_DIR, QUICK_DIR, STATE_FILE, ROADMAP_FILE, PROJECT_FILE, PATTERNS_FILE, SESSION_HISTORY_FILE, LEARNINGS_FILE, CONTEXT_SUFFIX, UAT_SUFFIX, VERIFICATION_SUFFIX, isPlanFile, isSummaryFile, ARCHIVE_DIR_RE, PHASE_DIR_RE, CONTEXT_WINDOW, WARNING_THRESHOLD, CRITICAL_THRESHOLD, VALID_COMMIT_TYPES, DEFAULT_SENSITIVE_PATTERNS } = require('./constants.cjs');
 const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, planningRel } = require('./utils.cjs');
@@ -220,7 +220,7 @@ function cmdHistoryDigest(cwd, raw) {
  * @param {string} [metadataJson] - Optional JSON string with task metadata for complexity routing
  * @returns {void}
  */
-function cmdResolveModel(cwd, agentType, raw, metadataJson) {
+function cmdResolveModel(cwd, agentType, raw, metadataJson, attempt) {
   if (!agentType) {
     error('agent-type required');
   }
@@ -230,6 +230,11 @@ function cmdResolveModel(cwd, agentType, raw, metadataJson) {
     try { taskMetadata = JSON.parse(metadataJson); }
     catch { /* ignore invalid metadata, use static routing */ }
   }
+  // --attempt N (M8): the retry number, 1 for a first try. It rides in the
+  // metadata so every resolution rule sees it; the flag wins over a metadata key.
+  if (attempt !== undefined) {
+    taskMetadata = { ...(taskMetadata && typeof taskMetadata === 'object' ? taskMetadata : {}), attempt };
+  }
 
   const config = loadConfig(cwd);
   const profile = config.model_profile || 'balanced';
@@ -243,9 +248,14 @@ function cmdResolveModel(cwd, agentType, raw, metadataJson) {
     return;
   }
 
-  const model = resolveModelInternal(cwd, agentType, taskMetadata);
+  const resolved = resolveModelDetailed(cwd, agentType, taskMetadata);
+  const model = resolved.model;
   const effort = resolveEffortInternal(cwd, agentType);
   const result = { model, profile, strategy, effort };
+  if (taskMetadata && Number.isInteger(taskMetadata.attempt)) {
+    result.attempt = taskMetadata.attempt;
+    result.escalated_from = resolved.escalated_from;
+  }
   output(result, raw, model);
 }
 
@@ -804,7 +814,13 @@ function cmdTodoComplete(cwd, filename, raw) {
   }
 
   const today = new Date().toISOString().split('T')[0];
-  content = `completed: ${today}\n` + content;
+  // /pan:todo-add writes YAML frontmatter; the date goes inside it. Prepending it
+  // put `completed:` above the opening `---` and broke the block. A file with no
+  // frontmatter keeps the old first-line form.
+  const fm = content.match(/^---\r?\n/);
+  content = fm
+    ? fm[0] + `completed: ${today}` + fm[0].slice(3) + content.slice(fm[0].length)
+    : `completed: ${today}\n` + content;
 
   try {
     fs.writeFileSync(path.join(completedDir, filename), content, 'utf-8');

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

@@ -84,6 +84,8 @@ function buildConfigDefaults(hasBraveSearch, userDefaults) {
       strategy: 'static',
       provider: 'auto',
       cascade_quality_gate: true,
+      // Failure-tier escalation (M8): how many tiers a retry may climb.
+      max_escalations: 1,
       complexity_thresholds: {
         downgrade_max: 2,
         upgrade_min: 6,

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

@@ -607,7 +607,9 @@ const SKILL_ALIGN_MAX_TASKS = 50;               // larger drafts are a planning
 const SKILL_ALIGN_CONTENT_CAP = 700;            // chars of file head scored (≈ objective paragraph)
 
 /** Valid conventional commit types */
-const VALID_COMMIT_TYPES = ['feat', 'fix', 'docs', 'test', 'refactor', 'chore'];
+// `perf` is a task commit type in references/git-integration.md; it was missing
+// here, so `pan-tools commit --type perf` refused a type the docs prescribe.
+const VALID_COMMIT_TYPES = ['feat', 'fix', 'docs', 'test', 'refactor', 'perf', 'chore'];
 
 /** Default sensitive file patterns for commit safety checks */
 const DEFAULT_SENSITIVE_PATTERNS = ['\\.env$', '\\.pem$', '\\.key$', 'credentials', 'secret', 'password', 'token'];

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

@@ -113,9 +113,23 @@ function assessCacheTtl(records, opts = {}) {
     // last record: its cache writes are not a subagent's re-write after an idle
     // gap, and the subagent cache lifetime setting does not govern them.
     .filter(r => !(r && r.token_source === 'session-transcript'))
-    .map(r => ({ t: r && r.ts ? new Date(r.ts).getTime() : NaN, w: Number(r && r.cache_write_tokens) || 0 }))
+    // A row that recorded the cache-write lifetime split (M13) says which writes
+    // were five-minute ones; only those can be a re-write after a short idle gap —
+    // a one-hour write already outlives it. Rows without the split fall back to the
+    // gap heuristic on the whole write.
+    .map(r => {
+      const measured = r && typeof r.cache_write_5m_tokens === 'number';
+      return {
+        t: r && r.ts ? new Date(r.ts).getTime() : NaN,
+        w: measured ? r.cache_write_5m_tokens : (Number(r && r.cache_write_tokens) || 0),
+        w1h: measured ? (Number(r.cache_write_1h_tokens) || 0) : 0,
+        measured,
+      };
+    })
     .filter(r => Number.isFinite(r.t))
     .sort((a, b) => a.t - b.t);
+  const measuredRows = rows.filter(r => r.measured);
+  const basis = measuredRows.length === 0 ? 'inferred' : measuredRows.length === rows.length ? 'measured' : 'mixed';
   let shortIdle = 0; let shortIdleTokens = 0; let longIdle = 0;
   for (let i = 1; i < rows.length; i++) {
     if (rows[i].w < minWrite) continue;
@@ -126,14 +140,25 @@ function assessCacheTtl(records, opts = {}) {
   const recommend = shortIdle >= recommendAt;
   const setting = 'subagentPromptCacheTtl';
   const severity = recommend && shortIdleTokens >= (opts.warnTokens ?? TTL_WARN_TOKENS) ? 'warn' : 'info';
+  const basisNote = basis === 'measured'
+    ? ' (measured: the ledger records each write\'s cache lifetime)'
+    : basis === 'mixed'
+      ? ' (partly measured: rows written before PAN recorded the cache lifetime are counted from idle gaps alone)'
+      : ' (inferred from idle gaps between rows: no row records the cache lifetime)';
   const advice = recommend
-    ? `${shortIdle} cache writes followed an idle gap of ${TTL_SHORT_MIN}–${TTL_LONG_MIN} min (~${shortIdleTokens.toLocaleString()} tokens re-written): subagents get the five-minute cache lifetime by default — set \`${setting}: "1h"\` in a Claude Code settings file. One-hour writes bill at 2× base input against 1.25×, so this pays off once a block is read twice within the hour.`
+    ? `${shortIdle} cache writes followed an idle gap of ${TTL_SHORT_MIN}–${TTL_LONG_MIN} min (~${shortIdleTokens.toLocaleString()} tokens re-written): subagents get the five-minute cache lifetime by default — set \`${setting}: "1h"\` in a Claude Code settings file. One-hour writes bill at 2× base input against 1.25×, so this pays off once a block is read twice within the hour.${basisNote}`
     : null;
   return {
     records_considered: rows.length,
     writes_after_short_idle: shortIdle,
     tokens_after_short_idle: shortIdleTokens,
     writes_after_long_idle: longIdle,
+    // Where the split came from: 'measured' (every row carries it), 'mixed', or
+    // 'inferred' (none does — the gap heuristic alone).
+    basis,
+    measured_rows: measuredRows.length,
+    cache_write_1h_tokens: measuredRows.reduce((n, r) => n + r.w1h, 0),
+    cache_write_5m_tokens: measuredRows.reduce((n, r) => n + r.w, 0),
     recommend,
     setting,
     severity,