pan-wizard 3.30.0 → 3.31.0

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

@@ -799,20 +799,32 @@ function calculateProgressBar(completed, total) {
  * Orchestrates extractFieldsFromState, scanPhaseProgress,
  * normalizePhaseStatus, and calculateProgressBar.
  */
-function buildStateFrontmatter(bodyContent, cwd) {
+function buildStateFrontmatter(bodyContent, cwd, existing = {}) {
   const fields = extractFieldsFromState(bodyContent);
+  const prior = existing && typeof existing === 'object' ? existing : {};
 
+  // The milestone comes from the roadmap resolver — unless the resolver only
+  // guessed (no milestone heading at all) and state.md already records one. A
+  // guess overwriting a recorded value is how a letter-series milestone ("R-2")
+  // was rewritten to the resolver's `v1.0` / `milestone` on every state write.
   let milestone = null;
   let milestoneName = null;
   if (cwd) {
     try {
       const info = getMilestoneInfo(cwd);
-      milestone = info.version;
-      milestoneName = info.name;
+      const guessed = info.basis === 'default' || info.basis === 'no-milestone-heading';
+      if (!(guessed && prior.milestone)) {
+        milestone = info.version;
+        milestoneName = info.name;
+      }
     } catch {
       // No milestone configured or milestone file unreadable -- skip milestone fields
     }
   }
+  if (milestone == null && prior.milestone) {
+    milestone = prior.milestone;
+    milestoneName = prior.milestone_name != null ? prior.milestone_name : null;
+  }
 
   let totalPhases = fields.totalPhasesRaw ? parseInt(fields.totalPhasesRaw, 10) : null;
   let completedPhases = null;
@@ -837,20 +849,27 @@ function buildStateFrontmatter(bodyContent, cwd) {
     if (pctMatch) progressPercent = parseInt(pctMatch[1], 10);
   }
 
-  const normalizedStatus = normalizePhaseStatus(fields.status, fields.pausedAt);
-
   const frontmatter = { pan_state_version: '1.0' };
 
   if (milestone) frontmatter.milestone = milestone;
   if (milestoneName) frontmatter.milestone_name = milestoneName;
-  if (fields.currentPhase) frontmatter.current_phase = fields.currentPhase;
-  if (fields.currentPhaseName) frontmatter.current_phase_name = fields.currentPhaseName;
-  if (fields.currentPlan) frontmatter.current_plan = fields.currentPlan;
-  frontmatter.status = normalizedStatus;
-  if (fields.stoppedAt) frontmatter.stopped_at = fields.stoppedAt;
-  if (fields.pausedAt) frontmatter.paused_at = fields.pausedAt;
+  // A field the body restates wins; one it does not keeps its recorded value.
+  // Rebuilding from the body alone dropped current_phase_name, current_plan and
+  // the rest whenever a project's state.md did not repeat them in prose.
+  const keep = (key, fromBody) => {
+    if (fromBody != null && fromBody !== '') frontmatter[key] = fromBody;
+    else if (prior[key] != null) frontmatter[key] = prior[key];
+  };
+  keep('current_phase', fields.currentPhase);
+  keep('current_phase_name', fields.currentPhaseName);
+  keep('current_plan', fields.currentPlan);
+  frontmatter.status = (fields.status || fields.pausedAt)
+    ? normalizePhaseStatus(fields.status, fields.pausedAt)
+    : (prior.status != null ? prior.status : normalizePhaseStatus(null, null));
+  keep('stopped_at', fields.stoppedAt);
+  keep('paused_at', fields.pausedAt);
   frontmatter.last_updated = new Date().toISOString();
-  if (fields.lastActivity) frontmatter.last_activity = fields.lastActivity;
+  keep('last_activity', fields.lastActivity);
 
   const progress = {};
   if (totalPhases !== null) progress.total_phases = totalPhases;
@@ -859,19 +878,48 @@ function buildStateFrontmatter(bodyContent, cwd) {
   if (completedPlans !== null) progress.completed_plans = completedPlans;
   if (progressPercent !== null) progress.percent = progressPercent;
   if (Object.keys(progress).length > 0) frontmatter.progress = progress;
-
-  return frontmatter;
+  else if (prior.progress != null) frontmatter.progress = prior.progress;
+
+  // Keys PAN does not manage (a project's own notes) survive every write, in the
+  // order the file already had them; PAN's keys fill in around them.
+  const merged = {};
+  for (const key of Object.keys(prior)) merged[key] = key in frontmatter ? frontmatter[key] : prior[key];
+  for (const key of Object.keys(frontmatter)) if (!(key in merged)) merged[key] = frontmatter[key];
+  return merged;
 }
 
+// One front-matter block at the top of state.md: BOM-tolerant, LF or CRLF. The
+// previous `^---\n…\n---\n` matched LF only, so on a CRLF checkout (git
+// core.autocrlf=true) the old block was never stripped and every state write
+// stacked a new, re-derived block on top of it.
+const STATE_FRONTMATTER_RE = /^\uFEFF?---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/;
+
 function stripFrontmatter(content) {
-  return content.replace(/^---\n[\s\S]*?\n---\n*/, '');
+  return String(content).replace(STATE_FRONTMATTER_RE, '').replace(/^\uFEFF/, '').replace(/^(?:\r?\n)+/, '');
 }
 
-function syncStateFrontmatter(content, cwd) {
-  const body = stripFrontmatter(content);
-  const frontmatter = buildStateFrontmatter(body, cwd);
+/**
+ * Re-derive state.md's front matter from its body, merged with the front matter
+ * already there. Output uses `eol` (default: whatever the content already uses).
+ * Throws (code STATE_STACKED_FRONTMATTER) when the content starts with more than
+ * one front-matter block — earlier releases stacked them on CRLF files, and
+ * choosing between them silently is exactly the guess this function must not make.
+ */
+function syncStateFrontmatter(content, cwd, eol) {
+  const text = String(content);
+  const lineEnd = eol || (/\r\n/.test(text) ? '\r\n' : '\n');
+  const m = text.match(STATE_FRONTMATTER_RE);
+  const existing = m ? extractFrontmatter(m[0]) : {};
+  const body = stripFrontmatter(text).replace(/\r\n/g, '\n');
+  if (STATE_FRONTMATTER_RE.test(body)) {
+    const err = new Error('state.md starts with more than one front-matter block (an earlier PAN release stacked them on CRLF files). Keep the block with the right values, delete the other, and run the command again — PAN will not pick one for you.');
+    err.code = 'STATE_STACKED_FRONTMATTER';
+    throw err;
+  }
+  const frontmatter = buildStateFrontmatter(body, cwd, existing);
   const yamlStr = reconstructFrontmatter(frontmatter);
-  return `---\n${yamlStr}\n---\n\n${body}`;
+  const out = `---\n${yamlStr}\n---\n\n${body}`;
+  return lineEnd === '\r\n' ? out.replace(/\n/g, '\r\n') : out;
 }
 
 /**
@@ -882,17 +930,33 @@ function syncStateFrontmatter(content, cwd) {
  * state.md.lock and lands atomically (temp + rename), so concurrent agents
  * cannot tear the file or interleave read-modify-write cycles. Lock
  * acquisition is best-effort — on timeout the write proceeds unlocked,
- * preserving single-agent behavior exactly.
+ * matching the file-lock contract.
+ *
+ * The file keeps its own line ending, and the write is verified: exactly one
+ * front-matter block goes in, and what is read back under the lock must be what
+ * was written. A write that cannot meet either stops with an error and leaves
+ * the file as it was — it never reports success over a file it did not produce.
  */
 function writeStateMd(statePath, content, cwd) {
-  const synced = syncStateFrontmatter(content, cwd);
+  let diskEol = null;
+  try { diskEol = /\r\n/.test(fs.readFileSync(statePath, 'utf-8')) ? '\r\n' : '\n'; } catch { /* new file */ }
+  let synced;
+  try {
+    synced = syncStateFrontmatter(content, cwd, diskEol);
+  } catch (err) {
+    if (err && err.code === 'STATE_STACKED_FRONTMATTER') error(err.message);
+    throw err;
+  }
+  let mismatch = false;
   try {
     withFileLock(statePath, () => {
       writeFileAtomic(statePath, synced);
+      mismatch = fs.readFileSync(statePath, 'utf-8') !== synced;
     });
   } catch (err) {
     throw new Error('Failed to write state.md: ' + err.message);
   }
+  if (mismatch) error('state.md did not read back as written — another writer changed it during the write. Re-run the command.');
 }
 
 /**
@@ -911,7 +975,7 @@ function cmdStateJson(cwd, raw) {
   const frontmatter = extractFrontmatter(content);
 
   if (!frontmatter || Object.keys(frontmatter).length === 0) {
-    const body = stripFrontmatter(content);
+    const body = stripFrontmatter(content).replace(/\r\n/g, '\n');
     const built = buildStateFrontmatter(body, cwd);
     output(built, raw, JSON.stringify(built, null, 2));
     return;

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

@@ -48,15 +48,27 @@
 function buildSubcommandIndex(sourceText) {
   const index = {};
   if (typeof sourceText !== 'string') return index;
-  const re = /Unknown ([a-z][a-z-]*) subcommand\. Available: ([^'"`\n]+)/g;
-  let m;
-  while ((m = re.exec(sourceText)) !== null) {
-    const group = m[1];
-    const subs = m[2]
-      .split(',')
-      .map((s) => s.trim().split(/\s+/)[0])   // drop " [--apply]"-style hints
-      .filter((s) => /^[a-z][a-z0-9-]*$/.test(s));
-    if (subs.length) index[group] = subs;
+  // The dispatcher words these messages three ways, and until 2026-09-26 only the
+  // first was read, so git, distill, experiment, init, state and links got no
+  // suggestion on a typo:
+  //   Unknown optimize subcommand. Available: …
+  //   Unknown state subcommand: ${subcommand}. Available: …   (also `unknown …`, and
+  //   Unknown init workflow: ${workflow}\nAvailable: …)
+  //   git subcommand required. Available: …
+  const patterns = [
+    /[Uu]nknown ([a-z][a-z-]*) (?:subcommand|workflow)[^'"`\n.]*(?:\.\s*|\\n)Available: ([^'"`\n\\]+)/g,
+    /([a-z][a-z-]*) subcommand required\. Available: ([^'"`\n\\]+)/g,
+  ];
+  for (const re of patterns) {
+    let m;
+    while ((m = re.exec(sourceText)) !== null) {
+      const group = m[1];
+      const subs = m[2]
+        .split(',')
+        .map((s) => s.trim().split(/\s+/)[0])   // drop " [--apply]"-style hints
+        .filter((s) => /^[a-z][a-z0-9-]*$/.test(s));
+      if (subs.length) index[group] = [...new Set([...(index[group] || []), ...subs])];
+    }
   }
   return index;
 }

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

@@ -28,9 +28,12 @@ function cmdTemplateSelect(cwd, planPath, raw) {
     const fullPath = path.join(cwd, planPath);
     const content = fs.readFileSync(fullPath, 'utf-8');
 
-    // Count task headings (### Task N)
-    const taskMatch = content.match(/###\s*Task\s*\d+/g) || [];
-    const taskCount = taskMatch.length;
+    // Count tasks: PAN plans write `<task type="...">` blocks (templates/phase-prompt.md,
+    // pan-planner); older plans used `### Task N` headings. Counting only the headings
+    // gave every current plan a task count of 0.
+    const xmlTasks = content.match(/<task[\s>]/g) || [];
+    const headingTasks = content.match(/###\s*Task\s*\d+/g) || [];
+    const taskCount = xmlTasks.length || headingTasks.length;
 
     // Check for decision-related keywords
     const decisionMatch = content.match(/decision/gi) || [];

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

@@ -32,6 +32,24 @@ function detectInstalledRuntimes(cwd) {
   return found;
 }
 
+/**
+ * Whether `buf` is the file a manifest hash was taken from, allowing for line
+ * endings: raw bytes, the all-LF form or the all-CRLF form may match, so a file
+ * git re-checked out with `core.autocrlf=true` is not reported as modified.
+ * Binary (NUL-bearing) buffers compare raw only. Same rule as
+ * `bytesMatchHashIgnoringEol` in bin/install-lib.cjs, which the installed core
+ * cannot require; tests/install-eol-hash.test.cjs pins both.
+ */
+function bytesMatchHashIgnoringEol(crypto, buf, expectedHash) {
+  if (!expectedHash) return false;
+  const sha = b => crypto.createHash('sha256').update(b).digest('hex');
+  if (sha(buf) === expectedHash) return true;
+  if (buf.includes(0)) return false;
+  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;
+}
+
 /**
  * Validate a single PAN runtime installation.
  * Checks: manifest files exist, hashes match, settings integrity.
@@ -61,8 +79,7 @@ function validateRuntimeInstall(cwd, configDir, runtime) {
     const absPath = path.join(baseDir, relPath);
     try {
       const content = fs.readFileSync(absPath);
-      const actualHash = crypto.createHash('sha256').update(content).digest('hex');
-      if (actualHash !== expectedHash) {
+      if (!bytesMatchHashIgnoringEol(crypto, content, expectedHash)) {
         modified.push(relPath);
       }
     } catch (_) {

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

@@ -420,7 +420,13 @@ async function main() {
     case 'resolve-model': {
       const metadataIdx = args.indexOf('--metadata');
       const metadataJson = metadataIdx !== -1 ? args[metadataIdx + 1] : undefined;
-      commands.cmdResolveModel(cwd, args[1], raw, metadataJson);
+      const attemptRaw = getArgValue(args, '--attempt');
+      let attempt;
+      if (attemptRaw !== null && attemptRaw !== undefined) {
+        if (!/^[1-9]\d*$/.test(String(attemptRaw))) error('--attempt must be a positive integer (1 for a first try)');
+        attempt = parseInt(attemptRaw, 10);
+      }
+      commands.cmdResolveModel(cwd, args[1], raw, metadataJson, attempt);
       break;
     }
 
@@ -1272,6 +1278,9 @@ async function main() {
           daily_budget: budget != null ? Number(budget) : undefined,
           enabled: args.includes('--disable') ? false : undefined,
           paused: args.includes('--pause') ? true : (args.includes('--resume') ? false : undefined),
+          // campaign.cjs has always honoured enforce_budget; no flag reached it, so
+          // making the daily budget a hard stop meant editing schedule.json by hand.
+          enforce_budget: args.includes('--enforce-budget') ? true : (args.includes('--advisory-budget') ? false : undefined),
         }, raw);
       } else if (subcommand === 'status' || !subcommand) {
         campaign.cmdCampaignStatus(cwd, raw);

package/pan-wizard-core/mcp/tool-registry.cjs

@@ -75,13 +75,23 @@ const RESOURCES = [
 const SPAWN_TOOLS = [
   {
     name: 'pan_resolve_model', title: 'Resolve model for an agent', verb: 'resolve-model',
-    description: 'Resolve the model tier/id PAN would use for an agent under the active profile.',
+    description: 'Resolve the model tier/id PAN would use for an agent under the active profile. Pass attempt > 1 for a retry after a failure: the tier climbs toward the agent\'s quality tier (routing.max_escalations caps it).',
     readOnly: true, destructive: false,
     inputSchema: {
       type: 'object', additionalProperties: false, required: ['agent'],
-      properties: { agent: { type: 'string', description: 'Agent type, e.g. pan-planner' } },
+      properties: {
+        agent: { type: 'string', description: 'Agent type, e.g. pan-planner' },
+        attempt: { type: 'integer', minimum: 1, maximum: 99, description: '1 for a first try; 2 for the first retry after a failure' },
+      },
+    },
+    args: (i) => {
+      const out = [str('agent', i && i.agent, AGENT_RE, 64)];
+      if (i && i.attempt !== undefined) {
+        if (!Number.isInteger(i.attempt) || i.attempt < 1 || i.attempt > 99) throw new Error('Invalid "attempt": must be an integer from 1 to 99');
+        out.push('--attempt', String(i.attempt));
+      }
+      return out;
     },
-    args: (i) => [str('agent', i && i.agent, AGENT_RE, 64)],
   },
   {
     name: 'pan_find_phase', title: 'Find a phase', verb: 'find-phase',
@@ -155,7 +165,7 @@ const { NATIVE_TOOLS } = require('./native-tools.cjs');
 // safety argument of ADR-0041 is that no client input reaches it.
 const PROJECT_CWD_PROPERTY = Object.freeze({
   type: 'string',
-  description: 'Absolute path of the PAN project to operate on. Optional: defaults to the directory the server was started in. Pass it when the server was launched from a plugin directory (Agent Plugins clients do this by default), or to address another project.',
+  description: 'Absolute path of the PAN project to operate on. Optional: defaults to the directory the server was started in. Pass it when the server was launched from a plugin directory (Agent Plugins clients do this by default), or to address another project. The server acts on any existing directory named here with the permissions of the user who runs it — it trusts its caller as it trusts the session that started it.',
 });
 
 const PROJECT_CWD_MAX = 1024;

package/pan-wizard-core/workflows/exec-phase.md

@@ -117,6 +117,14 @@ Parse JSON for: `phase`, `plans[]` (each with `id`, `wave`, `autonomous`, `objec
 
 **Filtering:** Skip plans where `has_summary: true`. If `--gaps-only`: also skip non-gap_closure plans. If all filtered: "No matching incomplete plans" → exit.
 
+**If `--gaps-only`:** this run is the fix round after a verification found gaps — a second attempt at work that failed once. Resolve the executor for that attempt and use it in place of `executor_model` for every spawn in this run:
+
+```bash
+EXECUTOR_MODEL=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-executor --attempt 2 --raw)
+```
+
+It equals `executor_model` unless the `budget` profile runs the executor below its quality tier; then it is one tier higher (capped by `routing.max_escalations`), so the gaps are not retried on the tier that left them.
+
 Report:
 ```
 ## Execution Plan

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

@@ -224,7 +224,7 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 | `/pan:plan-phase <N>` | Research + plan a phase with verification |
 | `/pan:exec-phase <N>` | Execute plans with wave-based parallelization |
 | `/pan:research-phase <N>` | Deep ecosystem research for specialized domains |
-| `/pan:verify-phase <N>` | Validate built features through UAT |
+| `/pan:verify-phase <N>` | Re-run goal-backward verification with a test-suite gate |
 
 ### Phase Management
 | Command | Description |
@@ -348,7 +348,7 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 
 **`/pan:exec-phase <N>`** — Execute all plans in a phase. Groups by wave, runs waves sequentially, plans within each wave in parallel.
 
-**`/pan:verify-phase <N>`** — Conversational UAT. Presents tests one at a time, diagnoses failures, creates fix plans.
+**`/pan:verify-phase <N>`** — Re-run goal-backward verification behind a test-suite gate. Writes the phase's verification report (passed, gaps_found or human_needed); fix gaps with `/pan:plan-phase <N> --gaps`.
 
 **`/pan:quick <desc>`** — Small tasks with PAN guarantees but shorter path. Skips researcher, checker, verifier. Lives in `.planning/quick/`.
 

package/pan-wizard-core/workflows/phase-tests.md

@@ -364,7 +364,7 @@ Present next steps:
 
 **Also available:**
 - `/pan:phase-tests {next_phase}` — test another phase
-- `/pan:verify-phase {phase_number}` — run UAT verification
+- `/pan:verify-phase {phase_number}` — re-run goal-backward verification
 
 ---
 ```

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

@@ -252,7 +252,7 @@ uat.md exists with gaps (diagnosed issues). User needs to plan fixes.
 
 **Also available:**
 - `/pan:exec-phase {phase}` — execute phase plans
-- `/pan:verify-phase {phase}` — run more UAT testing
+- `/pan:verify-phase {phase}` — re-run goal-backward verification
 
 ---
 ```

package/pan-wizard-core/workflows/todo-add.md

@@ -19,7 +19,7 @@ Extract from init JSON: `commit_docs`, `date`, `timestamp`, `todo_count`, `todos
 
 Ensure directories exist:
 ```bash
-mkdir -p .planning/todos/pending .planning/todos/done
+mkdir -p .planning/todos/pending .planning/todos/completed
 ```
 
 Note existing areas from the todos array for consistency in infer_area step.

package/pan-wizard-core/workflows/todo-check.md

@@ -105,7 +105,7 @@ Use AskUserQuestion:
 - header: "Action"
 - question: "This todo relates to Phase [N]: [name]. What would you like to do?"
 - options:
-  - "Work on it now" — move to done, start working
+  - "Work on it now" — mark it completed, start working
   - "Add to phase plan" — include when planning Phase [N]
   - "Brainstorm approach" — think through before deciding
   - "Put it back" — return to list
@@ -116,7 +116,7 @@ Use AskUserQuestion:
 - header: "Action"
 - question: "What would you like to do with this todo?"
 - options:
-  - "Work on it now" — move to done, start working
+  - "Work on it now" — mark it completed, start working
   - "Create a phase" — /pan:add-phase with this scope
   - "Brainstorm approach" — think through before deciding
   - "Put it back" — return to list
@@ -125,8 +125,9 @@ Use AskUserQuestion:
 <step name="execute_action">
 **Work on it now:**
 ```bash
-mv ".planning/todos/pending/[filename]" ".planning/todos/done/"
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs todo complete "[filename]"
 ```
+This moves it to `.planning/todos/completed/` with a `completed:` date — the directory `init todos` and `/pan:progress` count.
 Update state.md todo count. Present problem/solution context. Begin work or ask how to proceed.
 
 **Add to phase plan:**
@@ -150,11 +151,11 @@ Re-run `init todos` to get updated count, then update state.md "### Pending Todo
 </step>
 
 <step name="git_commit">
-If todo was moved to done/, commit the change:
+If the todo was completed, commit the change:
 
 ```bash
 git rm --cached .planning/todos/pending/[filename] 2>/dev/null || true
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: start work on todo - [title]" --files .planning/todos/done/[filename] .planning/state.md
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: start work on todo - [title]" --files .planning/todos/completed/[filename] .planning/state.md
 ```
 
 Tool respects `commit_docs` config and gitignore automatically.
@@ -172,5 +173,5 @@ Confirm: "Committed: docs: start work on todo - [title]"
 - [ ] Appropriate actions offered
 - [ ] Selected action executed
 - [ ] state.md updated if todo count changed
-- [ ] Changes committed to git (if todo moved to done/)
+- [ ] Changes committed to git (if the todo was completed)
 </success_criteria>

package/scripts/build-agent-plugin.js

@@ -150,6 +150,8 @@ function hookCommands(rootVar) {
     contextMonitorCommand: cmd('pan-context-monitor.js'),
     costLoggerCommand: cmd('pan-cost-logger.js'),
     traceLoggerCommand: cmd('pan-trace-logger.js'),
+    stopGuardCommand: cmd('pan-stop-guard.js'),
+    stateReinjectCommand: cmd('pan-state-reinject.js'),
   };
 }
 
@@ -166,6 +168,8 @@ function emitCopilotNamespace(agentsSrc, nsDir) {
     content = lib.rewriteAgentReferenceCopy(content, TOKEN_PREFIX);
     content = lib.stripThinkingFrontmatter(content, 'copilot');
     content = lib.convertClaudeToCopilotAgent(content);
+    // The agent carries the root token, so it carries what the token means.
+    if (content.includes(TOKEN_PREFIX)) content = content.replace(/\s*$/, '\n\n' + lib.agentPluginSkillAdapterNote('agent') + '\n');
     fs.writeFileSync(path.join(agentsDest, f.replace(/\.md$/, '.agent.md')), content);
     agents++;
   }

package/scripts/build-hooks.js

@@ -22,7 +22,8 @@ const HOOKS_TO_COPY = [
   'pan-statusline.js',
   'pan-cost-logger.js',
   'pan-trace-logger.js',
-  'pan-stop-guard.js'
+  'pan-stop-guard.js',
+  'pan-state-reinject.js'
 ];
 
 function build() {

package/scripts/build-plugin.js

@@ -169,6 +169,15 @@ function main() {
     );
   }
 
+  // 7. Eval suite (market-ideas M4). `claude plugin eval` reads `evals/` at the
+  // plugin root; the cases live in harness/plugin-evals/ beside the harness
+  // scenarios they come from. harness/ is not in the npm package, so a build from
+  // an installed copy has no suite to copy and the plugin ships without one.
+  const evalsSrc = path.join(ROOT, 'harness', 'plugin-evals');
+  if (fs.existsSync(evalsSrc)) {
+    fs.cpSync(evalsSrc, path.join(OUT, 'evals'), { recursive: true });
+  }
+
   // Sanity report
   const count = (p) => { try { return fs.readdirSync(p).length; } catch { return 0; } };
   console.log('PAN plugin built at', path.relative(ROOT, OUT));
@@ -176,6 +185,7 @@ function main() {
   console.log('  agents:', count(path.join(OUT, 'agents')));
   console.log('  hooks:', count(path.join(OUT, 'hooks')));
   console.log('  workflows:', workflowScripts.length);
+  console.log('  eval cases:', count(path.join(OUT, 'evals')) ? fs.readdirSync(path.join(OUT, 'evals'), { withFileTypes: true }).filter(e => e.isDirectory()).length : 0);
   console.log('  version:', pkg.version);
 }
 

package/scripts/npm-dist-tag.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * Print the npm dist-tag a version publishes under: `next` for a prerelease
+ * (`3.31.0-rc.1`), `latest` otherwise.
+ *
+ * WHY. The release workflow ran `npm publish` with no `--tag`, and npm's default
+ * tag is `latest` — so a release candidate would have become what
+ * `npm install pan-wizard` resolves to for every user (market-ideas queue M1,
+ * 2026-09-21). Publishing a candidate under `next` keeps it installable by name
+ * (`pan-wizard@next`, `pan-wizard@3.31.0-rc.1`) without moving anyone onto it.
+ *
+ * A version that is not `major.minor.patch[-prerelease]` exits 1 rather than
+ * guessing a tag: publishing junk under `latest` is the failure this prevents.
+ *
+ * Usage:
+ *   node scripts/npm-dist-tag.js            # the tag for package.json's version
+ *   node scripts/npm-dist-tag.js 3.31.0-rc.1
+ */
+
+'use strict';
+
+const path = require('path');
+const { parse } = require('./deprecate-old-versions.js');
+
+/**
+ * @param {string} version
+ * @returns {'latest'|'next'|null} null when the version does not parse
+ */
+function distTagFor(version) {
+  const v = parse(version);
+  if (!v) return null;
+  return v.pre === null ? 'latest' : 'next';
+}
+
+function main() {
+  const version = process.argv[2] || require(path.join(__dirname, '..', 'package.json')).version;
+  const tag = distTagFor(version);
+  if (!tag) {
+    process.stderr.write(`npm-dist-tag: '${version}' is not a semver version — refusing to pick a tag\n`);
+    process.exit(1);
+  }
+  process.stdout.write(tag + '\n');
+}
+
+module.exports = { distTagFor };
+
+if (require.main === module) main();

package/scripts/plugin-path.js

@@ -49,8 +49,13 @@ function fail(message) {
 function build() {
   try {
     // Relay the builder's stdout to stderr so stdout stays single-line.
+    // PAN_PLUGIN_OUT redirects the builder; this script prints PLUGIN_DIR, so a value
+    // inherited from the caller's environment would build one place and point the
+    // marketplace at another (3.28.0 review, LOW). Build where the path says.
+    const env = { ...process.env };
+    delete env.PAN_PLUGIN_OUT;
     const out = execFileSync(process.execPath, [path.join(ROOT, 'scripts', 'build-plugin.js')], {
-      cwd: ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+      cwd: ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env,
     });
     if (out) process.stderr.write(out);
   } catch (err) {

package/scripts/test-surface.cjs

@@ -68,6 +68,7 @@ const EVENT_HOOKS = Object.freeze({
   postToolUse: ['pan-context-monitor.js'],
   subagentStop: ['pan-cost-logger.js', 'pan-trace-logger.js'],
   stop: ['pan-stop-guard.js'],
+  compact: ['pan-state-reinject.js'],
 });
 
 // ─── Parsers (pure) ─────────────────────────────────────────────────────────