pan-wizard 3.32.0 → 3.33.0

package/commands/pan/focus-scan.md

@@ -73,10 +73,7 @@ Read these files to establish baseline:
 
 **Project Structure:**
 - All core modules in the project's source directories
-- All command definitions
-- All agent definitions
-- All workflow definitions
-- All hook source files
+- The project's own command, agent, workflow and hook definitions, if it has any (never PAN's, which the Project Scope Boundary excludes)
 
 **Planning State:**
 - `.planning/state.md` — Current state
@@ -95,9 +92,7 @@ In: source directories, hooks, tests
 Cross-reference found issues with documented items — flag any UNDOCUMENTED issues as new findings.
 
 ### 0.3 Check Test Results
-```bash
-npm test 2>&1
-```
+Run the project's test suite: the commands in `.planning/config.json → verification` when set, otherwise the test command discovered from `package.json` scripts, `Makefile`, or project docs.
 Record: total tests, passing, failing, suites.
 
 ### 0.4 Baseline Snapshot Table

package/commands/pan/map-codebase.md

@@ -17,7 +17,7 @@ Analyze existing codebase using parallel pan-document_code agents to produce str
 
 Each mapper agent explores a focus area and **writes documents directly** to `.planning/codebase/`. The orchestrator only receives confirmations, keeping context usage minimal.
 
-Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
+Output: .planning/codebase/ folder with structured documents about the codebase state.
 </objective>
 
 <execution_context>
@@ -61,7 +61,7 @@ The CLI returns `{mode, total_tokens, file_count, languages}`:
 
 Record the chosen mode + telemetry in the final `.planning/codebase/overview.md` so future runs can reason about drift.
 
-**The mode is decided by repo size alone** — `estimate-size` compares the token estimate to `--threshold` and applies no model check. So single-shot only pays off when the model you launched with actually has a 1M-context window (the default Opus and current Sonnet-class models do; legacy 200K-context models do not). On a 200K-context model, pass a threshold that matches your real window (e.g. `--threshold 150000`) so anything larger resolves to `sharded` instead of overflowing a single agent.
+**The mode is decided by repo size alone** — `estimate-size` compares the token estimate to `--threshold` and applies no model check. So single-shot only pays off when the model you launched with actually has a 1M-context window. On a model with a smaller window, pass a threshold that matches your real window (e.g. `--threshold 150000`) so anything larger resolves to `sharded` instead of overflowing a single agent.
 </stage_0_ingest_mode>
 
 <tool_priority>
@@ -99,14 +99,14 @@ The orchestrator loads context in layers — NOT everything upfront. Mapper agen
    - Agent 5: relationships focus → writes relationships.md
    - Agent 6: practices focus → writes best-practices.md
 4. Wait for agents to complete, collect confirmations (NOT document contents)
-5. Verify all 9 documents exist with line counts
+5. Verify all documents exist with line counts
 6. Commit codebase map
 7. Offer next steps (typically: /pan:new-project or /pan:plan-phase)
 </process>
 
 <success_criteria>
 - [ ] .planning/codebase/ directory created
-- [ ] All 7 codebase documents written by mapper agents
+- [ ] All codebase documents written by mapper agents
 - [ ] Documents follow template structure
 - [ ] Parallel agents completed without errors
 - [ ] User knows next steps

package/commands/pan/mcp-bridge.md

@@ -98,7 +98,7 @@ Normally the host runtime writes this file. The CLI path exists for test fixture
 
 <workflow>
 
-**New to a project with MCP tools?** Run `/pan:mcp-bridge list` to see what's available. If empty, check the host runtime's MCP config — each runtime keeps it somewhere different: Claude Code in `settings.json` under its config dir, OpenCode in `opencode.json`, Copilot in `.github/mcp.json`, Codex in its own config, Gemini in its settings file.
+**New to a project with MCP tools?** Run `/pan:mcp-bridge list` to see what's available. If empty, check the host runtime's MCP config — each runtime keeps it somewhere different: Claude Code in `.mcp.json` at the project root (project scope) or `~/.claude.json` (user and local scopes), OpenCode in `opencode.json`, Copilot in `.github/mcp.json`, Codex in its own config, Gemini in its settings file.
 
 **Planning a phase that might touch external systems?** Run `/pan:mcp-bridge recommend <phase>` to get a ranked shortlist. Copy relevant tool names into the phase plan's "External tools" section so the executor knows to invoke them.
 

