pan-wizard 3.34.0 → 3.36.0

package/commands/pan/what-if.md

@@ -20,7 +20,6 @@ Unchanged from Spec B v1's X-9. Already narrow enough to stand alone.
 </objective>
 
 <execution_context>
-@~/.claude/pan-wizard-core/bin/lib/whatif.cjs
 @~/.claude/agents/pan-counterfactual.md
 </execution_context>
 
@@ -80,7 +79,7 @@ This writes `.planning/counterfactuals/<phase>-<slug>.md`. The file belongs to t
 pan-tools whatif cleanup --worktree <path> --branch <name> --force
 ```
 
-Removes the worktree directory and deletes the counterfactual branch. Best-effort: warnings are surfaced but don't block.
+Removes the worktree directory and deletes the counterfactual branch. Pass the `worktree.worktree_path` and `worktree.branch` that `whatif prepare` returned, unchanged. Cleanup refuses (exit 1, nothing removed) a branch outside `pan-whatif/` and a worktree that is not checked out on that branch, so it can never delete your own work. Otherwise best-effort: warnings are surfaced but don't block.
 
 ### Stage 5 — Confirm
 

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

@@ -429,14 +429,23 @@ function buildContextWarning(metrics, warnState, nowSeconds, opts = {}) {
   };
 }
 
-/** Claude Code's settings for a project, highest precedence first: local, project, user. */
-function readClaudeSettings(projectDir, homeDir = os.homedir()) {
+/**
+ * Claude Code's settings for a project, highest precedence first: local, project, user.
+ * The user file lives in CLAUDE_CONFIG_DIR when that is set, as Claude Code reads it.
+ * A given homeDir is a test seam and ignores CLAUDE_CONFIG_DIR (as the statusline and
+ * hygiene do), unless configDir is passed too.
+ */
+function readClaudeSettings(projectDir, homeArg, configArg) {
+  const seam = homeArg !== undefined;
+  const homeDir = seam ? homeArg : os.homedir();
+  const configDir = configArg !== undefined ? configArg : (seam ? '' : (process.env.CLAUDE_CONFIG_DIR || ''));
   // Assembled, not a literal: the installer rewrites quoted .claude literals in hook
   // copies, and these are Claude Code's own settings (only it writes the bridge).
   const dir = ['.', 'claude'].join('');
   const files = [];
   if (typeof projectDir === 'string' && projectDir) files.push(path.join(projectDir, dir, 'settings.local.json'), path.join(projectDir, dir, 'settings.json'));
-  if (homeDir) files.push(path.join(homeDir, dir, 'settings.json'));
+  if (configDir) files.push(path.join(configDir, 'settings.json'));
+  else if (homeDir) files.push(path.join(homeDir, dir, 'settings.json'));
   const out = [];
   for (const f of files) {
     try { out.push(JSON.parse(fs.readFileSync(f, 'utf8'))); } catch { /* absent or unreadable */ }

package/hooks/dist/pan-guard.js

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+'use strict';
+// PAN guard — a pre-tool hook (program A7).
+//
+// Registered on the hosts with a pre-tool event that can deny a call: Claude Code
+// and Codex (`PreToolUse`), Gemini CLI (`BeforeTool`) and Copilot CLI (`preToolUse`).
+// OpenCode registers no hooks. The command carries `--host <runtime>`, because the
+// payload and the way to deny differ per host.
+//
+// Rules, over the files a tool call is about to write:
+//   secret_write          the written text holds a credential (known token shapes,
+//                         or a long key=value secret)
+//   state_write           a direct write to PAN's own state: state.md, findings.jsonl,
+//                         the token ledger (pan-tools owns those)
+//   undeclared_test_edit  a test file the phase in flight does not declare in any
+//                         unfinished plan's files_modified
+//
+// Mode, from the planning tree's config.json `hooks.guard`:
+//   off      nothing
+//   report   (default) every match is appended to <planning>/guard.jsonl, the call proceeds
+//   enforce  as report, and a secret_write is denied; the other rules still only report
+//            until the writers of PAN's state go through pan-tools verbs (A7b)
+//
+// Inert outside a PAN project. Fail-open on anything it cannot parse; never fail-open
+// on a matched deny. Never writes outside the planning tree.
+
+const fs = require('fs');
+const path = require('path');
+
+const TOKEN_RE = /\b(?:sk-ant-[A-Za-z0-9_-]{10,}|sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|xox[abprs]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|AIza[0-9A-Za-z_-]{30,}|-----BEGIN (?:RSA |EC |OPENSSH |)PRIVATE KEY-----)/;
+const SECRET_KV_RE = /\b(api[_-]?key|access[_-]?token|auth[_-]?token|refresh[_-]?token|client[_-]?secret|secret[_-]?key|password|passwd)\b["']?\s*[:=]\s*["']([^"'\s]{12,})["']/i;
+const TEST_PATH_RE = /(^|\/)(tests?|__tests__|specs?)\//i;
+const TEST_FILE_RE = /(\.(test|spec)\.[a-z0-9]+|(^|\/)test_[^/]+\.py|_test\.(py|go)|Tests?\.(java|kt|cs))$/i;
+const MODES = ['off', 'report', 'enforce'];
+
+// ─── 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;
+}
+
+
+function planningDirName() {
+  const raw = process.env.PAN_PLANNING_DIR || '';
+  if (raw.trim()) {
+    const rel = raw.trim().replace(/\\/g, '/');
+    const bad = 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';
+}
+
+function readJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; }
+}
+
+/** A value that is a placeholder, not a credential. */
+function isPlaceholder(v) {
+  return /^(?:\$\{|\$[A-Z_]|process\.env|os\.environ|<|xxx|your[_-]|changeme|example|dummy|placeholder|redacted|\*+$)/i.test(v);
+}
+
+function hasSecret(text) {
+  if (typeof text !== 'string' || !text) return false;
+  if (TOKEN_RE.test(text)) return true;
+  const m = text.match(SECRET_KV_RE);
+  return !!(m && !isPlaceholder(m[2]) && /\d/.test(m[2]) && /[A-Za-z]/.test(m[2]));
+}
+
+/**
+ * The tool call as `{tool, writes: [{path, text}], command}`, whatever the host.
+ * Claude/Codex/Gemini send `tool_name` + `tool_input`; Copilot sends `toolName` +
+ * `toolArgs` (a JSON string).
+ */
+function normalise(payload) {
+  const p = payload && typeof payload === 'object' ? payload : {};
+  const tool = String(p.tool_name || p.toolName || p.tool || '');
+  let input = p.tool_input || p.toolArgs || p.input || {};
+  if (typeof input === 'string') { try { input = JSON.parse(input); } catch { input = { command: input }; } }
+  if (!input || typeof input !== 'object') input = {};
+  const writes = [];
+  const file = input.file_path || input.filePath || input.path || input.notebook_path || input.absolute_path;
+  const texts = [input.content, input.new_string, input.newString, input.new_source, input.file_text, input.text]
+    .concat(Array.isArray(input.edits) ? input.edits.map((e) => e && (e.new_string || e.newString)) : [])
+    .filter((t) => typeof t === 'string');
+  if (typeof file === 'string' && file && (texts.length || /write|edit|create|replace|notebook/i.test(tool))) {
+    writes.push({ path: file, text: texts.join('\n') });
+  }
+  const command = typeof input.command === 'string' ? input.command : (Array.isArray(input.command) ? input.command.join(' ') : '');
+  // Codex edits files through apply_patch: the patch names its files and carries the text.
+  if (/\*\*\* (?:Add|Update) File: /.test(command)) {
+    let cur = null;
+    for (const line of command.split(/\r?\n/)) {
+      const m = line.match(/^\*\*\* (?:Add|Update) File: (.+)$/);
+      if (m) { cur = { path: m[1].trim(), text: '' }; writes.push(cur); continue; }
+      if (cur && line.startsWith('+')) cur.text += line.slice(1) + '\n';
+    }
+  }
+  return { tool, writes, command };
+}
+
+/** Project-relative POSIX path, or null when the path is outside the project. */
+function rel(projectDir, p) {
+  const abs = path.resolve(projectDir, p);
+  const r = path.relative(projectDir, abs).replace(/\\/g, '/');
+  return r.startsWith('..') || path.isAbsolute(r) ? null : r;
+}
+
+function isTestFile(r) {
+  return TEST_PATH_RE.test(r) || TEST_FILE_RE.test(r);
+}
+
+/** files_modified of the unfinished plans of the phase state.md names, or null when none is in flight. */
+function declaredFiles(projectDir, planningRel) {
+  let state;
+  try { state = fs.readFileSync(path.join(projectDir, planningRel, 'state.md'), 'utf8'); } catch { return null; }
+  const m = state.match(/\*\*Current Phase:\*\*[ \t]*([0-9]+(?:\.[0-9]+)?)/i) || state.match(/^Phase:[ \t]*([0-9]+(?:\.[0-9]+)?)/m);
+  if (!m) return null;
+  const want = String(parseFloat(m[1]));
+  const phasesDir = path.join(projectDir, planningRel, 'phases');
+  let dir;
+  try { dir = fs.readdirSync(phasesDir).find((d) => { const n = d.match(/^(\d+(?:\.\d+)?)-/); return n && String(parseFloat(n[1])) === want; }); } catch { return null; }
+  if (!dir) return null;
+  const full = path.join(phasesDir, dir);
+  const names = fs.readdirSync(full);
+  const done = new Set(names.filter((n) => n.endsWith('-summary.md')).map((n) => n.replace(/-summary\.md$/, '')));
+  const out = new Set();
+  let plans = 0;
+  for (const n of names.filter((x) => x.endsWith('-plan.md'))) {
+    if (done.has(n.replace(/-plan\.md$/, ''))) continue;
+    plans++;
+    const text = fs.readFileSync(path.join(full, n), 'utf8').replace(/\r\n/g, '\n');
+    const fm = text.match(/^---\n([\s\S]*?)\n---/);
+    if (!fm) continue;
+    const inline = fm[1].match(/^files_modified:[ \t]*\[([^\]]*)\]/m);
+    if (inline) inline[1].split(',').map((s) => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean).forEach((f) => out.add(f.replace(/^\.\//, '')));
+    const block = fm[1].match(/^files_modified:[ \t]*\n((?:[ \t]+-.*\n?)+)/m);
+    if (block) block[1].split('\n').map((l) => l.replace(/^[ \t]+-[ \t]*/, '').trim().replace(/^["']|["']$/g, '')).filter(Boolean).forEach((f) => out.add(f.replace(/^\.\//, '')));
+  }
+  return plans ? out : null;
+}
+
+/** The rule matches for one normalised call. */
+function evaluate(call, projectDir, planningRel) {
+  const hits = [];
+  const declared = call.writes.length ? declaredFiles(projectDir, planningRel) : null;
+  const ownState = new Set([`${planningRel}/state.md`, `${planningRel}/findings.jsonl`, `${planningRel}/metrics/tokens.jsonl`]);
+  for (const w of call.writes) {
+    const r = rel(projectDir, w.path);
+    if (hasSecret(w.text)) hits.push({ rule: 'secret_write', path: r || w.path });
+    if (!r) continue;
+    if (ownState.has(r)) hits.push({ rule: 'state_write', path: r });
+    if (declared && isTestFile(r) && !declared.has(r)) hits.push({ rule: 'undeclared_test_edit', path: r });
+  }
+  return hits;
+}
+
+function decide(hits, mode) {
+  if (mode !== 'enforce') return null;
+  return hits.find((h) => h.rule === 'secret_write') || null;
+}
+
+/** The host whose deny format this call needs: Copilot by payload shape, else the --host flag. */
+function hostOf(payload, flagHost) {
+  const p = payload && typeof payload === 'object' ? payload : {};
+  if (typeof p.toolName === 'string' && p.tool_name === undefined) return 'copilot';
+  return flagHost;
+}
+
+function main() {
+  const flagHost = (process.argv[process.argv.indexOf('--host') + 1] || 'claude').toLowerCase();
+  let raw = '';
+  try { raw = fs.readFileSync(0, 'utf8'); } catch { return; }
+  let payload;
+  try { payload = JSON.parse(raw); } catch { return; } // fail open
+  const projectDir = (payload && (payload.cwd || payload.workspace || payload.project_dir)) || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  if (deferToClaudeRegistration(projectDir)) return; // the Claude registration covers this call under Copilot
+  // The payload names the host better than the registration does: Copilot sends its own
+  // camelCase payload (toolName, toolArgs) even to a hook registered in .claude/settings.json,
+  // and denies only on the JSON decision, so a Copilot payload gets Copilot's deny whatever
+  // --host says. The flag decides for the snake_case hosts (Claude Code, Codex, Gemini).
+  const host = hostOf(payload, flagHost);
+  const planningRel = planningDirName();
+  const planning = path.join(projectDir, planningRel);
+  if (!fs.existsSync(planning)) return; // not a PAN project
+  const cfg = readJson(path.join(planning, 'config.json')) || {};
+  const mode = MODES.includes(cfg.hooks && cfg.hooks.guard) ? cfg.hooks.guard : 'report';
+  if (mode === 'off') return;
+  let hits = [];
+  try { hits = evaluate(normalise(payload), projectDir, planningRel); } catch { return; } // fail open
+  if (!hits.length) return;
+  const deny = decide(hits, mode);
+  try {
+    const ts = new Date().toISOString();
+    const lines = hits.map((h) => JSON.stringify({ ts, host, mode, rule: h.rule, path: h.path, tool: normalise(payload).tool, action: deny && h === deny ? 'denied' : 'reported' }));
+    fs.appendFileSync(path.join(planning, 'guard.jsonl'), lines.join('\n') + '\n');
+  } catch { /* the log is best effort; a deny below still stands */ }
+  if (!deny) return;
+  const reason = `PAN guard: this write puts a credential into ${deny.path}. Keep secrets out of the repository (an environment variable or a local, ignored file), then retry. (hooks.guard: enforce)`;
+  if (host === 'copilot') {
+    process.stdout.write(JSON.stringify({ permissionDecision: 'deny', permissionDecisionReason: reason }) + '\n');
+    return;
+  }
+  process.stderr.write(reason + '\n');
+  process.exitCode = 2;
+}
+
+if (require.main === module) main();
+
+module.exports = { normalise, evaluate, decide, hasSecret, declaredFiles, isTestFile, hostOf, deferToClaudeRegistration };

package/hooks/dist/pan-statusline.js

@@ -13,7 +13,7 @@ const os = require('os');
  *
  * @param {Object} data - Parsed stdin JSON from Claude Code.
  * @param {Object} [deps] - Optional dep injection for testing.
- *   {fs, path, homeDir, tmpDir} — defaults to real modules + OS paths.
+ *   {fs, path, homeDir, tmpDir, configDir} — defaults to real modules + OS paths (configDir: CLAUDE_CONFIG_DIR, ignored when homeDir is given).
  * @returns {string} The statusline content.
  */
 function buildStatuslineOutput(data, deps) {
@@ -155,7 +155,10 @@ function buildStatuslineOutput(data, deps) {
 
   // Current task from todos
   let task = '';
-  const todosDir = pathMod.join(homeDir, '.claude', 'todos');
+  // Claude Code keeps its todos in CLAUDE_CONFIG_DIR when that is set (a given
+  // homeDir is a test seam and ignores it).
+  const configDir = d.configDir !== undefined ? d.configDir : (d.homeDir ? '' : (process.env.CLAUDE_CONFIG_DIR || ''));
+  const todosDir = configDir ? pathMod.join(configDir, 'todos') : pathMod.join(homeDir, '.claude', 'todos');
   let todosExists = false;
   try { todosExists = fsMod.statSync(todosDir).isDirectory(); } catch { /* missing */ }
   if (session && todosExists) {

package/package.json

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

@@ -556,6 +556,21 @@ function cmdSummaryExtract(cwd, summaryPath, fields, raw) {
   output(fullResult, raw);
 }
 
+/**
+ * Map a --freshness value to Brave's `freshness` parameter, which accepts only
+ * pd/pw/pm/py or a YYYY-MM-DDtoYYYY-MM-DD range. Returns null for anything else.
+ * @param {string} value - day|week|month|year, or a value Brave accepts as is
+ * @returns {string|null}
+ */
+function braveFreshness(value) {
+  const v = String(value || '').trim().toLowerCase();
+  const named = { day: 'pd', week: 'pw', month: 'pm', year: 'py' };
+  if (named[v]) return named[v];
+  if (/^p[dwmy]$/.test(v)) return v;
+  if (/^\d{4}-\d{2}-\d{2}to\d{4}-\d{2}-\d{2}$/.test(v)) return v;
+  return null;
+}
+
 /**
  * Search the web using Brave Search API and return structured results.
  *
@@ -588,6 +603,12 @@ async function cmdWebsearch(query, options, raw) {
     return;
   }
 
+  const freshness = options.freshness ? braveFreshness(options.freshness) : null;
+  if (options.freshness && !freshness) {
+    output({ available: false, error: `Invalid --freshness "${options.freshness}": use day, week, month, year, pd, pw, pm, py or YYYY-MM-DDtoYYYY-MM-DD` }, raw, '');
+    return;
+  }
+
   const params = new URLSearchParams({
     q: query,
     count: String(options.limit || 10),
@@ -596,8 +617,8 @@ async function cmdWebsearch(query, options, raw) {
     text_decorations: 'false'
   });
 
-  if (options.freshness) {
-    params.set('freshness', options.freshness);
+  if (freshness) {
+    params.set('freshness', freshness);
   }
 
   try {
@@ -1161,6 +1182,7 @@ module.exports = {
   cmdSummaryExtract,
   summaryOneLiner,
   cmdWebsearch,
+  braveFreshness,
   cmdProgressRender,
   cmdTodoComplete,
   cmdScaffold,

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

@@ -53,10 +53,21 @@ function buildConfigDefaults(hasBraveSearch, userDefaults) {
       verifier: true,
       nyquist_validation: false,
       phase_record_compact: false,
+      // V1: the phase gate. `enforce` (the default since V1E) refuses; `warn` reports
+      // refusals and completes.
+      phase_gate: 'enforce',
+      // V5: the mutation report on a phase's diff. `report` lists surviving mutants and
+      // never refuses; `off` skips it; `gate` is reserved for V5G.
+      mutation_gate: 'report',
       // M2: opt-in per-phase HTML reports at the verify→complete gate.
       phase_reports: { enabled: false, open: false, theme: 'auto', index: true },
     },
     parallelization: true,
+    // A7: the pre-tool guard. `report` logs to <planning>/guard.jsonl; `enforce` also
+    // denies a write that puts a credential in a file; `off` disables it.
+    hooks: { guard: 'report' },
+    // Spend per phase, in API-equivalent dollars. It only warns (80% and over); 0 = off.
+    cost: { phase_budget_usd: 20 },
     brave_search: hasBraveSearch,
     budget: {
       default_points: 50,
@@ -97,6 +108,7 @@ function buildConfigDefaults(hasBraveSearch, userDefaults) {
     ...userDefaults,
     workflow: { ...hardcoded.workflow, ...(userDefaults.workflow || {}) },
     budget: { ...hardcoded.budget, ...(userDefaults.budget || {}) },
+    cost: { ...hardcoded.cost, ...(userDefaults.cost || {}) },
     commit: { ...hardcoded.commit, ...(userDefaults.commit || {}) },
     execution: { ...hardcoded.execution, ...(userDefaults.execution || {}) },
     routing: { ...hardcoded.routing, ...(userDefaults.routing || {}) },
@@ -114,7 +126,7 @@ const CONFIG_KEYS_BEYOND_DEFAULTS = Object.freeze({
   top: Object.freeze(['research', 'plan_checker', 'verifier', 'nyquist_validation', 'mode', 'depth', 'planning', 'git',
     'focus', 'model_overrides', 'effort_overrides', 'cost', 'cache', 'build', 'verification', 'concurrency', 'memory']),
   sections: Object.freeze({
-    workflow: Object.freeze(['auto_advance', 'stop_guard']),
+    workflow: Object.freeze(['auto_advance', 'stop_guard', 'test_command', 'test_file_command']),
     planning: Object.freeze(['commit_docs', 'search_gitignored']),
     git: Object.freeze(['branching_strategy', 'phase_branch_template', 'milestone_branch_template']),
   }),

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

@@ -559,23 +559,28 @@ function isGitRepo(cwd) {
 }
 
 /**
- * Execute a git command safely with proper argument escaping.
+ * Execute a git command safely with proper argument escaping. stdout is trimmed;
+ * `keepLeading` trims only whitespace at its end, for output whose first column means
+ * something (`git status --porcelain` starts an unstaged edit with a space, which a
+ * full trim cuts off the first line).
  * @param {string} cwd - Working directory for git
  * @param {string[]} args - Git arguments (e.g., ['add', 'file.md'])
+ * @param {{keepLeading?: boolean}} [opts]
  * @returns {{exitCode: number, stdout: string, stderr: string}}
  */
-function execGit(cwd, args) {
+function execGit(cwd, args, opts = {}) {
+  const clean = (s) => (opts.keepLeading ? String(s).replace(/\s+$/, '') : String(s).trim());
   try {
     const stdout = execFileSync('git', args, {
       cwd,
       stdio: 'pipe',
       encoding: 'utf-8',
     });
-    return { exitCode: 0, stdout: stdout.trim(), stderr: '' };
+    return { exitCode: 0, stdout: clean(stdout), stderr: '' };
   } catch (err) {
     return {
       exitCode: err.status ?? 1,
-      stdout: (err.stdout ?? '').toString().trim(),
+      stdout: clean((err.stdout ?? '').toString()),
       stderr: (err.stderr ?? '').toString().trim(),
     };
   }

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

@@ -664,6 +664,146 @@ function aggregate(cwd, opts) {
   };
 }
 
+// ─── Per-phase budget ───────────────────────────────────────────────────────
+// `cost.phase_budget_usd` (default $20, `0`/`false` = off). It only WARNS: `near` from
+// PHASE_BUDGET_WARN_PCT of the budget, `over` once spend reaches it. No run stops on it.
+// On a subscription the dollars are API-equivalent: what the tokens would cost at the
+// configured rates.
+
+const DEFAULT_PHASE_BUDGET_USD = 20;
+const PHASE_BUDGET_WARN_PCT = 80;
+
+function phaseBudgetUsd(cwd) {
+  let v;
+  try { v = loadConfig(cwd)?.cost?.phase_budget_usd; } catch { /* defaults */ }
+  if (v === false || v === 0 || v === '0') return 0;
+  const n = Number(v);
+  return v != null && Number.isFinite(n) && n > 0 ? n : DEFAULT_PHASE_BUDGET_USD;
+}
+
+/**
+ * A phase's spend against its budget.
+ * @returns {{phase, budget_usd, spent_usd, pct, status: 'off'|'ok'|'near'|'over', mode: 'warn', warn_at_pct, unpriced}}
+ */
+function phaseBudget(cwd, phase) {
+  const budget = phaseBudgetUsd(cwd);
+  const rates = effectiveRates(loadConfig(cwd));
+  const key = samePhaseKey(phase);
+  let spent = 0;
+  let unpriced = 0;
+  for (const r of readRecords(cwd)) {
+    if (samePhaseKey(r.phase) !== key || isSuspectRecord(r) || isEmptyRecord(r)) continue;
+    const usd = typeof r.cost_usd === 'number' ? r.cost_usd : computeCost(r, rates);
+    if (typeof usd === 'number') spent += usd;
+    else unpriced++;
+  }
+  spent = round4(spent);
+  const pct = budget > 0 ? Math.round((spent / budget) * 1000) / 10 : null;
+  let status = 'off';
+  if (budget > 0) status = pct >= 100 ? 'over' : pct >= PHASE_BUDGET_WARN_PCT ? 'near' : 'ok';
+  return { phase: String(phase), budget_usd: budget, spent_usd: spent, pct, status, mode: 'warn', warn_at_pct: PHASE_BUDGET_WARN_PCT, unpriced };
+}
+
+function cmdCostBudget(cwd, phase, raw) {
+  if (!phase) error('Usage: cost budget --phase <N>');
+  const r = phaseBudget(cwd, phase);
+  output(r, raw, r.status);
+}
+
+// ─── Cost forecast (program P6) ─────────────────────────────────────────────
+// What a plan and a phase will cost, as p10/p50/p90 dollars, from what this project's
+// agents have cost so far. Fewer than FORECAST_MIN_SAMPLES observations is no
+// forecast: the result says `insufficient` rather than extrapolating from two runs.
+
+const FORECAST_MIN_SAMPLES = 5;
+const FORECAST_ITERATIONS = 2000;
+const PLAN_AGENT = 'pan-executor';
+
+const round4 = (x) => Math.round(x * 10000) / 10000;
+
+/** Linear interpolation between the closest ranks (R type 7). */
+function quantile(sorted, q) {
+  const h = (sorted.length - 1) * q;
+  const lo = Math.floor(h);
+  return sorted[lo] + (sorted[Math.min(lo + 1, sorted.length - 1)] - sorted[lo]) * (h - lo);
+}
+
+function quantiles(values) {
+  const s = [...values].sort((a, b) => a - b);
+  return { p10: round4(quantile(s, 0.1)), p50: round4(quantile(s, 0.5)), p90: round4(quantile(s, 0.9)) };
+}
+
+/** mulberry32: a seeded PRNG, so a forecast is reproducible. */
+function prng(seed) {
+  let a = (Number(seed) >>> 0) || 1;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+const samePhaseKey = (p) => String(p == null ? '' : p).replace(/^0+(?=\d)/, '');
+
+/**
+ * Forecast a plan and a phase.
+ *
+ * - Per plan: the cost of each pan-executor call at one tier (the tier the latest
+ *   executor call ran at, unless `tier` is given). Tiers differ several-fold in price,
+ *   so they are never pooled.
+ * - Per phase: for each past phase, the cost of its other agents (planner, checkers,
+ *   verifier, reviewer …); a phase is resampled as one of those plus one executor
+ *   draw per plan, `FORECAST_ITERATIONS` times, seeded.
+ *
+ * @param {string} cwd
+ * @param {{plans?: number, tier?: string, excludePhase?: string, seed?: number}} [opts]
+ */
+function costForecast(cwd, opts = {}) {
+  const rates = effectiveRates(loadConfig(cwd));
+  const exclude = opts.excludePhase != null ? samePhaseKey(opts.excludePhase) : null;
+  const rows = [];
+  for (const r of readRecords(cwd)) {
+    if (isSuspectRecord(r) || isEmptyRecord(r)) continue;
+    if (exclude != null && samePhaseKey(r.phase) === exclude) continue;
+    const usd = typeof r.cost_usd === 'number' ? r.cost_usd : computeCost(r, rates);
+    if (typeof usd === 'number') rows.push({ ...r, usd });
+  }
+  const executor = rows.filter((r) => r.agent === PLAN_AGENT);
+  const tier = opts.tier || (executor.length ? executor[executor.length - 1].tier || null : null);
+  const planCosts = executor.filter((r) => (r.tier || null) === tier).map((r) => r.usd);
+  const parsedPlans = Number.parseInt(opts.plans, 10);
+  const plans = Number.isFinite(parsedPlans) && parsedPlans >= 0 ? parsedPlans : 1;
+  const insufficient = (n) => ({ status: 'insufficient', n, needed: FORECAST_MIN_SAMPLES });
+
+  const perPlan = planCosts.length >= FORECAST_MIN_SAMPLES ? { status: 'ok', n: planCosts.length, ...quantiles(planCosts) } : insufficient(planCosts.length);
+
+  // A past phase is one the executor ran in; its overhead is everything else it spent.
+  const ranIn = new Set(executor.filter((r) => r.phase != null).map((r) => samePhaseKey(r.phase)));
+  const overhead = new Map([...ranIn].map((p) => [p, 0]));
+  for (const r of rows) {
+    const p = samePhaseKey(r.phase);
+    if (r.agent !== PLAN_AGENT && overhead.has(p)) overhead.set(p, overhead.get(p) + r.usd);
+  }
+  const overheads = [...overhead.values()];
+  let phase;
+  if (perPlan.status !== 'ok') phase = { ...insufficient(planCosts.length), n_phases: overheads.length, reason: 'too few executor calls at this tier' };
+  else if (overheads.length < FORECAST_MIN_SAMPLES) phase = { ...insufficient(overheads.length), n_phases: overheads.length, reason: 'too few past phases' };
+  else {
+    const rand = prng(opts.seed == null ? 1 : opts.seed);
+    const pick = (arr) => arr[Math.floor(rand() * arr.length)];
+    const sims = [];
+    for (let i = 0; i < FORECAST_ITERATIONS; i++) {
+      let usd = pick(overheads);
+      for (let k = 0; k < plans; k++) usd += pick(planCosts);
+      sims.push(usd);
+    }
+    phase = { status: 'ok', n_phases: overheads.length, ...quantiles(sims) };
+  }
+  return { agent: PLAN_AGENT, tier, plans, min_samples: FORECAST_MIN_SAMPLES, per_plan: perPlan, phase };
+}
+
 /**
  * Render aggregation as a human-readable table.
  * @param {Object} agg - from aggregate()
@@ -900,6 +1040,12 @@ function cmdModelsCheck(raw) {
 
 module.exports = {
   computeCost,
+  phaseBudget,
+  cmdCostBudget,
+  DEFAULT_PHASE_BUDGET_USD,
+  costForecast,
+  quantiles,
+  FORECAST_MIN_SAMPLES,
   appendRecord,
   readRecords,
   aggregate,

package/pan-wizard-core/bin/lib/doc-lint.cjs

@@ -343,11 +343,13 @@ function scanDocFlags(cwd, opts = {}) {
   const docDirs = opts.docDirs || ['docs'];
   const collected = [];
   for (const d of docDirs) {
-    const abs = path.join(cwd, d);
+    const abs = path.resolve(cwd, d);
     if (!fs.existsSync(abs)) continue;
     for (const f of walkMarkdownFiles(abs)) {
       if (f.readError) continue;
-      collected.push({ rel: path.join(d, f.relativePath).replace(/\\/g, '/'), content: f.content });
+      // Relative to the project root whether --doc-dir was given relative or
+      // absolute, so the frozen-doc allowlist sees project segments only.
+      collected.push({ rel: path.relative(cwd, path.join(abs, f.relativePath)).replace(/\\/g, '/'), content: f.content });
     }
   }
   for (const rel of (opts.files || [])) {
@@ -379,7 +381,7 @@ function scanDocFlags(cwd, opts = {}) {
 
 function cmdDocLintFlags(cwd, opts = {}, raw) {
   for (const d of opts.docDirs || []) {
-    const abs = path.isAbsolute(d) ? d : path.join(cwd, d);
+    const abs = path.resolve(cwd, d);
     if (fs.existsSync(abs)) requireDirectory(abs);
   }
   const r = scanDocFlags(cwd, opts);