pan-wizard 3.21.1 → 3.24.0

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

@@ -121,7 +121,7 @@ function initTraceSession(cwd, opts = {}) {
 
     return { session_id: sessionId, started_at: meta.started_at, directory: sessionDir, reused: false };
   } catch (e) {
-    return { error: e.message };
+    return { error: e.message || 'trace_init_failed' };
   }
 }
 
@@ -278,7 +278,7 @@ function endTraceSession(cwd, sessionId) {
       ended_at: meta.ended_at,
     };
   } catch (e) {
-    return { error: e.message };
+    return { error: e.message || 'trace_read_failed' };
   }
 }
 
@@ -303,7 +303,7 @@ function reconcileTraceSession(cwd, sessionId) {
     fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2) + '\n');
     return { session_id: sid, reconciled: true, event_count: counts.event_count, malformed_count: counts.malformed_count };
   } catch (e) {
-    return { error: e.message };
+    return { error: e.message || 'trace_write_failed' };
   }
 }
 
@@ -349,7 +349,7 @@ function readTraceSession(cwd, sessionId) {
 
     return { session_id: sessionId, metadata, events, event_count: events.length, malformed_count: malformed };
   } catch (e) {
-    return { error: e.message };
+    return { error: e.message || 'trace_end_failed' };
   }
 }
 
@@ -380,7 +380,7 @@ function listTraceSessions(cwd) {
 
     return { sessions, count: sessions.length };
   } catch (e) {
-    return { error: e.message };
+    return { error: e.message || 'trace_reconcile_failed' };
   }
 }
 
@@ -585,7 +585,7 @@ function listOptimizationReports(cwd) {
 
     return { reports, count: reports.length };
   } catch (e) {
-    return { error: e.message };
+    return { error: e.message || 'report_write_failed' };
   }
 }
 