package/commands/pan/milestone-done.md

@@ -34,7 +34,7 @@ The full milestone-done workflow is inlined in <process> below — there is no s
 
 **User input:**
 
-- Version: {{version}} (e.g., "1.0", "1.1", "2.0")
+- Version: $ARGUMENTS (e.g., "1.0", "1.1", "2.0"); `{{version}}` below stands for this value
   </context>
 
 <process>
@@ -137,7 +137,6 @@ The full milestone-done workflow is inlined in <process> below — there is no s
 
 <critical_rules>
 
-- **Load workflow first:** Read milestone-done.md before executing
 - **Verify completion:** All phases must have summary.md files
 - **User confirmation:** Wait for approval at verification gates
 - **Archive before deleting:** Always create archive files before updating/deleting originals

package/commands/pan/phase-tests.md

@@ -19,7 +19,7 @@ Generate unit and E2E tests for a completed phase, using its summary.md, context
 
 Analyzes implementation files, classifies them into TDD (unit), E2E (browser), or Skip categories, presents a test plan for user approval, then generates tests following RED-GREEN conventions.
 
-Output: Test files committed with message `test(phase-{N}): add unit and E2E tests from add-tests command`
+Output: Test files committed with message `test(phase-{N}): add unit and E2E tests from phase-tests command`
 </objective>
 
 <execution_context>
@@ -34,6 +34,6 @@ Phase: $ARGUMENTS
 </context>
 
 <process>
-Execute the add-tests workflow from @~/.claude/pan-wizard-core/workflows/phase-tests.md end-to-end.
+Execute the phase-tests workflow from @~/.claude/pan-wizard-core/workflows/phase-tests.md end-to-end.
 Preserve all workflow gates (classification approval, test plan approval, RED-GREEN verification, gap reporting).
 </process>

package/commands/pan/profile.md

@@ -12,7 +12,7 @@ allowed-tools:
 <objective>
 Switch the model profile used by PAN agents. Controls which Claude model each agent uses, balancing quality vs token spend.
 
-Routes to the set-profile workflow which handles:
+Routes to the profile workflow which handles:
 - Argument validation (quality/balanced/budget)
 - Downgrade confirmation (quality → balanced → budget requires 'yes')
 - Config file creation if missing
@@ -25,7 +25,7 @@ Routes to the set-profile workflow which handles:
 </execution_context>
 
 <process>
-**Follow the set-profile workflow** from `@~/.claude/pan-wizard-core/workflows/profile.md`.
+**Follow the profile workflow** from `@~/.claude/pan-wizard-core/workflows/profile.md`.
 
 The workflow handles all logic including:
 1. Profile argument validation

package/commands/pan/research-phase.md

@@ -55,11 +55,9 @@ PHASE_INFO=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase
 
 ## 2. Check Existing Research
 
-```bash
-ls .planning/phases/${PHASE}-*/research.md 2>/dev/null
-```
+Use `has_research` and `research_path` from INIT.
 
-**If exists:** Offer: 1) Update research, 2) View existing, 3) Skip. Wait for response.
+**If exists:** Offer: 1) Update research, 2) View existing (`research_path`), 3) Skip. Wait for response.
 
 **If doesn't exist:** Continue.
 

package/commands/pan/review-deep.md

@@ -111,18 +111,18 @@ Verdict is driven by the highest-severity finding across all three sources. Meta
 
 | Runtime | hardener | meta-reviewer | merge |
 |---------|----------|---------------|-------|
-| Claude Code | Full, thinking enabled (6000/4000 budget) | Full | Full |
+| Claude Code | Full; reasoning depth from the agent's `effort:` frontmatter | Full | Full |
 | OpenCode | Prose "think step-by-step" preamble substitutes for thinking | Same | Full (runtime-agnostic CLI) |
 | Gemini | Same | Same | Full |
 | Codex | Same | Same | Full |
 | Copilot | Same | Same | Full |
 
