pan-wizard 3.30.0 → 3.32.0

package/bin/install-lib.cjs

@@ -677,7 +677,7 @@ function buildAgentPluginMcpConfig() {
  * @param {{updateCheckCommand?:string, contextMonitorCommand?:string, costLoggerCommand?:string, traceLoggerCommand?:string}} commands
  */
 function buildCopilotPluginHooksConfig(commands) {
-  const { updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand } = commands || {};
+  const { updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand } = commands || {};
   const hooks = {};
   if (updateCheckCommand) hooks.SessionStart = [{ type: 'command', command: updateCheckCommand }];
   if (contextMonitorCommand) hooks.PostToolUse = [{ type: 'command', command: contextMonitorCommand }];
@@ -685,6 +685,8 @@ function buildCopilotPluginHooksConfig(commands) {
   if (costLoggerCommand) subagentStop.push({ type: 'command', command: costLoggerCommand });
   if (traceLoggerCommand) subagentStop.push({ type: 'command', command: traceLoggerCommand });
   if (subagentStop.length > 0) hooks.SubagentStop = subagentStop;
+  // Copilot's documented PascalCase alias for agentStop (M14).
+  if (stopGuardCommand) hooks.Stop = [{ type: 'command', command: stopGuardCommand }];
   return { hooks };
 }
 
@@ -692,9 +694,15 @@ function buildCopilotPluginHooksConfig(commands) {
 const COPILOT_PLUGIN_NAMESPACE = 'com.github.copilot';
 
 /** The adapter paragraph appended to every bundled skill (ADR-0045 D3). */
-function agentPluginSkillAdapterNote() {
+function agentPluginSkillAdapterNote(kind = 'skill') {
+  // An agent file (<root>/com.github.copilot/agents/<name>.agent.md) sits as deep as a
+  // skill (<root>/skills/<name>/SKILL.md), so the same derivation holds; until
+  // 2026-09-26 only the skills carried the note, and the bundled Copilot agents held
+  // the token with nothing to say what it meant (3.28.0 review, LOW).
+  const what = kind === 'agent' ? 'agent' : 'skill';
+  const file = kind === 'agent' ? 'this agent file' : 'this SKILL.md';
   return `Plugin bundle (Agent Plugins format):
-- \`${AGENT_PLUGIN_ROOT_TOKEN}\` in this skill is the directory that holds this plugin's \`plugin.json\` — two levels above this SKILL.md. Your runtime reports this skill's file location when it loads it; derive the root from that path and substitute it wherever \`${AGENT_PLUGIN_ROOT_TOKEN}\` appears before running a command.
+- \`${AGENT_PLUGIN_ROOT_TOKEN}\` in this ${what} is the directory that holds this plugin's \`plugin.json\` — two levels above ${file}. Your runtime reports this ${what}'s file location when it loads it; derive the root from that path and substitute it wherever \`${AGENT_PLUGIN_ROOT_TOKEN}\` appears before running a command.
 - Prefer the \`pan\` MCP server's tools when your runtime has connected this plugin's \`mcp.json\`, and pass the project's absolute path as each tool's \`cwd\` argument — the server is started in the plugin's directory, which is never the project. Otherwise run \`node ${AGENT_PLUGIN_ROOT_TOKEN}/pan-wizard-core/bin/pan-tools.cjs <verb>\` from the project root.
 - \`${AGENT_PLUGIN_RUNTIME_HOME_TOKEN}\` is your runtime's user-level configuration directory (for example \`~/.claude\`, \`~/.codex\`, \`~/.gemini\`, \`~/.config/opencode\`, \`~/.copilot\`) and \`${AGENT_PLUGIN_RUNTIME_DIR_TOKEN}\` its project-level directory (\`.claude\`, \`.codex\`, \`.gemini\`, \`.opencode\`, \`.github\`). Substitute the one that applies to the runtime you are.`;
 }
@@ -742,13 +750,29 @@ function convertClaudeCommandToCopilotSkill(content, skillName) {
 /**
  * @param {string} content - Claude agent markdown
  * @param {object} [opts]
- * @param {Record<string,string[]>} [opts.modelLists] - Copilot CLI (>= 1.0.83) accepts a
- *   `model:` LIST tried in order plus `model-policy`. When a PAN agent pins `model:
- *   <alias>` and this map has an entry for the alias, the Copilot agent gets that list
- *   and `model-policy: prefer` (degrade gracefully; `required` would refuse to run).
- *   NOT wired into the installer yet: the Copilot model ids must be verified on a live
- *   CLI first (ADR-0028's rule; harness/scenarios/live-gate-copilot.json carries the
- *   probe). Reality check RC15 / plan item R13, 2026-09-10.
+ * Every agent carries `include-custom-instructions: true` (market-ideas M15). Copilot
+ * does not give a custom agent spawned as a subagent the repository's instruction
+ * files — `copilot-instructions.md`, `AGENTS.md`, `CLAUDE.md` — unless its frontmatter
+ * opts in (Copilot CLI reference, "Repository custom instructions for subagents";
+ * default false). PAN's rules section lives in AGENTS.md, and PAN's agents run as
+ * subagents. Measured 2026-09-26 on Copilot CLI 1.0.88: with an AGENTS.md canary, a
+ * subagent with the field answered it and the same agent without the field answered
+ * that it had none.
+ *
+ * @param {Record<string,string[]>} [opts.modelLists] - Copilot CLI accepts a priority
+ *   list under `models:` ("the runtime uses the first model the user's plan can
+ *   access; if none resolve, dispatch falls back to the session's model") plus
+ *   `model-policy`. When a PAN agent pins `model: <alias>` and this map has an entry
+ *   for the alias, the Copilot agent gets that list and `model-policy: preferred`
+ *   (degrade gracefully; `required` would refuse to run). Until 2026-09-26 the list
+ *   was written under the singular `model:` and the policy as `prefer`; the first live
+ *   probe (Copilot CLI 1.0.88) refused to load that agent — `model-policy: Expected
+ *   "preferred" or "required"` — and the reference names the list field `models`.
+ *   Copilot's model ids are dotted (`claude-opus-5.5`; its /models list, same day). A
+ *   session on `auto` — every Copilot Free session — ignores the list, so the list's
+ *   fall-through is still unmeasured; NOT wired into the installer until it is, on a
+ *   paid plan (harness/scenarios/copilot-agent-frontmatter.json). Reality check RC15 /
+ *   plan item R13, 2026-09-10.
  */
 function convertClaudeToCopilotAgent(content, opts = {}) {
   const converted = convertClaudeToCopilotMarkdown(content);
@@ -806,10 +830,10 @@ function convertClaudeToCopilotAgent(content, opts = {}) {
     const pinned = extractFrontmatterField(frontmatter, 'model');
     const list = pinned && Array.isArray(lists[pinned]) ? lists[pinned].filter(Boolean) : null;
     if (list && list.length) {
-      modelYaml = `\nmodel:\n${list.map(m => `  - ${yamlQuote(m)}`).join('\n')}\nmodel-policy: prefer`;
+      modelYaml = `\nmodels:\n${list.map(m => `  - ${yamlQuote(m)}`).join('\n')}\nmodel-policy: preferred`;
     }
   }
-  return `---\nname: ${yamlQuote(name)}\ndescription: ${yamlQuote(description)}${toolsYaml}${modelYaml}\n---\n${body}`;
+  return `---\nname: ${yamlQuote(name)}\ndescription: ${yamlQuote(description)}${toolsYaml}\ninclude-custom-instructions: true${modelYaml}\n---\n${body}`;
 }
 
 // ─── Attribution Processing ─────────────────────────────────────────────────
@@ -1021,7 +1045,7 @@ function stripThinkingFrontmatter(content, runtime) {
  * @returns {Object} A `.github/hooks/pan.json` config object
  */
 function buildCopilotHooksConfig(commands) {
-  const { updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand } = commands || {};
+  const { updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand } = commands || {};
   const config = { version: 1, hooks: {} };
   if (updateCheckCommand) {
     config.hooks.sessionStart = [{ type: 'command', command: updateCheckCommand }];
@@ -1037,6 +1061,12 @@ function buildCopilotHooksConfig(commands) {
   if (subagentStop.length > 0) {
     config.hooks.subagentStop = subagentStop;
   }
+  // agentStop: the auto-advance stop guard (M14). Copilot blocks a stop only on
+  // the JSON `decision: "block"` output, and ends the turn anyway after eight
+  // consecutive blocks; the guard blocks once per stop chain.
+  if (stopGuardCommand) {
+    config.hooks.agentStop = [{ type: 'command', command: stopGuardCommand }];
+  }
   return config;
 }
 
@@ -1066,20 +1096,38 @@ function buildCopilotHooksConfig(commands) {
  *   - copilot: `.github/hooks/pan.json`, camelCase (docs.github.com hooks reference).
  *   - opencode: no hook system.
  *
- * `stop` is where the auto-advance stop guard registers (P-1809): Claude's Stop
- * and Gemini's AfterAgent, both of which re-prompt the agent when a hook blocks.
- * Codex and Copilot have a stop event too; PAN does not register the guard there yet.
+ * `stop` is where the auto-advance stop guard registers (P-1809): Claude's Stop,
+ * Gemini's AfterAgent, Codex's Stop and Copilot's agentStop — each re-prompts the
+ * agent when a hook prints `{"decision":"block","reason":…}`, and each hands the
+ * hook `stop_hook_active` (M14, 2026-09-26: codex-rs hooks/schema
+ * stop.command.input.schema.json; Copilot hooks-reference, where the field stays
+ * snake_case in the camelCase agentStop payload). Copilot does not block on exit
+ * code 2 for agentStop — only the JSON form, which is what the guard prints.
+ *
+ * `compact` is where the state re-injection hook registers (M10): SessionStart with
+ * the `compact` matcher (HOOK_SLOT_MATCHERS), the one event after a compaction whose
+ * `hookSpecificOutput.additionalContext` reaches the model on Claude Code and Codex —
+ * both hosts' PostCompact discard it (hooks references, read 2026-09-26). Gemini's
+ * PreCompress fires before the summary and Copilot's preCompact is notification-only,
+ * so neither gets it.
  */
 const HOOK_EVENT_MAP = Object.freeze({
-  claude: { surface: 'settings.json', sessionStart: 'SessionStart', postToolUse: 'PostToolUse', subagentStop: 'SubagentStop', stop: 'Stop' },
-  gemini: { surface: 'settings.json', sessionStart: 'SessionStart', postToolUse: null, subagentStop: null, stop: 'AfterAgent' },
-  codex: { surface: 'hooks.json', sessionStart: 'SessionStart', postToolUse: 'PostToolUse', subagentStop: 'SubagentStop', stop: null },
-  copilot: { surface: 'hooks/pan.json', sessionStart: 'sessionStart', postToolUse: 'postToolUse', subagentStop: 'subagentStop', stop: null },
+  claude: { surface: 'settings.json', sessionStart: 'SessionStart', postToolUse: 'PostToolUse', subagentStop: 'SubagentStop', stop: 'Stop', compact: 'SessionStart' },
+  gemini: { surface: 'settings.json', sessionStart: 'SessionStart', postToolUse: null, subagentStop: null, stop: 'AfterAgent', compact: null },
+  codex: { surface: 'hooks.json', sessionStart: 'SessionStart', postToolUse: 'PostToolUse', subagentStop: 'SubagentStop', stop: 'Stop', compact: 'SessionStart' },
+  copilot: { surface: 'hooks/pan.json', sessionStart: 'sessionStart', postToolUse: 'postToolUse', subagentStop: 'subagentStop', stop: 'agentStop', compact: null },
   opencode: null,
 });
 
+/**
+ * The matcher a slot's registration carries, where the event alone is too broad.
+ * `compact` is SessionStart narrowed to the start that follows a compaction — the
+ * `source: "compact"` matcher value on Claude Code and Codex alike.
+ */
+const HOOK_SLOT_MATCHERS = Object.freeze({ compact: 'compact' });
+
 /** The hook scripts PAN registers in a Claude-shaped settings.json `hooks` block. */
-const PAN_SETTINGS_HOOKS = Object.freeze(['pan-check-update', 'pan-context-monitor', 'pan-cost-logger', 'pan-trace-logger', 'pan-stop-guard']);
+const PAN_SETTINGS_HOOKS = Object.freeze(['pan-check-update', 'pan-context-monitor', 'pan-cost-logger', 'pan-trace-logger', 'pan-stop-guard', 'pan-state-reinject']);
 
 /**
  * Remove, from every event array of a Claude-shaped `hooks` object except
@@ -1263,7 +1311,7 @@ function buildCodexMcpSnippet(serverPath, panToolsPath, projectRoot, serverName
  * @returns {object} Merged config object to serialize back to hooks.json
  */
 function mergeCodexHooksConfig(existing, commands) {
-  const { updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand } = commands || {};
+  const { updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand, stateReinjectCommand } = commands || {};
   const config = (existing && typeof existing === 'object') ? existing : {};
   if (!config.hooks || typeof config.hooks !== 'object') config.hooks = {};
 
@@ -1276,6 +1324,10 @@ function mergeCodexHooksConfig(existing, commands) {
   //   - check-update spawns a detached child and prints nothing → async.
   //   - context-monitor returns `additionalContext` the model must see THIS
   //     turn → stays synchronous.
+  //   - stop-guard decides whether the turn may end (`decision: "block"`), which
+  //     an async handler cannot do → synchronous (M14).
+  //   - state-reinject returns `additionalContext` for the continuation after a
+  //     compaction → synchronous, and matched to `source: "compact"` (M10).
   // Codex-only: Claude Code and Copilot hook schemas were not checked for an
   // equivalent flag (plan item 2 gate) — do not copy this column into their
   // builders without reading their docs first.
@@ -1284,9 +1336,11 @@ function mergeCodexHooksConfig(existing, commands) {
     ['PostToolUse', contextMonitorCommand, 'pan-context-monitor', false],
     ['SubagentStop', costLoggerCommand, 'pan-cost-logger', true],
     ['SubagentStop', traceLoggerCommand, 'pan-trace-logger', true],
+    ['Stop', stopGuardCommand, 'pan-stop-guard', false],
+    ['SessionStart', stateReinjectCommand, 'pan-state-reinject', false, HOOK_SLOT_MATCHERS.compact],
   ];
 
-  for (const [event, command, marker, async] of wanted) {
+  for (const [event, command, marker, async, matcher] of wanted) {
     if (!command) continue;
     if (!Array.isArray(config.hooks[event])) config.hooks[event] = [];
     let existingHandler = null;
@@ -1306,7 +1360,7 @@ function mergeCodexHooksConfig(existing, commands) {
     }
     const handler = { type: 'command', command };
     if (async) handler.async = true;
-    config.hooks[event].push({ hooks: [handler] });
+    config.hooks[event].push({ ...(matcher ? { matcher } : {}), hooks: [handler] });
   }
   return config;
 }
@@ -1322,7 +1376,7 @@ function removeCodexPanHooks(existing) {
   for (const event of Object.keys(existing.hooks)) {
     if (!Array.isArray(existing.hooks[event])) continue;
     existing.hooks[event] = existing.hooks[event].filter(group =>
-      !(Array.isArray(group.hooks) && group.hooks.some(h => h.command && /pan-(check-update|context-monitor|cost-logger|trace-logger)/.test(h.command))));
+      !(Array.isArray(group.hooks) && group.hooks.some(h => h.command && /pan-(check-update|context-monitor|cost-logger|trace-logger|stop-guard|state-reinject)/.test(h.command))));
     if (existing.hooks[event].length === 0) delete existing.hooks[event];
   }
   if (Object.keys(existing.hooks).length === 0) delete existing.hooks;
@@ -1395,6 +1449,8 @@ function codexTrustNotice() {
     'installed pan-* agents) only loads once the project is trusted in Codex.',
     'If commands or agents seem missing, approve the project when Codex prompts,',
     'or set trust_level for this path in ~/.codex/config.toml.',
+    'Codex also skips new or changed hooks until you trust them: after installing',
+    'or upgrading PAN, run /hooks in Codex and trust the pan-* hooks.',
   ].join('\n');
 }
 
@@ -1688,20 +1744,26 @@ function buildPluginManifest(pkg) {
 }
 
 /**
- * Build the plugin hooks/hooks.json — PAN's four hooks registered with
- * ${CLAUDE_PLUGIN_ROOT}-anchored commands (the documented plugin-relative
- * path convention for hook configs).
+ * Build the plugin hooks/hooks.json — every hook a Claude settings.json install
+ * registers (PAN_SETTINGS_HOOKS), with ${CLAUDE_PLUGIN_ROOT}-anchored commands
+ * (the documented plugin-relative path convention for hook configs). The stop
+ * guard was missing until R43 (2026-09-26), so an autonomous chain run from the
+ * plugin could drop at a phase boundary with nothing to catch it.
  * @returns {object} hooks.json object
  */
 function buildPluginHooksConfig() {
-  const hook = (script) => ({
+  const hook = (script, matcher) => ({
+    ...(matcher ? { matcher } : {}),
     hooks: [{ type: 'command', command: `node "\${CLAUDE_PLUGIN_ROOT}/hooks/${script}"` }],
   });
+  const events = HOOK_EVENT_MAP.claude;
   return {
     hooks: {
-      SessionStart: [hook('pan-check-update.js')],
-      PostToolUse: [hook('pan-context-monitor.js')],
-      SubagentStop: [hook('pan-cost-logger.js'), hook('pan-trace-logger.js')],
+      // compact shares SessionStart with the update check, narrowed by its matcher (M10).
+      [events.sessionStart]: [hook('pan-check-update.js'), hook('pan-state-reinject.js', HOOK_SLOT_MATCHERS.compact)],
+      [events.postToolUse]: [hook('pan-context-monitor.js')],
+      [events.subagentStop]: [hook('pan-cost-logger.js'), hook('pan-trace-logger.js')],
+      [events.stop]: [hook('pan-stop-guard.js')],
     },
   };
 }
@@ -2305,6 +2367,7 @@ module.exports = {
   // Copilot CLI hooks config (2026-06)
   buildCopilotHooksConfig,
   HOOK_EVENT_MAP,
+  HOOK_SLOT_MATCHERS,
   PAN_SETTINGS_HOOKS,
   stripPanHookEntries,
   mergeCodexHooksConfig,
@@ -2364,7 +2427,9 @@ function dirDigest(dir) {
   const crypto = require('crypto');
   const lines = [];
   const walk = (abs, rel) => {
-    const entries = fs.readdirSync(abs, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    // Code-unit order, not localeCompare: the digest compares builds across machines,
+    // and a locale-dependent sort could order the same tree two ways (3.28.0 review, LOW).
+    const entries = fs.readdirSync(abs, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
     for (const e of entries) {
       const childAbs = path.join(abs, e.name);
       const childRel = rel ? `${rel}/${e.name}` : e.name;
@@ -2376,3 +2441,34 @@ function dirDigest(dir) {
   return crypto.createHash('sha256').update(lines.join('\n')).digest('hex');
 }
 module.exports.dirDigest = dirDigest;
+
+/**
+ * Whether `buf` is the file a manifest hash was taken from, allowing for line
+ * endings. The manifest records sha256 over raw bytes, so a file git re-checked
+ * out with `core.autocrlf=true` — or one an editor saved with the other line
+ * ending — hashed as a user edit, and every upgrade backed it up to
+ * pan-local-patches/ as a "locally modified PAN file" with nothing to merge (the
+ * 3.30.0 upgrade sweep: 8 such files in three projects, 357 in one that commits
+ * `.claude/` to git). A file matches when its raw bytes, its all-LF form or its
+ * all-CRLF form hash to `expectedHash`, so existing manifests keep working
+ * whichever line ending they were written with. A buffer holding a NUL byte is
+ * treated as binary and compared raw only. Pure. `validateRuntimeInstall` in
+ * pan-wizard-core/bin/lib/verify-deploy.cjs carries the same rule (the installed
+ * core cannot require this file); tests/install-eol-hash.test.cjs pins both.
+ * @param {Buffer} buf
+ * @param {string|null|undefined} expectedHash - hex sha256 from the manifest
+ * @returns {boolean}
+ */
+function bytesMatchHashIgnoringEol(buf, expectedHash) {
+  if (!expectedHash) return false;
+  const crypto = require('crypto');
+  const sha = b => crypto.createHash('sha256').update(b).digest('hex');
+  if (sha(buf) === expectedHash) return true;
+  if (buf.includes(0)) return false;
+  // latin1 maps every byte to one char and back, so the round trip is lossless;
+  // no UTF-8 multi-byte sequence contains 0x0D or 0x0A.
+  const lf = buf.toString('latin1').replace(/\r\n/g, '\n');
+  if (sha(Buffer.from(lf, 'latin1')) === expectedHash) return true;
+  return sha(Buffer.from(lf.replace(/\n/g, '\r\n'), 'latin1')) === expectedHash;
+}
+module.exports.bytesMatchHashIgnoringEol = bytesMatchHashIgnoringEol;

package/bin/install.js

@@ -1218,7 +1218,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.json'];
+    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'];
     let hookCount = 0;
     for (const hook of panHooks) {
       const hookPath = path.join(hooksDir, hook);
@@ -2014,8 +2014,10 @@ function saveLocalPatches(configDir) {
 
     const fullPath = path.join(configDir, relPath);
     if (!fs.existsSync(fullPath)) continue;
-    const currentHash = fileHash(fullPath);
-    if (currentHash !== originalHash) {
+    // A line-ending-only difference is not a user edit (git autocrlf, editors).
+    let current;
+    try { current = fs.readFileSync(fullPath); } catch { continue; }
+    if (!lib.bytesMatchHashIgnoringEol(current, originalHash)) {
       const backupPath = path.join(patchesDir, safeRel);
       // Defence in depth: never write outside patchesDir, whatever the manifest says.
       const resolvedPatches = path.resolve(patchesDir);
@@ -2739,6 +2741,9 @@ function install(isGlobal, runtime = 'claude') {
   const stopGuardCommand = isGlobal
     ? buildHookCommand(targetDir, 'pan-stop-guard.js')
     : 'node ' + dirName + '/hooks/pan-stop-guard.js';
+  const stateReinjectCommand = isGlobal
+    ? buildHookCommand(targetDir, 'pan-state-reinject.js')
+    : 'node ' + dirName + '/hooks/pan-state-reinject.js';
 
   if (isCodex) {
     // Codex hooks (2026-06): Claude-compatible PascalCase events in the shared
@@ -2750,13 +2755,13 @@ 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,
+        updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand, stateReinjectCommand,
       });
       fs.writeFileSync(hooksJsonPath, JSON.stringify(merged, null, 2) + '\n');
       // Print the path we actually wrote. The hardcoded '.codex/hooks.json' was
       // wrong for --global and for --config-dir, telling users to inspect a file
       // that does not exist while the real one sat elsewhere.
-      console.log(`  ${green}✓${reset} Configured hooks (${displayPath(hooksJsonPath)}: update check, context monitor, cost + trace loggers)`);
+      console.log(`  ${green}✓${reset} Configured hooks (${displayPath(hooksJsonPath)}: update check, context monitor, cost + trace loggers, stop guard, state re-injection)`);
     } catch (e) {
       pushInstallWarning('codexHooks', 'hooks.json', e);
     }
@@ -2768,12 +2773,12 @@ 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 });
+    const hooksConfig = buildCopilotHooksConfig({ updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand });
     try {
       fs.mkdirSync(path.dirname(hooksConfigPath), { recursive: true });
       fs.writeFileSync(hooksConfigPath, JSON.stringify(hooksConfig, null, 2) + '\n');
       // Same as the Codex case: a global Copilot install writes to ~/.copilot/, not .github/.
-      console.log(`  ${green}✓${reset} Configured hooks (${displayPath(hooksConfigPath)}: update check, context monitor, cost + trace loggers)`);
+      console.log(`  ${green}✓${reset} Configured hooks (${displayPath(hooksConfigPath)}: update check, context monitor, cost + trace loggers, stop guard)`);
     } catch (e) {
       console.error(`  ${yellow}✗${reset} Failed to write Copilot hooks config: ${e.message}`);
     }
@@ -2866,6 +2871,7 @@ function install(isGlobal, runtime = 'claude') {
       { slot: 'subagentStop', hook: 'pan-cost-logger', command: costLoggerCommand, label: 'cost logger hook' },
       { slot: 'subagentStop', hook: 'pan-trace-logger', command: traceLoggerCommand, label: 'trace logger hook' },
       { slot: 'stop', hook: 'pan-stop-guard', command: stopGuardCommand, label: 'auto-advance stop guard hook' },
+      { slot: 'compact', hook: 'pan-state-reinject', command: stateReinjectCommand, label: 'state re-injection hook (after compaction)' },
     ];
     const unsupported = [];
     for (const r of registrations) {
@@ -2888,7 +2894,8 @@ function install(isGlobal, runtime = 'claude') {
         entry.hooks && entry.hooks.some(h => h.command && h.command.includes(r.hook))
       );
       if (!registered) {
-        settings.hooks[event].push({ hooks: [{ type: 'command', command: r.command }] });
+        const matcher = lib.HOOK_SLOT_MATCHERS[r.slot];
+        settings.hooks[event].push({ ...(matcher ? { matcher } : {}), hooks: [{ type: 'command', command: r.command }] });
         console.log(`  ${green}✓${reset} Configured ${r.label}`);
       }
     }
@@ -2896,7 +2903,7 @@ function install(isGlobal, runtime = 'claude') {
       delete settings.hooks;
     }
     if (isGemini && unsupported.length > 0) {
-      console.log(`  ${dim}ℹ Gemini CLI has no context-window metric for hooks and no subagent-completion event, so ${unsupported.join(', ')} ${unsupported.length === 1 ? 'is' : 'are'} not registered there${reset}`);
+      console.log(`  ${dim}ℹ Gemini CLI has no context-window metric for hooks, no subagent-completion event and no post-compaction event that adds context, so ${unsupported.join(', ')} ${unsupported.length === 1 ? 'is' : 'are'} not registered there${reset}`);
     }
   }
 

package/commands/pan/army.md

@@ -85,14 +85,14 @@ Every cap the conductor enforces applies to the campaign, scaled up:
 | `--source` | `backlog` | Work selection (delegates to focus-auto): `backlog` = ranked roadmap/requirements items; `scan` = category code-scan. |
 | `--max-cycles` | 5 | Mission items landed before stopping. |
 | `--total-budget` | 300 | Cumulative point budget. **Advisory by default** — tracked/surfaced but not a hard stop unless `--enforce-budget` / config `budget.enforce: true`. |
-| `--enforce-budget` | off | Make `--total-budget` a hard stop again (also settable via config `budget.enforce: true`); `--daily-budget` is enforced only by `enforce_budget: true` in `schedule.json`. |
+| `--enforce-budget` | off | Make `--total-budget` a hard stop again (also settable via config `budget.enforce: true`). With `--schedule`, also arm the campaign with `pan-tools campaign schedule --enforce-budget`, so `--daily-budget` pauses the day's run once spent. |
 | `--verify-reserve` | 0.15 | Fraction of `--total-budget` (0–0.5) held back for the final Quality re-review so it can't be starved (config `budget.verify_reserve`). Advisory by default (surfaced as `into_verify_reserve`); under `--enforce-budget` it stops taking on new missions early (`budget_reserve_reached`) and the reserved points fund the closing `--clean-seal` re-verification before the last INTEGRATE. |
 | `--squads` | all | Restrict to a subset, e.g. `--squads architecture,build,quality`. |
 | `--no-build-worktrees` | off | Build in the main tree instead of branch-per-agent worktrees (small/serial projects). |
 | `--push` | off | Push approved merges to origin (still human-gated). |
 | `--clean-seal` | off | One clean build + full verification after the last item (commands from config). |
 | `--schedule` | off | Arm a self-resuming campaign at this cadence (`hourly`/`daily`/`weekly`/`Nh`/`Nd`) instead of running once — writes the schedule descriptor (ADR-0034). Pair with `--daily-budget`. |
-| `--daily-budget` | 300 | Per-day point budget for a scheduled campaign. Advisory by default (an indicator of the day's spend); it only pauses the day's run when `enforce_budget: true` is set by hand in the schedule descriptor (`schedule.json`); no flag or config key sets it. |
+| `--daily-budget` | 300 | Per-day point budget for a scheduled campaign. Advisory by default (an indicator of the day's spend); it pauses the day's run only when the schedule is armed with `--enforce-budget` (`enforce_budget: true` in `schedule.json`). |
 | `--dry-run` | off | Plan + squad delegation preview only; STOP. |
 | `--continue` / `--stop` / `--status` | — | Resume / halt / report from `.planning/orchestration/` + focus-auto state. |
 
@@ -163,10 +163,10 @@ PAN is not a daemon — it cannot wake itself while the session is closed. `--sc
 - **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.
 - **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 `enforce_budget: true` is set by hand in `schedule.json`. 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.
+- **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.
 
-Manage it: `pan-tools campaign status` (active/paused, spent today, next-due), `campaign schedule --pause` / `--resume` / `--disable`.
+Manage it: `pan-tools campaign status` (active/paused, spent today, next-due), `campaign schedule --pause` / `--resume` / `--disable`, and `--enforce-budget` / `--advisory-budget` for the daily budget.
 
 ---
 

package/commands/pan/design-phase.md

@@ -58,6 +58,14 @@ ELSE (default):
    - If it finds gaps (iteration 1) → `pan-designer` revises (address genuine gaps only), re-check.
    - If it finds gaps (iteration 2) → final revision, record remaining gaps as caveats.
    - **Max 2 revision iterations** (design → check → revise → check → final) — the same guardrail `plan-phase` uses with `pan-plan-checker`.
+   - **Record each check.** Save the checker's returned text verbatim to `{phase_dir}/{padded_phase}-design-check.md` with the Write tool. Record it and branch on the verdict it prints (`PASS` or `GAPS`):
+     ```bash
+     node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings record --phase "{phase}" --agent pan-design-checker --file "{phase_dir}/{padded_phase}-design-check.md" --raw
+     ```
+     A re-check is the next attempt and closes the gaps it no longer reports. When the final iteration still has gaps, record them as the caveats they are before writing the design:
+     ```bash
+     node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings dispose --phase "{phase}" --agent pan-design-checker --open --as deferred --reason "design caveat after 2 revision iterations"
+     ```
 5. **Write** `{phase}-design.md` to the phase directory and commit via `pan-tools commit`.
 6. **Present** results + next step (`/pan:plan-phase` — which will consume this design.md).
 </process>

package/commands/pan/exec-phase.md

@@ -61,7 +61,7 @@ Phase: $ARGUMENTS
 - `--skip-tests` — Skip automatic test generation after execution completes.
 - `--skip-review` — Skip automatic code review after execution completes.
 - `--fast` — Skip both test generation and code review (implies `--skip-tests --skip-review`).
-- `--deep-review` (v3.4+) — After the normal reviewer step, also run `/pan:review-deep <phase>` (security audit via pan-hardener + cross-check via pan-meta-reviewer). Produces `.planning/reviews/<N>/deep-review.md`. Recommended for phases touching auth, payment, PII, migrations, or public APIs. Costs roughly 3× a normal review.
+- `--deep-review` — After the normal code review, run the deep review inline: the `/pan:review-deep` process, a security audit by pan-hardener plus a cross-check by pan-meta-reviewer, merged into `.planning/reviews/<N>/deep-review.md`. It builds on the normal review, so it is skipped with `--skip-review` or `--fast`. Recommended for phases touching auth, payment, PII, migrations, or public APIs. Costs roughly 3× a normal review.
 - `--hierarchical` (v3.4+, Claude Code only — needs native sub-agent spawning) — Spawn `pan-conductor` as a top-level orchestrator that decomposes the phase and spawns executor/reviewer/verifier sub-agents in sequence. `pan-conductor` runs on the reasoning tier under the default profile, which inherits the model you launched with (the `budget` profile drops it to mid). Bounded by safety harness: max 2 nesting levels, 12 spawns per phase, budget ceiling, `.planning/orchestration/abort` kill-switch. On runtimes that cannot spawn nested agents, this flag is a no-op with a warning and falls back to flat exec. Use only for large phases (≥4 autonomous plans) where wall-clock reduction justifies the ~20-30% orchestration tax.
 
 Context files are resolved inside the workflow via `pan-tools init execute-phase` and per-subagent `<files_to_read>` blocks.

package/commands/pan/git.md

@@ -13,7 +13,7 @@ allowed-tools:
 ---
 
 <objective>
-Phase-aware git workflow with safety guardrails built in. Every subcommand that modifies history runs safety checks. Rollback uses PAN snapshot tags created by exec-phase.
+Phase-aware git workflow with safety guardrails built in. Every subcommand that modifies history runs safety checks. Rollback uses PAN snapshot tags (`pan-rollback-*`), which `pan-tools rollback-snapshot <phase>` creates; no workflow creates them for you.
 
 Works with any git repository — PAN installation not required.
 </objective>
@@ -185,7 +185,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git rollback --tag pan-rollback
 ```
 
 **Rollback workflow:**
-1. Lists all `pan-rollback-*` tags (created by exec-phase before wave execution)
+1. Lists all `pan-rollback-*` tags (created with `pan-tools rollback-snapshot <phase>`)
 2. Verifies working tree is clean (blocks on dirty tree unless `--dry-run`)
 3. Runs `git reset --hard <tag>`
 

package/commands/pan/learn.md

@@ -18,12 +18,14 @@ Analyze the most recent trace session and generate an optimization report.
 ```
 /pan:learn
 /pan:learn --session <session-id>
+/pan:learn --sessions 3
 /pan:learn --experiment <slug>
 /pan:learn --apply
 ```
 
 **Flags:**
 - `--session <id>` — analyze a specific session instead of the most recent
+- `--sessions <n>` — pool the last n sessions into one analysis, so recommendations rest on failures that recur across runs
 - `--experiment <slug>` *(v3.7.0+, W3)* — analyze a harvested experiment instead of the current project's traces. Reads from `<source-repo>/experiments/<slug>/.planning/optimization/` and writes the report to `<source-repo>/experiments/<slug>/learnings/report-<timestamp>.md`. Used by the self-improvement loop. Run `/pan:experiment harvest <slug>` first.
 - `--apply` — automatically apply safe optimizations after generating the report (equivalent to running `/pan:optimize apply` immediately after)
 

package/commands/pan/optimize.md

@@ -19,6 +19,8 @@ Manage the circular optimization loop: apply recommendations, view stats, list r
 ```
 /pan:optimize apply
 /pan:optimize apply --report <filename>
+/pan:optimize revert <apply_id>
+/pan:optimize revert --last
 /pan:optimize list
 /pan:optimize stats
 /pan:optimize trace init [--description "what you're building"]
@@ -42,7 +44,17 @@ Requires human review (never auto-applied):
 - Workflow step additions
 - Structural changes to commands
 
-After applying, the report lists what was applied and what still needs review.
+After applying, the report lists what was applied and what still needs review, plus the `apply_id` that undoes it. Every apply is recorded action by action in `.planning/optimization/applied.jsonl`: the path, whether the file was created or appended to, the exact text, and a hash of the file after the write. Applying the same report a second time writes nothing: each action names the apply that already wrote it.
+
+### revert
+Undo one apply exactly: delete the memory files it created and cut the text it appended (`revert --last` for the newest).
+
+Revert never destroys work someone did since:
+- It refuses a file whose content changed after the apply. The comparison ignores line endings, so a CRLF checkout still matches.
+- It refuses a file that a later apply also wrote. Revert that later apply first.
+- It says which files it refused, and why.
+
+A CRLF file comes back CRLF. Applies logged before apply records existed cannot be reverted. After a revert, the same report can be applied again.
 
 ### list
 List all optimization reports in `.planning/optimization/reports/`, most recent first.
@@ -52,7 +64,7 @@ Show cumulative optimization statistics:
 - Total trace sessions run
 - Total events traced
 - Total errors/gaps/redundancies seen
-- Total optimizations applied across all runs
+- Total optimizations applied across all runs, the apply runs, the reverted runs, and the last `apply_id`
 - Current active trace session (if any)
 
 ### trace init

package/commands/pan/review-deep.md

@@ -38,7 +38,7 @@ Consolidates Spec B v1's X-4 (self-review) + X-12 (harden) into a single command
 /pan:review-deep 07
 ```
 
-Run after `/pan:exec-phase 07` completes. Requires `pan-reviewer` to have already written its review to `.planning/phases/07/review.md` (exec-phase does this automatically).
+Run after `/pan:exec-phase 07` completes. It reads the review that exec-phase's code-review step saved in the phase directory (`.planning/phases/07-<slug>/07-review.md`). The reviewer is read-only, so it is exec-phase that writes the review there.
 
 ### Integrated with exec-phase
 
@@ -46,7 +46,7 @@ Run after `/pan:exec-phase 07` completes. Requires `pan-reviewer` to have alread
 /pan:exec-phase 07 --deep-review
 ```
 
-Runs the normal exec → reviewer pipeline, then auto-invokes this command. Recommended for phases touching auth, payment, PII, migrations, or public APIs.
+Runs the normal exec → reviewer pipeline, then runs this command's process inline, before the verifier. Recommended for phases touching auth, payment, PII, migrations, or public APIs.
 
 ### Integrated with focus-exec
 
@@ -60,7 +60,7 @@ Per-item deep review during focus campaigns. Useful for high-stakes batches.
 
 <process>
 
-1. **Load reviewer output** — read `.planning/phases/<N>/review.md` written by the earlier `pan-reviewer` step. If missing, warn and offer to run `pan-reviewer` first.
+1. **Load reviewer output.** Resolve the phase with `pan-tools find-phase <N>`, then read `{directory}/{phase_number}-review.md`, which exec-phase's code-review step wrote. If it is missing, warn and offer to run `pan-reviewer` first. Its findings come from the report's closing `pan-verdict` block.
 
 2. **Spawn pan-hardener** (parallel-safe with step 3 isolation below, but recommended sequential for audit clarity):
    - Prompt includes: `<files_to_read>` with phase plan + diff + reviewer output; `<output_path>` = `.planning/reviews/<N>/hardener.md`; `<framework_scope>` block reminding of OWASP/STRIDE coverage.
@@ -73,7 +73,7 @@ Per-item deep review during focus campaigns. Useful for high-stakes batches.
 4. **Merge** — call:
    ```
    pan-tools review-deep merge <N> \
-     --reviewer-file .planning/phases/<N>/review.md \
+     --reviewer-file {directory}/{phase_number}-review.md \
      --hardener-file .planning/reviews/<N>/hardener.md \
      --meta-file .planning/reviews/<N>/meta.md
    ```
@@ -99,7 +99,7 @@ Verdict is driven by the highest-severity finding across all three sources. Meta
 
 <output_files>
 
-- `.planning/phases/<N>/review.md` — pan-reviewer output (written earlier by exec-phase)
+- `{phase_dir}/{phase_number}-review.md` — pan-reviewer output (written by exec-phase's code-review step)
 - `.planning/reviews/<N>/hardener.md` — pan-hardener output (new)
 - `.planning/reviews/<N>/meta.md` — pan-meta-reviewer output (new)
 - `.planning/reviews/<N>/deep-review.md` — merged consolidated report (final deliverable)