pan-wizard 3.33.0 → 3.35.0

package/bin/install.js

@@ -369,13 +369,11 @@ function getCommitAttribution(runtime) {
     const settings = readSettings(path.join(getGlobalDir('claude', explicitConfigDir), 'settings.json')) || {}; // unusable file = no info (read-only probe)
     result = lib.commitAttributionFromSettings(settings);
   } else if (runtime === 'copilot') {
-    // Copilot CLI: user-editable settings live in settings.json; config.json is
-    // legacy (auto-migrated by the CLI, now internal state) — fall back for old installs
+    // Copilot CLI: user settings live in settings.json only. config.json is the CLI's
+    // internal state, and Copilot 1.0.93 ignores user settings there (R48), so a
+    // stale `attribution` left in it must not decide PAN's attribution.
     const copilotDir = getGlobalDir('copilot', explicitConfigDir);
-    let config = readSettings(path.join(copilotDir, 'settings.json')) || {}; // unusable file = no info (read-only probe)
-    if (!config.attribution) {
-      config = readSettings(path.join(copilotDir, 'config.json')) || {}; // unusable file = no info (read-only probe)
-    }
+    const config = readSettings(path.join(copilotDir, 'settings.json')) || {}; // unusable file = no info (read-only probe)
     if (!config.attribution || config.attribution.commit === undefined) {
       result = undefined;
     } else if (config.attribution.commit === '') {
@@ -445,6 +443,8 @@ function copyFlattenedCommands(srcDir, destDir, prefix, pathPrefix, runtime) {
       content = content.replace(globalClaudeRegex, pathPrefix);
       content = content.replace(localClaudeRegex, `./${getDirName(runtime)}/`);
       content = content.replace(opencodeDirRegex, pathPrefix);
+      // As in copyWithPathReplacement: no `pan-tools` bin is on PATH.
+      content = content.replace(/\bpan-tools\b(?=\s+[a-z])/g, `node ${pathPrefix}pan-wizard-core/bin/pan-tools.cjs`);
       content = processAttribution(content, getCommitAttribution(runtime));
       content = convertClaudeToOpencodeFrontmatter(content);
 
@@ -504,6 +504,7 @@ function copyCommandsAsCodexSkills(srcDir, skillsDir, prefix, pathPrefix, runtim
       content = content.replace(globalClaudeRegex, pathPrefix);
       content = content.replace(localClaudeRegex, `./${getDirName(runtime)}/`);
       content = content.replace(codexDirRegex, pathPrefix);
+      content = lib.rewriteAgentFileRefs(content, runtime, pathPrefix);
       // Codex executes commands literally; no `pan-tools` bin on PATH.
       const panToolsPath = `${pathPrefix}pan-wizard-core/bin/pan-tools.cjs`;
       content = content.replace(/\bpan-tools\b(?=\s+[a-z])/g, `node ${panToolsPath}`);
@@ -821,6 +822,7 @@ function copyCommandsAsCopilotSkills(srcDir, skillsDir, prefix, pathPrefix, runt
       const localClaudeRegex = /\.\/\.claude\//g;
       content = content.replace(globalClaudeRegex, pathPrefix);
       content = content.replace(localClaudeRegex, `./${getDirName(runtime)}/`);
+      content = lib.rewriteAgentFileRefs(content, runtime, pathPrefix);
       // Copilot CLI executes commands literally; there's no `pan-tools` bin on PATH.
       // Replace bare `pan-tools` invocations with the explicit node + .cjs path.
       const panToolsPath = `${pathPrefix}pan-wizard-core/bin/pan-tools.cjs`;
@@ -876,6 +878,11 @@ function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand
         const localClaudeRegex = /\.\/\.claude\//g;
         content = content.replace(globalClaudeRegex, pathPrefix);
         content = content.replace(localClaudeRegex, `./${dirName}/`);
+        // No runtime puts a `pan-tools` bin on PATH: invoke it via node, as the Codex
+        // and Copilot converters already did. A bare `pan-tools <verb>` in an installed
+        // Claude, Gemini or OpenCode command or workflow was a call that could not run.
+        content = content.replace(/\bpan-tools\b(?=\s+[a-z])/g, `node ${pathPrefix}pan-wizard-core/bin/pan-tools.cjs`);
+        content = lib.rewriteAgentFileRefs(content, runtime, pathPrefix);
         content = processAttribution(content, getCommitAttribution(runtime));
 
         // Convert frontmatter for opencode compatibility
@@ -1213,7 +1220,7 @@ function uninstall(isGlobal, runtime = 'claude') {
   // 4. Remove PAN hooks (scripts + Copilot CLI hooks config file)
   const hooksDir = path.join(targetDir, 'hooks');
   if (fs.existsSync(hooksDir)) {
-    const panHooks = ['pan-statusline.js', 'pan-check-update.js', 'pan-check-update.sh', 'pan-context-monitor.js', 'pan-cost-logger.js', 'pan-trace-logger.js', 'pan-stop-guard.js', 'pan-state-reinject.js', 'pan.json'];
+    const panHooks = ['pan-statusline.js', 'pan-check-update.js', 'pan-check-update.sh', 'pan-guard.js', 'pan-context-monitor.js', 'pan-cost-logger.js', 'pan-trace-logger.js', 'pan-stop-guard.js', 'pan-state-reinject.js', 'pan.json'];
     let hookCount = 0;
     for (const hook of panHooks) {
       const hookPath = path.join(hooksDir, hook);
@@ -1244,6 +1251,16 @@ function uninstall(isGlobal, runtime = 'claude') {
     }
   }
 
+  // 4a'. Remove the OpenCode plugin (O12); the plugins directory goes too when
+  // nothing else is in it.
+  const opencodePlugin = path.join(targetDir, 'plugins', OPENCODE_PLUGIN_FILE);
+  if (fs.existsSync(opencodePlugin)) {
+    try { fs.unlinkSync(opencodePlugin); } catch {}
+    try { fs.rmdirSync(path.dirname(opencodePlugin)); } catch { /* not empty: the user's own plugins stay */ }
+    removedCount++;
+    console.log(`  ${green}✓${reset} Removed the PAN plugin`);
+  }
+
   // 4b. Codex: strip PAN entries from the shared .codex/hooks.json (foreign
   // hook registrations are preserved; the file is deleted only when nothing
   // but PAN content remained).
@@ -1557,35 +1574,12 @@ function uninstall(isGlobal, runtime = 'claude') {
       // CodeQL js/file-system-race. Same idiom as the hooks' metrics read.
       try {
         const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-        let modified = false;
-
-        // Remove PAN permission entries
-        if (config.permission) {
-          for (const permType of ['read', 'external_directory']) {
-            if (config.permission[permType]) {
-              const keys = Object.keys(config.permission[permType]);
-              for (const key of keys) {
-                // Match `pan-wizard` rather than `pan-wizard-core` so the malformed
-                // key earlier versions wrote (`~/.config/opencode/pan-wizard/*`) is
-                // cleaned too. Without this, machines that ran any global OpenCode
-                // install before the glob was fixed keep that entry forever — the
-                // uninstaller could never match it, which is what made it residue
-                // rather than a cosmetic typo.
-                if (key.includes('pan-wizard')) {
-                  delete config.permission[permType][key];
-                  modified = true;
-                }
-              }
-              // Clean up empty objects
-              if (Object.keys(config.permission[permType]).length === 0) {
-                delete config.permission[permType];
-              }
-            }
-          }
-          if (Object.keys(config.permission).length === 0) {
-            delete config.permission;
-          }
-        }
+        let modified;
+
+        // Remove PAN permission entries, v1 `permission` keys and OpenCode 2
+        // `permissions[]` rules alike (R47). Keys matching `pan-wizard` rather than
+        // `pan-wizard-core` also clean the malformed key earlier versions wrote.
+        ({ modified } = lib.stripOpencodePermissions(config));
 
         if (modified) {
           // If stripping PAN permissions emptied the config, remove the file
@@ -1699,6 +1693,18 @@ function uninstall(isGlobal, runtime = 'claude') {
     console.log(`  ${yellow}⚠${reset} No PAN files found to remove.`);
   }
 
+  // A local install's runtime directory that the removal left empty goes too (X1).
+  // Never a global one (~/.claude and the like are the host's own homes), and never a
+  // directory that still holds anything: `.github` usually holds the project's files.
+  if (!isGlobal) {
+    try {
+      if (fs.readdirSync(targetDir).length === 0) {
+        fs.rmdirSync(targetDir);
+        console.log(`  ${green}✓${reset} Removed empty ${locationLabel}`);
+      }
+    } catch { /* already gone or unreadable: leave it */ }
+  }
+
   console.log(`
   ${green}Done!${reset} PAN has been uninstalled from ${runtimeLabel}.
   Your other files and settings have been preserved.
@@ -1741,10 +1747,6 @@ function configureOpencodePermissions(isGlobal = true) {
     }
   }
 
-  // Ensure permission structure exists
-  if (!config.permission) {
-    config.permission = {};
-  }
 
   // Build the PAN path using the actual config directory
   // Use ~ shorthand if it's in the default location, otherwise use full path
@@ -1761,25 +1763,9 @@ function configureOpencodePermissions(isGlobal = true) {
     ? '~/.config/opencode/pan-wizard-core/*'
     : `${opencodeConfigDir.replace(/\\/g, '/')}/pan-wizard-core/*`;
   
-  let modified = false;
-
-  // Configure read permission
-  if (!config.permission.read || typeof config.permission.read !== 'object') {
-    config.permission.read = {};
-  }
-  if (config.permission.read[panPath] !== 'allow') {
-    config.permission.read[panPath] = 'allow';
-    modified = true;
-  }
-
-  // Configure external_directory permission (the safety guard for paths outside project)
-  if (!config.permission.external_directory || typeof config.permission.external_directory !== 'object') {
-    config.permission.external_directory = {};
-  }
-  if (config.permission.external_directory[panPath] !== 'allow') {
-    config.permission.external_directory[panPath] = 'allow';
-    modified = true;
-  }
+  // v1 `permission` object in a new or v1 file; the native `permissions[]` array
+  // in a file the user already converted to OpenCode 2, never both (R47).
+  const { modified } = lib.addOpencodePermissions(config, panPath);
 
   if (!modified) {
     return; // Already configured
@@ -1842,6 +1828,8 @@ const PATCHES_DIR_NAME = 'pan-local-patches';
 // the patches tree stays self-contained.
 const EXTERNAL_PATCHES_SUBDIR = '_external';
 const MANIFEST_NAME = 'pan-file-manifest.json';
+// PAN's OpenCode plugin, installed as <opencode dir>/plugins/pan-wizard.js (O12).
+const OPENCODE_PLUGIN_FILE = 'pan-wizard.js';
 
 /**
  * Compute SHA256 hash of file contents
@@ -1963,6 +1951,11 @@ function writeManifest(configDir, runtime = 'claude', isGlobal = false) {
       }
     }
   }
+  // The OpenCode plugin (O12)
+  const opencodePlugin = path.join(configDir, 'plugins', OPENCODE_PLUGIN_FILE);
+  if (isOpencode && fs.existsSync(opencodePlugin)) {
+    manifest.files[`plugins/${OPENCODE_PLUGIN_FILE}`] = fileHash(opencodePlugin);
+  }
 
   try {
     fs.writeFileSync(path.join(configDir, MANIFEST_NAME), JSON.stringify(manifest, null, 2));
@@ -2248,7 +2241,9 @@ function install(isGlobal, runtime = 'claude') {
       // last; the per-runtime core remains for agents/hooks.
       const sharedCoreDest = path.join(agentsRoot, 'pan-wizard-core');
       copySharedCore(path.join(src, 'pan-wizard-core'), sharedCoreDest, corePrefix, pathPrefix, runtime);
-      try { fs.writeFileSync(path.join(sharedCoreDest, 'VERSION'), pkg.version); } catch { /* non-fatal */ }
+      // With its newline, as the per-runtime core writes it: `/pan:update` cats the file
+      // and prints the runtime flag next, which glued onto a bare version.
+      try { fs.writeFileSync(path.join(sharedCoreDest, 'VERSION'), pkg.version + '\n'); } catch { /* non-fatal */ }
 
       // Canonical agent-definition reference copies (ADR-0028 agent-ref
       // canonicalization): shared content references these instead of the
@@ -2451,6 +2446,9 @@ function install(isGlobal, runtime = 'claude') {
           // Always replace ~/.claude/ as it is the source of truth in the repo
           const dirRegex = /~\/\.claude\//g;
           content = content.replace(dirRegex, pathPrefix);
+          // As in copyWithPathReplacement: no `pan-tools` bin is on PATH.
+          content = content.replace(/\bpan-tools\b(?=\s+[a-z])/g, `node ${pathPrefix}pan-wizard-core/bin/pan-tools.cjs`);
+          content = lib.rewriteAgentFileRefs(content, runtime, pathPrefix);
           content = processAttribution(content, getCommitAttribution(runtime));
           // Codex custom agents are standalone TOML files (2026-06 format);
           // markdown in .codex/agents/ is not recognized. Handle before
@@ -2639,6 +2637,21 @@ function install(isGlobal, runtime = 'claude') {
     }
   }
 
+  // OpenCode plugin (memory optimisation O12). OpenCode runs no command hooks, but a
+  // plugin can add to the prompt it compacts a session with; PAN's keeps the phase
+  // in flight through a compaction, as hooks/pan-state-reinject.js does on the other
+  // hosts. CommonJS, beside the package.json written above.
+  if (isOpencode) {
+    try {
+      const pluginsDir = path.join(targetDir, 'plugins');
+      fs.mkdirSync(pluginsDir, { recursive: true });
+      fs.copyFileSync(path.join(src, 'pan-wizard-core', 'opencode', OPENCODE_PLUGIN_FILE), path.join(pluginsDir, OPENCODE_PLUGIN_FILE));
+      console.log(`  ${green}✓${reset} Installed the PAN plugin to plugins/ (keeps PAN's position through compaction)`);
+    } catch (e) {
+      pushInstallWarning('opencodePlugin', `plugins/${OPENCODE_PLUGIN_FILE}`, e);
+    }
+  }
+
   if (failures.length > 0) {
     console.error(`\n  ${yellow}Installation incomplete!${reset} Failed: ${failures.join(', ')}`);
     process.exit(1);
@@ -2739,6 +2752,10 @@ function install(isGlobal, runtime = 'claude') {
   const stateReinjectCommand = isGlobal
     ? buildHookCommand(targetDir, 'pan-state-reinject.js')
     : 'node ' + dirName + '/hooks/pan-state-reinject.js';
+  // The guard names its host: payloads and the way to deny differ per runtime (A7).
+  const guardCommand = (isGlobal
+    ? buildHookCommand(targetDir, 'pan-guard.js')
+    : 'node ' + dirName + '/hooks/pan-guard.js') + ` --host ${runtime}`;
   // Gemini and Copilot (M33): a marker before the compaction, the block on the next
   // tool result. The inject mode names the host, whose output shapes differ.
   const stateReinjectMarkCommand = `${stateReinjectCommand} --mark`;
@@ -2752,7 +2769,7 @@ function install(isGlobal, runtime = 'claude') {
   if (!isOpencode) {
     const entrypoints = lib.verifyHookEntrypoints([
       updateCheckCommand, contextMonitorCommand, statuslineCommand, costLoggerCommand,
-      traceLoggerCommand, stopGuardCommand, stateReinjectCommand, stateReinjectMarkCommand, stateReinjectInjectCommand,
+      traceLoggerCommand, stopGuardCommand, stateReinjectCommand, stateReinjectMarkCommand, stateReinjectInjectCommand, guardCommand,
     ], process.cwd());
     if (!entrypoints.ok) {
       console.error(`\n  ${red}✖ Hook verification FAILED — these hook commands would run a script that is not there:${reset}`);
@@ -2772,7 +2789,7 @@ function install(isGlobal, runtime = 'claude') {
       let existing = null;
       try { existing = JSON.parse(fs.readFileSync(hooksJsonPath, 'utf8')); } catch { /* absent or invalid — start fresh */ }
       const merged = lib.mergeCodexHooksConfig(existing, {
-        updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand, stateReinjectCommand,
+        updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand, stateReinjectCommand, guardCommand,
       });
       fs.writeFileSync(hooksJsonPath, JSON.stringify(merged, null, 2) + '\n');
       // Print the path we actually wrote. The hardcoded '.codex/hooks.json' was
@@ -2790,7 +2807,7 @@ function install(isGlobal, runtime = 'claude') {
   // from any legacy config.json registration.
   if (isCopilot) {
     const hooksConfigPath = path.join(targetDir, 'hooks', 'pan.json');
-    const hooksConfig = buildCopilotHooksConfig({ updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand, stateReinjectMarkCommand, stateReinjectInjectCommand });
+    const hooksConfig = buildCopilotHooksConfig({ updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand, stateReinjectMarkCommand, stateReinjectInjectCommand, guardCommand });
     try {
       fs.mkdirSync(path.dirname(hooksConfigPath), { recursive: true });
       fs.writeFileSync(hooksConfigPath, JSON.stringify(hooksConfig, null, 2) + '\n');
@@ -2884,6 +2901,7 @@ function install(isGlobal, runtime = 'claude') {
     // unbuilt phases — fail-open and inert outside PAN projects.
     const registrations = [
       { slot: 'sessionStart', hook: 'pan-check-update', command: updateCheckCommand, label: 'update check hook' },
+      { slot: 'preToolUse', hook: 'pan-guard', command: guardCommand, label: 'pre-tool guard hook' },
       { slot: 'postToolUse', hook: 'pan-context-monitor', command: contextMonitorCommand, label: 'context window monitor hook' },
       { slot: 'subagentStop', hook: 'pan-cost-logger', command: costLoggerCommand, label: 'cost logger hook' },
       { slot: 'subagentStop', hook: 'pan-trace-logger', command: traceLoggerCommand, label: 'trace logger hook' },

package/commands/pan/army.md

@@ -1,6 +1,7 @@
 ---
 name: army
 group: Army
+argument-hint: "<goal> [--source scan|backlog] [--max-cycles N] [--total-budget N] [--enforce-budget] [--verify-reserve F] [--squads a,b,c] [--no-build-worktrees] [--push] [--clean-seal] [--schedule <cadence>] [--daily-budget N] [--dry-run] [--continue] [--stop] [--status]"
 description: Bot-army campaign — Mission Control (the reasoning-tier conductor) delegates a whole-project goal to squads (architecture / build / quality / release), each squad working branch-per-agent worktrees under a hard safety harness, gated by CI + a human merge, looping plan→delegate→execute→review→integrate→learn until the goal ships or a stop condition fires.
 allowed-tools:
   - Read
@@ -25,7 +26,7 @@ The army is the campaign-scale sibling of `/pan:exec-phase --hierarchical` (one
 
 | Tier | Who | Model tier | Access |
 |------|-----|-----------|--------|
-| 0 · Mission Control | `pan-conductor` | `reasoning` (`mid` under `budget`) | delegation-first (Agent toolset) — instructed to route work, not write it |
+| 0 · Mission Control | `pan-conductor` | the session model (spawned with no `model`, so under every profile) | delegation-first (Agent toolset) — instructed to route work, not write it |
 | 1 · Architecture | design + planning agents — `squad show architecture` lists them | `reasoning` | `read-only` |
 | 1 · Build | `pan-executor` | `reasoning` | `read-write-bash` — one branch+worktree per agent |
 | 1 · Quality | adversarial review + debug agents — `squad show quality` lists them | `mid` | `read-only`, adversarial |
@@ -34,11 +35,11 @@ The army is the campaign-scale sibling of `/pan:exec-phase --hierarchical` (one
 
 **Where each row comes from.** The tier-1 rows mirror the `squads[]` records `pan-tools squad list` prints — label, `tier`, `access` (their member names come from `squad show <name>`, since `squad list` reports only a count). The Tier 0 and Tier 2 rows are PAN's hierarchy positions: the same command names them under its `coordinator` and `workers` keys, but reports nothing else about them, so the Model-tier and Access values on those two rows are written here rather than returned by the command. Resolve the roster at runtime — never hardcode it: `pan-tools squad list` and `pan-tools squad show <name>`.
 
-**Reading the Model-tier column.** These are PAN *tiers*, not model names. `reasoning` resolves to `inherit` — the model you launched with — while `mid` and `fast` map to the provider's mid/fast models (Sonnet and Haiku on Anthropic).
+**Reading the Model-tier column.** These are PAN *tiers*, not model names. `reasoning` resolves to `inherit` — the model you launched with — while `mid` and `fast` map to the provider's mid/fast models (Sonnet and Haiku on Anthropic). They are what `squad list` and `resolve-model` report: the army's spawns pass no model, so an agent spawned under its own type runs on its file's `model:` (the reviewer-class agents pin `opus` on Claude Code) or, without one, the session model.
 
 **Reading the Access column.** The backticked values on the tier-1 rows are the `access` labels `squad list` reports; tier 0 and tier 2 carry PAN's own. They are role contracts the conductor's prompt assigns when it delegates, not a sandbox: `squads.cjs` says of itself that it "modifies no agent and changes no execution path", so a label can differ from what an agent may actually do — expect that, since several `read-only` squad members hold `Write` to emit planning or verification artifacts. The binding grant is each agent's own `tools:` frontmatter (`grep '^tools:' ~/.claude/agents/*.md`), and Mission Control's includes `Write` and `Bash`: routing rather than coding is how it is instructed to behave, not something the runtime prevents. The rail those grants do enforce is delegation depth — `grep -l '^tools:.*Task' ~/.claude/agents/*.md` names every agent able to spawn another (today, `pan-conductor`), so a squad agent cannot fan out further.
 
-**Squad tier is not profile tier.** The tier column above is a `squads.cjs` grouping attribute — what `pan-tools squad list` reports — and it is not what resolves an agent's model; that comes from the active `model_profile` (`quality` and `balanced` are `reasoning` for every agent, and `budget` is the only profile that down-tiers), plus any `model:` pin in an agent's own frontmatter. So the `mid` on the Quality and Release rows does not describe what those agents run under the default profile — under `quality` and `balanced` they resolve `reasoning` like everything else. The tier-1 values above are the squad groupings; the tier-0 and tier-2 values are per-agent profile tiers. **`budget` resolves per agent, not per row:** it sends some workers to `fast` and others to `mid`, so no single value is true of the Tier 2 row — `MODEL_PROFILES` in `~/.claude/pan-wizard-core/bin/lib/core.cjs` is the table, and it is the one to read rather than a tier written into a doc. For the agents that pin a model outright, `grep -l '^model: opus' ~/.claude/agents/*.md` lists them — the pin applies on Claude Code only, since the installer strips it for the other runtimes.
+**Squad tier is not profile tier.** The tier column above is a `squads.cjs` grouping attribute — what `pan-tools squad list` reports — and it is not an agent's profile tier, which is what `resolve-model` reports from the active `model_profile` (`quality` and `balanced` are `reasoning` for every agent, and `budget` is the only profile that down-tiers). The army applies neither: its spawns pass no model, so an agent runs on its own `model:` pin, else the session model, under every profile. So the `mid` on the Quality and Release rows does not describe what those agents run. The tier-1 values above are the squad groupings; the tier-2 value is the per-agent profile tier `resolve-model` reports. **`budget` resolves per agent, not per row:** `resolve-model` reports `fast` for some workers and `mid` for others, so no single value is true of the Tier 2 row — `MODEL_PROFILES` in `~/.claude/pan-wizard-core/bin/lib/core.cjs` is the table, and it is the one to read rather than a tier written into a doc. For the agents that pin a model outright, `grep -l '^model: opus' ~/.claude/agents/*.md` lists them — the pin applies on Claude Code only, since the installer strips it for the other runtimes.
 
 ---
 
@@ -75,6 +76,7 @@ Every cap the conductor enforces applies to the campaign, scaled up:
 
 ```
 /pan:army "<goal>" [--source scan|backlog] [--max-cycles N] [--total-budget N]
+          [--enforce-budget] [--verify-reserve F]
           [--squads a,b,c] [--no-build-worktrees] [--push] [--clean-seal]
           [--schedule <cadence>] [--daily-budget N]
           [--dry-run] [--continue] [--stop] [--status]
@@ -102,20 +104,20 @@ Every cap the conductor enforces applies to the campaign, scaled up:
 
 ```
 /pan:army
-  Phase 0  MUSTER   — squad list + roster validate · cache prime · baseline · loop-state · abort-file clear
+  Phase 0  MUSTER   — squad list + roster validate · baseline · loop-state · abort-file clear
   Phase 1  PLAN     — Mission Control (session model, xhigh effort) decomposes the goal into dependency-ordered missions
   Phase 2  DELEGATE — pick the next item (focus-auto --source) · route to the owning squad over the Agent toolset
   Phase 3  EXECUTE  — Build squad: one army/<task> worktree per agent (parallel); Architecture/Quality research in parallel (read-only)
   Phase 4  REVIEW   — Quality squad on the built tree: reviewer + hardener + meta → verdict ladder; a block is a hard gate
   Phase 5  INTEGRATE— Release squad: prepare squash-merge → CI/verification → ALWAYS-ASK human approval → tag → deploy hand-off
-  Phase 6  LEARN    — summaries return to Mission Control; retro/learn writes patterns to memory (this is "Dreaming")
+  Phase 6  LEARN    — summaries return to Mission Control; retro/learn patterns go into the next mission's plan (this is "Dreaming")
   → loop to Phase 2 until a stop condition; --clean-seal once at the end
 ```
 
 ### Phase 0 — Muster (once)
-1. **Onboarding gate (existing projects).** Run `pan-tools init new-project` to detect state. If `is_brownfield` (existing code) and `needs_codebase_map` (no `.planning/codebase/`), the army cannot plan blind — STOP and route through onboarding first: `/pan:map-codebase` (Architecture squad's `pan-document_code` maps the existing system into `.planning/codebase/`), then `/pan:new-project` to build `roadmap.md` + `requirements.md` *against the existing system*. Re-run `/pan:army` once a backlog exists. If a codebase map + roadmap already exist, continue.
+1. **Onboarding gate (existing projects).** Run `pan-tools init new-project` to detect state. If `is_brownfield` (existing code) and `needs_codebase_map` (no `.planning/codebase/`), the army cannot plan blind — STOP and route through onboarding first: `/pan:map-codebase` (its `pan-document_code` mappers — workers in `pan-tools squad list`, not Architecture squad members — map the existing system into `.planning/codebase/`), then `/pan:new-project` to build `roadmap.md` + `requirements.md` *against the existing system* — only when `project_exists` is false: it refuses an initialized project, which needs just the map. Re-run `/pan:army` once a backlog exists. If a codebase map + roadmap already exist, continue.
 2. `pan-tools squad list` and validate the roster is healthy.
-3. Prime the cache; capture baseline (`git status` clean of project source; tests green or STOP). On a brownfield repo, the baseline is the current `main` — every `army/<task>` branch forks from it, so the existing code is never edited in place.
+3. Capture the baseline (`git status` clean of project source; tests green or STOP). On a brownfield repo, the baseline is the commit you have checked out — every `army/<task>` branch forks from it (`worktree create` bases it on `HEAD`), so the existing code is never edited in place.
 4. Ensure `.planning/orchestration/` exists; clear any stale `abort` file; init loop-state.
 5. `--dry-run` → print the plan + per-squad delegation and STOP.
 
@@ -138,7 +140,7 @@ Spawn `pan-release`. It prepares the squash-merge, runs the configured `verifica
 **Phase report (opt-in build deliverable):** when `workflow.phase_reports.enabled` is `true`, generate the mission's self-contained per-phase HTML report **in the built tree, before staging the squash-merge** — `pan-tools report phase <N>` — so the report rides along in the merge as a phase deliverable. **Never run `report index` inside a squad worktree:** the timeline index is a single shared file that aggregates *all* phases, so a worktree would see only its own phase and concurrent squads would race on it. The index is a single-writer, post-merge concern (Phase 6). Never opens a browser.
 
 ### Phase 6 — Learn (Dreaming)
-Squad summaries return to Mission Control. Run `/pan:retro --write-memory` (and `/pan:learn` if traces exist) so recurring patterns persist into agent memory for the next mission. Strike the landed item; update loop-state. For a scheduled campaign, also `pan-tools campaign record-run --items <n> --points <p>` so the next-due time and the day's spend advance.
+Squad summaries return to Mission Control. Run `/pan:retro` (and `/pan:learn` if traces exist) and carry the recurring patterns into the next mission yourself: name them in the plan you hand the Architecture squad. Agent memory does not do this, because PAN does not load it into agents. A pattern that should outlast the campaign goes to the human at the merge gate as a proposed line for the project's instructions. Strike the landed item; update loop-state. For a scheduled campaign, also `pan-tools campaign record-run --items <n> --points <p>` so the next-due time and the day's spend advance.
 
 **Rebuild the timeline index (single writer).** When `workflow.phase_reports.enabled` and `workflow.phase_reports.index` are `true`, Mission Control — and *only* Mission Control, on the integration branch after the merge has landed — rebuilds the project index once against the now-merged set of phases: `pan-tools report index`, then commit it (the commit honors `commit_docs`). Doing this post-merge from the single conductor is what keeps `report-index.html` consistent while builds run in parallel worktrees.
 
@@ -161,7 +163,7 @@ Nothing under `pan-army-*` or on an `army/*` branch is a deliverable: the squash
 PAN is not a daemon — it cannot wake itself while the session is closed. `--schedule` arms a campaign and lets an external trigger drive it; the human merge gate is never relaxed.
 
 - **Arm:** `/pan:army "<goal>" --schedule daily --daily-budget 200` writes `.planning/orchestration/schedule.json` (cadence, daily budget, next-due) instead of running once.
-- **The trigger (you wire one):** a host scheduler (Claude Code routines / cron / scheduled-tasks) or a `/loop` runs `pan-tools campaign due` and, when it reports due, invokes `/pan:army --continue`. On next session open, a due campaign is surfaced as a nudge.
+- **The trigger (you wire one):** a host scheduler (Claude Code routines / cron / scheduled-tasks) or a `/loop` runs `pan-tools campaign due` and, when it reports due, invokes `/pan:army --continue`. Nothing surfaces a due campaign on its own: PAN does not wake itself, so without a trigger the campaign waits until you run `/pan:army --continue` (`pan-tools campaign due` says whether one is due).
 - **Resume (`--continue`):** read the schedule + `.planning/orchestration/` + focus-auto state. If `campaign due` is true and the day's `--daily-budget` isn't spent, run the next mission(s), then `campaign record-run` (advances next-due, accrues the day's spend). If not due or budget-spent, report next-due and STOP.
 - **Bounded spend:** point budgets (`--total-budget`, `--daily-budget`) are **advisory indicators by default** — they're tracked and surfaced, not hard stops. `--enforce-budget` (or config `budget.enforce`) makes `--total-budget` a hard stop; a scheduled campaign's `--daily-budget` pauses the day's run only when the schedule was armed with `--enforce-budget` (`campaign schedule --enforce-budget`; `--advisory-budget` turns it back off). The real bounds are `--max-cycles`, the conductor caps, the abort file, and the human merge gate at every integrate. A scheduled campaign runs the backlog down to staged, reviewed, green PRs over days.
 - **Verify reserve:** a fraction of `--total-budget` (`--verify-reserve`, default 0.15) is held back so the closing Quality re-review isn't starved. Surfaced always via `campaign status` / `focus auto --status` (`into_verify_reserve`, `new_work_budget_remaining`); under `--enforce-budget` the run stops taking on new missions early (`budget_reserve_reached`) and spends the reserve on the final `--clean-seal` verification before the last INTEGRATE.
@@ -171,7 +173,9 @@ Manage it: `pan-tools campaign status` (active/paused, spent today, next-due), `
 ---
 
 ## Completion contract
-The campaign is complete when ANY holds: `--max-cycles` reached · backlog empty · abort file present · context < 25% · a mission cannot pass Quality and can't be cleanly reverted (HARD STOP — preserve state, report). (Budget exhaustion is advisory by default — a stop condition only when `budget.enforce`/`--enforce-budget` is set; under enforcement, crossing into the verify reserve (`budget_reserve_reached`) stops new missions but the reserved points still fund the closing re-verification.) Always run `--clean-seal` (unless omitted) after the last item.
+The campaign is complete when ANY holds: `--max-cycles` reached · backlog empty · abort file present · a mission cannot pass Quality and can't be cleanly reverted (HARD STOP — preserve state, report). (Budget exhaustion is advisory by default — a stop condition only when `budget.enforce`/`--enforce-budget` is set; under enforcement, crossing into the verify reserve (`budget_reserve_reached`) stops new missions but the reserved points still fund the closing re-verification.) Before each new mission, run `pan-tools cost limits --raw`: `weekly_limit_reached` (Claude Code's 7-day usage window at `cost.weekly_limit_stop_pct`, default 90%) is a stop condition too, so the rest of the window stays the user's. Always run `--clean-seal` (unless omitted) after the last item.
+
+The context monitor's notes are not a stop condition: they give no figure and ask for a checkpoint. On the critical note, bring the mission's state in `.planning/orchestration/` up to date and carry on. After the host compacts, re-read the campaign with `pan-tools focus auto --status` and `.planning/orchestration/`: PAN's state re-injection carries state.md's position, not the campaign's.
 
 ## NEVER DO
 - Let Mission Control write code, or let a squad agent spawn further agents (depth cap).
@@ -184,7 +188,7 @@ The campaign is complete when ANY holds: `--max-cycles` reached · backlog empty
 - Plan on the session model Mission Control inherits, delegate over the Agent toolset, keep each squad's return a tight summary.
 - One worktree per Build agent; parallel research/verify; serial human-gated integrate.
 - Check the abort file + spawn/budget caps before every spawn.
-- Finish with the clean-build seal; write learnings back to memory.
+- Finish with the clean-build seal; carry the learnings into the next mission's plan.
 
 ## Examples
 ```

package/commands/pan/assumptions.md

@@ -2,7 +2,7 @@
 name: pan:assumptions
 group: Phase Management
 description: Surface Claude's assumptions about a phase approach before planning
-argument-hint: "[phase]"
+argument-hint: "<phase>"
 allowed-tools:
   - Read
   - Bash
@@ -70,7 +70,7 @@ GOOD: "Assumption: The project uses Express for routing — Evidence: require('e
    - Surface assumptions about: technical approach, implementation order, scope, risks, dependencies
    - Present assumptions clearly with file:line references where applicable
    - Prompt "What do you think?"
-5. Gather feedback and offer next steps
+6. Gather feedback and offer next steps
 </process>
 
 <success_criteria>

package/commands/pan/audit-deployment.md

@@ -54,8 +54,7 @@ Claude:   <target>/.claude/
 Gemini:   <target>/.gemini/
 OpenCode: <target>/.opencode/
 Codex:    <target>/.codex/
-Copilot:  <target>/.copilot/ (or ~/.copilot/)
-GitHub:   <target>/.github/
+Copilot:  <target>/.github/ (local install) or ~/.copilot/ (global)
 ```
 
 For the detected runtime config directory (CONFIG_DIR), audit ALL of the following:
@@ -88,14 +87,14 @@ For the detected runtime config directory (CONFIG_DIR), audit ALL of the followi
 - [ ] `CONFIG_DIR/agents/` — every manifest-listed agent file present
 - Verify key agents exist: pan-planner, pan-executor, pan-verifier, pan-debugger
 
-**1.6 Hooks**
+**1.6 Hooks** (not OpenCode: its install copies no hooks — check `CONFIG_DIR/plugins/pan-wizard.js` instead)
 - [ ] `CONFIG_DIR/hooks/pan-statusline.js` exists
 - [ ] `CONFIG_DIR/hooks/pan-check-update.js` exists
 - [ ] `CONFIG_DIR/hooks/pan-context-monitor.js` exists
 
 **1.7 Settings/Config**
 - [ ] Settings file exists (settings.json / opencode.json / config.json)
-- [ ] Hooks are registered — Claude `settings.json`: SessionStart, PostToolUse, SubagentStop, Stop, statusLine; Gemini `settings.json`: SessionStart and AfterAgent only (no statusLine); Codex: `.codex/hooks.json`; Copilot: `.github/hooks/pan.json`
+- [ ] Hooks are registered — Claude `settings.json`: SessionStart, PostToolUse, SubagentStop, Stop, statusLine; Gemini `settings.json`: SessionStart, AfterAgent, PreCompress and AfterTool (the last two for state re-injection; no statusLine); Codex: `.codex/hooks.json`; Copilot: `.github/hooks/pan.json`
 - [ ] Hook commands point to existing files
 
 **1.8 Manifest Integrity**
@@ -137,13 +136,13 @@ Check `.planning/` directory in the target:
 - Parse state.md "Current Position" — extract phase number
 - Count actual phase directories — do they match?
 - Check roadmap.md phase count vs actual directories
-- Verify no orphaned .continue-here-*.md files (paused but not resumed)
+- Check `.planning/phases/*/.continue-here*.md` (pause writes `.continue-here.md`): resuming does not delete it (only the transition workflow removes a completed phase's handoffs), so its presence alone does not mean the session was never resumed
 
 **2.5 Config Sanity**
 - Validate config.json values are within expected ranges
 - `model_profile`: "quality" | "balanced" | "budget"
 - `commit_docs`: boolean
-- `workflow.*` toggles (research, plan_check, verifier, ...): all boolean
+- `workflow.*` toggles (research, plan_check, verifier, ...): boolean — except `workflow.phase_reports`, an object (`enabled`, `open`, `theme`, `index`)
 - `budget`: `default_points` numeric, `enforce` boolean
 </step>
 
@@ -170,7 +169,7 @@ For each phase with plan files (`*-plan.md`, e.g. `01-01-plan.md`):
 - Check for PAN-style commit messages
 
 **3.4 Session Continuity**
-- Check for .continue-here-*.md files (indicates paused sessions)
+- Check for `.planning/phases/*/.continue-here*.md` files (a pause happened at some point; nothing removes them on resume)
 - Check state.md session logs for gaps
 - Look for evidence of context loss (repeated work, contradictory decisions)
 
@@ -250,7 +249,7 @@ Verification Coverage: <N>%
 If `--repair` flag was provided, attempt auto-fixes for repairable issues:
 - Regenerate missing settings.json with default hook config
 - Create missing .planning/config.json with defaults
-- Remove orphaned .continue-here-*.md files
+- Remove `.planning/phases/*/.continue-here*.md` files the user confirms are stale
 
 Report repairs performed.
 </step>
@@ -285,10 +284,10 @@ The spec MUST follow this exact format to be consumable by superplan.md:
 
 ## Success Criteria
 
-```
+~~~
 SC-1: <measurable criterion>
 SC-2: <measurable criterion>
-```
+~~~
 
 ## Design
 
@@ -313,9 +312,9 @@ SC-2: <measurable criterion>
 
 ### Dependency Graph
 
-```
+~~~
 A.1 ──> A.2 ──> A.3
-```
+~~~
 
 ## Test Plan
 

package/commands/pan/cost.md

@@ -2,7 +2,7 @@
 name: pan:cost
 group: Observability
 description: Show token usage and estimated cost across PAN commands and agents
-argument-hint: "[report|append|clear|rebuild] [--format json|table|chart] [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--apply] [--no-main-thread]"
+argument-hint: "[report|append|clear|rebuild|limits] [--format json|table|chart] [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--apply] [--no-main-thread]"
 allowed-tools:
   - Read
   - Bash
@@ -13,13 +13,9 @@ Report token usage and estimated cost across all PAN invocations in this project
 
 Reads `.planning/metrics/tokens.jsonl` — an append-only log where each line is one call (agent or command) with token counts and model. Cost is computed from a built-in rate table (overridable via `.planning/config.json` → `cost.rates`).
 
-Default output is JSON for piping. Use `--format table` for human-readable tables or `--format chart` for an ASCII bar chart of daily spend.
+Default output is JSON for piping. Use `--format table` for human-readable tables or `--format chart` for an ASCII bar chart of daily spend; both print text, with or without `--raw`.
 </objective>
 
-<execution_context>
-@~/.claude/pan-wizard-core/bin/lib/cost.cjs
-</execution_context>
-
 <subcommands>
 
 ### `report` (default)
@@ -33,7 +29,7 @@ pan-tools cost report [--format json|table|chart] [--since YYYY-MM-DD] [--until
 **Flags:**
 - `--format` — `json` (default, for tools) | `table` (aligned text columns) | `chart` (per-day ASCII bars).
 - `--since` — ISO date lower bound (inclusive). Records without `ts` always pass.
-- `--until` — ISO date upper bound (inclusive).
+- `--until` — ISO upper bound (inclusive): a bare date covers that whole day.
 
 **JSON output shape:**
 ```json
@@ -81,6 +77,10 @@ Delete the cost log. Useful at the start of a billing cycle.
 pan-tools cost clear
 ```
 
+### `limits`
+
+`pan-tools cost limits` shows Claude Code's 5-hour and 7-day usage windows as the status line last saw them, and whether the 7-day one has reached `cost.weekly_limit_stop_pct` (default 90%), where `/pan:focus-auto` and `/pan:army` stop. Interactive Claude Code sessions on a subscription only: headless runs and other runtimes have no reading.
+
 ### `rebuild`
 
 Rebuild the ledger from Claude Code's own transcripts (session file plus the per-agent files under `<session>/subagents/`, Workflow-tool subagents one level down). Rows written by hooks before v3.29 booked a slice of the parent session to whichever subagent stopped and counted turns once per content block; the rebuild replaces them with one exact row per agent transcript, typed from the main thread's `Agent` calls, plus one row per session for the main thread's own usage (`--no-main-thread` omits it). Rows whose session transcript is gone, and caller-appended rows, are kept. Dry-run by default — show the user the per-session before → after (and any `warnings`), then apply only on their say-so; the previous ledger is kept beside the new one as `tokens.jsonl.rebuilt-<date>` (a later copy never overwrites an earlier one). Run it **before** `/pan:hygiene --apply` on a poisoned ledger: quarantine moves the whole file aside, and a rebuild afterwards has no rows left to keep. The main-thread row is dated to the session's last record, so `--since`/`--until` windows and the per-day view see a session's own usage on its final day.
@@ -134,7 +134,7 @@ If `.planning/metrics/tokens.jsonl` is empty, `/pan:cost` returns zero totals
 | Runtime | Support |
 |---------|---------|
 | Claude Code | Full — data format + aggregation + all output formats |
-| OpenCode | Full aggregator; PAN registers no hooks on OpenCode, so records come from `pan-tools cost append` or an external script |
+| OpenCode | Full aggregator; PAN's only OpenCode hook is its plugin's compaction hook (`plugins/pan-wizard.js`), so cost records come from `pan-tools cost append` or an external script |
 | Gemini | Full aggregator; PAN registers no cost hook on Gemini CLI (no subagent-completion event), so records come from `pan-tools cost append` or an external script |
 | Codex | Full — `pan-cost-logger` registered on `SubagentStop` in `.codex/hooks.json` |
 | Copilot CLI | Full aggregator; `pan-cost-logger` registered on `subagentStop` in `.github/hooks/pan.json` (token counts depend on what the payload carries) |

package/commands/pan/dashboard.md

@@ -20,6 +20,3 @@ pan-tools hud [--out <file>] [--open] [--stdout]
 See **`/pan:hud`** for the full panel list, flags, JSON result shape, and runtime compatibility. The two commands are interchangeable.
 </objective>
 
-<execution_context>
-@~/.claude/pan-wizard-core/bin/lib/hud.cjs
-</execution_context>

package/commands/pan/debug.md

@@ -35,7 +35,7 @@ ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state load)
 ```
 
-Extract `commit_docs` from init JSON. Resolve debugger model:
+Extract `config.commit_docs` from the JSON (`state load` nests it under `config`). Resolve debugger model:
 ```bash
 DEBUGGER_MODEL=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-debugger --raw)
 ```
@@ -125,7 +125,10 @@ Task(
 
 ## 4. Handle Agent Return
 
-**If `## ROOT CAUSE FOUND`:**
+**If `## DEBUG COMPLETE`** (the success return for `goal: find_and_fix`, after the user confirmed the fix at the `human-verify` checkpoint):
+- Display the root cause, the fix, its verification and the commit; the session file is now `.planning/debug/resolved/{slug}.md`
+
+**If `## ROOT CAUSE FOUND`** (returned only for `goal: find_root_cause_only`, which this command does not pass):
 - Display root cause and evidence summary
 - Offer options:
   - "Fix now" - spawn fix subagent
@@ -148,7 +151,7 @@ Task(
   - "Add more context" - gather more symptoms, spawn again
 
 <debug_handoff_schema>
-Debug session files (`.planning/debug/{slug}.md`) MUST contain structured state for cross-agent handoff:
+Debug session files (`.planning/debug/{slug}.md`) follow pan-debugger's own structure (agents/pan-debugger.md, "File Structure"): frontmatter `status: gathering | investigating | diagnosed | fixing | verifying | awaiting_human_verify | resolved`, then Current Focus, Symptoms, Reproduction, Eliminated, Evidence and Resolution. The YAML below names the facts a handoff needs; its field names and status values are not the file's:
 
 ```yaml
 # Required sections in debug session file
@@ -182,7 +185,7 @@ fix:                                 # Populated when applied
   tests_added: ["{test paths}"]
 ```
 
-**Why structured:** Each continuation agent starts with 0 context. Without structured state, it re-reads the entire investigation log and may re-test eliminated hypotheses. With structured state, it reads `hypotheses_tested` (skip these), checks `hypotheses_remaining` (do these next), and picks up exactly where the previous agent stopped.
+**Why structured:** Each continuation agent starts with 0 context. Without structured state, it re-reads the entire investigation log and may re-test eliminated hypotheses. With structured state, it skips the hypotheses under Eliminated, starts from Current Focus `next_action`, and picks up exactly where the previous agent stopped.
 </debug_handoff_schema>
 
 ## 5. Spawn Continuation Agent (After Checkpoint)
@@ -210,9 +213,9 @@ goal: find_and_fix
 </mode>
 
 <handoff_instructions>
-1. Parse the debug file's structured sections (symptoms, investigation, root_cause, fix)
-2. Do NOT re-test hypotheses marked "eliminated" — they are dead ends
-3. Start from hypotheses_remaining or the checkpoint's next action
+1. Parse the debug file's sections (frontmatter status, Current Focus, Symptoms, Reproduction, Eliminated, Evidence, Resolution — the format in templates/debug.md)
+2. Do NOT re-test hypotheses listed under Eliminated — they are dead ends
+3. Start from Current Focus `next_action` or the checkpoint's next action
 4. Update the debug file's structured sections as you progress
 </handoff_instructions>
 ```