-The merger CLI (`pan-tools review-deep merge`) is pure Node.js and works identically across runtimes. Only the *quality* of the hardener and meta-reviewer outputs varies with model capability — an Opus-class model with extended thinking produces the richest findings.
+The merger CLI (`pan-tools review-deep merge`) is pure Node.js and works identically across runtimes. Only the *quality* of the hardener and meta-reviewer outputs varies with model capability.
 
 </runtime_compatibility>
 
 <calibration_note>
 
-Deep review is opt-in for a reason: it costs roughly 3× a normal review (hardener + meta + merge adds two agent spawns per phase). Use it for high-stakes phases, not every phase. `--deep-review` gating by phase tags is a v3.4 candidate enhancement.
+Deep review is opt-in for a reason: it costs roughly 3× a normal review (hardener + meta + merge adds two agent spawns per phase). Use it for high-stakes phases, not every phase.
 
 </calibration_note>

package/commands/pan/todo-add.md

@@ -13,7 +13,7 @@ allowed-tools:
 <objective>
 Capture an idea, task, or issue that surfaces during a PAN session as a structured todo for later work.
 
-Routes to the add-todo workflow which handles:
+Routes to the todo-add workflow which handles:
 - Directory structure creation
 - Content extraction from arguments or conversation
 - Area inference from file paths
@@ -34,7 +34,7 @@ State is resolved in-workflow via `init todos` and targeted reads.
 </context>
 
 <process>
-**Follow the add-todo workflow** from `@~/.claude/pan-wizard-core/workflows/todo-add.md`.
+**Follow the todo-add workflow** from `@~/.claude/pan-wizard-core/workflows/todo-add.md`.
 
 The workflow handles all logic including:
 1. Directory ensuring

package/commands/pan/todo-check.md

@@ -13,7 +13,7 @@ allowed-tools:
 <objective>
 List all pending todos, allow selection, load full context for the selected todo, and route to appropriate action.
 
-Routes to the check-todos workflow which handles:
+Routes to the todo-check workflow which handles:
 - Todo counting and listing with area filtering
 - Interactive selection with full context loading
 - Roadmap correlation checking
@@ -32,7 +32,7 @@ Todo state and roadmap correlation are loaded in-workflow using `init todos` and
 </context>
 
 <process>
-**Follow the check-todos workflow** from `@~/.claude/pan-wizard-core/workflows/todo-check.md`.
+**Follow the todo-check workflow** from `@~/.claude/pan-wizard-core/workflows/todo-check.md`.
 
 The workflow handles all logic including:
 1. Todo existence checking

package/hooks/dist/pan-state-reinject.js

@@ -18,11 +18,30 @@
 // `compact` matcher on both; the source is re-checked here so a registration
 // without the matcher stays inert on every other start.
 //
+// Gemini CLI and Copilot CLI (market-ideas M33) restart no session after a
+// compaction (Gemini's SessionStart sources: startup | resume | clear; Copilot's:
+// startup | resume | new), and their pre-compaction events cannot add context
+// (Gemini PreCompress and Copilot preCompact are advisory). So there the block
+// arrives in two steps:
+//   --mark            on PreCompress / preCompact: when a PAN phase is in flight,
+//                     leave a per-session marker in the per-user hook directory
+//                     under the OS temp directory (0700, written 0600);
+//   --inject <host>   on the next tool result (Gemini AfterTool, Copilot
+//                     postToolUse): consume the marker and return the block once,
+//                     in that host's output shape. With no marker it prints nothing.
+// A tool result is the first point after a compaction where both hosts take added
+// context, including an autonomous `-p` run that never sees another prompt (read
+// 2026-10-03: gemini-cli v0.61.0 docs/hooks/reference.md; the Copilot hooks
+// reference on docs.github.com). The marker modes need no R39 deferral: in a
+// project with both installs, Copilot also runs Claude's registration of this
+// script, but that one is the SessionStart mode, which a Copilot start never matches.
+//
 // Inert unless the project is a PAN project with work in flight: `.planning/`
 // holds a state.md that names a current phase AND a roadmap.md with an unticked
 // phase. Everywhere else — no planning tree, a focus-only project, a finished
