pan-wizard 3.35.0 → 3.37.0

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

@@ -0,0 +1,143 @@
+'use strict';
+/**
+ * CI as an oracle for the autodev loop (program A2).
+ *
+ * The loop never takes a session's word for its tests. Locally the oracle is the phase
+ * gate and the test-run engine (V1, V2); with `autodev run --ci` it is also the pull
+ * request's checks, read through GitHub's `gh` CLI (optional: without it the CI oracle
+ * is `unavailable`). A check that already fails on the base branch is not this change's
+ * doing and is ignored. The failing log tail is what a fix round gets as feedback, and a
+ * breaker stops after N rounds.
+ *
+ * `autodev run --ci local` needs no pull request: the oracle is the project's own gate,
+ * run here — `npm run ci:local` when package.json has that script, else `npm test`.
+ */
+
+const { spawnSync } = require('child_process');
+
+const DEFAULT_CI_ROUNDS = 3;
+
+function defaultExec(cwd) {
+  const refused = require('./autodev.cjs').standinMissing('gh');
+  if (refused) return () => ({ status: null, error: new Error(refused), stdout: '', stderr: refused });
+  return (args) => spawnSync('gh', args, { cwd, encoding: 'utf8', shell: process.platform === 'win32', timeout: 120000 });
+}
+
+function parseJson(r) {
+  if (!r || r.error || r.status !== 0) return null;
+  try { return JSON.parse(r.stdout); } catch { return null; }
+}
+
+const BUCKET = { pass: 'pass', fail: 'fail', pending: 'pending', skipping: 'skip', cancel: 'fail' };
+function bucketOf(c) {
+  if (c.bucket && BUCKET[c.bucket]) return BUCKET[c.bucket];
+  const s = String(c.state || c.conclusion || '').toUpperCase();
+  if (['SUCCESS', 'NEUTRAL'].includes(s)) return 'pass';
+  if (['SKIPPED'].includes(s)) return 'skip';
+  if (['FAILURE', 'ERROR', 'CANCELLED', 'TIMED_OUT', 'ACTION_REQUIRED', 'STARTUP_FAILURE'].includes(s)) return 'fail';
+  return 'pending';
+}
+
+/** Names (check and workflow) whose latest run on the base branch failed. */
+function baseFailing(exec, base) {
+  if (!base) return new Set();
+  const runs = parseJson(exec(['run', 'list', '--branch', base, '--limit', '30', '--json', 'name,workflowName,conclusion']));
+  const latest = new Map();
+  for (const r of Array.isArray(runs) ? runs : []) {
+    const key = r.workflowName || r.name;
+    if (!latest.has(key)) latest.set(key, r);
+  }
+  const out = new Set();
+  for (const [key, r] of latest) if (String(r.conclusion).toLowerCase() === 'failure') { out.add(key); if (r.name) out.add(r.name); }
+  return out;
+}
+
+function logTail(exec, checks) {
+  for (const c of checks) {
+    const m = String(c.link || '').match(/\/actions\/runs\/(\d+)/);
+    if (!m) continue;
+    const r = exec(['run', 'view', m[1], '--log-failed']);
+    if (r && r.status === 0 && r.stdout) return r.stdout.trim().split(/\r?\n/).slice(-40).join('\n');
+  }
+  return '';
+}
+
+/**
+ * The CI oracle for the current branch's pull request.
+ * @param {string} cwd
+ * @param {{exec?: Function, ref?: string, base?: string, head?: string}} opts
+ * @returns {{status: 'passed'|'failed'|'pending'|'unavailable'|'stale', failed: string[], ignored: string[], tail: string, reason?: string}}
+ */
+function ciOracle(cwd, opts = {}) {
+  const exec = opts.exec || defaultExec(cwd);
+  const res = { status: 'unavailable', failed: [], ignored: [], tail: '' };
+  const checksRaw = exec(['pr', 'checks', ...(opts.ref ? [opts.ref] : []), '--json', 'name,state,bucket,link,workflow']);
+  if (!checksRaw || checksRaw.error || checksRaw.status == null) return { ...res, reason: 'gh is not available' };
+  const checks = parseJson(checksRaw);
+  if (!Array.isArray(checks)) return { ...res, reason: (checksRaw.stderr || 'no pull request checks').trim().slice(0, 200) };
+  if (opts.head) {
+    const pr = parseJson(exec(['pr', 'view', ...(opts.ref ? [opts.ref] : []), '--json', 'headRefOid']));
+    if (pr && pr.headRefOid && pr.headRefOid !== opts.head) return { ...res, status: 'stale', reason: `the checks are for ${pr.headRefOid.slice(0, 9)}, HEAD is ${opts.head.slice(0, 9)}: push the branch` };
+  }
+  const onBase = baseFailing(exec, opts.base);
+  const failing = checks.filter((c) => bucketOf(c) === 'fail');
+  const ignored = failing.filter((c) => onBase.has(c.name) || onBase.has(c.workflow));
+  const counted = failing.filter((c) => !ignored.includes(c));
+  res.ignored = ignored.map((c) => c.name);
+  res.failed = counted.map((c) => c.name);
+  if (counted.length) return { ...res, status: 'failed', tail: logTail(exec, counted) };
+  if (checks.some((c) => bucketOf(c) === 'pending')) return { ...res, status: 'pending' };
+  return { ...res, status: 'passed' };
+}
+
+/** Wait for pending checks, up to `timeoutMs`. */
+function waitForCi(cwd, opts = {}) {
+  const deadline = Date.now() + (opts.timeoutMs || 30 * 60 * 1000);
+  for (;;) {
+    const r = ciOracle(cwd, opts);
+    if (r.status !== 'pending' || Date.now() >= deadline) return r;
+    spawnSync(process.execPath, ['-e', `setTimeout(() => {}, ${Math.min(opts.pollMs || 30000, Math.max(0, deadline - Date.now()))})`]);
+  }
+}
+
+/** The project's own gate: its `ci:local` script, else its `test` script, else none. */
+function localGate(cwd) {
+  let scripts = {};
+  try { scripts = JSON.parse(require('fs').readFileSync(require('path').join(cwd, 'package.json'), 'utf8')).scripts || {}; } catch { /* no package.json */ }
+  if (scripts['ci:local']) return { name: 'ci:local', args: ['run', 'ci:local'] };
+  if (scripts.test) return { name: 'test', args: ['test'] };
+  return null;
+}
+
+/**
+ * The local CI oracle: run the project's gate in `cwd` and judge it by its exit code.
+ * With ci:local, the failing gate ids come from .ci-local/report.json.
+ * @param {string} cwd
+ * @param {{exec?: Function, timeoutMs?: number}} opts
+ * @returns {{status: 'passed'|'failed'|'unavailable', failed: string[], ignored: string[], tail: string, reason?: string}}
+ */
+function localOracle(cwd, opts = {}) {
+  const res = { status: 'unavailable', failed: [], ignored: [], tail: '' };
+  const gate = localGate(cwd);
+  if (!gate) return { ...res, reason: 'package.json has neither a ci:local nor a test script' };
+  const exec = opts.exec || ((args) => spawnSync('npm', args, { cwd, encoding: 'utf8', shell: process.platform === 'win32', timeout: opts.timeoutMs || 60 * 60 * 1000, maxBuffer: 256 * 1024 * 1024 }));
+  const r = exec(gate.args);
+  if (!r || r.error || r.status == null) return { ...res, reason: `npm ${gate.args.join(' ')} did not run${r && r.error ? `: ${r.error.message}` : ''}` };
+  const tail = `${r.stdout || ''}${r.stderr || ''}`.trim().split(/\r?\n/).slice(-40).join('\n');
+  if (r.status === 0) return { ...res, status: 'passed', tail };
+  let failed = [gate.name];
+  if (gate.name === 'ci:local') {
+    try {
+      const report = JSON.parse(require('fs').readFileSync(require('path').join(cwd, '.ci-local', 'report.json'), 'utf8'));
+      const ids = (report.gates || []).filter((g) => g.status === 'fail').map((g) => g.id);
+      if (ids.length) failed = ids;
+    } catch { /* the exit code is the verdict; the gate names are a courtesy */ }
+  }
+  return { ...res, status: 'failed', failed, tail };
+}
+
+function breakerTripped(rounds, max = DEFAULT_CI_ROUNDS) {
+  return rounds >= max;
+}
+
+module.exports = { ciOracle, waitForCi, localOracle, localGate, breakerTripped, baseFailing, bucketOf, DEFAULT_CI_ROUNDS };

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

