role-os 2.8.0 → 2.9.1

package/src/route.mjs

@@ -1,11 +1,11 @@
 import { existsSync } from "node:fs";
-import { resolve, dirname } from "node:path";
+import { resolve, dirname, join } from "node:path";
 import { readFileSafe } from "./fs-utils.mjs";
 import { detectConflicts } from "./conflicts.mjs";
 import { resolveConflict, resolveSplit, formatEscalation } from "./escalation.mjs";
 import { suggestPack, getPack, checkPackMismatch, getPackRoles } from "./packs.mjs";
 
-// ── Full 31-Role Catalog ─────────────────────────────────────────────────────
+// ── Full Role Catalog ────────────────────────────────────────────────────────
 // Every role in the OS is scoreable. Keywords from routing-rules.md + contracts.
 // Triggers are strong multi-word signals worth bonus points.
 
@@ -502,7 +502,7 @@ function scoreRole(role, content, packetType, deliverableType) {
 // ── Type detection ────────────────────────────────────────────────────────────
 
 function detectType(content) {
-  const typeMatch = content.match(/## Packet Type\n(\w+)/);
+  const typeMatch = content.match(/## Packet Type\r?\n(\w+)/);
   if (typeMatch && ["feature", "integration", "identity"].includes(typeMatch[1])) {
     return typeMatch[1];
   }
@@ -521,7 +521,7 @@ function detectType(content) {
 // ── Deliverable type extraction ───────────────────────────────────────────────
 
 function extractDeliverableType(content) {
-  const match = content.match(/## Deliverable Type\n(\w+)/);
+  const match = content.match(/## Deliverable Type\r?\n(\w+)/);
   if (match && DELIVERABLE_TYPES.includes(match[1])) return match[1];
   return null;
 }
@@ -553,17 +553,34 @@ function assessConfidence(scoredRoles) {
 
 // ── File reference extraction ─────────────────────────────────────────────────
 
-function extractFileRefs(content, packetDir) {
+/**
+ * Find the base directory file refs should resolve against: the nearest
+ * ancestor of the packet that contains .claude/ (the repo root), falling
+ * back to the current working directory for packets outside any repo.
+ */
+function repoBaseFor(packetFile) {
+  let dir = dirname(packetFile);
+  for (let i = 0; i < 20; i++) {
+    if (existsSync(join(dir, ".claude"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return process.cwd();
+}
+
+function extractFileRefs(content, packetFile) {
   const refs = [];
-  const inputsMatch = content.match(/## Inputs\n([\s\S]*?)(?=\n## |\n---)/);
+  const inputsMatch = content.match(/## Inputs\r?\n([\s\S]*?)(?=\r?\n## |\r?\n---)/);
   if (!inputsMatch) return refs;
 
+  const base = repoBaseFor(packetFile);
   const inputsSection = inputsMatch[1];
   const pathPattern = /(?:^|\s|`)((?:\.\/|\.\.\/|[a-zA-Z][\w\-]*\/)[^\s`\n,)]+\.\w+)/gm;
   let match;
   while ((match = pathPattern.exec(inputsSection)) !== null) {
     const ref = match[1];
-    const resolved = resolve(dirname(packetDir), "..", "..", ref);
+    const resolved = resolve(base, ref);
     refs.push({ ref, resolved, exists: existsSync(resolved) });
   }
 
@@ -610,6 +627,22 @@ const HANDOFF_HINTS = {
 
 export async function routeCommand(args) {
   const verbose = args.includes("--verbose");
+
+  // A bare --pack would be silently swallowed as a flag and the pack name
+  // treated as the packet file — reject loudly instead of mis-routing.
+  if (args.includes("--pack")) {
+    const err = new Error("The --pack flag requires a value: use --pack=<name> (e.g. --pack=feature)");
+    err.exitCode = 1;
+    err.hint = "Run 'roleos packs list' for available pack names.";
+    throw err;
+  }
+
+  const knownFlag = a => a === "--verbose" || a === "--debug" || a.startsWith("--pack=");
+  const unknownFlags = args.filter(a => a.startsWith("--") && !knownFlag(a));
+  if (unknownFlags.length > 0) {
+    console.log(`! Ignoring unrecognized flag(s): ${unknownFlags.join(", ")}`);
+  }
+
   const packFlag = args.find(a => a.startsWith("--pack="));
   const requestedPack = packFlag ? packFlag.split("=")[1] : null;
   const packetFile = args.find(a => !a.startsWith("--"));
@@ -632,7 +665,7 @@ export async function routeCommand(args) {
   const type = detectType(content);
   const deliverableType = extractDeliverableType(content);
 
-  // Score all 32 roles
+  // Score every role in the catalog
   const allScored = ROLE_CATALOG.map(role => ({
     role,
     ...scoreRole(role, content, type, deliverableType),

package/src/run-cmd.mjs

@@ -94,7 +94,6 @@ export async function runCommand(args) {
   }
 
   // roleos run "<task>"
-  const task = args.join(" ");
   const opts = {};
 
   // Parse --mission= and --pack= flags

package/src/run.mjs

@@ -16,9 +16,11 @@ import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, rename
 import { join } from "node:path";
 import { decideEntry } from "./entry.mjs";
 import { getMission } from "./mission.mjs";
-import { TEAM_PACKS, getPack } from "./packs.mjs";
+import { TEAM_PACKS, getPack, getPackRoles } from "./packs.mjs";
 import { ROLE_CATALOG } from "./route.mjs";
 import { ROLE_ARTIFACT_CONTRACTS, validateArtifact, getHandoffContract } from "./artifacts.mjs";
+import { buildSwarmSteps, buildDynamicSteps } from "./mission-run.mjs";
+import { isValidStepTransition } from "./state-machine.mjs";
 import { retrieveForDispatch, isKnowledgeConfigured } from "./knowledge/index.mjs";
 
 // ── Run directory ────────────────────────────────────────────────────────────
@@ -87,6 +89,9 @@ let _counter = 0;
  * @param {object} [opts]
  * @param {string} [opts.forceMission] - force a specific mission key
  * @param {string} [opts.forcePack] - force a specific pack key
+ * @param {object} [opts.manifest] - dispatch manifest for dynamic missions
+ *   (swarm-manifest.json for dogfood-swarm, audit-manifest.json for deep-audit);
+ *   scales steps per domain/component instead of using the static artifactFlow
  * @returns {PersistentRun}
  */
 export async function createPersistentRun(taskDescription, cwd, opts = {}) {
@@ -106,7 +111,7 @@ export async function createPersistentRun(taskDescription, cwd, opts = {}) {
     if (!mission) throw new Error(`Mission "${opts.forceMission}" not found`);
     level = "mission";
     missionKey = opts.forceMission;
-    steps = buildMissionSteps(opts.forceMission);
+    steps = buildMissionSteps(opts.forceMission, opts.manifest);
   } else if (opts.forcePack) {
     const pack = getPack(opts.forcePack);
     if (!pack) throw new Error(`Pack "${opts.forcePack}" not found`);
@@ -172,9 +177,23 @@ export async function createPersistentRun(taskDescription, cwd, opts = {}) {
 
 // ── Step builders ────────────────────────────────────────────────────────────
 
-function buildMissionSteps(missionKey) {
+function buildMissionSteps(missionKey, manifest = null) {
   const mission = getMission(missionKey);
-  return mission.artifactFlow.map((step, i) => ({
+
+  // Dynamic dispatch — when a manifest is supplied, scale steps from it:
+  // dogfood-swarm builds per-domain steps with stage/gate metadata,
+  // deep-audit builds one auditor step per component/boundary.
+  let flow = mission.artifactFlow;
+  if (manifest && mission.dynamicDispatch) {
+    flow = missionKey === "dogfood-swarm"
+      ? buildSwarmSteps(mission, manifest)
+      : buildDynamicSteps(mission, manifest);
+  }
+
+  // Spread first so dispatch metadata (stage, domain, isGate, userApproval,
+  // parcel, consumedBy, …) carries through, then pin the run.mjs step shape.
+  return flow.map((step, i) => ({
+    ...step,
     index: i,
     role: step.role,
     produces: step.produces,
@@ -190,12 +209,26 @@ function buildMissionSteps(missionKey) {
 function buildPackSteps(packKey) {
   const pack = getPack(packKey);
   const handoff = getHandoffContract(packKey);
-  const roles = pack.chainOrder
-    ? pack.chainOrder.split(" → ")
-    : pack.roles;
+
+  // Derive steps from the pack's real roster (includes the final review gate
+  // and conditional Orchestrator) — never from chainOrder prose, which for
+  // brainstorm/deep-audit/swarm contains pseudo-role fragments.
+  const roles = getPackRoles(packKey) || pack.roles;
+
+  // Fail loudly on roles missing from the catalog — a run built around a
+  // nonexistent role breaks guidance, artifact contracts, and escalation.
+  const unknown = roles.filter(name => !ROLE_CATALOG.some(r => r.name === name));
+  if (unknown.length > 0) {
+    throw new Error(
+      `Pack "${packKey}" contains roles not in the role catalog: ${unknown.join(", ")}`
+    );
+  }
 
   return roles.map((roleName, i) => {
-    const artifact = handoff?.flow?.[i]?.produces || guessArtifact(roleName);
+    // Resolve produces by role lookup into the handoff flow — index alignment
+    // is wrong whenever the roster and flow are ordered differently.
+    const flowEntry = handoff?.flow?.find(f => f.role === roleName);
+    const artifact = flowEntry?.produces || guessArtifact(roleName);
     return {
       index: i,
       role: roleName,
@@ -279,6 +312,7 @@ function buildStepGuidance(roleName, produces, mission) {
 
 function guessArtifact(roleName) {
   const map = {
+    "Orchestrator": "decomposition-plan",
     "Product Strategist": "strategy-brief",
     "Spec Writer": "implementation-spec",
     "Backend Engineer": "change-plan",
@@ -512,6 +546,13 @@ export function escalate(run, from, to, trigger, action, cwd) {
         run.steps[i].note = `Unblocked: ${to} re-opened for escalation`;
       }
     }
+
+    // A completed run with a re-opened step is no longer complete —
+    // mirror reopenStep so formatNext doesn't report "All done."
+    if (run.status === "completed") {
+      run.status = "paused";
+      run.completedAt = null;
+    }
   } else {
     const inChain = run.steps.some(s => s.role === to);
     escalation.warning = inChain
@@ -540,13 +581,15 @@ export function escalate(run, from, to, trigger, action, cwd) {
 export function retry(run, stepIndex, cwd) {
   const step = run.steps[stepIndex];
   if (!step) throw new Error(`Invalid step index: ${stepIndex}`);
-  if (step.status !== "failed" && step.status !== "partial") {
-    throw new Error(`Step ${stepIndex} is "${step.status}", not failed/partial`);
+  // blocked is retryable so an operator block (or a mistaken one) has a recovery path
+  if (step.status !== "failed" && step.status !== "partial" && step.status !== "blocked") {
+    throw new Error(`Step ${stepIndex} is "${step.status}", not failed/partial/blocked`);
   }
 
+  const previousStatus = step.status;
   step.status = "pending";
   step.artifact = null;
-  step.note = `Retried (was ${step.status})`;
+  step.note = `Retried (was ${previousStatus})`;
   step.completedAt = null;
 
   // Unblock downstream
@@ -583,6 +626,14 @@ export function retry(run, stepIndex, cwd) {
 export function blockStep(run, stepIndex, reason, cwd) {
   const step = run.steps[stepIndex];
   if (!step) throw new Error(`Invalid step index: ${stepIndex}`);
+  // Enforce the canonical state machine — blocking a completed/failed step
+  // would strand the run with no CLI recovery path.
+  if (!isValidStepTransition(step.status, "blocked")) {
+    throw new Error(
+      `Cannot block step ${stepIndex} (${step.role}) — invalid transition "${step.status}" → "blocked". ` +
+      `Only pending or active steps can be blocked.`
+    );
+  }
 
   step.status = "blocked";
   step.note = reason;
@@ -609,8 +660,8 @@ export function blockStep(run, stepIndex, reason, cwd) {
 export function reopenStep(run, stepIndex, reason, cwd) {
   const step = run.steps[stepIndex];
   if (!step) throw new Error(`Invalid step index: ${stepIndex}`);
-  if (step.status !== "completed" && step.status !== "partial") {
-    throw new Error(`Step ${stepIndex} is "${step.status}", can only reopen completed/partial`);
+  if (step.status !== "completed" && step.status !== "partial" && step.status !== "blocked") {
+    throw new Error(`Step ${stepIndex} is "${step.status}", can only reopen completed/partial/blocked`);
   }
 
   step.status = "pending";
@@ -743,7 +794,7 @@ export function formatNext(run) {
 
   if (run.status === "failed" || run.status === "partial") {
     const failedStep = run.steps.find(s => s.status === "failed" || s.status === "partial");
-    return `Run ${run.status} at step ${failedStep?.index || "?"} (${failedStep?.role || "?"}). ` +
+    return `Run ${run.status} at step ${failedStep?.index ?? "?"} (${failedStep?.role || "?"}). ` +
            `Use \`roleos retry ${failedStep?.index}\` to retry or \`roleos escalate\` to reroute.`;
   }
 
@@ -920,7 +971,7 @@ export function loadRun(cwd, id) {
 /**
  * List all runs in the working directory.
  * @param {string} cwd
- * @returns {Array<{id: string, task: string, status: string, level: string, createdAt: string}>}
+ * @returns {Array<{id: string, task: string, status: string, level: string, missionKey: string|null, createdAt: string}>}
  */
 export function listRuns(cwd) {
   const dir = runsDir(cwd);
@@ -936,6 +987,7 @@ export function listRuns(cwd) {
           task: run.taskDescription,
           status: run.status,
           level: run.entryLevel,
+          missionKey: run.missionKey ?? null,
           createdAt: run.createdAt,
         };
       } catch { return null; }

package/src/session.mjs

@@ -15,6 +15,8 @@ import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { writeFileSafe } from "./fs-utils.mjs";
 import { scaffoldHooks, generateHooksConfig } from "./hooks.mjs";
+import { ROLE_CATALOG } from "./route.mjs";
+import { TEAM_PACKS } from "./packs.mjs";
 
 // ── roleos init claude ────────────────────────────────────────────────────────
 
@@ -302,7 +304,7 @@ Before starting non-trivial work in this repo, route the task through Role OS:
 3. Use structured handoffs between roles
 4. Review with evidence-based verdicts
 
-Role OS provides 31 specialized roles across 8 packs (engineering, design, product, research, growth, treatment, marketing, core). It detects broken chains, auto-routes recovery, and requires structured evidence in every verdict.
+Role OS provides ${ROLE_CATALOG.length} specialized roles across ${Object.keys(TEAM_PACKS).length} packs (${Object.keys(TEAM_PACKS).join(", ")}). It detects broken chains, auto-routes recovery, and requires structured evidence in every verdict.
 
 If the task is composite (feature + docs + launch), Role OS will recommend splitting into child packets with dependency ordering.
 

package/src/specialist/capability-gate.mjs

@@ -21,7 +21,9 @@
  *     not, so its asymmetry runs the other way.)
  *
  * The grant manifest (`.claude/role-os/capabilities.json`, director-authored) maps an action id to a
- * grant, e.g.: { "npm:publish": { "granted": true, "scope": "@mcptoolshop/roll", "expires": "2026-07-01" } }
+ * grant, e.g.: { "npm:publish": { "granted": true, "expires": "2026-07-01" } }. The gate enforces
+ * `granted` and `expires` ONLY — any other field (e.g. a "scope" annotation) is informational/audit
+ * metadata and does NOT narrow the grant: a granted action id authorizes ALL matching invocations.
  */
 
 import { existsSync, readFileSync } from "node:fs";
@@ -41,17 +43,21 @@ const _bash = (re) => (toolName, call) =>
 /**
  * The GATED SET — the irreversible / world-touching actions from the NAMED_COMPENSATORS standard.
  * Each entry: { id, label, test(toolName, call) -> boolean }. Detection is deterministic + pattern-
- * based and errs toward FLAGGING (a benign match just needs a one-line grant), never toward missing
- * an irreversible action.
+ * based and errs toward FLAGGING (a benign match just needs a one-line grant). The patterns allow
+ * flags between the command word and its verb — `git -C <dir> push`, `npm --workspace <pkg> publish`,
+ * `gh release -R <repo> create` all match — without crossing a shell separator (| ; & or newline).
+ * KNOWN LIMIT: script indirection (`npm run release` wrapping a publish, a shell script invoking
+ * git push) is NOT detected — the gate bounds direct invocations; it is opt-in defense-in-depth,
+ * not an evasion-proof sandbox.
  */
 export const GATED_ACTIONS = [
-  { id: "npm:publish", label: "npm/pnpm/yarn publish", test: _bash(/\b(?:npm|pnpm|yarn)\s+publish\b/) },
-  { id: "pypi:publish", label: "PyPI publish (twine/uv)", test: _bash(/\btwine\s+upload\b|\buv\s+publish\b/) },
-  { id: "gh:release", label: "gh release create", test: _bash(/\bgh\s+release\s+create\b/) },
-  { id: "gh:pr-create", label: "gh pr create", test: _bash(/\bgh\s+pr\s+create\b/) },
-  { id: "gh:repo-edit", label: "gh repo edit/delete", test: _bash(/\bgh\s+repo\s+(?:edit|delete)\b/) },
-  { id: "git:push", label: "git push", test: _bash(/\bgit\s+push\b/) },
-  { id: "pages:deploy", label: "GitHub Pages / gh-pages deploy", test: _bash(/\bgh-pages\b|\bpages\s+deploy\b/) },
+  { id: "npm:publish", label: "npm/pnpm/yarn publish", test: _bash(/\b(?:npm|pnpm|yarn)\b[^|;&\n]*\bpublish\b/) },
+  { id: "pypi:publish", label: "PyPI publish (twine/uv)", test: _bash(/\btwine\b[^|;&\n]*\bupload\b|\buv\b[^|;&\n]*\bpublish\b/) },
+  { id: "gh:release", label: "gh release create", test: _bash(/\bgh\b[^|;&\n]*\brelease\b[^|;&\n]*\bcreate\b/) },
+  { id: "gh:pr-create", label: "gh pr create", test: _bash(/\bgh\b[^|;&\n]*\bpr\b[^|;&\n]*\bcreate\b/) },
+  { id: "gh:repo-edit", label: "gh repo edit/delete", test: _bash(/\bgh\b[^|;&\n]*\brepo\b[^|;&\n]*\b(?:edit|delete)\b/) },
+  { id: "git:push", label: "git push", test: _bash(/\bgit\b[^|;&\n]*\bpush\b/) },
+  { id: "pages:deploy", label: "GitHub Pages / gh-pages deploy", test: _bash(/\bgh-pages\b|\bpages\b[^|;&\n]*\bdeploy\b/) },
 ];
 
 /** Read the director's capability manifest, or {} if absent/malformed (=> nothing granted). */
@@ -66,15 +72,24 @@ export function loadCapabilities(cwd) {
   }
 }
 
-/** Is `actionId` granted (granted:true and not expired) in the manifest? */
-function _granted(manifest, actionId, now) {
+/**
+ * Evaluate `actionId`'s grant. Returns null when granted and valid; otherwise a short problem
+ * string for the deny reason. An unparseable `expires` is treated as INVALID (deny) — a
+ * fail-closed gate must never turn a typo'd date into a permanent grant.
+ */
+function _grantProblem(manifest, actionId, now) {
   const g = manifest && manifest[actionId];
-  if (!g || typeof g !== "object" || g.granted !== true) return false;
+  if (!g || typeof g !== "object" || g.granted !== true) {
+    return `No capability "${actionId}" is granted in ${CAPABILITIES_FILE}`;
+  }
   if (typeof g.expires === "string") {
     const t = Date.parse(g.expires);
-    if (!Number.isNaN(t) && t < now) return false; // grant expired
+    if (Number.isNaN(t)) {
+      return `The grant for "${actionId}" has an unparseable "expires" value ("${g.expires}") — an invalid expiry DENIES (fail-closed), it never extends the grant; fix the date`;
+    }
+    if (t < now) return `The grant for "${actionId}" expired at ${g.expires}`;
   }
-  return true;
+  return null;
 }
 
 /**
@@ -100,14 +115,16 @@ export function capabilityGate(cwd, toolName, toolInput, opts = {}) {
     if (!action) return { denied: false }; // not an irreversible action -> allow
     const manifest = opts.capabilities || loadCapabilities(cwd);
     const now = typeof opts.now === "number" ? opts.now : Date.now();
-    if (_granted(manifest, action.id, now)) return { denied: false };
+    const problem = _grantProblem(manifest, action.id, now);
+    if (!problem) return { denied: false };
     return {
       denied: true,
       action: action.id,
       reason:
         `Capability gate: "${action.label}" is an irreversible action requiring an explicit grant. ` +
-        `No capability "${action.id}" is granted in ${CAPABILITIES_FILE}. To authorize it, the ` +
-        `director adds {"${action.id}": {"granted": true}} (optionally with "scope"/"expires").`,
+        `${problem}. To authorize it, the director adds {"${action.id}": {"granted": true}}, ` +
+        `optionally with an "expires" date. (Note: the gate enforces only "granted"/"expires" — ` +
+        `a grant authorizes ALL matching ${action.label} calls; a "scope" field is informational only.)`,
     };
   } catch {
     // A gate that errors must not silently allow an irreversible action: if a gated action matched

package/src/specialist/dispatch.mjs

@@ -145,7 +145,6 @@ export async function dispatchSpecialist({
     if (specialistCall.ok) {
       result = specialistCall.verdict;
       source = "specialist";
-      recordDispatch(state, role, windowSize, parseIsoMs(nowIso));
     } else {
       // Specialist call failed → fail open to Claude. The gate's "route" was specialist, but
       // the realized source is Claude. Both are recorded in the receipt.
@@ -157,6 +156,11 @@ export async function dispatchSpecialist({
     source = "claude";
   }
 
+  // Record EVERY dispatch (both routes) in the quota window, tagged with the REALIZED source.
+  // The window only rolls when Claude traffic is recorded too — recording only specialist
+  // successes froze the window and locked every role out permanently once the quota tripped.
+  recordDispatch(state, source, windowSize, parseIsoMs(nowIso));
+
   // ── Shadow probe ─────────────────────────────────────────────────────────────────────────
   // Probes only fire when the dispatch actually went to a specialist (source === "specialist").
   // A failed-open dispatch already ran Claude; there is nothing left to probe.
@@ -175,12 +179,13 @@ export async function dispatchSpecialist({
         claude_summary: summarize(claudeVerdict),
       });
       resetProbeCounter(state, role);
-      const { probes, rate, shouldHalt } = checkHalt(eventsPath, role, N, tau);
+      const { probes, rate, agreed: agreedCount, shouldHalt } = checkHalt(eventsPath, role, N, tau);
       shadow = { fired: true, agreed, probes, rate, halt_triggered: shouldHalt };
       if (shouldHalt && !getHalt(state, role).halted) {
         const reason = contrastiveHaltMessage({ role, probes, rate, tau });
         setHalt(state, role, { reason, since: nowIso });
-        appendHaltEvent(eventsPath, { role, ts: nowIso, reason, probes, agreed: probes - Math.round(probes * (1 - rate)), rate, tau });
+        // `agreed` is checkHalt's exact window count — never recompute it lossily from the rate.
+        appendHaltEvent(eventsPath, { role, ts: nowIso, reason, probes, agreed: agreedCount, rate, tau });
       }
     } else {
       shadow = { fired: false, counter: c };

package/src/specialist/registry.mjs

@@ -199,6 +199,12 @@ function validateVersion(v, tag) {
   if (v.exam_centroid !== undefined && !Array.isArray(v.exam_centroid)) {
     errors.push(`${tag}: exam_centroid, if present, must be an array of numbers`);
   }
+  // ood_floor feeds defaultOodFn directly (gate.mjs): a string silently falls back to the 0.4
+  // default and a value outside cosine range disables routing entirely — both must fail loudly
+  // at load time, mirroring the R5 gate_threshold check.
+  if (v.ood_floor !== undefined && (typeof v.ood_floor !== "number" || !(v.ood_floor >= -1 && v.ood_floor <= 1))) {
+    errors.push(`${tag}: R5 — ood_floor, if present, must be a number in [-1, 1] (cosine range; got ${JSON.stringify(v.ood_floor)})`);
+  }
   return errors;
 }
 

package/src/specialist/shadow.mjs

@@ -67,6 +67,13 @@ export function recordProbe(eventsPath, probe) {
  * narrow fine-tunes show step changes, so an early halt on a small sample would be a noise
  * trigger, not a real disagreement signal).
  *
+ * Only probes recorded AFTER the role's most recent clear-halt event count. A clear-halt is
+ * an operator decision that the disagreement evidence before it is adjudicated; without this
+ * boundary the stale disagreeing probes keep dominating the window and the role re-halts on
+ * the very next probe — the documented recovery command could never actually recover a role.
+ * The fresh-start window also restarts the ≥N thin-sample guard, so a cleared role gets a
+ * full new sample before it can halt again.
+ *
  * @param {string} eventsPath
  * @param {string} role
  * @param {number} [N]
@@ -74,8 +81,10 @@ export function recordProbe(eventsPath, probe) {
  * @returns {{ probes: number, agreed: number, rate: number, shouldHalt: boolean }}
  */
 export function checkHalt(eventsPath, role, N = SHADOW_DEFAULTS.N, tau = SHADOW_DEFAULTS.TAU) {
-  const events = readEvents(eventsPath, { role, kind: "shadow-probe" });
-  const window = events.slice(-N);
+  const events = readEvents(eventsPath, { role, kind: ["shadow-probe", "clear-halt"] });
+  const lastClear = events.map((e) => e.kind).lastIndexOf("clear-halt");
+  const probesSinceClear = events.slice(lastClear + 1).filter((e) => e.kind === "shadow-probe");
+  const window = probesSinceClear.slice(-N);
   const probes = window.length;
   const agreed = window.filter((e) => e.data && e.data.agreed === true).length;
   const rate = probes === 0 ? 1 : agreed / probes;
@@ -94,7 +103,8 @@ export function contrastiveHaltMessage({ role, probes, rate, tau }) {
   return (
     `specialist for role "${role}" halted: shadow-probe agreement ${pct}% over the last ` +
     `${probes} probes < required ${required}% (τ=${tau}). The specialist's verdicts have ` +
-    `drifted from Claude's on the same inputs. Clear with: roleos specialist clear-halt ${role}`
+    // Role names contain spaces ("Token Budget Analyst") — the copy-pasteable command must quote.
+    `drifted from Claude's on the same inputs. Clear with: roleos specialist clear-halt "${role}"`
   );
 }