-// milestone — it prints nothing. It never writes a file (field finding: hooks
-// that scaffolded `.planning/` in projects that never ran PAN).
+// milestone — it prints nothing. It never writes into the project (field finding:
+// hooks that scaffolded `.planning/` in projects that never ran PAN); the only
+// file it writes is the marker, outside the project.
 //
 // Fail-open everywhere: bad stdin, unreadable files — exit 0 silently. A missing
 // reminder costs a re-read; a crashed hook is a failing hook at every start.
@@ -31,7 +50,9 @@
 // additionalContext; each field is truncated on its own.
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
+const crypto = require('crypto');
 
 /**
  * Which planning tree this hook acts on.
@@ -124,7 +145,99 @@ function readIfExists(p) {
   try { return fs.readFileSync(p, 'utf8'); } catch { return null; }
 }
 
+// ─── The marker (Gemini, Copilot) ─────────────────────────────────────────────
+
+// A marker older than this belongs to a session that never made another tool call.
+const MARKER_TTL_MS = 6 * 60 * 60 * 1000;
+
+/** Gemini sends `session_id`; Copilot's camelCase payloads send `sessionId`. */
+function sessionIdOf(payload) {
+  for (const k of ['session_id', 'sessionId']) {
+    if (typeof payload[k] === 'string' && payload[k]) return payload[k];
+  }
+  return '';
+}
+
+/** The per-user hook directory's name: the stop guard's and the context monitor's too. */
+function hookDirName() {
+  const uid = (typeof process.getuid === 'function' ? process.getuid() : process.env.USERNAME || 'win');
+  return `pan-hooks-${uid}`;
+}
+
+// Per-user hook state directory inside tmpdir, created 0700 — the same directory
+// and the same checks as hookStateDir() in pan-stop-guard.js (hooks are standalone
+// files and cannot require one another). Null when the directory is not provably
+// ours: on a shared host another user must not be able to plant a marker that
+// injects, or a symlink the marker is written through (M60).
+function hookStateDir() {
+  const dir = path.join(os.tmpdir(), hookDirName());
+  try {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const st = fs.lstatSync(dir);
+    if (st.isSymbolicLink()) return null;
+    // POSIX-only ownership and mode checks: Windows fakes mode bits (N15).
+    if (typeof process.getuid === 'function') {
+      if (st.uid !== process.getuid()) return null;
+      if ((st.mode & 0o077) !== 0) return null;
+    }
+    return dir;
+  } catch { return null; }
+}
+
+/** One marker per (session, project), named by a hash so neither leaks into a file name. Pure. */
+function markerName(sessionId, projectDir) {
+  const key = crypto.createHash('sha256').update(`${sessionId}\u0000${path.resolve(projectDir)}`).digest('hex').slice(0, 32);
+  return `state-reinject-${key}.json`;
+}
+
+// This hook's files in the shared directory: markers, and one a crash left mid-take.
+const MARKER_FILE_RE = /^state-reinject-[0-9a-f]{32}\.json(?:\.\d+\.taken)?$/;
+
+function writeMarker(file, now = Date.now()) {
+  fs.writeFileSync(file, JSON.stringify({ at: now }), { mode: 0o600 });
+  // Sweep markers no session came back for — only this hook's: the directory
+  // holds the other hooks' state too. Best effort.
+  try {
+    for (const name of fs.readdirSync(path.dirname(file))) {
+      if (!MARKER_FILE_RE.test(name)) continue;
+      const p = path.join(path.dirname(file), name);
+      try { if (now - fs.statSync(p).mtimeMs > MARKER_TTL_MS) fs.unlinkSync(p); } catch { /* raced */ }
+    }
+  } catch { /* unreadable dir */ }
+}
+
+/**
+ * Take the marker if there is a fresh one: rename it first, so two hooks racing on
+ * the same tool result cannot both inject. True when this call took it.
+ */
+function takeMarker(file, now = Date.now()) {
+  const taken = `${file}.${process.pid}.taken`;
+  try { fs.renameSync(file, taken); } catch { return false; }
+  let fresh = false;
+  try { fresh = now - JSON.parse(fs.readFileSync(taken, 'utf8')).at <= MARKER_TTL_MS; } catch { /* unreadable: stale */ }
+  try { fs.unlinkSync(taken); } catch { /* gone */ }
+  return fresh;
+}
+
+/** The block in the shape each host's tool-result event takes. */
+function injectOutput(host, context) {
+  if (host === 'gemini') return { hookSpecificOutput: { hookEventName: 'AfterTool', additionalContext: context } };
+  if (host === 'copilot') return { additionalContext: context };
+  return null;
+}
+
+function contextFor(projectDir) {
+  return buildReinjectContext({
+    stateContent: readIfExists(planningPath(projectDir, 'state.md')),
+    roadmapContent: readIfExists(planningPath(projectDir, 'roadmap.md')),
+    planningRel: planningDirName(),
+  });
+}
+
 function main() {
+  const argv = process.argv.slice(2);
+  const mode = argv.includes('--mark') ? 'mark' : argv.includes('--inject') ? 'inject' : 'session-start';
+  const host = mode === 'inject' ? argv[argv.indexOf('--inject') + 1] : null;
   let input = '';
   process.stdin.setEncoding('utf8');
   process.stdin.on('data', chunk => { input += chunk; });
@@ -133,20 +246,32 @@ function main() {
       let payload = {};
       try { payload = JSON.parse(input); } catch { /* fail open on bad stdin */ }
       if (!payload || typeof payload !== 'object') payload = {};
-      if (payload.source !== 'compact') { process.exit(0); return; }
-
       const projectDir = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd();
-      const context = buildReinjectContext({
-        stateContent: readIfExists(planningPath(projectDir, 'state.md')),
-        roadmapContent: readIfExists(planningPath(projectDir, 'roadmap.md')),
-        planningRel: planningDirName(),
-      });
-      if (context) {
-        process.stdout.write(JSON.stringify({
-          hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: context },
-        }));
+
+      if (mode === 'session-start') {
+        if (payload.source !== 'compact') { process.exit(0); return; }
+        const context = contextFor(projectDir);
+        if (context) {
+          process.stdout.write(JSON.stringify({
+            hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: context },
+          }));
+        }
+      } else {
+        const sid = sessionIdOf(payload);
+        // An unknown host leaves the marker for a host that can use it.
+        if (!sid || (mode === 'inject' && !injectOutput(host, ''))) { process.exit(0); return; }
+        const dir = hookStateDir();
+        if (!dir) { process.exit(0); return; }
+        const file = path.join(dir, markerName(sid, projectDir));
+        if (mode === 'mark') {
+          if (contextFor(projectDir)) writeMarker(file);
+        } else if (takeMarker(file)) {
+          // Re-read now: the position after the compaction, not before it.
+          const context = contextFor(projectDir);
+          if (context) process.stdout.write(JSON.stringify(injectOutput(host, context)));
+        }
       }
-    } catch { /* fail open — never break a session start */ }
+    } catch { /* fail open — never break a session or a tool call */ }
     process.exit(0);
   });
 }