@@ -626,8 +626,19 @@ function applyReportRecommendations(cwd, reportPath) {
   const applied = [];
   const skipped = [];
 
+  const resolvedCwd = path.resolve(cwd);
   for (const action of actions) {
     try {
+      // Containment: action.path on memory writes is report/agent-authored and
+      // must stay inside the project. A `../` (or absolute) path otherwise
+      // escapes and writes anywhere the process can (M23, ADR audit 2026-08).
+      if (action.type === 'memory' || action.type === 'memory_append') {
+        const abs = path.resolve(cwd, action.path || '');
+        if (abs !== resolvedCwd && !abs.startsWith(resolvedCwd + path.sep)) {
+          skipped.push({ action, reason: 'path escapes project root — skipped' });
+          continue;
+        }
+      }
       if (action.type === 'memory') {
         // Write new memory entry (skip if file exists to avoid overwriting manual edits)
         const memPath = path.join(cwd, action.path);
@@ -751,7 +762,7 @@ function getOptimizeStats(cwd) {
       current_session: getCurrentSessionId(cwd),
     };
   } catch (e) {
-    return { error: e.message };
+    return { error: e.message || 'apply_failed' };
   }
 }
 

package/pan-wizard-core/bin/lib/phase-remove.cjs

@@ -20,7 +20,7 @@ function removePhaseFromDisk(phaseDir) {
   try {
     fs.rmSync(phaseDir, { recursive: true, force: true });
   } catch (e) {
-    return { removed: false, error: e.message };
+    return { removed: false, error: e.message || 'remove_failed' };
   }
   return { removed: true };
 }
@@ -214,7 +214,12 @@ function updateRoadmapAfterRemoval(cwd, phaseNum, isDecimal, normalized) {
 
     // Reasonable upper bound for phase numbers
     const maxPhase = 99;
-    for (let oldNum = maxPhase; oldNum > removedInt; oldNum--) {
+    // Floor the loop independently of removedInt. cmdPhaseRemove rejects a phase
+    // below 1 before we get here, but this function is also reachable directly,
+    // and an unbounded lower end is how `phase remove -1234567890` turned into
+    // ~1.2 billion regex passes. The loop can now never exceed maxPhase steps.
+    const stopAt = Math.max(removedInt, 0);
+    for (let oldNum = maxPhase; oldNum > stopAt; oldNum--) {
       const newNum = oldNum - 1;
       const oldStr = String(oldNum);
       const newStr = String(newNum);
@@ -269,6 +274,23 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
     error('phase number required for phase remove');
   }
 
+  // Validate the identifier BEFORE touching the roadmap or any directory.
+  // normalizePhaseName does not validate — it returns its input unchanged when
+  // PHASE_NUM_RE does not match — so a bad argument used to reach the renumber
+  // logic and do real damage, in both cases reporting success and exiting 0:
+  //   `phase remove 0`      renumbered EVERY roadmap heading down to "Phase 0"
+  //                         (the descending renumber loop runs 99..1 and re-hits
+  //                         its own output, collapsing 3->2->1->0) and renamed
+  //                         every phase directory one lower.
+  //   `phase remove -1e9`   spun that same loop ~1.2 billion times, each pass
+  //                         running several regex replaces over the roadmap —
+  //                         hours of CPU, no output, no way to tell it was stuck.
+  // Phases are numbered from 1, so anything below that is a typo, never a target.
+  const phaseIdent = String(targetPhase).trim();
+  if (!/^\d+[A-Za-z]?(?:\.\d+)*$/.test(phaseIdent) || parseInt(phaseIdent, 10) < 1) {
+    error(`invalid phase number: ${targetPhase} (expected a phase numbered from 1, e.g. 3, 3A or 3.1)`);
+  }
+
   const roadmapPath = path.join(planningPath(cwd), ROADMAP_FILE);
   const phasesDir = phasesPath(cwd);
   const force = options.force || false;
@@ -291,6 +313,23 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
     // Phases directory does not exist; targetDir remains null
   }
 
+  // Refuse a phase that exists nowhere. A phase CAN legitimately have a roadmap
+  // entry and no directory yet (planned, not scaffolded), so only refuse when it
+  // is in neither place. Previously this reported {removed: <n>} with exit 0 for
+  // a phase that was never there, and claimed roadmap.md and state.md had been
+  // rewritten — an orchestrator reads that as "it is gone" and moves on.
+  if (!targetDir) {
+    let roadmapText = '';
+    try {
+      roadmapText = fs.readFileSync(roadmapPath, 'utf8');
+    } catch { /* unreadable roadmap is reported below as not-found */ }
+    const displayNum = escapeRegex(String(parseInt(phaseIdent, 10)) + (phaseIdent.includes('.') ? '.' + phaseIdent.split('.').slice(1).join('.') : ''));
+    const inRoadmap = new RegExp(`^#{2,4}\\s*Phase\\s+0*${displayNum}(\\D|$)`, 'im').test(roadmapText);
+    if (!inRoadmap) {
+      error(`Phase ${targetPhase} not found — no phase directory and no roadmap entry`);
+    }
+  }
+
   // Check for executed work (summary.md files)
   if (targetDir && !force) {
     const targetPath = path.join(phasesDir, targetDir);

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

@@ -41,11 +41,19 @@ function cmdPhasesList(cwd, options, raw) {
     // Get all phase directories
     let dirs = entries.filter(entry => entry.isDirectory()).map(entry => entry.name);
 
-    // Include archived phases if requested
+    // Include archived phases if requested. Archived entries are DECORATED
+    // display strings ("<name> [<milestone>]") that do not exist under
+    // phasesDir — their real location is getArchivedPhaseDirs()'s fullPath
+    // (under .planning/milestones/). M24: track that real path so a later
+    // --type read opens the archive dir instead of crashing with ENOENT on the
+    // decorated name joined to phasesDir.
+    const archivedPaths = new Map();
     if (includeArchived) {
       const archived = getArchivedPhaseDirs(cwd);
       for (const arch of archived) {
-        dirs.push(`${arch.name} [${arch.milestone}]`);
+        const decorated = `${arch.name} [${arch.milestone}]`;
+        dirs.push(decorated);
+        archivedPaths.set(decorated, arch.fullPath);
       }
     }
 
@@ -67,7 +75,7 @@ function cmdPhasesList(cwd, options, raw) {
     if (type) {
       const files = [];
       for (const dir of dirs) {
-        const dirPath = path.join(phasesDir, dir);
+        const dirPath = archivedPaths.get(dir) || path.join(phasesDir, dir);
         const dirFiles = fs.readdirSync(dirPath);
 
         let filtered;
@@ -347,6 +355,32 @@ function buildPlanIndex(phaseDir, planFiles, summaryFiles) {
   return { plans, waves, incomplete, hasCheckpoints };
 }
 
+/**
+ * Add a `- [ ] **Phase N: name**` entry to the roadmap's checklist, after the last
+ * existing entry.
+ *
+ * Returns the content unchanged when the roadmap has no checklist at all — some
+ * roadmaps only carry detail sections, and inventing a list there would be a bigger
+ * surprise than omitting one entry. Format matches templates/roadmap.md exactly, so
+ * the entry is picked up by the same parsers that read the template's own output.
+ *
+ * @param {string} content - Full roadmap.md content
+ * @param {string|number} phaseNum - Phase number as it should appear
+ * @param {string} name - Phase name/description
+ * @returns {string} Updated content
+ */
+function appendPhaseChecklistEntry(content, phaseNum, name) {
+  const lines = content.split('\n');
+  const isChecklistLine = (l) => /^\s*- \[[ x]\]\s*(?:\*\*)?Phase\s+\d/i.test(l);
+  let lastIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (isChecklistLine(lines[i])) lastIdx = i;
+  }
+  if (lastIdx === -1) return content; // no checklist to extend
+  lines.splice(lastIdx + 1, 0, `- [ ] **Phase ${phaseNum}: ${name}**`);
+  return lines.join('\n');
+}
+
 /**
  * Append a new phase to the end of the roadmap and create its directory.
  * @param {string} cwd - Working directory path
@@ -402,6 +436,13 @@ function cmdPhaseAdd(cwd, description, raw) {
     updatedContent = content + phaseEntry;
   }
 
+  // Also add the checklist entry. Only the detail section was written before, so a
+  // phase created by `phase add` was permanently absent from the roadmap's "## Phases"
+  // list — the surface users read, and the one preview/progress consumers parse. Worse,
+  // `phase complete` then reported roadmap_updated:true having changed nothing, because
+  // it ticks a checklist line that was never there.
+  updatedContent = appendPhaseChecklistEntry(updatedContent, newPhaseNum, description);
+
   try {
     fs.writeFileSync(roadmapPath, updatedContent, 'utf-8');
   } catch (e) {
@@ -501,7 +542,10 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
     insertIdx = content.length;
   }
 
-  const updatedContent = content.slice(0, insertIdx) + phaseEntry + content.slice(insertIdx);
+  // Insert the detail section, then the matching checklist entry — same reason as
+  // cmdPhaseAdd: without it the inserted phase never appears in the "## Phases" list.
+  const withEntry = content.slice(0, insertIdx) + phaseEntry + content.slice(insertIdx);
+  const updatedContent = appendPhaseChecklistEntry(withEntry, decimalPhase, description);
   try {
     fs.writeFileSync(roadmapPath, updatedContent, 'utf-8');
   } catch (e) {
@@ -542,20 +586,33 @@ function markPhaseCompleteInRoadmap(cwd, phaseNum, _phaseName, planCount, summar
   try {
     roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
   } catch {
-    return;
+    return { roadmap_warning: `${ROADMAP_FILE} unreadable — phase completion was not recorded in the roadmap` };
   }
 
+  // Match the phase number the way the roadmap spells it, not the way the
+  // caller spelled it. Callers pass "01" (the dir/state spelling) as often as
+  // "1", while the template checklist says "Phase 1:" — matching on the raw
+  // argument made the tick a silent no-op for padded calls: state advanced,
+  // checkbox stayed unticked (PanLoop finding 8). `0*` on the unpadded form
+  // accepts both spellings; decimals ("1.1") survive the strip.
+  const unpadded = String(phaseNum).replace(/^0+(?=\d)/, '');
+  const numPat = `0*${escapeRegex(unpadded)}`;
+
+  // A tick that silently misses is indistinguishable from one that landed, so
+  // detect up front whether ANY checklist entry (ticked or not) names this
+  // phase — if none does, say so instead of best-effort-ing past it.
+  const hasChecklistEntry = new RegExp(`-\\s*\\[[ xX]\\]\\s*.*Phase\\s+${numPat}[:\\s]`, 'i').test(roadmapContent);
+
   // Checkbox: - [ ] Phase N: -> - [x] Phase N: (...completed DATE)
   const checkboxPattern = new RegExp(
-    `(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${escapeRegex(phaseNum)}[:\\s][^\\n]*)`,
+    `(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${numPat}[:\\s][^\\n]*)`,
     'i'
   );
   roadmapContent = roadmapContent.replace(checkboxPattern, `$1x$2 (completed ${today})`);
 
   // Progress table: update Plans Complete, Status, and Date columns
-  const phaseEscaped = escapeRegex(phaseNum);
   const tablePattern = new RegExp(
-    `(\\|\\s*${phaseEscaped}\\.?\\s[^|]*\\|)\\s*[^|]*(\\|)\\s*[^|]*(\\|)\\s*[^|]*(\\|)`,
+    `(\\|\\s*${numPat}\\.?\\s[^|]*\\|)\\s*[^|]*(\\|)\\s*[^|]*(\\|)\\s*[^|]*(\\|)`,
     'i'
   );
   roadmapContent = roadmapContent.replace(
@@ -565,7 +622,7 @@ function markPhaseCompleteInRoadmap(cwd, phaseNum, _phaseName, planCount, summar
 
   // Update plan count in phase section
   const planCountPattern = new RegExp(
-    `(#{2,4}\\s*Phase\\s+${phaseEscaped}[\\s\\S]*?(?:\\*\\*Plans:\\*\\*|\\*\\*Plans\\*\\*:)\\s*)[^\\n]+`,
+    `(#{2,4}\\s*Phase\\s+${numPat}[\\s\\S]*?(?:\\*\\*Plans:\\*\\*|\\*\\*Plans\\*\\*:)\\s*)[^\\n]+`,
     'i'
   );
   roadmapContent = roadmapContent.replace(
@@ -573,14 +630,21 @@ function markPhaseCompleteInRoadmap(cwd, phaseNum, _phaseName, planCount, summar
     `$1${summaryCount}/${planCount} plans complete`
   );
 
+  let roadmapWarning = hasChecklistEntry
+    ? null
+    : `no roadmap checklist entry found for Phase ${phaseNum} — checkbox not ticked; check the "- [ ] **Phase N:" line in ${ROADMAP_FILE}`;
+
   try {
     fs.writeFileSync(roadmapPath, roadmapContent, 'utf-8');
   } catch {
-    // Roadmap write is best-effort during phase completion
+    roadmapWarning = `${ROADMAP_FILE} could not be written — phase completion was not recorded in the roadmap`;
   }
 
   const reqResult = markRequirementsCompleteForPhase(cwd, phaseNum, roadmapContent);
-  return { requirements_warning: reqResult && reqResult.error ? reqResult.error : null };
+  return {
+    requirements_warning: reqResult && reqResult.error ? reqResult.error : null,
+    roadmap_warning: roadmapWarning,
+  };
 }
 
 /**
@@ -779,6 +843,13 @@ function cmdPhaseComplete(cwd, phaseNum, raw, opts) {
   if (roadmapResult && roadmapResult.requirements_warning) {
     result.requirements_warning = roadmapResult.requirements_warning;
   }
+  if (roadmapResult && roadmapResult.roadmap_warning) {
+    // roadmap_updated previously meant "roadmap.md exists", which reads as
+    // "the tick landed" and masked a silently missed checkbox (finding 8).
+    // When the tick did not land, say so on both fields.
+    result.roadmap_warning = roadmapResult.roadmap_warning;
+    result.roadmap_updated = false;
+  }
 
   // Auto-commit .planning/ metadata unless --no-commit or not a git repo
   const noCommit = opts && opts.noCommit;

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

@@ -139,7 +139,7 @@ function buildPhasePreview(cwd, phaseNum) {
 
   return {
     phase: String(phaseNum),
-    phase_name: phaseInfo.name || (roadmapPhase && roadmapPhase.phase_name) || null,
+    phase_name: phaseInfo.phase_name || (roadmapPhase && roadmapPhase.phase_name) || null,
     directory: toPosix(phaseInfo.directory),
     status,
     plan_count: planFiles.length,
@@ -269,11 +269,30 @@ function buildPhaseDependencyGraph(cwd) {
   };
 }
 
+// Checklist entries come in two shapes. templates/roadmap.md prescribes the bold
+// one WITH a trailing description:
+//   - [ ] **Phase 1: Foundation** - Core scaffolding
+// and hand-written roadmaps often use the plain one:
+//   - [ ] Phase 1: Foundation
+//
+// A single regex handled these badly. The previous pattern
+// (`([^\n*]+?)(?:\*\*)?\s*$`) required the line to END at the closing `**`, so
+// every template-shaped line — the format PAN itself writes — failed to match and
+// `preview phases` reported a phase_count with an EMPTY phases array, contradicting
+// itself. Widening the name group to allow a trailing description then broke names
+// containing a hyphen, because the lazy match stopped at the first one.
+//
+// Matching bold-first is what resolves it: `[^*\n]+` cannot cross `*`, so it runs
+// to the closing `**` regardless of hyphens inside the name, and anything after it
+// is description we discard.
+const CHECKLIST_BOLD_RE = /^\s*- \[([ x])\]\s*\*\*Phase\s+(\d+(?:\.\d+)?)\s*[:\-—]?\s*([^*\n]+?)\s*\*\*/i;
+const CHECKLIST_PLAIN_RE = /^\s*- \[([ x])\]\s*Phase\s+(\d+(?:\.\d+)?)\s*[:\-—]?\s*([^\n]+?)\s*$/i;
+
 function extractPhaseListFromRoadmap(content) {
   const phases = [];
-  const re = /- \[([ x])\]\s*(?:\*\*)?Phase\s+(\d+(?:\.\d+)?)\s*[:\-—]?\s*([^\n*]+?)(?:\*\*)?\s*$/gim;
-  let m;
-  while ((m = re.exec(content)) !== null) {
+  for (const line of String(content).split('\n')) {
+    const m = line.match(CHECKLIST_BOLD_RE) || line.match(CHECKLIST_PLAIN_RE);
+    if (!m) continue;
     phases.push({
       num: m[2],
       name: m[3].trim(),

package/pan-wizard-core/bin/lib/review-deep.cjs

@@ -246,11 +246,19 @@ function writeDeepReview(cwd, phaseNum, payload, opts) {
 
 // ─── CLI wrappers ───────────────────────────────────────────────────────────
 
+// M25: input files must resolve against the passed cwd, not process.cwd().
+// A relative --reviewer-file/--hardener-file/--meta-file was read from the
+// process working directory, silently missing the file when --cwd differed.
+function resolveAgainstCwd(cwd, p) {
+  if (!p) return p;
+  return path.isAbsolute(p) ? p : path.join(cwd, p);
+}
+
 function cmdReviewDeepMerge(cwd, phaseNum, opts, raw) {
   if (!phaseNum) error('Usage: review-deep merge <phase> --reviewer-file X --hardener-file Y [--meta-file Z]');
-  const reviewerContent = opts.reviewerFile ? safeReadFile(opts.reviewerFile) : '';
-  const hardenerContent = opts.hardenerFile ? safeReadFile(opts.hardenerFile) : '';
-  const metaContent = opts.metaFile ? safeReadFile(opts.metaFile) : '';
+  const reviewerContent = opts.reviewerFile ? safeReadFile(resolveAgainstCwd(cwd, opts.reviewerFile)) : '';
+  const hardenerContent = opts.hardenerFile ? safeReadFile(resolveAgainstCwd(cwd, opts.hardenerFile)) : '';
+  const metaContent = opts.metaFile ? safeReadFile(resolveAgainstCwd(cwd, opts.metaFile)) : '';
   if (!reviewerContent && !hardenerContent && !metaContent) {
     output({ error: 'No input files provided or readable' }, raw);
     return;
@@ -264,9 +272,9 @@ function cmdReviewDeepMerge(cwd, phaseNum, opts, raw) {
 function cmdReviewDeepAnalyze(cwd, phaseNum, opts, raw) {
   // Returns the merged payload WITHOUT writing a file. Useful for piping.
   if (!phaseNum) error('Usage: review-deep analyze <phase> --reviewer-file X --hardener-file Y [--meta-file Z]');
-  const reviewerContent = opts.reviewerFile ? safeReadFile(opts.reviewerFile) : '';
-  const hardenerContent = opts.hardenerFile ? safeReadFile(opts.hardenerFile) : '';
-  const metaContent = opts.metaFile ? safeReadFile(opts.metaFile) : '';
+  const reviewerContent = opts.reviewerFile ? safeReadFile(resolveAgainstCwd(cwd, opts.reviewerFile)) : '';
+  const hardenerContent = opts.hardenerFile ? safeReadFile(resolveAgainstCwd(cwd, opts.hardenerFile)) : '';
+  const metaContent = opts.metaFile ? safeReadFile(resolveAgainstCwd(cwd, opts.metaFile)) : '';
   output(mergeReviews(reviewerContent, hardenerContent, metaContent), raw);
 }
 

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

@@ -336,6 +336,8 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
   const summaryCount = phaseInfo.summaries.length;
 
   if (planCount === 0) {
+    // No error key, exit 0: a phase with no plans has nothing to sync. The roadmap
+    // already says what it should say.
     output({ updated: false, reason: 'No plans found', plan_count: 0, summary_count: 0 }, raw, 'no plans');
     return;
   }
@@ -348,7 +350,8 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
   try {
     roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
   } catch {
-    output({ updated: false, reason: 'roadmap.md not found', plan_count: planCount, summary_count: summaryCount }, raw, 'no roadmap');
+    // error key => exit 1: there are plans to record and nowhere to record them.
+    output({ updated: false, reason: 'roadmap.md not found', error: 'roadmap_not_found', plan_count: planCount, summary_count: summaryCount }, raw, 'no roadmap');
     return;
   }
   const phaseEscaped = escapeRegex(phaseNum);
@@ -400,7 +403,8 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
   try {
     fs.writeFileSync(roadmapPath, roadmapContent, 'utf-8');
   } catch (err) {
-    output({ updated: false, reason: 'Failed to write roadmap.md: ' + err.message }, raw, 'write error');
+    // error key => exit 1: the write failed, so progress was computed and then lost.
+    output({ updated: false, reason: 'Failed to write roadmap.md: ' + err.message, error: err.message || 'roadmap_write_failed' }, raw, 'write error');
     return;
   }
 

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

@@ -13,7 +13,8 @@
  * Exports:
  *   - runExperiment(slug, opts)           — spawn + observe + return result
  *   - tailExperimentState(slug, opts)     — read run-state.json snapshot
- *   - stopExperiment(slug, opts)          — graceful halt of a running experiment
+ *   - stopExperiment(slug, opts)          — reconcile the run-state of an experiment
+ *                                           (see its doc for the spawnSync limitation)
  *   - RUNTIME_RUNNERS                     — adapter map (per-runtime headless invocation)
  */
 
@@ -170,7 +171,7 @@ function appendEvent(state, type, details) {
  * @param {string} [opts.root] - experiment root (default PAN_EXPERIMENTS_ROOT_DEFAULT)
  * @param {string} [opts.prompt] - prompt passed to the external runtime; default
  *   is `/pan:new-project --auto @.planning/idea.md`
- * @param {number} [opts.timeoutMs] - hard timeout (default 30 min)
+ * @param {number} [opts.timeoutMs] - hard timeout (default 60 min)
  * @param {object} [opts.runtimeOverride] - { bin, buildArgs } to bypass the manifest's
  *   runtime adapter (used by tests)
  * @param {function} [opts.onProgress] - callback invoked per line of stdout/stderr
@@ -415,13 +416,22 @@ function tailExperimentState(slug, opts = {}) {
 // ── stopExperiment ──────────────────────────────────────────────────────────
 
 /**
- * Stop a running experiment.
+ * Reconcile the run-state of an experiment.
  *
- * If the experiment is currently running (run-state.json shows status=running
- * and pid is alive), send SIGTERM. If still alive after a short grace period,
- * SIGKILL.
+ * IMPORTANT (M26): this CANNOT terminate a live, in-flight run. runExperiment()
+ * uses a synchronous spawnSync (see its comments — a real-time/async runner is
+ * deferred to W3), which blocks until the child exits and only learns the child
+ * pid FROM the return value. So while a run is in flight run-state.json still has
+ * pid=null, and by the time a pid is recorded the process has already exited.
+ * There is therefore no live child for this function to signal.
  *
- * If the experiment has already finished, return its current state (no error).
+ * Behavior:
+ *   - status != 'running'  → return the current state (already finished; no error).
+ *   - status == 'running' but no pid recorded → return an error explaining that
+ *     the synchronous runner does not expose a live pid to signal.
+ *   - status == 'running' with a (stale) pid → best-effort SIGTERM and mark the
+ *     run failed/manual. Note the pid is almost certainly already dead under the
+ *     spawnSync model; live termination lands with the W3 async runner.
  */
 function stopExperiment(slug, opts = {}) {
   const root = opts.root || PAN_EXPERIMENTS_ROOT_DEFAULT;

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

@@ -1,10 +1,31 @@
 /**
  * Squads — agent groupings for the bot-army model (ADR-0032).
  *
- * A squad is a named, tool-scoped, model-tiered grouping of existing PAN
- * agents under the pan-conductor coordinator. This module is a registry +
- * resolver only — it modifies no agent and changes no execution path. The
- * army campaign command (ADR-0033) consumes it; until then it is inert.
+ * A squad is a named grouping of existing PAN agents under the pan-conductor
+ * coordinator, labelled with an intended model tier and an intended access
+ * contract. This module is a registry + resolver only — it modifies no agent
+ * and changes no execution path. `/pan:army` (ADR-0033) and `hud.cjs` read it;
+ * `grep -rn "squads.cjs')" pan-wizard-core/` enumerates its consumers.
+ *
+ * BOTH LABELS BELOW ARE ADVISORY METADATA, NOT ENFORCEMENT. Read this before
+ * writing any doc sentence about them, because the live docs now quote this
+ * header as the authority for exactly that (`grep -rn 'changes no execution
+ * path' docs commands` finds them):
+ *
+ *  - `access` is the intended least-privilege contract the conductor's prompt is
+ *    told to honour when it delegates. Nothing here strips a tool from an agent
+ *    or narrows a grant at spawn time. The binding grant is each agent's own
+ *    `tools:` frontmatter (`grep '^tools:' agents/*.md`), and it can be wider
+ *    than the label: several members of a `read-only` squad hold `Write` so they
+ *    can emit planning or verification artifacts, and the coordinator itself
+ *    holds `Write` and `Bash`. So a squad agent doing more than its label says
+ *    is the expected case, not a bug in this file.
+ *  - `tier` is a squad grouping attribute, not the resolver of anybody's model.
+ *    The active `model_profile` plus any per-agent `model:` pin decides that.
+ *
+ * The one rail the grants do enforce is delegation depth: only an agent granted
+ * `Task` can spawn another (`grep -l '^tools:.*Task' agents/*.md`), so squad
+ * members cannot fan out further.
  */
 
 'use strict';
@@ -14,13 +35,21 @@ const { output, error } = require('./core.cjs');
 /**
  * Coordinator + worker/utility agents that are NOT squad members.
  * - coordinator: the top of the hierarchy (Tier 0).
- * - workers: cheap narrow-job agents (Tier 2) + standalone utility agents
+ * - workers: narrow-job agents (Tier 2) + standalone utility agents
  *   invoked directly by commands, not delegated through a squad.
+ *
+ * "Tier 2" is a hierarchy position, not a model tier. Post-COST-RESET (2026-07)
+ * every agent in MODEL_PROFILES resolves to `reasoning` under both quality and
+ * balanced (the default); `budget` is the only profile that down-tiers, and it is
+ * the profile — never this list — that decides what an agent drops to. Note it
+ * down-tiers per agent, not per group: `budget` sends some of the workers below
+ * to `fast` and others to `mid`. MODEL_PROFILES in core.cjs is the table; read it
+ * rather than assuming one tier covers a row of a doc.
  */
 const COORDINATOR = 'pan-conductor';
 const WORKERS = Object.freeze([
-  'pan-document_code',     // Haiku-tier codebase mapper
-  'pan-distiller',         // Haiku-tier code-bloat optimizer
+  'pan-document_code',     // codebase mapper
+  'pan-distiller',         // code-bloat optimizer
   'pan-optimizer',         // optimization loop
   'pan-experiment-runner', // self-improvement loop
   'pan-knowledge',         // retrieval/Q&A
@@ -29,9 +58,12 @@ const WORKERS = Object.freeze([
 ]);
 
 /**
- * The four squads, keyed by lifecycle role. `tier` is a PAN model tier
- * (resolve-model maps it to a provider model); `access` is the least-privilege
- * tool contract the conductor grants when delegating to the squad.
+ * The squads, keyed by lifecycle role — `squad list` enumerates them at runtime.
+ * `tier` is a PAN model tier label (resolve-model maps a tier to a provider
+ * model); `access` is the intended
+ * least-privilege contract the conductor is instructed to honour when delegating
+ * to the squad. Neither is applied by this module — see the advisory note in the
+ * file header before describing either one as a restriction.
  */
 const SQUADS = Object.freeze({
   architecture: Object.freeze({
@@ -40,7 +72,7 @@ const SQUADS = Object.freeze({
     access: 'read-only',
     summary: 'Designs the system before code — contract-first.',
     agents: Object.freeze([
-      'pan-roadmapper', 'pan-planner', 'pan-plan-checker',
+      'pan-roadmapper', 'pan-planner', 'pan-designer', 'pan-plan-checker', 'pan-design-checker',
       'pan-project-researcher', 'pan-phase-researcher', 'pan-research-synthesizer',
     ]),
   }),