@@ -941,7 +941,7 @@ function cmdScaffold(cwd, type, options, raw) {
     }
     case 'uat': {
       filePath = path.join(phaseDir, `${padded}${UAT_SUFFIX}`);
-      content = `---\nphase: "${padded}"\nname: "${name || phaseInfo?.phase_name || 'Unnamed'}"\ncreated: ${today}\nstatus: pending\n---\n\n# Phase ${phase}: ${name || phaseInfo?.phase_name || 'Unnamed'} -- User Acceptance Testing\n\n## Test Results\n\n| # | Test | Status | Notes |\n|---|------|--------|-------|\n\n## Summary\n\n_Pending UAT_\n`;
+      content = `---\nphase: "${padded}"\nname: "${name || phaseInfo?.phase_name || 'Unnamed'}"\ncreated: ${today}\nstatus: pending\n---\n\n# Phase ${phase}: ${name || phaseInfo?.phase_name || 'Unnamed'} -- User Acceptance Testing\n\n## Tests\n\n_One \`### N. <name>\` per user-observable truth, with \`expected:\` and \`result: [pending]\` (the walkthrough writes them; \`uat record\` fills the results)_\n\n## Gaps\n\n## Summary\n\n_Pending UAT_\n`;
       break;
     }
     case 'verification': {

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

@@ -48,13 +48,36 @@ function buildConfigDefaults(hasBraveSearch, userDefaults) {
     phase_branch_template: 'pan/phase-{phase}-{slug}',
     milestone_branch_template: 'pan/{milestone}-{slug}',
     workflow: {
-      research: true,
+      // Research is opt-in (2026-10-25): `--research` on new-project or plan-phase, or
+      // this key set true. A config that already says true keeps it.
+      research: false,
       plan_check: true,
       verifier: true,
       nyquist_validation: false,
       phase_record_compact: false,
-      // V1: the phase gate. `warn` reports refusals and completes; `enforce` refuses.
-      phase_gate: 'warn',
+      // 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',
+      // V5G: the score `gate` mode needs (killed / sampled, 0..1).
+      mutation_floor: 0.6,
+      // R2: `single` runs one reviewer pass; `lenses` runs one per lens (review-vote.cjs
+      // LENSES) and keeps only the findings a quorum of passes reported. Opt-in until
+      // its paired corpus run decides.
+      review_mode: 'single',
+      // R4: a second review on another host's CLI (another model family), read-only.
+      // `off`, or a host: claude | codex | copilot | gemini | opencode.
+      cross_family_review: 'off',
+      // A3: pan-exec-waves runs each executor in its own git worktree (Claude Code).
+      worktree_isolation: false,
+      // Right-sized ceremony (sizing.cjs): `auto` sizes each phase and quick task and gives a
+      // small, well-specified one the lean path; `full` always runs the whole ceremony. The
+      // `quality` profile also means full.
+      ceremony: 'auto',
+      // The most requirements a phase can map and still be sized lean.
+      lean_max_requirements: 5,
       // M2: opt-in per-phase HTML reports at the verify→complete gate.
       phase_reports: { enabled: false, open: false, theme: 'auto', index: true },
     },
@@ -62,6 +85,8 @@ function buildConfigDefaults(hasBraveSearch, userDefaults) {
     // 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,
@@ -74,6 +99,10 @@ function buildConfigDefaults(hasBraveSearch, userDefaults) {
       // Fraction of the spawn budget held back for re-verification (0..0.5).
       // Surfaced as an indicator always; a hard early stop only under enforce.
       verify_reserve: 0.15,
+      // A6: autodev's dollar caps, per run and per day (UTC), across every run's ledger.
+      // null: none set. An unattended run needs a run cap, here or as --max-usd.
+      max_usd_run: null,
+      max_usd_day: null,
     },
     commit: {
       safety_checks: true,
@@ -102,6 +131,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 || {}) },
@@ -119,7 +149,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']),
   }),
