pan-wizard 3.29.0 → 3.31.0

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

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

@@ -2,8 +2,9 @@
 
 // ─── AGENTS.md universal rules layer (ADR-0028 Phase 3) ─────────────────────
 //
-// AGENTS.md is the cross-runtime project-instructions standard; every PAN
-// target runtime (and Antigravity CLI) reads it natively. PAN contributes one
+// AGENTS.md is the cross-runtime project-instructions standard; Codex,
+// OpenCode and Copilot CLI read it natively, Claude Code only through the @AGENTS.md
+// import in CLAUDE.md; Gemini CLI reads GEMINI.md by default, not this file. PAN contributes one
 // marker-fenced section so agents in any runtime understand the PAN context
 // when reading the repo. User content outside the markers is never touched.
 //

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

@@ -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,