@@ -155,4 +280,4 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { buildReinjectContext, UNTICKED_PHASE_RE };
+module.exports = { buildReinjectContext, UNTICKED_PHASE_RE, markerName, hookDirName, sessionIdOf, injectOutput, MARKER_TTL_MS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pan-wizard",
-  "version": "3.32.0",
+  "version": "3.33.0",
   "description": "Command a bot army for your codebase: a reasoning-tier Mission Control delegates whole-project goals to specialist squads and ships behind a human merge gate. Five AI CLIs, zero context rot.",
   "bin": {
     "pan-wizard": "bin/install.js"

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

@@ -29,7 +29,10 @@ function buildAgentsMdSection() {
     'This project uses PAN Wizard for structured, phase-based planning and execution.',
     '',
     '- `.planning/` is PAN\'s state directory (state.md, roadmap.md, phase directories). Treat it as the source of truth for planning state and modify it through PAN commands, not by hand.',
-    '- PAN commands install as `pan-*` skills/commands (for example `/pan-help`, `/pan-new-project`, `/pan-exec-phase`). Start with `/pan-help`.',
+    // One section serves every runtime in the project, so it names each one's form
+    // (the README's list); `/pan-help` alone sent Claude Code users to a command
+    // that does not exist there (prompt audit, market-ideas M34).
+    '- PAN\'s commands are named per runtime: `/pan:help`, `/pan:new-project`, `/pan:exec-phase` in Claude Code and Gemini CLI; `/pan-help` and so on in OpenCode, Copilot CLI and unified-skills Claude installs; `$pan-help` in Codex. Start with the help command.',
     '- The `pan-tools` dispatcher backs every command; it lives under `pan-wizard-core/` inside the runtime\'s config directory (or `.agents/` for unified installs).',
     PAN_AGENTS_END,
   ].join('\n');

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

@@ -10,6 +10,8 @@ const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, planningR
 const { estimateTokens } = require('./context-budget.cjs');
 const { collectPhaseSummaries, readErrorPatterns, appendErrorPattern, appendSessionSummary, parseLearnings, formatLearningEntry, cmdLearningsExtract, cmdLearningsList, cmdLearningsPrune } = require('./commands-learnings.cjs');
 const { planningRootRel } = require('./planning-root.cjs');
+const { verificationFreshness } = require('./verify-scope.cjs');
+const { isVerificationFile } = require('./constants.cjs');
 
 /**
  * Generate a URL-safe slug from text by lowercasing and replacing non-alphanumeric chars.
@@ -631,6 +633,7 @@ function cmdProgressRender(cwd, format, raw) {
   const milestone = getMilestoneInfo(cwd);
 
   const phases = [];
+  const verifiedPhases = []; // indexes into phases[] of phases with a verification file
   let totalPlans = 0;
   let totalSummaries = 0;
 
@@ -661,12 +664,25 @@ function cmdProgressRender(cwd, format, raw) {
       else if (summaryCount > 0) status = 'In Progress';
       else status = 'Planned';
 
+      if (phaseFiles.some(isVerificationFile)) verifiedPhases.push(phases.length);
       phases.push({ number: phaseNum, name: phaseName, plans: planCount, summaries: summaryCount, status });
     }
   } catch {
     // Phases directory does not exist or is unreadable; return empty progress
   }
 
+  // A verified phase whose covered files changed since the verified commit is
+  // stale (market-ideas M27). Not for the bar or the health score: the statusline
+  // calls the bar, which never shows it, and each check costs a git call.
+  if (format !== 'bar' && format !== 'health') {
+    for (const i of verifiedPhases) {
+      const f = verificationFreshness(cwd, phases[i].number);
+      if (f.error) continue;
+      phases[i].verification = f.state;
+      if (f.state === 'stale') phases[i].changed_since_verification = f.changed_since;
+    }
+  }
+
   const percent = totalPlans > 0 ? Math.min(100, Math.round((totalSummaries / totalPlans) * 100)) : 0;
 
   if (format === 'health') {
@@ -682,7 +698,7 @@ function cmdProgressRender(cwd, format, raw) {
     rendered += '| Phase | Name | Plans | Status |\n';
     rendered += '|-------|------|-------|--------|\n';
     for (const phase of phases) {
-      rendered += `| ${phase.number} | ${phase.name} | ${phase.summaries}/${phase.plans} | ${phase.status} |\n`;
+      rendered += `| ${phase.number} | ${phase.name} | ${phase.summaries}/${phase.plans} | ${phase.status}${phase.verification === 'stale' ? ' (verification stale)' : ''} |\n`;
     }
     output({ rendered }, raw, rendered);
   } else if (format === 'bar') {
@@ -1027,9 +1043,85 @@ function shouldSkipTests(files) {
   return files.every(f => /\.md$/i.test(f));
 }
 
+// ─── version (market-ideas M29) ──────────────────────────────────────────────
+// The version of the PAN core that is running, where it lives, and, with --check,
+// the update state the SessionStart update check last recorded. Reads only local
+// files: the check itself (`npm view`, up to 10 s) stays in the hook's background
+// child, so `version --check` never waits on the network and never throws offline.
+
+// Where each install directory's update-check hook writes its cache: the hook's
+// `join(homeDir, '.claude', 'cache')` is rewritten to the runtime's GLOBAL config dir
+// (getConfigDirFromHome(runtime, true) in the installer).
+const UPDATE_CACHE_HOME_DIR = {
+  '.claude': ['.claude'], '.codex': ['.codex'], '.gemini': ['.gemini'],
+  '.opencode': ['.config', 'opencode'], opencode: ['.config', 'opencode'],
+  '.github': ['.copilot'], '.copilot': ['.copilot'],
+};
+
+/** The running core's version, its directory, and the install directory holding it. */
+function panVersionInfo(coreDir = path.resolve(__dirname, '..', '..')) {
+  let version = null;
+  // VERSION is written by the installer; a source checkout has the package.json instead.
+  try { version = fs.readFileSync(path.join(coreDir, 'VERSION'), 'utf8').trim() || null; } catch { /* not an install */ }
+  if (!version) {
+    try { version = JSON.parse(fs.readFileSync(path.join(coreDir, '..', 'package.json'), 'utf8')).version || null; } catch { /* neither */ }
+  }
+  return { version, core: toPosix(coreDir), install_dir: path.basename(path.dirname(coreDir)) };
+}
+
+/** The update-check cache for this install's runtime, else the newest one any runtime wrote. */
+function readUpdateCache(homeDir, installDir) {
+  const read = (segments) => {
+    const file = path.join(homeDir, ...segments, 'cache', 'pan-update-check.json');
+    try { return { file: toPosix(file), data: JSON.parse(fs.readFileSync(file, 'utf8')) }; } catch { return null; }
+  };
+  const own = UPDATE_CACHE_HOME_DIR[installDir] ? read(UPDATE_CACHE_HOME_DIR[installDir]) : null;
+  if (own) return own;
+  const seen = new Set();
+  const all = [];
+  for (const segs of Object.values(UPDATE_CACHE_HOME_DIR)) {
+    const key = segs.join('/');
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const c = read(segs);
+    if (c) all.push(c);
+  }
+  all.sort((a, b) => (Number(b.data.checked) || 0) - (Number(a.data.checked) || 0));
+  return all[0] || null;
+}
+
+/**
+ * The update state from a cache record: `unchecked` (no check has run), `offline`
+ * (the last check could not reach npm), `available`, `current`, or `ahead` (this
+ * core is newer than npm's latest, e.g. a prerelease or a source checkout).
+ */
+function updateState(version, cache) {
+  if (!cache) return { state: 'unchecked', latest: null, checked_at: null, cache: null };
+  const checkedAt = Number(cache.data.checked) ? new Date(Number(cache.data.checked) * 1000).toISOString() : null;
+  const latest = cache.data.latest && cache.data.latest !== 'unknown' ? String(cache.data.latest) : null;
+  if (!latest) return { state: 'offline', latest: null, checked_at: checkedAt, cache: cache.file };
+  const { compareVersions } = require('./hygiene.cjs');
+  const cmp = version ? compareVersions(version, latest) : -1;
+  return { state: cmp < 0 ? 'available' : cmp > 0 ? 'ahead' : 'current', latest, checked_at: checkedAt, cache: cache.file };
+}
+
+function cmdVersion(_cwd, opts, raw) {
+  const info = panVersionInfo();
+  const result = { version: info.version, core: info.core, install_dir: info.install_dir, node: process.version };
+  if (opts.check) result.update = updateState(info.version, readUpdateCache(require('os').homedir(), info.install_dir));
+  const text = opts.check
+    ? `${info.version || 'unknown'} (${result.update.state}${result.update.latest ? `, npm latest ${result.update.latest}` : ''})`
+    : String(info.version || 'unknown');
+  output(result, raw, text);
+}
+
 // ---- Error patterns, session history, learnings — extracted to commands-learnings.cjs (re-exported below)
 
 module.exports = {
+  cmdVersion,
+  panVersionInfo,
+  readUpdateCache,
+  updateState,
   cmdGenerateSlug,
   cmdCurrentTimestamp,
   cmdListTodos,