@@ -149,8 +179,13 @@ function knownConfigKeys() {
  * @param {string} keyPath
  * @returns {boolean}
  */
+// A lowercase `x-` key is the user's own metadata, never a typo (market-ideas M51,
+// after OpenSpec v1.14.2): PAN ignores it at the top level and inside a section.
+const USER_KEY = /^x-/;
+
 function isKnownConfigPath(keyPath) {
   const [head, sub] = String(keyPath).split('.');
+  if (USER_KEY.test(head) || (sub !== undefined && USER_KEY.test(sub))) return true;
   const { top, sections } = knownConfigKeys();
   if (!top.has(head)) return false;
   return sub === undefined || !sections.has(head) || sections.get(head).has(sub);
@@ -167,10 +202,11 @@ function unknownConfigKeys(config) {
   const { top, sections } = knownConfigKeys();
   const unknown = [];
   for (const [k, v] of Object.entries(config)) {
+    if (USER_KEY.test(k)) continue;
     if (!top.has(k)) { unknown.push(k); continue; }
     const known = sections.get(k);
     if (!known || !v || typeof v !== 'object' || Array.isArray(v)) continue;
-    for (const sub of Object.keys(v)) if (!known.has(sub)) unknown.push(`${k}.${sub}`);
+    for (const sub of Object.keys(v)) if (!known.has(sub) && !USER_KEY.test(sub)) unknown.push(`${k}.${sub}`);
   }
   return unknown;
 }

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

@@ -165,6 +165,29 @@ const CATEGORY_DEFAULTS = {
 /** Doc files to scan for staleness (focus sync) */
 const DOC_SYNC_FILES = ['README.md', 'docs/DEVELOPMENT.md', 'docs/CLI-REFERENCE.md', 'docs/USER-GUIDE.md', 'docs/ARCHITECTURE.md'];
 
+/**
+ * Commands folded into another (program L7). The installer writes an alias command for
+ * each old name on every runtime, so `/pan:<old>` keeps working: it runs `to` with
+ * `args` in front of whatever the user passed.
+ */
+const COMMAND_ALIASES = {
+  dashboard: { to: 'hud', args: '' },
+  'milestone-cleanup': { to: 'milestone-done', args: '--cleanup' },
+  'milestone-gaps': { to: 'milestone-audit', args: '--gaps' },
+  optimize: { to: 'learn', args: '--optimize' },
+  'research-phase': { to: 'plan-phase', args: '--research-only' },
+  profile: { to: 'settings', args: '--profile' },
+  'focus-doc-audit': { to: 'focus-docs', args: '' },
+  'focus-sync': { to: 'focus-docs', args: '--sync' },
+  'focus-scan': { to: 'focus-auto', args: '--step scan' },
+  'focus-plan': { to: 'focus-auto', args: '--step plan' },
+  'focus-exec': { to: 'focus-auto', args: '--step exec' },
+  'focus-drift-walking': { to: 'focus-auto', args: '--step drift' },
+};
+
+/** Commands removed with no replacement (program L7). */
+const RETIRED_COMMANDS = ['discord', 'mcp-bridge'];
+
 /** Old→new command name mapping for detecting stale docs */
 const COMMAND_RENAME_MAP = {
   'execute-phase': 'exec-phase',
@@ -178,7 +201,8 @@ const COMMAND_RENAME_MAP = {
   'new-milestone': 'milestone-new',
   'complete-milestone': 'milestone-done',
   'audit-milestone': 'milestone-audit',
-  'plan-milestone-gaps': 'milestone-gaps',
+  'plan-milestone-gaps': 'milestone-audit --gaps',
+  ...Object.fromEntries(Object.entries(COMMAND_ALIASES).map(([old, a]) => [old, a.args ? `${a.to} ${a.args}` : a.to])),
 };
 
 /** Default max cycles for auto-runner */
@@ -818,6 +842,8 @@ module.exports = {
   FOCUS_SOURCES,
   DOC_SYNC_FILES,
   COMMAND_RENAME_MAP,
+  COMMAND_ALIASES,
+  RETIRED_COMMANDS,
   CATEGORY_PRIORITY_RANGE,
   CATEGORY_DEFAULTS,
   DEFAULT_MAX_CYCLES,

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

@@ -132,13 +132,14 @@ const MODEL_PROFILES = {
   'pan-designer':             { quality: 'reasoning', balanced: 'reasoning', budget: 'mid' },
   'pan-roadmapper':           { quality: 'reasoning', balanced: 'reasoning', budget: 'mid' },
   'pan-executor':             { quality: 'reasoning', balanced: 'reasoning', budget: 'mid' },
-  'pan-phase-researcher':     { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
-  'pan-project-researcher':   { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
-  'pan-research-synthesizer': { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
+  // Right-sized ceremony (2026-10-24): balanced runs the researchers and the plan-checker
+  // on the mid tier, about half the launch model's price; quality keeps them on reasoning.
+  'pan-phase-researcher':     { quality: 'reasoning', balanced: 'mid', budget: 'fast' },
+  'pan-project-researcher':   { quality: 'reasoning', balanced: 'mid', budget: 'fast' },
   'pan-debugger':             { quality: 'reasoning', balanced: 'reasoning', budget: 'mid' },
   'pan-document_code':        { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
   'pan-verifier':             { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
-  'pan-plan-checker':         { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
+  'pan-plan-checker':         { quality: 'reasoning', balanced: 'mid', budget: 'fast' },
   'pan-design-checker':       { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
   'pan-integration-checker':  { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
   'pan-reviewer':             { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
@@ -193,7 +194,6 @@ const AGENT_BASE_EFFORT = {
   // Research/synthesis/review — moderate depth
   'pan-phase-researcher':     'medium',
   'pan-project-researcher':   'medium',
-  'pan-research-synthesizer': 'medium',
   'pan-knowledge':            'medium',
   'pan-distiller':            'medium',
   'pan-meta-reviewer':        'medium',
@@ -324,7 +324,7 @@ function reportsFailure(result) {
  */
 function output(result, raw, rawValue, exitCode) {
   if (raw && rawValue !== undefined) {
-    process.stdout.write(String(rawValue));
+    writeStdoutSync(String(rawValue));
   } else {
     const json = JSON.stringify(result, null, 2);
     // Large payloads exceed Claude Code's Bash tool buffer (~50KB).
@@ -337,19 +337,31 @@ function output(result, raw, rawValue, exitCode) {
         const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pan-'));
         const tmpPath = path.join(tmpDir, 'out.json');
         fs.writeFileSync(tmpPath, json, { encoding: 'utf-8', flag: 'wx' });
-        process.stdout.write('@file:' + tmpPath);
+        writeStdoutSync('@file:' + tmpPath);
       } catch {
         // Tmpfile write failed (disk full, permissions) — truncate and write to stdout
         const truncated = json.slice(0, MAX_JSON_SIZE);
-        process.stdout.write(truncated);
+        writeStdoutSync(truncated);
       }
     } else {
-      process.stdout.write(json);
+      writeStdoutSync(json);
     }
   }
   process.exit(exitCode === undefined ? (reportsFailure(result) ? 1 : 0) : exitCode);
 }
 
+/**
+ * Write all of `text` to stdout before returning. output() exits right after it writes,
+ * and on macOS (and Linux) stdout to a pipe is asynchronous: process.exit() dropped
+ * whatever had not drained past the pipe buffer, so a reader got JSON cut at about 8 KB.
+ * Making the stdout handle blocking first turns the write synchronous on a pipe too.
+ */
+function writeStdoutSync(text) {
+  const handle = process.stdout._handle;
+  if (handle && typeof handle.setBlocking === 'function') handle.setBlocking(true);
+  process.stdout.write(String(text));
+}
+
 /**
  * Write error message to stderr and exit with code 1.
  * @param {string} message - Error message
@@ -434,7 +446,7 @@ function loadConfig(cwd) {
     branching_strategy: 'none',
     phase_branch_template: 'pan/phase-{phase}-{slug}',
     milestone_branch_template: 'pan/{milestone}-{slug}',
-    research: true,
+    research: false, // opt-in: a config that says true keeps it
     plan_checker: true,
     verifier: true,
     nyquist_validation: false,
@@ -559,23 +571,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

@@ -149,7 +149,8 @@ const DEFAULT_RATES = {
 
   // Google Gemini — ai.google.dev/gemini-api/docs/pricing, paid tier, text input,
   // the ≤200K-token prompt tier where the page splits by length, read 2026-09-23.
-  // cache_read is the page's "context caching" price: 0.1× input on every row, not
+  // cache_read is the page's "context caching" price: 0.1× input on every row but
+  // Gemini 4 Argon (0.05×), not
   // the 0.25× this block carried until 2026-09-22 (cache reads 2.5× high, R26). The
   // tokens that CREATE a cache bill at the standard input price (Google Cloud's
   // context-cache overview; the Gemini API pages list only cached-token and storage
@@ -157,7 +158,12 @@ const DEFAULT_RATES = {
   // HOUR, which a per-token table cannot carry: PAN's Gemini totals exclude it.
   // The 3.6/3.7/3.8 Flash prices run "through December 31, 2026" and double from
   // January 1, 2027 (the page states both) — re-read them after that date.
-  'gemini-3.8-flash':       { input: 0.75, output: 3.75, cache_read: 0.075, cache_write: 0.75 },
+  // Gemini 4 Argon (paid tier only; one price at every prompt length; implicit caching
+  // only): these rates run "through November 30, 2026" and double from December 1,
+  // 2026 (input $4.00, output $20.00, caching $0.20; read 2026-10-19) — change the row
+  // on that date.
+  'gemini-4-argon':         { input: 2.00, output: 10.0, cache_read: 0.10,  cache_write: 2.00 },
+  'gemini-3.8-flash':      { input: 0.75, output: 3.75, cache_read: 0.075, cache_write: 0.75 },
   'gemini-3.7-flash':       { input: 0.75, output: 3.75, cache_read: 0.075, cache_write: 0.75 },
   'gemini-3.6-flash':       { input: 0.75, output: 3.75, cache_read: 0.075, cache_write: 0.75 },
   'gemini-3.5-flash':       { input: 1.50, output: 9.00, cache_read: 0.15,  cache_write: 1.50 },
@@ -664,6 +670,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()
@@ -759,8 +905,12 @@ function cmdCostAppend(cwd, rec, raw) {
 
 function cmdCostClear(cwd, raw) {
   try {
-    fs.unlinkSync(tokensFile(cwd));
-    output({ cleared: true, file: tokensFile(cwd) }, raw);
+    // L6a: the ledger is the only record of what was spent; keep a copy before deleting it.
+    const file = tokensFile(cwd);
+    const backup = `${file}.bak-${new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)}`;
+    fs.copyFileSync(file, backup);
+    fs.unlinkSync(file);
+    output({ cleared: true, file, backup }, raw);
   } catch (e) {
     output({ cleared: false, error: e.message || 'ledger_clear_failed' }, raw);
   }
@@ -900,6 +1050,12 @@ function cmdModelsCheck(raw) {
 
 module.exports = {
   computeCost,
+  phaseBudget,
+  cmdCostBudget,
+  DEFAULT_PHASE_BUDGET_USD,
+  costForecast,
+  quantiles,
+  FORECAST_MIN_SAMPLES,
   appendRecord,
   readRecords,
   aggregate,