pan-wizard 3.21.1 → 3.24.0

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

@@ -274,6 +274,17 @@ function cmdEstimateCost(cwd, raw) {
  * @param {boolean} [opts.force] - Skip deleted-file safety check
  * @returns {void}
  */
+/**
+ * List the paths currently in the index (staged), or [] if git says nothing.
+ * @param {string} cwd - Working directory
+ * @returns {string[]} Staged paths, as git reports them
+ */
+function stagedFiles(cwd) {
+  const r = execGit(cwd, ['diff', '--cached', '--name-only']);
+  if (r.exitCode !== 0 || !r.stdout) return [];
+  return r.stdout.split('\n').filter(Boolean);
+}
+
 /**
  * Run commit safety checks (deleted files, sensitive patterns).
  * @param {string} cwd - Working directory
@@ -315,7 +326,22 @@ function runCommitSafetyChecks(cwd, config, force) {
     }
   }
   if (safetyChecks.sensitive_files_blocked.length > 0) {
-    return { blocked: true, reason: 'sensitive_file_detected', safetyChecks, hint: 'Remove sensitive files from staging before committing' };
+    // The hint must not say "unstage them" — cmdCommit now unstages PAN's own
+    // additions before returning, so that advice would describe work already done.
+    // It matters that the user knows this can be a FALSE positive: the patterns
+    // match the PATH, never file content, and the bare words in
+    // DEFAULT_SENSITIVE_PATTERNS (credentials/secret/password/token) are unanchored,
+    // so an ordinary planning doc under a phase like `03-secrets-design/` trips it
+    // with no secret anywhere. Without that context the block reads as "PAN found a
+    // secret in your files", which is not what was checked.
+    return {
+      blocked: true,
+      reason: 'sensitive_file_detected',
+      safetyChecks,
+      hint: 'Matched on filename/path, not content — this can be a false positive. '
+        + 'If the file is safe, narrow commit.sensitive_patterns in .planning/config.json '
+        + 'or commit it yourself; if it is a real secret, gitignore it.',
+    };
   }
 
   return { blocked: false, safetyChecks };
@@ -331,6 +357,10 @@ function cmdCommit(cwd, message, files, raw, amend, opts) {
   const failOnError = opts && opts.failOnError;
 
   if (!isGitRepo(cwd)) {
+    // No error key, exit 0. Unlike `git commit` (an explicit git command, where a
+    // missing repo IS the failure), commit-docs is an auto-commit convenience and
+    // PAN fully supports non-git projects - the skip is the expected outcome of the
+    // environment the caller chose, not a malfunction.
     output({ committed: false, hash: null, reason: 'not_a_git_repo', hint: 'Run git init to initialize a repository' }, raw, 'not a git repo');
     return;
   }
@@ -345,14 +375,25 @@ function cmdCommit(cwd, message, files, raw, amend, opts) {
   const config = loadConfig(cwd);
 
   if (!config.commit_docs) {
+    // No error key, exit 0: the user set commit_docs=false. Honouring configuration
+    // is a success; exiting non-zero here would break every workflow of every user
+    // who opted out of doc commits.
     output({ committed: false, hash: null, reason: 'skipped_commit_docs_false' }, raw, 'skipped');
     return;
   }
   if (isGitIgnored(cwd, PLANNING_DIR)) {
+    // No error key, exit 0: .planning/ is gitignored - also the user's choice.
     output({ committed: false, hash: null, reason: 'skipped_gitignored' }, raw, 'skipped');
     return;
   }
 
+  // Snapshot the index BEFORE staging so a blocked commit can put it back exactly
+  // as the user left it. The safety check reads `git diff --cached`, so it can only
+  // see what staging produced — `--files .planning/` is a directory, and the file
+  // that trips the check is only discoverable after `git add`. So we stage, check,
+  // and undo on refusal, rather than trying to predict the expansion ourselves.
+  const preStaged = new Set(stagedFiles(cwd));
+
   // Stage files
   const filesToStage = files && files.length > 0 ? files : [PLANNING_DIR + '/'];
   for (const file of filesToStage) execGit(cwd, ['add', file]);
@@ -360,7 +401,22 @@ function cmdCommit(cwd, message, files, raw, amend, opts) {
   // Safety checks
   const safety = runCommitSafetyChecks(cwd, config, force);
   if (safety.blocked) {
-    output({ committed: false, hash: null, reason: safety.reason, safety_checks: safety.safetyChecks, hint: safety.hint }, raw, 'blocked');
+    // Unstage what WE just added. Leaving it staged was the whole harm: the check
+    // that exists to keep a secret out of git was what put it INTO the index, where
+    // the next `git commit` from any source — the user, an IDE, another tool — would
+    // have included it. It also wedged every later `pan-tools commit`, since the
+    // offending file stayed staged and kept tripping the same check, so an autonomous
+    // run silently stopped persisting its plans behind a message that reads like a
+    // safety success. Restore only OUR additions; anything the user had staged before
+    // this call is theirs and stays untouched.
+    const added = stagedFiles(cwd).filter(f => !preStaged.has(f));
+    for (const f of added) execGit(cwd, ['reset', '--quiet', '--', f]);
+    safety.safetyChecks.unstaged_by_pan = added;
+    // error key => exit 1. A blocked commit is a refusal that protected something
+    // (a staged deletion, a secret) - the docs did NOT land, which is the same harm
+    // as commit_failed for an autonomous loop. The JSON body still goes to stdout,
+    // so callers that parse `reason`/`safety_checks` are unaffected.
+    output({ committed: false, hash: null, reason: safety.reason, error: 'commit_blocked', safety_checks: safety.safetyChecks, hint: safety.hint }, raw, 'blocked');
     return;
   }
 
@@ -378,7 +434,12 @@ function cmdCommit(cwd, message, files, raw, amend, opts) {
     if (failOnError) {
       error('commit_failed: ' + (commitResult.stderr || 'unknown git error').trim());
     }
-    output({ committed: false, hash: null, reason: 'commit_failed', error: commitResult.stderr }, raw, 'failed');
+    // `|| 'unknown git error'`: the exit code is derived from a TRUTHY error key, and
+    // git does not always write to stderr — an empty string would launder this real
+    // failure back into exit 0. (experiment.cjs documents the harm: an autonomous run
+    // took `committed: false, reason: commit_failed` with exit 0 and kept going,
+    // leaving 24 minutes of work uncommitted.)
+    output({ committed: false, hash: null, reason: 'commit_failed', error: commitResult.stderr || 'unknown git error' }, raw, 'failed');
     return;
   }
 
@@ -471,6 +532,10 @@ async function cmdWebsearch(query, options, raw) {
 
   if (!apiKey) {
     // No key = silent skip, agent falls back to built-in WebSearch
+    // No error key, exit 0: an unconfigured capability is an ANSWER ("web search is
+    // unavailable") and callers degrade gracefully. Contrast the sites below - a
+    // configured search that then fails (bad query, API 5xx, network) IS a failure
+    // and carries `error`. Unconfigured vs broken is the distinction.
     output({ available: false, reason: 'BRAVE_API_KEY not set' }, raw, '');
     return;
   }
@@ -525,7 +590,7 @@ async function cmdWebsearch(query, options, raw) {
     }, raw, results.map(item => `${item.title}\n${item.url}\n${item.description}`).join('\n\n'));
   } catch (err) {
     // Network error, DNS failure, or JSON parse error from Brave API
-    output({ available: false, error: err.message }, raw, '');
+    output({ available: false, error: err.message || 'web_search_failed' }, raw, '');
   }
 }
 
@@ -641,7 +706,11 @@ function renderHealthReport(cwd, { phasesDir, phases, totalPlans, totalSummaries
   try { phaseDirEntries = fs.readdirSync(phasesDir); } catch { phaseDirEntries = []; }
 
   for (const phase of phases) {
-    const match = phaseDirEntries.find(d => d.startsWith(phase.number + '-') || d === phase.number);
+    // Normalize first — roadmap headings are unpadded ("Phase 1") while phase
+    // directories are zero-padded ("01-foundation"), so the raw number never
+    // matched. Same defect as focus.cjs collectWorkItems; see the note there.
+    const normalizedNum = normalizePhaseName(phase.number);
+    const match = phaseDirEntries.find(d => d.startsWith(normalizedNum + '-') || d === normalizedNum);
     if (!match) continue;
     const phaseDir = path.join(phasesDir, match);
     try {
@@ -769,6 +838,14 @@ function cmdScaffold(cwd, type, options, raw) {
     error(`Phase ${phase} directory not found`);
   }
 
+  // Every artifact type except phase-dir writes into a resolved phase directory.
+  // Without --phase there is no directory to write to, so guard before the
+  // switch — otherwise path.join(phaseDir, …) below crashes with a raw
+  // TypeError instead of a usage error.
+  if (!phaseDir && type !== 'phase-dir') {
+    error(`--phase required for ${type} scaffold`);
+  }
+
   let filePath, content;
 
   switch (type) {
@@ -812,6 +889,9 @@ function cmdScaffold(cwd, type, options, raw) {
     fs.writeFileSync(filePath, content, { encoding: 'utf-8', flag: 'wx' });
   } catch (e) {
     if (e.code === 'EEXIST') {
+      // No error key, exit 0: scaffolding is idempotent - the file the caller asked
+      // for exists, which is the state it wanted. `created:false` reports only that
+      // this call was not the one that made it.
       output({ created: false, reason: 'already_exists', path: relPath }, raw, 'exists');
       return;
     }
@@ -880,6 +960,7 @@ function cmdBatchCommit(cwd, items, raw) {
     return;
   }
   if (!Array.isArray(items) || items.length === 0) {
+    // No error key, exit 0: an empty batch is a legitimate no-op.
     output({ committed: false, reason: 'no_items' }, raw, 'no items');
     return;
   }
@@ -904,7 +985,8 @@ function cmdBatchCommit(cwd, items, raw) {
   const message = 'docs: focus-exec batch — ' + items.length + ' items completed\n\n' + titles;
   const commitResult = execGit(cwd, ['commit', '-m', message]);
   if (commitResult.exitCode !== 0) {
-    output({ committed: false, reason: 'commit_failed', error: commitResult.stderr }, raw, 'failed');
+    // See cmdCommitDocs above: a truthy error key is what makes this exit non-zero.
+    output({ committed: false, reason: 'commit_failed', error: commitResult.stderr || 'unknown git error' }, raw, 'failed');
     return;
   }
 

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

@@ -140,6 +140,12 @@ function cmdConfigSet(cwd, keyPath, value, raw) {
     error('Usage: config-set <key.path> <value>');
   }
 
+  // A missing value would be assigned as `undefined`, which JSON.stringify drops
+  // — so the command reported updated:true while writing nothing. Reject it.
+  if (value === undefined) {
+    error('Usage: config-set <key.path> <value>');
+  }
+
   // Parse value (handle booleans and numbers)
   let parsedValue = value;
   if (value === 'true') parsedValue = true;
@@ -157,6 +163,24 @@ function cmdConfigSet(cwd, keyPath, value, raw) {
     }
   }
 
+  // Valid JSON of the wrong SHAPE is still unusable, and used to fail two different
+  // silent ways. `null` crashed with a raw TypeError stack dump ("Cannot set
+  // properties of null") because the traversal assigned straight into it. An array,
+  // string or number took the assignment without complaint and then serialized
+  // without the key, so the command reported {"updated": true} at exit 0 while
+  // persisting nothing — the user is told their setting took effect and PAN keeps
+  // using the old one forever.
+  //
+  // Refuse rather than overwrite: a config.json that is not an object is the user's
+  // data in an unexpected state, and replacing it wholesale would be the
+  // settings.json data-loss bug in another file.
+  if (config === null || typeof config !== 'object' || Array.isArray(config)) {
+    error(
+      `config.json is not a JSON object (found ${config === null ? 'null' : Array.isArray(config) ? 'an array' : typeof config})`
+      + ` — refusing to overwrite it. Fix or remove ${configPath} and re-run.`
+    );
+  }
+
   // Traverse the dot-notation key path to build nested objects.
   // For a path like "workflow.research", this loop walks through each
   // segment except the last, creating intermediate objects as needed.
@@ -558,7 +582,7 @@ function cmdStandardsPhaseTrack(cwd, phaseNum, raw) {
   if (!combinedContent) {
     output({
       phase: phaseNum,
-      phase_name: phase.name,
+      phase_name: phase.phase_name,
       relevant_standards: [],
       compliance: [],
       message: 'No plan files found in phase',
@@ -578,7 +602,7 @@ function cmdStandardsPhaseTrack(cwd, phaseNum, raw) {
 
   output({
     phase: phaseNum,
-    phase_name: phase.name,
+    phase_name: phase.phase_name,
     relevant_standards: detectedIds,
     compliance,
   }, raw, compliance.map(c => `${c.standard_id}: ${c.selected ? c.coverage || 'N/A' : 'not selected'}`).join('\n'));
@@ -637,6 +661,7 @@ function cmdStandardsTools(cwd, standardId, raw) {
 }
 
 module.exports = {
+  buildConfigDefaults,
   cmdConfigEnsureSection,
   cmdConfigSet,
   cmdConfigGet,

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

@@ -653,6 +653,7 @@ const CACHEABLE_CONTEXT_FILES = [
 /** Default thinking budget (tokens) for verification-heavy agents */
 const THINKING_BUDGETS = {
   'pan-plan-checker': 8000,
+  'pan-design-checker': 8000,
   'pan-verifier': 6000,
   'pan-integration-checker': 6000,
   'pan-reviewer': 4000,

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

@@ -60,6 +60,7 @@ const COST_MULTIPLIERS = { reasoning: 15, mid: 3, fast: 1 };
 const MODEL_PROFILES = {
   // Original planning/execution agents (pre-v3.0)
   'pan-planner':              { quality: 'reasoning', balanced: 'reasoning', budget: 'mid' },
+  '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' },
@@ -69,6 +70,7 @@ const MODEL_PROFILES = {
   '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-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' },
   // Spec B v2 agents (v3.0–v3.4) — added v3.7.5 to close MODEL_PROFILES drift
@@ -103,9 +105,11 @@ const EFFORT_ORDER = ['low', 'medium', 'high', 'xhigh'];
 const AGENT_BASE_EFFORT = {
   // Heavy planning/orchestration/debugging — deepest reasoning
   'pan-planner':              'xhigh',
+  'pan-designer':             'xhigh',
   'pan-conductor':            'xhigh',
   'pan-debugger':             'xhigh',
   'pan-plan-checker':         'xhigh',
+  'pan-design-checker':       'xhigh',
   // Execution and verification — thorough but bounded
   'pan-executor':             'high',
   'pan-roadmapper':           'high',
@@ -154,14 +158,102 @@ function resolveEffortInternal(cwd, agentType) {
 
 // ─── Output helpers ───────────────────────────────────────────────────────────
 
+/**
+ * Explicit opt-in to exit 0 for a payload that carries an `error` key but is NOT
+ * a failure — a legitimate empty/negative answer the caller must not treat as one.
+ * Pass it as output()'s 4th argument so the intent is visible and greppable:
+ *   `grep -rn "EXIT_OK" pan-wizard-core/bin` enumerates every documented exception.
+ */
+const EXIT_OK = 0;
+
+/**
+ * Names of the ERROR FAMILY: `error` itself, and any key ending in `_error`
+ * (`worktree_error`, `drain_error`, `commit_error`). A renamed error key is still
+ * an error key — that rename is exactly how this class escaped the first fix,
+ * which matched the literal name `error` and therefore missed
+ * `whatif prepare`'s `worktree_error` sitting three lines below a guard that
+ * handled plain `ctx.error` correctly.
+ *
+ * Deliberately NOT in the family:
+ *  - plural collections — `errors`, `schema_errors`, `error_patterns`. Those are
+ *    the *detail* of a verdict payload (`{ passed, errors, warnings }`), and an
+ *    empty array is truthy in JS, so matching them would make every clean
+ *    `verify` run exit 1. Commands that gate on a verdict pass their code
+ *    explicitly (see `links validate`, `doc-lint`).
+ *  - counters — `error_count`, `total_errors_traced`.
+ */
+const ERROR_FAMILY_KEY = /(^|_)error$/;
+
+/**
+ * True when `result` reports a FAILURE: an object carrying a truthy own key in
+ * the error family. `error: null` / `''` / `false` are "no error", so a payload
+ * may carry the key unset without being reported as a failure.
+ *
+ * This is the ONLY shape that means "failure" to output(). See the exit-code
+ * contract below for why no other shape is inferred.
+ */
+function reportsFailure(result) {
+  if (!result || typeof result !== 'object' || Array.isArray(result)) return false;
+  // Object.keys → own enumerable keys only: an inherited `error` is not ours,
+  // and a nested `{ summary: { error } }` is data, not a top-level signal.
+  for (const key of Object.keys(result)) {
+    if (ERROR_FAMILY_KEY.test(key) && result[key]) return true;
+  }
+  return false;
+}
+
 /**
  * Write result to stdout and exit. JSON by default, or raw string if --raw flag is set.
  * Large JSON (>50KB) is written to a tmpfile with @file: prefix.
+ *
+ * ── EXIT-CODE CONTRACT (read before adding an output() call) ──
+ * A payload carrying a truthy ERROR-FAMILY key (`error` or `*_error`) exits **1**
+ * by default. That default is deliberate and must not be relaxed: PAN's own
+ * orchestrators, hooks, CI steps and autonomous loops gate on the exit code, and an
+ * error body delivered with exit 0 is a dead gate — invisible. (Historically every
+ * `output({ error: … })` site exited 0, so `pan-tools state json` in a project with
+ * no state.md printed `{"error":"state.md not found"}` and reported success. An
+ * over-eager exit code is loud and gets fixed; a missed failure is silent, so
+ * failure is the safe default.) The error body still goes to **stdout** — callers
+ * parse it as before; only the exit code changed. `error()` remains the
+ * stderr+exit-1 path for bare messages.
+ *
+ * Three ways to choose an exit code, in precedence order:
+ *  1. Pass `exitCode` explicitly — for gates and verdicts whose payload has no
+ *     error-family key (e.g. `campaign due` answering "not due",
+ *     `verify stubs --gate`, `links validate`, `doc-lint`).
+ *  2. Pass `EXIT_OK` — an error-keyed payload that is a legitimate empty/negative
+ *     RESULT, not a failure. Every such site must carry a comment saying why.
+ *  3. Pass nothing — derived: truthy error-family key ⇒ 1, otherwise 0.
+ *
+ * ── WHY THE DERIVATION STOPS AT THE ERROR FAMILY ──
+ * PAN's other failure shape is `<verb>: false` plus a `reason`/`detail`. That shape
+ * cannot be classified structurally, because the identical shape carries both
+ * meanings — sometimes inside one function:
+ *     { committed: false, reason: 'commit_failed' }            ← failure
+ *     { committed: false, reason: 'skipped_commit_docs_false' } ← the user's own config
+ *     { advanced: false, reason: 'last_plan' }                  ← normal end of phase
+ *     { updated: false, reason: 'No plans found' }              ← nothing to sync
+ *     { available: false, reason: 'BRAVE_API_KEY not set' }     ← capability absent
+ *     { found: false, phase_number: 12 }                        ← the answer is "no"
+ *     { clean: false, … } / { exists: false, … }                ← a state description
+ * A rule like "false flag + a reason ⇒ failure" would turn all but the first into
+ * failures, and a false failure is a NEW bug, as loud as the one it fixes. So the
+ * classification is made per site, by the author, and recorded in the payload: a
+ * site that reports a FAILURE gives its payload an error-family key, which routes
+ * it through this one derivation — including payloads built by pure functions in
+ * other modules and passed straight through by the dispatcher.
+ *
+ * Corollary for such sites: harden the value against emptiness
+ * (`error: r.stderr || 'unknown git error'`). A subprocess that fails silently
+ * yields `''`, and an empty string would launder the failure back into exit 0.
+ *
  * @param {Object} result - The result object to serialize as JSON
  * @param {boolean} [raw] - If true and rawValue is provided, output rawValue as plain string
  * @param {string} [rawValue] - Plain string to output when raw mode is active
+ * @param {number} [exitCode] - Explicit exit code; omit to derive it from the payload
  */
-function output(result, raw, rawValue) {
+function output(result, raw, rawValue, exitCode) {
   if (raw && rawValue !== undefined) {
     process.stdout.write(String(rawValue));
   } else {
@@ -186,7 +278,7 @@ function output(result, raw, rawValue) {
       process.stdout.write(json);
     }
   }
-  process.exit(0);
+  process.exit(exitCode === undefined ? (reportsFailure(result) ? 1 : 0) : exitCode);
 }
 
 /**
@@ -589,8 +681,13 @@ function getRoadmapPhaseInternal(cwd, phaseNum) {
 
   try {
     const content = fs.readFileSync(roadmapPath, 'utf-8');
-    const escapedPhase = escapeRegex(phaseNum.toString());
-    const phasePattern = new RegExp(`#{2,4}\\s*Phase\\s+${escapedPhase}:\\s*([^\\n]+)`, 'i');
+    // Normalize the phase number so a padded id ('01') still matches an
+    // unpadded 'Phase 1:' heading (and vice-versa) — matching findPhaseInternal,
+    // which accepts both forms. Strip leading zeros, then allow any zero-padding
+    // in the heading via the `0*` prefix.
+    const unpadded = phaseNum.toString().trim().replace(/^0+(?=\d)/, '');
+    const escapedPhase = escapeRegex(unpadded);
+    const phasePattern = new RegExp(`#{2,4}\\s*Phase\\s+0*${escapedPhase}:\\s*([^\\n]+)`, 'i');
     const headerMatch = content.match(phasePattern);
     if (!headerMatch) return null;
 
@@ -631,14 +728,20 @@ function getPhaseModelTier(cwd, phaseNum) {
 }
 
 /**
- * Adjust a resolved tier given Opus 4.7-era capability hints.
+ * Adjust a resolved tier given optional task capability hints.
  *
  * Rules, in priority order:
- *   1. context_estimate > LARGE_CONTEXT_TOKEN_THRESHOLD → force reasoning (only 1M-ctx tier).
+ *   1. context_estimate > LARGE_CONTEXT_TOKEN_THRESHOLD → force reasoning.
  *   2. needs_thinking → upgrade fast → mid; leave mid/reasoning alone.
  *   3. cache_warm + !needs_thinking + context_estimate < SMALL_CONTEXT_TOKEN_THRESHOLD →
  *      allow downgrade mid → fast (cheap, cached, simple tasks don't need mid).
  *
+ * These are TIER hints, not capability facts. `reasoning` resolves to `inherit`
+ * on Anthropic (see PROVIDER_MODELS above), so rule 1 asks the host runtime for
+ * its own top-tier model — it neither selects a large-context model nor checks
+ * that the session model has one. PAN never probes the running model's real
+ * context window or feature set; nothing here is a gate.
+ *
  * @param {string} tier - Baseline tier (reasoning|mid|fast)
  * @param {Object} [opts] - {context_estimate, needs_thinking, cache_warm}
  * @returns {string} Possibly-adjusted tier
@@ -672,7 +775,7 @@ function adjustTierForCapabilities(tier, opts) {
  * @param {string} cwd - Project root directory
  * @param {string} agentType - Agent name (e.g., "pan-planner", "pan-executor")
  * @param {Object} [taskMetadata] - Optional metadata. Supports complexity fields and
- *   Opus 4.7 capability hints: {context_estimate, needs_thinking, cache_warm}.
+ *   capability hints: {context_estimate, needs_thinking, cache_warm}.
  * @returns {string} Model identifier: "inherit", "sonnet", "haiku", "mid", "fast", etc.
  */
 function resolveModelInternal(cwd, agentType, taskMetadata) {
@@ -707,7 +810,7 @@ function resolveModelInternal(cwd, agentType, taskMetadata) {
     tier = resolveComplexityTier(tier, { ...taskMetadata, thresholds });
   }
 
-  // Opus 4.7 capability adjustment (only when hints are present)
+  // Capability-hint adjustment (only when hints are present)
   if (taskMetadata && (
     taskMetadata.context_estimate !== undefined ||
     taskMetadata.needs_thinking !== undefined ||
@@ -962,6 +1065,8 @@ module.exports = {
   LEGACY_ALIASES,
   COST_MULTIPLIERS,
   output,
+  EXIT_OK,
+  reportsFailure,
   error,
   verbose,
   safeReadFile,

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

@@ -30,7 +30,7 @@
  *   - hit rate: cache_read / (cache_read + input - cache_write) if any cache activity
  *
  * Rate table is approximate — real pricing comes from the provider's API.
- * Rates are US dollars per million tokens, indicative as of 2026-06. Users
+ * Rates are US dollars per million tokens, indicative as of 2026-08. Users
  * can override with `.planning/config.json` → `cost.rates`.
  */
 
@@ -48,19 +48,29 @@ const TOKENS_FILE = 'tokens.jsonl';
  * Override per-model in config.json → cost.rates.
  */
 const DEFAULT_RATES = {
-  // Anthropic — verified against platform pricing 2026-06. Opus 4.6+ is $5/$25
-  // (the old $15/$75 Opus pricing ended with the 4.5 generation). Cache rates
-  // follow Anthropic's convention: read ≈ 0.1× input, write ≈ 1.25× input.
+  // Anthropic — verified against platform pricing 2026-08. Opus 4.6+/Opus 5 are
+  // $5/$25 (the old $15/$75 Opus pricing ended with the 4.5 generation). Cache
+  // rates follow Anthropic's convention: read ≈ 0.1× input, write ≈ 1.25× input.
   'claude-fable-5':     { input: 10.0, output: 50.0, cache_read: 1.0,  cache_write: 12.5 },
+  'claude-opus-5':      { input: 5.0,  output: 25.0, cache_read: 0.5,  cache_write: 6.25 },
   'claude-opus-4-8':    { input: 5.0,  output: 25.0, cache_read: 0.5,  cache_write: 6.25 },
   'claude-opus-4-7':    { input: 5.0,  output: 25.0, cache_read: 0.5,  cache_write: 6.25 },
   'claude-opus-4-6':    { input: 5.0,  output: 25.0, cache_read: 0.5,  cache_write: 6.25 },
+  // Sonnet 5 standard is $3/$15; a launch promo runs $2/$10 through 2026-08-31.
+  // We track the stable post-promo rate (the table is indicative; the staleness
+  // checker flags it for re-verification).
+  'claude-sonnet-5':    { input: 3.0,  output: 15.0, cache_read: 0.3,  cache_write: 3.75 },
   'claude-sonnet-4-6':  { input: 3.0,  output: 15.0, cache_read: 0.3,  cache_write: 3.75 },
   'claude-haiku-4-5':   { input: 1.0,  output: 5.0,  cache_read: 0.1,  cache_write: 1.25 },
 
-  // OpenAI — verified against published pricing 2026-06 ($5/$30 standard tier).
-  // Prompt caching is a 90% input discount with no separate write charge, so
-  // cache_write bills at the plain input rate.
+  // OpenAI — verified against published pricing 2026-08. Prompt caching is a 90%
+  // input discount with no separate write charge, so cache_write bills at the
+  // plain input rate. GPT-5.6 ships in three tiers; the bare `gpt-5.6` id prices
+  // as the Sol flagship, with tier-specific keys for Terra/Luna (longest-prefix
+  // match wins in resolveRate). Luna reflects the 2026-07-30 price cut.
+  'gpt-5.6':            { input: 5.0,  output: 30.0, cache_read: 0.5,  cache_write: 5.0 },
+  'gpt-5.6-terra':      { input: 2.0,  output: 12.0, cache_read: 0.2,  cache_write: 2.0 },
+  'gpt-5.6-luna':       { input: 0.20, output: 1.20, cache_read: 0.02, cache_write: 0.20 },
   'gpt-5.5':            { input: 5.0,  output: 30.0, cache_read: 0.5,  cache_write: 5.0 },
 
   // Google Gemini — published rates (per million tokens, approximate; users can override via config.json → cost.rates).
@@ -86,20 +96,35 @@ function tokensFile(cwd) {
   return path.join(metricsDir(cwd), TOKENS_FILE);
 }
 
+// Longest-prefix family match against a rates table. Transcript/hook-captured
+// ids are versioned ("claude-opus-4-8-20260301", "claude-fable-5[1m]") while
+// rate tables use family keys — match the longest key the model starts with so
+// the most specific family wins.
+function familyPrefixRate(rates, model) {
+  const families = Object.keys(rates)
+    .filter(k => model.startsWith(k))
+    .sort((a, b) => b.length - a.length);
+  return families.length > 0 ? rates[families[0]] : null;
+}
+
 function resolveRate(model, tier, configRates) {
+  // Config overrides win over the built-in table — including for versioned ids.
+  // Without the family-prefix pass here, a cost.rates override keyed on a family
+  // ("claude-opus-5") was silently ignored for the versioned id the hooks
+  // actually record ("claude-opus-5-20260101"), which fell through to
+  // DEFAULT_RATES instead.
   if (configRates) {
     if (model && configRates[model]) return configRates[model];
+    if (model) {
+      const fam = familyPrefixRate(configRates, model);
+      if (fam) return fam;
+    }
     if (tier && configRates[tier]) return configRates[tier];
   }
   if (model && DEFAULT_RATES[model]) return DEFAULT_RATES[model];
-  // Transcript/hook-captured ids are versioned ("claude-opus-4-8-20260301",
-  // "claude-fable-5[1m]") while the table uses family keys — prefix-match,
-  // longest key first so the most specific family wins.
   if (model) {
-    const families = Object.keys(DEFAULT_RATES)
-      .filter(k => model.startsWith(k))
-      .sort((a, b) => b.length - a.length);
-    if (families.length > 0) return DEFAULT_RATES[families[0]];
+    const fam = familyPrefixRate(DEFAULT_RATES, model);
+    if (fam) return fam;
   }
   if (tier && DEFAULT_RATES[tier]) return DEFAULT_RATES[tier];
   return null;
@@ -119,10 +144,19 @@ function computeCost(rec, configRates) {
   const output = rec.output_tokens || 0;
   const cacheRead = rec.cache_read_tokens || 0;
   const cacheWrite = rec.cache_write_tokens || 0;
-  // Non-cache-hit input tokens = input - cache_read (cache_read already in input on some providers,
-  // separate on others; we treat cache_read as a reduction of effective new input).
-  const newInput = Math.max(0, input - cacheRead);
-  const usd = (newInput * rate.input + output * rate.output
+  // The three input axes are DISJOINT as PAN records them. hooks/pan-cost-logger.js
+  // copies Anthropic's `input_tokens`, `cache_read_input_tokens` and
+  // `cache_creation_input_tokens` into separate fields, and Anthropic's
+  // `input_tokens` already EXCLUDES both cache axes — so each token is counted once
+  // and billed at its own rate.
+  //
+  // This previously subtracted cache_read from input, hedging that "cache_read is
+  // already in input on some providers". That double-discounted: with a warm cache,
+  // cache_read is far larger than input, so Math.max(0, …) zeroed the billed input
+  // outright. On a realistic row (30k input / 5k output / 200k cache read / 12k
+  // cache write on Opus-5 rates) it reported $0.30 against a true $0.45 — a 33%
+  // understatement, always in the direction of looking cheaper.
+  const usd = (input * rate.input + output * rate.output
     + cacheRead * rate.cache_read + cacheWrite * rate.cache_write) / 1_000_000;
   return Math.round(usd * 10000) / 10000;
 }
@@ -161,7 +195,7 @@ function appendRecord(cwd, rec) {
     fs.appendFileSync(tokensFile(cwd), JSON.stringify(normalized) + '\n', 'utf-8');
     return { appended: true, file: tokensFile(cwd) };
   } catch (e) {
-    return { appended: false, error: e.message };
+    return { appended: false, error: e.message || 'ledger_append_failed' };
   }
 }
 
@@ -284,9 +318,12 @@ function aggregate(cwd, opts) {
 
   totals.cost_usd = Math.round(totals.cost_usd * 10000) / 10000;
 
-  // Cache hit rate: cache_read / (cache_read + new input tokens billed at full rate)
-  const billedInput = Math.max(0, totals.input_tokens - totals.cache_read_tokens);
-  const hitDenom = totals.cache_read_tokens + billedInput;
+  // Cache hit rate: cached input / all input read. Same disjoint-axes fact as
+  // computeCost — input_tokens excludes the cache axes, so the denominator is simply
+  // their sum. Subtracting cache_read from input here made the denominator collapse
+  // to cache_read whenever the cache was warm (the normal case), pinning the metric
+  // at exactly 100% and making it carry no information at all.
+  const hitDenom = totals.cache_read_tokens + totals.input_tokens;
   const cacheHitRatePct = hitDenom > 0
     ? Math.round((totals.cache_read_tokens / hitDenom) * 1000) / 10
     : null;
@@ -396,7 +433,7 @@ function cmdCostClear(cwd, raw) {
     fs.unlinkSync(tokensFile(cwd));
     output({ cleared: true, file: tokensFile(cwd) }, raw);
   } catch (e) {
-    output({ cleared: false, error: e.message }, raw);
+    output({ cleared: false, error: e.message || 'ledger_clear_failed' }, raw);
   }
 }
 
@@ -406,7 +443,7 @@ function cmdCostClear(cwd, raw) {
 // Bump this whenever the table is re-verified; `models check` flags the table
 // once it is older than RATES_STALE_AFTER_DAYS (provider prices move faster
 // than PAN releases do).
-const RATES_VERIFIED_AT = '2026-06-10';
+const RATES_VERIFIED_AT = '2026-08-03';
 const RATES_STALE_AFTER_DAYS = 180;
 const RATE_TIERS = ['reasoning', 'mid', 'fast'];