pan-wizard 3.28.0 → 3.29.0

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

@@ -5,7 +5,9 @@
  * campaigns run: runtime installs fall behind the latest version, legacy
  * uppercase planning filenames linger from pre-v2.2 layouts, atomic-write
  * .tmp orphans survive crashes, per-agent memory logs grow past the cap,
- * cost ledgers written by pre-v3.12.4 hooks are 100% poisoned, telemetry
+ * cost ledgers carry oversum rows (a session's cumulative usage booked to one
+ * subagent — pre-v3.12.4 hooks wrote nothing else, and the parent-transcript
+ * slice path kept producing them up to v3.28), telemetry
  * trace sessions pile up unboundedly, and stray fragment `.planning/`
  * directories appear where a mapping step once ran.
  *
@@ -39,7 +41,7 @@ const {
   CHARS_PER_TOKEN,
   STATE_FILE,
 } = require('./constants.cjs');
-const { planningPath, planningRel } = require('./utils.cjs');
+const { planningPath, planningRel, detectPlanningModel } = require('./utils.cjs');
 const { detectForeignPlanningTree } = require('./foreign-planning.cjs');
 const { listMemoryAgents, readMemory, compactMemory } = require('./memory.cjs');
 const { readRecords, isSuspectRecord, METRICS_DIR, TOKENS_FILE } = require('./cost.cjs');
@@ -253,7 +255,8 @@ function recordMass(r) {
 }
 
 /**
- * H-5: cost ledger dominated by physically implausible (pre-v3.12.4) records.
+ * H-5: cost ledger dominated by physically implausible records — the oversum
+ * signature, a session's cumulative usage booked to one subagent row.
  *
  * Gated on token MASS as well as record count. A count-only gate passes a ledger
  * whose few bad rows carry most of the tokens — field case: 24% of rows suspect
@@ -286,7 +289,7 @@ function checkCostLedger(cwd) {
       : 'token mass';
   findings.push(mkFinding('poisoned-ledger', 'critical',
     planningRel(METRICS_DIR, TOKENS_FILE),
-    `${suspect}/${records.length} records suspect (${Math.round(ratio * 100)}% of rows, ${Math.round(massRatio * 100)}% of token mass) — pre-v3.12.4 oversum signature, tripped on ${basis}; aggregates quarantine them but the file is dead weight`,
+    `${suspect}/${records.length} records suspect (${Math.round(ratio * 100)}% of rows, ${Math.round(massRatio * 100)}% of token mass) — oversum signature (a session's cumulative usage booked to one subagent row), tripped on ${basis}; aggregates quarantine them but the file is dead weight. Run \`cost rebuild\` first while the session transcripts still exist — quarantining moves the whole ledger aside, and a rebuild afterwards has no rows left to keep`,
     { action: 'quarantine-ledger' }));
   return { findings };
 }
@@ -466,7 +469,7 @@ function checkCachedContext(cwd) {
   try {
     const ttl = assessCacheTtl(readRecords(cwd).filter(r => !isSuspectRecord(r)));
     if (ttl.recommend) {
-      findings.push(mkFinding('cache-context', 'info', planningRel(path.join(METRICS_DIR, TOKENS_FILE)), ttl.advice, null));
+      findings.push(mkFinding('cache-context', ttl.severity, planningRel(path.join(METRICS_DIR, TOKENS_FILE)), ttl.advice, null));
     }
   } catch { /* no ledger, or unreadable — nothing to say */ }
   return { findings };
