role-os 2.6.0 → 2.7.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 2.7.0
+
+### Added
+
+#### Token Budget Analyst — production budget consult (opt-in, default-off)
+
+- **`src/specialist/budget-consult.mjs`** — wires the budgeter specialist into dispatch assembly. `consultBudgetForManifest(manifest)` / `buildDispatchManifestWithBudget(options)` consult the Token Budget Analyst per dispatch step (via the proven `dispatchSpecialist` path), attaching an advisory `budgetForecast` + `budgetReceipt` to each step.
+- **Opt-in** via `ROLEOS_BUDGET_CONSULT` (default **off** — production dispatch is byte-identical until the flip, which is a release decision). **Fail-open** to the deterministic baseline `max(ctx*1.5, 50000)` (not Claude); the consult swallows any error into a receipt so it can never break manifest assembly. **Advisory** — it never blocks or gates a dispatch. Compensator: `roleos specialist rollback <role> <version>`.
+- Also lands the **Token Budget Analyst dataset tooling** under `tools/token-budget-dataset/` (the v0.1 harvester + puzzle curriculum + review/freeze pipeline that produced the budgeter's training corpus). Not part of the published CLI package (`files` ships `bin`/`src`/`starter-pack`).
+
+### Tests
+- 9 new tests (`specialist-budget-consult`: off=no-op, specialist forecast, fail-open on backend-down + no-registry, never-throws). **1334 total, all green.**
+
 ## 2.6.0
 
 ### Changed

package/bin/roleos.mjs

@@ -16,6 +16,7 @@ import { auditCommand } from "../src/audit-cmd.mjs";
 import { swarmCommand } from "../src/swarm-cmd.mjs";
 import { startCommand } from "../src/entry-cmd.mjs";
 import { verifyCitationsCommand } from "../src/verify-citations-cmd.mjs";
+import { specialistCommand } from "../src/specialist-cmd.mjs";
 import {
   runCommand, resumeCommand, nextCommand, explainCommand,
   completeCommand, failCommand, retryCommand, rerouteCommand,
@@ -75,6 +76,12 @@ Usage:
   roleos swarm approve                Approve the current feature gate
   roleos swarm verify                 Verify manifest and run state
   roleos verify-citations <dispatch>  Verify a research dispatch's citations via prism (gate)
+  roleos specialist list              List all specialists in the registry (active version + cert)
+  roleos specialist status [--role]   Show registry + halt + quota state per role
+  roleos specialist register <r> <f>  Register a new version for a role
+  roleos specialist promote <r> <v>   Promote a certified version to active (refused on L0)
+  roleos specialist rollback <r> <v>  NAMED COMPENSATOR — pointer-swap to a prior certified version
+  roleos specialist clear-halt <r>    Clear a shadow-probe halt on a role
   roleos mission list                List all missions
   roleos mission show <key>          Show full mission detail
   roleos mission suggest <text>      Suggest a mission for a task
@@ -206,6 +213,9 @@ try {
     case "verify-citations":
       await verifyCitationsCommand(args);
       break;
+    case "specialist":
+      await specialistCommand(args);
+      break;
     case "mission":
       await missionCommand(args);
       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "role-os",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "Role OS — a multi-Claude operating system where 61 specialized roles execute work through contracts, conflict detection, escalation, and structured evidence. 10 team packs, 9 missions including dogfood swarm (multi-pass convergence), deep audit with manifest-scaled dynamic dispatch, and brainstorm with traceable disagreement.",
   "homepage": "https://mcp-tool-shop-org.github.io/role-os/",
   "bugs": {

package/src/specialist/budget-consult.mjs

@@ -0,0 +1,120 @@
+/**
+ * Budget consult — the production seam that consults the Token Budget Analyst specialist for each step
+ * of a dispatch manifest, attaching an ADVISORY budget forecast + receipt.
+ *
+ * This is the B-DEFAULT wiring: it puts the proven dispatchSpecialist pattern (wire_test.mjs) on the
+ * production dispatch-assembly path. Three properties make it safe to land before the default-on flip:
+ *
+ *   - OPT-IN, default OFF (ROLEOS_BUDGET_CONSULT). With the flag off, buildDispatchManifestWithBudget
+ *     returns EXACTLY what buildDispatchManifest returns — the production dispatch is byte-identical
+ *     until the flip (a Mike-gated release decision).
+ *   - FAIL-OPEN to the DETERMINISTIC baseline max(ctx*1.5, 50000) — NOT Claude (the budgeter's
+ *     contracted fallback). dispatchSpecialist is itself fail-open in three places (gate, specialist
+ *     call, consumer reject); on top of that, this consult swallows any error into an error-receipt so
+ *     a budget consult can NEVER break manifest assembly.
+ *   - ADVISORY. The forecast/receipt is attached to each step for the audit trail; it never blocks or
+ *     gates the dispatch. The budgeter forecasts spend; it does not stop work.
+ *
+ * Reject conditions (lockdown doctrine): the flag turns it off; fail-open means it can't halt a
+ * dispatch; the shadow-probe halt + `roleos specialist rollback <role> <version>` revert a bad adapter.
+ */
+
+import { buildDispatchManifest } from "../dispatch.mjs";
+import { dispatchSpecialist } from "./dispatch.mjs";
+
+export const BUDGET_ROLE = "Token Budget Analyst";
+const CHARS_PER_TOKEN = 3.5;
+const OUTPUT_TOKENS_PER_TURN = 300;
+
+/** The budgeter's contracted DETERMINISTIC fail-open baseline (not Claude): max(ctx*1.5, 50000). */
+export function deterministicBudget(input) {
+  return {
+    spend_weighted: Math.max(Math.round((input?.context_tokens || 0) * 1.5), 50000),
+    source: "deterministic-baseline",
+  };
+}
+
+/** Shadow-probe agreement: the specialist forecast is within 25% of the deterministic baseline. */
+export function budgetAgree(specialistVerdict, baselineVerdict) {
+  const s = specialistVerdict?.spend_weighted ?? specialistVerdict?.verdict?.spend_weighted ?? 0;
+  const b = baselineVerdict?.spend_weighted ?? 0;
+  return Math.abs(s - b) <= 0.25 * (b || 1);
+}
+
+/** Derive the {context_tokens, steps, output_estimate} the budgeter expects from a manifest step. */
+export function budgetInputForStep(step, totalSteps) {
+  const ctxChars = typeof step?.systemPrompt === "string" ? step.systemPrompt.length : 0;
+  return {
+    context_tokens: Math.round(ctxChars / CHARS_PER_TOKEN),
+    steps: totalSteps,
+    output_estimate: Math.round((step?.maxTurns || 1) * OUTPUT_TOKENS_PER_TURN),
+  };
+}
+
+/** Read the wiring flag. Default OFF — flipping it on is a Mike-gated release decision. */
+export function budgetConsultEnabled() {
+  const v = process.env.ROLEOS_BUDGET_CONSULT;
+  return v === "1" || v === "true";
+}
+
+/**
+ * Consult the Token Budget Analyst for every step of a built manifest, mutating each step with
+ * `budgetForecast` (the spend estimate) + `budgetReceipt` (the roleos-specialist-receipt/v1 audit
+ * record). No-op when not enabled. NEVER throws.
+ *
+ * @param {object} manifest  a DispatchManifest from buildDispatchManifest
+ * @param {object} [opts]
+ * @param {boolean} [opts.enabled]   default: budgetConsultEnabled()
+ * @param {object}  [opts.paths]     { registry, state, events } for dispatchSpecialist
+ * @param {string}  [opts.nowIso]
+ * @param {Function}[opts.httpFn]    injectable HTTP for the specialist call (tests)
+ * @param {object}  [opts.classifier]
+ * @param {object}  [opts.shadow]
+ * @returns {Promise<object>} the same manifest, enriched
+ */
+export async function consultBudgetForManifest(manifest, opts = {}) {
+  const { enabled = budgetConsultEnabled(), paths, nowIso, httpFn, classifier, shadow } = opts;
+  if (!enabled || !manifest?.steps?.length) return manifest;
+
+  for (const step of manifest.steps) {
+    try {
+      const { result, receipt } = await dispatchSpecialist({
+        role: BUDGET_ROLE,
+        input: budgetInputForStep(step, manifest.steps.length),
+        claudeFn: async (i) => deterministicBudget(i),
+        agreeFn: budgetAgree,
+        traceId: `${manifest.runId || "run"}-${step.packetId ?? step.stepIndex}-budget`,
+        nowIso: nowIso || new Date().toISOString(),
+        ...(paths ? { paths } : {}),
+        ...(httpFn ? { httpFn } : {}),
+        ...(classifier ? { classifier } : {}),
+        ...(shadow ? { shadow } : {}),
+      });
+      step.budgetForecast = result;
+      step.budgetReceipt = receipt;
+    } catch (err) {
+      // A budget consult must never break manifest assembly — record the error and move on.
+      step.budgetReceipt = {
+        schema: "roleos-specialist-receipt/v1",
+        role: BUDGET_ROLE,
+        source: "consult-error",
+        error: String(err && err.message ? err.message : err),
+      };
+    }
+  }
+  return manifest;
+}
+
+/**
+ * Budget-aware dispatch assembly. Build the manifest, then (when the consult is enabled) attach a
+ * per-step budget forecast. This is the single production entry point to call in place of
+ * buildDispatchManifest once the consult is turned on; with the flag OFF (default) it returns exactly
+ * what buildDispatchManifest returns.
+ *
+ * @param {object} options       buildDispatchManifest options
+ * @param {object} [consultOpts] consultBudgetForManifest options
+ */
+export async function buildDispatchManifestWithBudget(options, consultOpts = {}) {
+  const manifest = buildDispatchManifest(options);
+  return consultBudgetForManifest(manifest, consultOpts);
+}

package/src/specialist/client.mjs

@@ -0,0 +1,131 @@
+/**
+ * Specialist HTTP client — POST to `<backend_url>/verify` per the Specialist HTTP contract in
+ * `starter-pack/policy/specialist-tier.md`.
+ *
+ * Hides one secret family (Parnas): the vLLM HTTP wire format and the fail-open mapping from
+ * (timeout | non-200 | malformed JSON | adapter_id mismatch) to a result the dispatcher can
+ * use to fail open without leaking transport details upward.
+ *
+ * The `httpFn` is injectable so tests do not need a live server. Production default uses the
+ * global `fetch` (Node 18+, required by package.json engines).
+ */
+
+/**
+ * @typedef {object} SpecialistCallResult
+ * @property {boolean} ok
+ * @property {object}  [verdict]      role-specific opaque verdict from the backend
+ * @property {number}  [score]        backend self-reported score in [0, 1] (INFORMATIONAL only)
+ * @property {string}  [adapter_id]   echo of the adapter pin
+ * @property {string}  [base_model]   echo of the base model
+ * @property {number}  [duration_ms]  backend-reported duration
+ * @property {string}  [error]        on !ok — fail-open reason
+ * @property {string}  [detail]       on !ok — human-readable detail
+ * @property {number}  [status]       HTTP status (when relevant)
+ */
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/**
+ * Default httpFn: a thin wrapper over global fetch that returns the same shape as the
+ * injectable contract — { ok, status, json|null, error|null }.
+ */
+async function defaultHttpFn(url, { method, headers, body, timeoutMs }) {
+  // AbortController is available on Node 18+ (engines: >=18.0.0).
+  const ac = new AbortController();
+  const t = setTimeout(() => ac.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { method, headers, body, signal: ac.signal });
+    let json = null;
+    let parseError = null;
+    try { json = await res.json(); }
+    catch (err) { parseError = err.message; }
+    return { ok: res.ok, status: res.status, json, error: parseError };
+  } catch (err) {
+    if (err.name === "AbortError") return { ok: false, status: 0, json: null, error: "timeout" };
+    return { ok: false, status: 0, json: null, error: err.message };
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+/**
+ * Call the specialist backend. Always returns a result object; never throws on transport
+ * failure. A failed call returns `{ ok: false, error, detail }` and the dispatcher fails open
+ * to Claude — that's the contract.
+ *
+ * @param {object} params
+ * @param {string} params.backendUrl
+ * @param {string} params.adapterId
+ * @param {string} params.role
+ * @param {*}      params.input
+ * @param {string} params.traceId
+ * @param {number} [params.timeoutMs=10000]
+ * @param {Function} [params.httpFn]  injectable for tests: (url, opts) => Promise<{ok,status,json,error}>
+ * @returns {Promise<SpecialistCallResult>}
+ */
+export async function callSpecialist({
+  backendUrl,
+  adapterId,
+  role,
+  input,
+  traceId,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  httpFn = defaultHttpFn,
+}) {
+  if (typeof backendUrl !== "string" || !backendUrl) {
+    return { ok: false, error: "no_backend_url", detail: "backendUrl is required" };
+  }
+  if (typeof adapterId !== "string" || !adapterId) {
+    return { ok: false, error: "no_adapter_id", detail: "adapterId is required" };
+  }
+  const url = `${backendUrl.replace(/\/+$/, "")}/verify`;
+  const body = JSON.stringify({ adapter_id: adapterId, role, input, trace_id: traceId });
+  const t0 = Date.now();
+  const res = await httpFn(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body,
+    timeoutMs,
+  });
+  const wireMs = Date.now() - t0;
+
+  if (!res.ok) {
+    // Prefer http_<status> when the backend gave us a status (e.g. 500 with no body —
+    // the parse error is incidental, the HTTP status is what matters). Fall back to the
+    // transport error string only when there's no status to report (status === 0 = no
+    // response, e.g. timeout / ECONNREFUSED).
+    const error = res.status > 0 ? `http_${res.status}` : (res.error || "transport_error");
+    return {
+      ok: false,
+      error,
+      detail: `specialist backend at ${url} returned status=${res.status || 0}${res.error ? ` (${res.error})` : ""}`,
+      status: res.status || 0,
+    };
+  }
+  if (!res.json || typeof res.json !== "object") {
+    return { ok: false, error: "malformed_response", detail: "backend response was not a JSON object", status: res.status };
+  }
+  const { verdict, score, adapter_id: echoedAdapterId, base_model, duration_ms } = res.json;
+  if (verdict === undefined) {
+    return { ok: false, error: "missing_verdict", detail: "backend response had no `verdict` field", status: res.status };
+  }
+  if (typeof echoedAdapterId !== "string" || echoedAdapterId !== adapterId) {
+    // Adapter-id echo mismatch: the backend served a different adapter than we pinned.
+    // This is a load-bearing safety check — the registry's `adapter_id` is the pin, and a
+    // different adapter could be a different specialist entirely. Fail open.
+    return {
+      ok: false,
+      error: "adapter_id_mismatch",
+      detail: `pinned adapter_id="${adapterId}", backend echoed "${echoedAdapterId}"`,
+      status: res.status,
+    };
+  }
+  return {
+    ok: true,
+    verdict,
+    score: typeof score === "number" ? score : undefined,
+    adapter_id: echoedAdapterId,
+    base_model: typeof base_model === "string" ? base_model : undefined,
+    duration_ms: typeof duration_ms === "number" ? duration_ms : wireMs,
+  };
+}

package/src/specialist/dispatch.mjs

@@ -0,0 +1,237 @@
+/**
+ * Specialist dispatch — the consumer-facing entry point. Wires registry → gate → (specialist
+ * | Claude) → shadow probe → halt check, and returns a receipt the caller can attach to its
+ * own audit trail.
+ *
+ * The consumer supplies the Claude path (`claudeFn`) and the domain-aware agreement
+ * comparator (`agreeFn`). This keeps the tier consumer-agnostic — `verify-citations` will
+ * supply prism-aware functions; the future Token Budget Analyst will supply budget-aware
+ * ones; an external consumer can supply anything.
+ *
+ * The dispatch is fail-open in three places:
+ *   1. The gate fails open (registry/gate-level rejects → Claude).
+ *   2. The specialist call fails open (transport/parse/adapter-mismatch errors → Claude).
+ *   3. A consumer-side reject of the specialist's verdict (its own guards, e.g. prism's
+ *      submodularity check) is reported back through `consumerReject` and the caller can
+ *      retry against Claude. The dispatcher itself doesn't see consumer guards — it just
+ *      surfaces the specialist's verdict and lets the caller apply them.
+ *
+ * Shadow probes happen on the Kth specialist dispatch (the gate routed to a specialist).
+ * They never fire when the gate routed to Claude — there is nothing to compare. After a
+ * probe, the halt check runs and may flip the role into a halted state.
+ */
+
+import { loadRegistry } from "./registry.mjs";
+import { gate, defaultClassifier } from "./gate.mjs";
+import { callSpecialist } from "./client.mjs";
+import {
+  loadState,
+  saveState,
+  emptyState,
+  quotaStateFor,
+  recordDispatch,
+  incrementProbeCounter,
+  resetProbeCounter,
+  getHalt,
+  setHalt,
+} from "./state.mjs";
+import {
+  shouldShadowProbe,
+  recordProbe,
+  checkHalt,
+  contrastiveHaltMessage,
+  appendHaltEvent,
+  SHADOW_DEFAULTS,
+} from "./shadow.mjs";
+
+const DEFAULT_REGISTRY_PATH = ".role-os/specialists.json";
+const DEFAULT_STATE_PATH = ".role-os/specialist-state.json";
+const DEFAULT_EVENTS_PATH = ".role-os/specialist-events.jsonl";
+const DEFAULT_WINDOW = 200;
+
+/**
+ * @typedef {object} DispatchReceipt
+ * @property {string} schema
+ * @property {string} role
+ * @property {string} ts                       ISO-8601
+ * @property {string} trace_id
+ * @property {"specialist"|"claude"} route     gate's decision
+ * @property {"specialist"|"claude"} source    where `result` actually came from
+ * @property {object} decision                 from gate.mjs
+ * @property {object} [specialist_call]
+ * @property {object} [shadow]
+ */
+
+/**
+ * Run a dispatch through the specialist tier.
+ *
+ * @param {object} params
+ * @param {string} params.role
+ * @param {*}      params.input
+ * @param {(input:any) => Promise<*>} params.claudeFn  the role's Claude-backed path
+ * @param {(specialistVerdict:any, claudeVerdict:any) => boolean} [params.agreeFn]
+ *        domain comparator for shadow probes; defaults to strict deep-equal
+ * @param {string} params.traceId
+ * @param {string} params.nowIso              ISO-8601; injected for testability
+ * @param {object} [params.paths]             { registry, state, events } file paths
+ * @param {object} [params.classifier]        gate classifier (scoreFn + oodFn)
+ * @param {Function} [params.httpFn]          injectable HTTP for the specialist call
+ * @param {object} [params.shadow]            { K, N, tau } overrides
+ * @param {number} [params.windowSize]        quota window size; default 200
+ * @param {number} [params.timeoutMs]         specialist call timeout
+ * @returns {Promise<{ result: *, receipt: DispatchReceipt }>}
+ */
+export async function dispatchSpecialist({
+  role,
+  input,
+  claudeFn,
+  agreeFn = strictEqualVerdicts,
+  traceId,
+  nowIso,
+  paths = {},
+  classifier = defaultClassifier,
+  httpFn,
+  shadow: shadowCfg = {},
+  windowSize = DEFAULT_WINDOW,
+  timeoutMs,
+}) {
+  if (typeof claudeFn !== "function") {
+    throw new Error("dispatchSpecialist: claudeFn (the Claude-backed path) is required");
+  }
+  if (typeof traceId !== "string" || !traceId) {
+    throw new Error("dispatchSpecialist: traceId is required");
+  }
+  if (typeof nowIso !== "string" || !nowIso) {
+    throw new Error("dispatchSpecialist: nowIso is required");
+  }
+
+  const registryPath = paths.registry || process.env.ROLEOS_SPECIALISTS_PATH || DEFAULT_REGISTRY_PATH;
+  const statePath = paths.state || process.env.ROLEOS_SPECIALIST_STATE_PATH || DEFAULT_STATE_PATH;
+  const eventsPath = paths.events || process.env.ROLEOS_SPECIALIST_EVENTS_PATH || DEFAULT_EVENTS_PATH;
+
+  const K = shadowCfg.K ?? SHADOW_DEFAULTS.K;
+  const N = shadowCfg.N ?? SHADOW_DEFAULTS.N;
+  const tau = shadowCfg.tau ?? SHADOW_DEFAULTS.TAU;
+
+  // ── Load registry + state ────────────────────────────────────────────────────────────────
+  const { byRole, errors: regErrors } = loadRegistry(registryPath);
+  let state;
+  try { state = loadState(statePath); }
+  catch { state = emptyState(); } // a corrupt state file resets; we re-record on the next dispatch
+  const entry = byRole.get(role) || null;
+  const haltState = entry ? getHalt(state, role) : { halted: false };
+
+  // ── Gate decision ────────────────────────────────────────────────────────────────────────
+  const quotaState = quotaStateFor(state, role, windowSize);
+  const decision = entry
+    ? gate({ role, input, registryEntry: entry, quotaState, haltState, classifier })
+    : { route: "claude", reason: "no_registry_entry", score: 0, ood: false, quotaOk: true, detail: regErrors.length ? `registry errors: ${regErrors.join("; ")}` : "no registry entry for role" };
+
+  // ── Route to specialist or Claude ────────────────────────────────────────────────────────
+  let specialistCall = null;
+  let result;
+  let source;
+  if (decision.route === "specialist" && entry) {
+    const active = entry.versions.find((v) => v.id === entry.active_version);
+    specialistCall = await callSpecialist({
+      backendUrl: entry.backend_url,
+      adapterId: active.adapter_id,
+      role,
+      input,
+      traceId,
+      ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+      ...(httpFn ? { httpFn } : {}),
+    });
+    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.
+      result = await claudeFn(input);
+      source = "claude";
+    }
+  } else {
+    result = await claudeFn(input);
+    source = "claude";
+  }
+
+  // ── 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.
+  let shadow = null;
+  if (source === "specialist") {
+    const c = incrementProbeCounter(state, role);
+    if (shouldShadowProbe(c, K)) {
+      const claudeVerdict = await claudeFn(input);
+      const agreed = !!safeAgree(agreeFn, result, claudeVerdict);
+      recordProbe(eventsPath, {
+        role,
+        ts: nowIso,
+        trace_id: traceId,
+        agreed,
+        specialist_summary: summarize(result),
+        claude_summary: summarize(claudeVerdict),
+      });
+      resetProbeCounter(state, role);
+      const { probes, rate, 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 });
+      }
+    } else {
+      shadow = { fired: false, counter: c };
+    }
+  }
+
+  // ── Persist state ────────────────────────────────────────────────────────────────────────
+  try { saveState(statePath, state); } catch { /* best-effort */ }
+
+  // ── Receipt ──────────────────────────────────────────────────────────────────────────────
+  const receipt = {
+    schema: "roleos-specialist-receipt/v1",
+    role,
+    ts: nowIso,
+    trace_id: traceId,
+    route: decision.route,
+    source,
+    decision,
+    ...(specialistCall ? { specialist_call: stripVerdictFromCall(specialistCall) } : {}),
+    ...(shadow ? { shadow } : {}),
+  };
+
+  return { result, receipt };
+}
+
+/** Default verdict comparator — strict deep-equal on JSON-stringifiable verdicts. */
+function strictEqualVerdicts(a, b) {
+  try { return JSON.stringify(a) === JSON.stringify(b); }
+  catch { return false; }
+}
+
+function safeAgree(fn, a, b) {
+  try { return fn(a, b); }
+  catch { return false; }
+}
+
+function parseIsoMs(iso) {
+  const t = Date.parse(iso);
+  return Number.isFinite(t) ? t : 0;
+}
+
+/** Operator-facing one-liner for the shadow-probe log. */
+function summarize(v) {
+  if (v === null || v === undefined) return "(none)";
+  if (typeof v === "string") return v.slice(0, 80);
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  try { return JSON.stringify(v).slice(0, 120); } catch { return "(unserializable)"; }
+}
+
+/** Don't repeat the verdict in `specialist_call`; it's already in `result`/receipt source. */
+function stripVerdictFromCall(call) {
+  const { verdict, ...rest } = call;
+  return rest;
+}

package/src/specialist/events.mjs

@@ -0,0 +1,56 @@
+/**
+ * Specialist event log — append-only JSONL of operator actions (promote, rollback, halt,
+ * clear-halt) and shadow-probe outcomes. Default path:
+ * `<repo>/.role-os/specialist-events.jsonl`. Override with `ROLEOS_SPECIALIST_EVENTS_PATH`.
+ *
+ * Hides one secret family: the history representation. Operators read the log; the rest of
+ * the tier sees `appendEvent` / `readEvents` and does not parse JSONL.
+ */
+
+import { appendFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+/**
+ * @typedef {object} SpecialistEvent
+ * @property {string} kind         one of: promote | rollback | halt | clear-halt | shadow-probe
+ * @property {string} role
+ * @property {string} ts           ISO-8601
+ * @property {object} [data]       kind-specific payload
+ */
+
+/** Append a single event to the log. Creates the parent directory if needed. */
+export function appendEvent(path, event) {
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, JSON.stringify(event) + "\n", "utf8");
+}
+
+/**
+ * Read events from the log, optionally filtered. Returns events in file order (oldest
+ * first). Lines that don't parse as JSON are skipped silently — the log is operator-edited
+ * in a pinch.
+ *
+ * @param {string} path
+ * @param {object} [filter]
+ * @param {string} [filter.role]
+ * @param {string|string[]} [filter.kind]
+ * @returns {SpecialistEvent[]}
+ */
+export function readEvents(path, filter = {}) {
+  if (!existsSync(path)) return [];
+  const text = readFileSync(path, "utf8");
+  const kindSet = filter.kind
+    ? new Set(Array.isArray(filter.kind) ? filter.kind : [filter.kind])
+    : null;
+  const out = [];
+  for (const line of text.split(/\r?\n/)) {
+    const s = line.trim();
+    if (!s) continue;
+    let ev;
+    try { ev = JSON.parse(s); } catch { continue; }
+    if (!ev || typeof ev !== "object") continue;
+    if (filter.role && ev.role !== filter.role) continue;
+    if (kindSet && !kindSet.has(ev.kind)) continue;
+    out.push(ev);
+  }
+  return out;
+}