@@ -494,15 +497,11 @@ function checkPlanningFragment(cwd) {
   const dir = planningPath(cwd);
   let entries = [];
   try { entries = fs.readdirSync(dir); } catch { return { findings, planning_exists: false }; }
-  const lower = entries.map(e => e.toLowerCase());
-  // Spine = anything that marks a deliberate PAN workflow: the phase model
-  // (project/state/phases/roadmap/requirements/milestones) OR the focus model
-  // (focus/quick) OR an orchestration campaign. A dir holding only generated
-  // artifacts (codebase maps, metrics, traces) is a stray fragment.
-  const SPINE = ['project.md', 'state.md', 'phases', 'roadmap.md', 'requirements.md',
-    'milestones', 'focus', 'quick', 'orchestration'];
-  const hasSpine = SPINE.some(s => lower.includes(s));
-  if (!hasSpine && entries.length > 0) {
+  // A spine is whatever marks a deliberate PAN workflow — the phase model, the focus
+  // model, or an orchestration campaign (PLANNING_MODEL_MARKERS, shared with
+  // `validate health` so the two verbs cannot disagree about a tree). A dir holding
+  // only generated artifacts (codebase maps, metrics, traces) is a stray fragment.
+  if (detectPlanningModel(dir).model === 'fragment') {
     findings.push(mkFinding('planning-fragment', 'info', planningRootRel(),
       `.planning exists with ${entries.length} entr${entries.length === 1 ? 'y' : 'ies'} (${entries.slice(0, 5).join(', ')}) but no workflow spine (project/state/phases/focus/…) — likely a stray partial run; review and delete manually`,
       null));
@@ -661,16 +660,14 @@ function applyFix(cwd, finding) {
         const dest = `${abs}.quarantined-${stamp}`;
         fs.renameSync(abs, dest);
 
-        // The cursor is a per-transcript high-water mark INTO the ledger we just
-        // moved aside. Left behind it points at rows that are no longer there,
-        // so the fresh ledger starts mid-stream and the next slice is undercounted.
-        // A "fresh ledger" that inherits the old ledger's read position is not fresh.
-        let cursorNote = '';
-        try {
-          const cursor = path.join(path.dirname(abs), COST_CURSOR_FILE);
-          fs.unlinkSync(cursor);
-          cursorNote = ', cursor reset';
-        } catch { /* no cursor to reset */ }
+        // The cost cursor (COST_CURSOR_FILE) STAYS. It is a per-TRANSCRIPT
+        // high-water mark — how many records of each session transcript the
+        // hooks have already attributed — not a position in the ledger, so it
+        // has nothing to do with the file being moved aside. This step used to
+        // delete it as "a fresh ledger must not inherit the old read position",
+        // and the next SubagentStop then re-summed every session transcript from
+        // line 0: a fresh oversum row the day after each quarantine (field,
+        // 2026-08-25 → 08-26). Quarantine and poison had become a loop.
 
         // Quarantine leaves a dated copy behind, and nothing else ever removes
         // one. Run hygiene a few times over a year and the metrics dir fills
@@ -680,7 +677,7 @@ function applyFix(cwd, finding) {
 
         return {
           applied: true,
-          detail: `renamed to ${path.basename(dest)}${cursorNote}${prunedNote} — fresh ledger starts clean`,
+          detail: `renamed to ${path.basename(dest)}${prunedNote} — fresh ledger starts clean; transcript cursor kept`,
         };
       }
       default:

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

@@ -301,11 +301,17 @@ function selectMemory(cwd, agent, opts = {}) {
 /**
  * Memory-load telemetry gate (ADR-0036 acceptance signal). Estimates the tokens
  * of memory that would be injected whole (every agent log) and compares to the
- * median per-agent input from the trustworthy cost ledger (suspect records
+ * median per-agent PROMPT from the trustworthy cost ledger (suspect records
  * quarantined). Read-only, non-blocking; degrades to an absolute-token check
  * when the ledger is thin.
  *
- * @returns {{memory_tokens, agents, median_input_tokens, fraction, status, advisory}}
+ * The prompt is `input + cache_read + cache_write`, not `input` alone: under prompt
+ * caching the uncached remainder is tens of tokens, so dividing by it reported 1.8k
+ * of memory as 8,940% of a "median agent input" and called it critical (field sweep
+ * 2026-09-17). Memory is injected into the whole prompt, so the whole prompt is what
+ * it must be measured against.
+ *
+ * @returns {{memory_tokens, agents, median_prompt_tokens, fraction, status, advisory}}
  */
 function memoryLoadBudget(cwd, opts = {}) {
   const { agents } = listMemoryAgents(cwd);
@@ -317,12 +323,12 @@ function memoryLoadBudget(cwd, opts = {}) {
   let median = null;
   try {
     const cost = require('./cost.cjs');
-    const inputs = (cost.readRecords(cwd) || [])
-      .filter(r => !cost.isSuspectRecord(r))
-      .map(r => Number(r.input_tokens) || 0)
+    const prompts = (cost.readRecords(cwd) || [])
+      .filter(r => !cost.isSuspectRecord(r) && !cost.isEmptyRecord(r))
+      .map(r => (Number(r.input_tokens) || 0) + (Number(r.cache_read_tokens) || 0) + (Number(r.cache_write_tokens) || 0))
       .filter(n => n > 0)
       .sort((a, b) => a - b);
-    if (inputs.length) median = inputs[Math.floor(inputs.length / 2)];
+    if (prompts.length) median = prompts[Math.floor(prompts.length / 2)];
   } catch { /* thin/absent ledger — absolute-token check only */ }
 
   const fraction = median ? memoryTokens / median : null;
@@ -335,9 +341,9 @@ function memoryLoadBudget(cwd, opts = {}) {
   const advisory = status === 'ok'
     ? 'Memory-load within budget.'
     : `Memory injection is ~${memoryTokens} tokens across ${agents.length} agent log(s)` +
-      (fraction != null ? ` (~${Math.round(fraction * 100)}% of median agent input)` : '') +
+      (fraction != null ? ` (~${Math.round(fraction * 100)}% of a median agent prompt)` : '') +
       `. Bound it with cue-scoped 'memory select' or trim with 'memory compact <agent>'.`;
-  return { memory_tokens: memoryTokens, agents: agents.length, median_input_tokens: median, fraction, status, advisory };
+  return { memory_tokens: memoryTokens, agents: agents.length, median_prompt_tokens: median, fraction, status, advisory };
 }
 
 // ─── CLI command wrappers ────────────────────────────────────────────────────

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

@@ -134,9 +134,82 @@ function getCurrentSessionId(cwd) {
   }
 }
 
+/**
+ * Day-scoped auto-session id, the same shape the trace hook mints
+ * (`sess_auto_YYYYMMDD`) so a day's hook-written and agent-reported events share one
+ * session instead of splitting into two.
+ */
+function autoSessionId(now = new Date()) {
+  const p = (n) => String(n).padStart(2, '0');
+  return `sess_auto_${now.getFullYear()}${p(now.getMonth() + 1)}${p(now.getDate())}`;
+}
+
+/**
+ * How long a `current-session` pointer is evidence of a live session. An explicit
+ * (non-auto) session used to stay "current" indefinitely — a July session was still
+ * current in September in a field project, so `readActiveSessionMeta` in the cost hook
+ * backfilled two-month-old command/phase onto today's ledger rows, and agent-reported
+ * events would have landed in a long-dead session's directory (field sweep 2026-09-17).
+ */
+const SESSION_STALE_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Last time anything was written to a session: its event log if it has one, else the
+ * moment it started. Null when the session cannot be read at all.
+ */
+function sessionLastActivityMs(cwd, sid) {
+  const dir = path.join(getTracesDir(cwd), sid);
+  try {
+    return fs.statSync(path.join(dir, TRACE_EVENT_FILE)).mtimeMs;
+  } catch { /* no events yet */ }
+  try {
+    const meta = JSON.parse(fs.readFileSync(path.join(dir, OPT_SESSION_FILE), 'utf-8'));
+    const t = new Date(meta.started_at).getTime();
+    return Number.isFinite(t) ? t : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Is this session finished, or too old to still be the one running? Read-only —
+ * finalizing a stale session is the writing path's job (the trace hook's rollover).
+ */
+function isSessionStale(cwd, sid, now = Date.now()) {
+  const dir = path.join(getTracesDir(cwd), sid);
+  try {
+    const meta = JSON.parse(fs.readFileSync(path.join(dir, OPT_SESSION_FILE), 'utf-8'));
+    if (meta && meta.ended_at) return true;
+  } catch { /* unreadable meta — fall through to the age test */ }
+  const last = sessionLastActivityMs(cwd, sid);
+  if (last === null) return true;
+  return now - last > SESSION_STALE_MS;
+}
+
+/**
+ * Append one trace event.
+ *
+ * Creates the day's auto-session when none is active. It used to return false instead,
+ * and the 16 `optimize trace log` call sites in the workflows are fire-and-forget
+ * (`2>/dev/null || true`), so on the phase pipeline — which never starts a trace
+ * session — every agent-reported event was silently discarded. Across fourteen field
+ * projects the instrument held 3,737 events, 99.7% of them the completion rows the hook
+ * writes, and not one error, gap or correction in its whole history (sweep 2026-09-17).
+ * An explicit `--session` is still honoured verbatim.
+ */
 function logTraceEvent(cwd, event, sessionId) {
-  const sid = sessionId || getCurrentSessionId(cwd);
-  if (!sid) return false;
+  // An explicit id is honoured verbatim. A POINTER, by contrast, is only evidence while
+  // the session it names is alive; a dead one is no session at all.
+  let sid = sessionId || null;
+  if (!sid) {
+    const current = getCurrentSessionId(cwd);
+    if (current && !isSessionStale(cwd, current)) sid = current;
+  }
+  if (!sid) {
+    const created = initTraceSession(cwd, { sessionId: autoSessionId(), description: 'auto-session (day-scoped)' });
+    if (!created || created.error) return false;
+    sid = created.session_id;
+  }
 
   try {
     const sessionDir = path.join(getTracesDir(cwd), sid);
@@ -1290,6 +1363,9 @@ module.exports = {
   TRACE_EVENT_FILE,
   OPT_SESSION_FILE,
   CURRENT_SESSION_FILE,
+  autoSessionId,
+  isSessionStale,
+  SESSION_STALE_MS,
   EVENT_TYPES,
   IMPACT_LEVELS,
   VALID_SCOPES,

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

@@ -182,10 +182,32 @@ function hasBraveSearchKey() {
   return fileAccessible(path.join(os.homedir(), '.pan-wizard', 'brave_api_key'));
 }
 
+/**
+ * Which workflow model a planning tree runs (PLANNING_MODEL_MARKERS). The phase model
+ * wins when its markers are present, since a phase project may also hold focus
+ * artifacts; `fragment` means entries exist but none of them mark a deliberate
+ * workflow, and `absent` that the directory could not be read.
+ *
+ * @param {string} planningDir - absolute path to the tree (e.g. planningPath(cwd))
+ * @returns {{model: 'phase'|'focus'|'campaign'|'fragment'|'empty'|'absent', evidence: string[], entries: number}}
+ */
+function detectPlanningModel(planningDir) {
+  const { PLANNING_MODEL_MARKERS } = require('./constants.cjs');
+  let entries;
+  try { entries = fs.readdirSync(planningDir); } catch { return { model: 'absent', evidence: [], entries: 0 }; }
+  const lower = new Set(entries.map(e => String(e).toLowerCase()));
+  for (const model of ['phase', 'focus', 'campaign']) {
+    const evidence = PLANNING_MODEL_MARKERS[model].filter(m => lower.has(m));
+    if (evidence.length) return { model, evidence, entries: entries.length };
+  }
+  return { model: entries.length ? 'fragment' : 'empty', evidence: [], entries: entries.length };
+}
+
 module.exports = {
   readJsonFile,
   removeQuotes,
   planningPath,
+  detectPlanningModel,
   planningRel,
   phasesPath,
   milestonesPath,

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

@@ -14,7 +14,7 @@ const {
   PLAN_SUFFIX, SUMMARY_SUFFIX, STANDARDS_FILE, STANDARDS_CATALOG, HEALTH_STATUS,
   BUILTIN_DRIFT_RULES, DRIFT_VERDICTS, BINARY_EXTENSIONS, DRIFT_MAX_FILES, DRIFT_MAX_FILE_SIZE, DRIFT_SEVERITY_WEIGHTS,
 } = require('./constants.cjs');
-const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, fileAccessible } = require('./utils.cjs');
+const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, fileAccessible, detectPlanningModel } = require('./utils.cjs');
 const { detectForeignPlanningTree } = require('./foreign-planning.cjs');
 // Drift detection lives in verify-drift.cjs; re-exported below so consumers of
 // verify.cjs are unaffected by the decomposition.
@@ -1320,19 +1320,33 @@ function cmdValidateHealth(cwd, options, raw) {
     return;
   }
 
+  // Check 1c: which workflow model is this tree running? Checks 2-8b below are the
+  // PHASE model's — a focus-model project (`/pan:focus`, no project/roadmap/state by
+  // design) and an orchestration campaign would each fail all of them and be called
+  // broken, which is what eight of fourteen field projects hit (sweep 2026-09-17).
+  // config.json is the one check every model shares.
+  const shape = detectPlanningModel(planningPath(cwd));
+  const phaseModel = shape.model === 'phase' || shape.model === 'fragment' || shape.model === 'empty';
+
   // Checks 2-8: individual structure and consistency checks
-  checkProjectFile(cwd, addIssue);
-  checkRoadmapFile(cwd, addIssue);
-  checkStateFile(cwd, addIssue, repairs);
+  if (phaseModel) {
+    checkProjectFile(cwd, addIssue);
+    checkRoadmapFile(cwd, addIssue);
+    checkStateFile(cwd, addIssue, repairs);
+  } else {
+    addIssue('info', 'I003', `${shape.model}-model project (${shape.evidence.join(', ')}) — the phase-model checks (project.md, roadmap.md, state.md, phases/) do not apply`, null);
+  }
   checkConfigFile(cwd, addIssue, repairs);
-  checkPhaseDirectories(cwd, addIssue);
-  checkPhaseContents(cwd, addIssue);
+  if (phaseModel) {
+    checkPhaseDirectories(cwd, addIssue);
+    checkPhaseContents(cwd, addIssue);
 
-  // Check 8b: cross-document state consistency
-  checkStateConsistency(cwd, addIssue, repairs);
+    // Check 8b: cross-document state consistency
+    checkStateConsistency(cwd, addIssue, repairs);
 
-  // Check 8c: verification gate (phases with verifier enabled need verification.md)
-  checkVerificationGate(cwd, addIssue);
+    // Check 8c: verification gate (phases with verifier enabled need verification.md)
+    checkVerificationGate(cwd, addIssue);
+  }
 
   // Check 9 (optional): standards compliance
   if (options.standards) {

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

@@ -203,6 +203,7 @@ const codebase = require('./lib/codebase.cjs');
 const memory = require('./lib/memory.cjs');
 const bus = require('./lib/bus.cjs');
 const cost = require('./lib/cost.cjs');
+const costRebuild = require('./lib/cost-rebuild.cjs');
 const preview = require('./lib/preview.cjs');
 const reviewDeep = require('./lib/review-deep.cjs');
 const knowledge = require('./lib/knowledge.cjs');
@@ -1207,8 +1208,14 @@ async function main() {
         cost.cmdCostAppend(cwd, rec, raw);
       } else if (subcommand === 'clear') {
         cost.cmdCostClear(cwd, raw);
+      } else if (subcommand === 'rebuild') {
+        costRebuild.cmdCostRebuild(cwd, {
+          apply: args.includes('--apply'),
+          mainThread: !args.includes('--no-main-thread'),
+          claudeDir: getArgValue(args, '--claude-dir'),
+        }, raw);
       } else {
-        error('Unknown cost subcommand. Available: report, append, clear');
+        error('Unknown cost subcommand. Available: report, append, clear, rebuild');
       }
       break;
     }

package/pan-wizard-core/workflows/health.md

@@ -162,6 +162,7 @@ Report final status.
 | W007 | warning | Phase on disk but not in ROADMAP | No |
 | I001 | info | Plan without SUMMARY (may be in progress) | No |
 | I002 | info | Phase in ROADMAP ahead of current phase, not planned yet | No |
+| I003 | info | Focus-model or campaign tree — the phase-model checks do not apply | No |
 | STATE_REQ_DRIFT | warning | state.md complete but REQUIREMENTS.md has unchecked boxes | Yes |
 | STATE_ROADMAP_DRIFT | warning | state.md complete but roadmap.md has unchecked plan boxes | Yes |
 | VERIFICATION_GATE_MISSING | warning | Phase has completed plans but no verification record | No |

package/scripts/coverage-gate.cjs

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * coverage-gate.cjs — did the shipped code actually run under the tests?
+ *
+ * Runs the whole suite under Node's own coverage instrumentation (no dependency:
+ * `node --test --experimental-test-coverage`, lcov reporter; the child processes
+ * the tests spawn — pan-tools, the installer, the hooks — are captured through the
+ * inherited NODE_V8_COVERAGE), then enforces:
+ *   - line and function floors overall and per module group (tests/fixtures/
+ *     coverage-policy.json — a floor sits a point below the measured baseline, so
+ *     a real regression fails and normal churn does not);
+ *   - every dispatcher `case` arm executed at least once — the binary rule that
+ *     catches "a verb no test dispatches", which a percentage hides. An arm may be
+ *     allowlisted in the policy with a reason (interactive, network, a P2 item).
+ * The never-called functions are printed, ranked, so a gap has a name.
+ *
+ *   node scripts/coverage-gate.cjs             run the suite, evaluate, exit 1 on a violation
+ *   node scripts/coverage-gate.cjs --lcov f    evaluate an existing lcov file (no run)
+ *   node scripts/coverage-gate.cjs --json      machine-readable result
+ *
+ * Node < 22 lacks the coverage include/exclude flags: the gate reports "skipped"
+ * and exits 0 there, so the 18/20 CI jobs stay green and the 22 job carries it.
+ * Wired as release-check Gate 9 and as an advisory CI step on the Node 22 job.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { parseCaseArms } = require('./test-surface.cjs');
+
+const ROOT = path.resolve(__dirname, '..');
+const POLICY_REL = path.join('tests', 'fixtures', 'coverage-policy.json');
+const DISPATCHER_REL = 'pan-wizard-core/bin/pan-tools.cjs';
+const TEST_DIRS = ['tests', 'tests/scenarios'];
+const INCLUDE = ['pan-wizard-core/**/*.cjs', 'pan-wizard-core/**/*.js', 'bin/**', 'hooks/*.js', 'scripts/**'];
+const EXCLUDE = ['tests/**', '**/node_modules/**'];
+const MIN_NODE_MAJOR = 22;
+
+const DEFAULT_POLICY = Object.freeze({
+  floors: { overall_lines: 92, overall_functions: 93, groups: { lib: 92, installer: 90, hooks: 90, mcp: 95 } },
+  arms_allow: [],
+});
+
+// ─── lcov ───────────────────────────────────────────────────────────────────
+
+/** Parse lcov text into [{ path, lines: Map(line→hits), fn: Map(name→line), fnda: Map(name→hits), lf, lh, brf, brh }]. */
+function parseLcov(text) {
+  const files = [];
+  let cur = null;
+  for (const raw of String(text || '').split(/\r?\n/)) {
+    const ci = raw.indexOf(':');
+    const k = ci >= 0 ? raw.slice(0, ci) : raw;
+    const v = ci >= 0 ? raw.slice(ci + 1) : '';
+    if (k === 'SF') { cur = { path: v.split('\\').join('/'), lines: new Map(), fn: new Map(), fnda: new Map(), lf: 0, lh: 0, brf: 0, brh: 0 }; continue; }
+    if (!cur) continue;
+    if (k === 'DA') { const [ln, c] = v.split(',').map(Number); cur.lines.set(ln, c); }
+    else if (k === 'FN') { const i = v.indexOf(','); cur.fn.set(v.slice(i + 1), Number(v.slice(0, i))); }
+    else if (k === 'FNDA') { const i = v.indexOf(','); cur.fnda.set(v.slice(i + 1), Number(v.slice(0, i))); }
+    else if (k === 'LF') cur.lf = Number(v); else if (k === 'LH') cur.lh = Number(v);
+    else if (k === 'BRF') cur.brf = Number(v); else if (k === 'BRH') cur.brh = Number(v);
+    else if (raw === 'end_of_record') { files.push(cur); cur = null; }
+  }
+  return files;
+}
+
+function relPath(p, root = ROOT) {
+  const r = root.split('\\').join('/');
+  const i = p.indexOf(r);
+  return i >= 0 ? p.slice(i + r.length).replace(/^\//, '') : p;
+}
+
+function groupOf(rel) {
+  if (/^pan-wizard-core\/bin\/lib\//.test(rel)) return 'lib';
+  if (/^pan-wizard-core\/mcp\//.test(rel)) return 'mcp';
+  if (/^pan-wizard-core\/bin\//.test(rel)) return 'cli';
+  if (/^pan-wizard-core\/workflows\//.test(rel)) return 'native-workflows';
+  if (/^bin\//.test(rel)) return 'installer';
+  if (/^hooks\//.test(rel)) return 'hooks';
+  if (/^scripts\//.test(rel)) return 'scripts';
+  return 'other';
+}
+
+/**
+ * Which case arms executed. An arm is executed when the first instrumented line
+ * after its label (before the next arm at the same or a shallower indent) ran; a
+ * label immediately followed by another label shares that arm's body (fallthrough).
+ */
+function armCoverage(dispatcherSrc, dispatcherFile) {
+  const arms = parseCaseArms(dispatcherSrc);
+  const byLine = new Map(arms.map((a) => [a.line, a]));
+  const lines = dispatcherSrc.split(/\r?\n/);
+  const da = dispatcherFile ? dispatcherFile.lines : new Map();
+  const result = [];
+  for (const a of arms) {
+    let verdict = null;
+    for (let ln = a.line + 1; ln <= lines.length; ln++) {
+      const nxt = byLine.get(ln);
+      if (nxt && nxt.indent <= a.indent) {
+        if (nxt.indent === a.indent && /^\s*case\s+'/.test(lines[ln - 1])) verdict = 'fallthrough';
+        break;
+      }
+      if (da.has(ln)) { verdict = da.get(ln) > 0; break; }
+    }
+    result.push({ id: a.parent ? `${a.parent} > ${a.label}` : a.label, line: a.line, verdict });
+  }
+  // A fallthrough label takes the verdict of the arm it shares.
+  for (let i = 0; i < result.length; i++) {
+    if (result[i].verdict === 'fallthrough') {
+      let j = i + 1;
+      while (j < result.length && result[j].verdict === 'fallthrough') j++;
+      result[i].verdict = j < result.length ? result[j].verdict : null;
+    }
+  }
+  return result;
+}
+
+function validatePolicy(policy) {
+  const errors = [];
+  for (const a of policy.arms_allow || []) {
+    if (!a || typeof a.arm !== 'string') errors.push(`arms_allow entry without an arm: ${JSON.stringify(a)}`);
+    else if (!a.reason || !String(a.reason).trim()) errors.push(`arms_allow entry "${a.arm}" has no reason`);
+  }
+  return errors;
+}
+
+/**
+ * Evaluate parsed lcov against the policy and the dispatcher source.
+ * Pure. Returns { ok, violations[], groups, overall, arms, never_called, policy_errors }.
+ */
+function evaluateCoverage(lcovFiles, { dispatcherSrc, policy = DEFAULT_POLICY, root = ROOT } = {}) {
+  const violations = [];
+  const policyErrors = validatePolicy(policy);
+  violations.push(...policyErrors.map((e) => `policy: ${e}`));
+  if (!lcovFiles.length) violations.push('lcov parsed no files — malformed or empty coverage output (failing closed)');
+
+  const groups = {};
+  const overall = { lf: 0, lh: 0, ff: 0, fh: 0 };
+  const neverCalled = [];
+  let dispatcherFile = null;
+  for (const f of lcovFiles) {
+    const rel = relPath(f.path, root);
+    if (rel.endsWith(DISPATCHER_REL) || rel === DISPATCHER_REL) dispatcherFile = f;
+    const g = groupOf(rel);
+    const fns = [...f.fn.keys()];
+    const fh = fns.filter((n) => (f.fnda.get(n) || 0) > 0).length;
+    const acc = groups[g] = groups[g] || { files: 0, lf: 0, lh: 0, ff: 0, fh: 0 };
+    acc.files++; acc.lf += f.lf; acc.lh += f.lh; acc.ff += fns.length; acc.fh += fh;
+    overall.lf += f.lf; overall.lh += f.lh; overall.ff += fns.length; overall.fh += fh;
+    for (const n of fns) if (!((f.fnda.get(n) || 0) > 0)) neverCalled.push(`${rel}:${f.fn.get(n)} ${n || '(anonymous)'}`);
+  }
+  const pct = (h, t) => (t ? Math.round((h / t) * 1000) / 10 : 100);
+  const overallPct = { lines: pct(overall.lh, overall.lf), functions: pct(overall.fh, overall.ff) };
+  const floors = policy.floors || DEFAULT_POLICY.floors;
+  if (lcovFiles.length) {
+    if (overallPct.lines < floors.overall_lines) violations.push(`overall line coverage ${overallPct.lines}% is below the floor ${floors.overall_lines}%`);
+    if (overallPct.functions < floors.overall_functions) violations.push(`overall function coverage ${overallPct.functions}% is below the floor ${floors.overall_functions}%`);
+    for (const [g, floor] of Object.entries(floors.groups || {})) {
+      const acc = groups[g];
+      if (!acc) { violations.push(`group "${g}" has no files under coverage — include globs or layout changed`); continue; }
+      const p = pct(acc.lh, acc.lf);
+      if (p < floor) violations.push(`${g} line coverage ${p}% is below the floor ${floor}%`);
+    }
+  }
+
+  let arms = [];
+  if (dispatcherSrc) {
+    arms = armCoverage(dispatcherSrc, dispatcherFile);
+    const allow = new Map((policy.arms_allow || []).map((a) => [a.arm, a.reason]));
+    if (!dispatcherFile && lcovFiles.length) violations.push('the dispatcher was not in the coverage output — no test ran pan-tools.cjs?');
+    for (const a of arms) {
+      if (a.verdict === true) continue;
+      if (allow.has(a.id)) { a.allowlisted = allow.get(a.id); continue; }
+      violations.push(`dispatcher arm never executed: ${a.id} (line ${a.line}) — add a test that dispatches it, or allowlist it in ${POLICY_REL} with a reason`);
+    }
+    for (const [arm] of allow) if (!arms.some((a) => a.id === arm)) violations.push(`policy: arms_allow names an arm that no longer exists: ${arm}`);
+    for (const [arm, reason] of allow) { const a = arms.find((x) => x.id === arm); if (a && a.verdict === true) violations.push(`policy: arm "${arm}" is executed now — remove its allowlist entry (${reason})`); }
+  }
+
+  const groupTable = Object.fromEntries(Object.entries(groups).map(([g, a]) => [g, { files: a.files, lines: pct(a.lh, a.lf), functions: pct(a.fh, a.ff) }]));
+  return { ok: violations.length === 0, violations, overall: overallPct, groups: groupTable, arms, never_called: neverCalled.sort(), policy_errors: policyErrors };
+}
+
+// ─── Running the suite ──────────────────────────────────────────────────────
+
+function expandTestFiles(root = ROOT, dirs = TEST_DIRS) {
+  const files = [];
+  for (const dir of dirs) {
+    const abs = path.join(root, dir);
+    let entries = [];
+    try { entries = fs.readdirSync(abs); } catch { continue; }
+    for (const f of entries) if (f.endsWith('.test.cjs')) files.push(path.join(abs, f));
+  }
+  return files.sort();
+}
+
+function runSuiteWithCoverage(root = ROOT, lcovPath) {
+  const specLog = lcovPath + '.spec.log';
+  const args = ['--test', '--experimental-test-coverage'];
+  for (const g of INCLUDE) args.push(`--test-coverage-include=${g}`);
+  for (const g of EXCLUDE) args.push(`--test-coverage-exclude=${g}`);
+  args.push('--test-reporter=lcov', `--test-reporter-destination=${lcovPath}`, '--test-reporter=spec', `--test-reporter-destination=${specLog}`);
+  args.push(...expandTestFiles(root));
+  const r = spawnSync(process.execPath, args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 64 * 1024 * 1024 });
+  return { status: r.status, specLog, stderr: r.stderr || '' };
+}
+
+function loadPolicy(root = ROOT) {
+  try { return JSON.parse(fs.readFileSync(path.join(root, POLICY_REL), 'utf8')); } catch { return DEFAULT_POLICY; }
+}
+
+function render(result) {
+  const lines = [];
+  lines.push(`coverage gate — ${result.ok ? 'OK' : 'FAIL'}`);
+  lines.push(`  overall: lines ${result.overall.lines}% · functions ${result.overall.functions}%`);
+  for (const [g, a] of Object.entries(result.groups).sort()) lines.push(`  ${g.padEnd(18)} files ${String(a.files).padStart(3)}  lines ${String(a.lines).padStart(5)}%  functions ${String(a.functions).padStart(5)}%`);
+  const executed = result.arms.filter((a) => a.verdict === true).length;
+  const allowed = result.arms.filter((a) => a.allowlisted).length;
+  lines.push(`  dispatcher arms: ${executed}/${result.arms.length} executed${allowed ? `, ${allowed} allowlisted` : ''}`);
+  if (result.never_called.length) {
+    lines.push(`  never-called functions: ${result.never_called.length} (first 12)`);
+    for (const n of result.never_called.slice(0, 12)) lines.push(`    ${n}`);
+  }
+  for (const v of result.violations) lines.push(`  ✖ ${v}`);
+  return lines.join('\n');
+}
+
+function main(argv) {
+  const major = Number(process.versions.node.split('.')[0]);
+  const lcovArg = argv.includes('--lcov') ? argv[argv.indexOf('--lcov') + 1] : null;
+  if (!lcovArg && major < MIN_NODE_MAJOR) {
+    console.log(`coverage gate — skipped on Node ${process.versions.node} (needs ${MIN_NODE_MAJOR}+ for coverage include/exclude flags)`);
+    return 0;
+  }
+  let lcovPath = lcovArg;
+  let tmp = null;
+  if (!lcovPath) {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'pan-coverage-'));
+    lcovPath = path.join(tmp, 'coverage.lcov');
+    const r = runSuiteWithCoverage(ROOT, lcovPath);
+    if (r.status !== 0) {
+      console.error(`coverage gate — the suite itself failed (exit ${r.status}); see ${r.specLog}`);
+      return 1;
+    }
+  }
+  let text = '';
+  try { text = fs.readFileSync(lcovPath, 'utf8'); } catch (e) { console.error(`coverage gate — cannot read ${lcovPath}: ${e.message}`); return 1; }
+  const result = evaluateCoverage(parseLcov(text), { dispatcherSrc: fs.readFileSync(path.join(ROOT, DISPATCHER_REL), 'utf8'), policy: loadPolicy(ROOT), root: ROOT });
+  if (argv.includes('--json')) console.log(JSON.stringify(result, null, 2));
+  else console.log(render(result));
+  if (tmp && !argv.includes('--keep')) { try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* best-effort */ } }
+  return result.ok ? 0 : 1;
+}
+
+if (require.main === module) process.exit(main(process.argv.slice(2)));
+
+module.exports = { parseLcov, groupOf, armCoverage, evaluateCoverage, validatePolicy, expandTestFiles, render, DEFAULT_POLICY, POLICY_REL, INCLUDE, EXCLUDE, MIN_NODE_MAJOR };

package/scripts/install-git-hooks.js

@@ -52,6 +52,11 @@ try {
 
 // 3. Confirm the hook file is executable on Unix. On Windows the bit doesn't
 //    matter — Git Bash treats `.sh` and shebanged scripts as executable.
+//    The file is TRACKED as 100755, so this is a safety net rather than the source
+//    of truth: it used to be tracked 100644, and since npm ci runs this script
+//    through `prepare`, every Linux and macOS checkout was left with a one-bit dirty
+//    tree that nothing looked at until CI began asserting the tree is unchanged
+//    (2026-09-17).
 const hookFile = path.join(REPO_ROOT, HOOKS_DIR, 'pre-commit');
 if (process.platform !== 'win32') {
   try {