muse-crew 0.16.0 → 0.17.0

package/lib/crew-dispatch-worker.js

@@ -0,0 +1,1059 @@
+#!/usr/bin/env node
+// lib/crew-dispatch-worker.js — worker-layer dispatcher (Piece 1, 2026-09-26).
+//
+// Mechanical port of workflows/crew-dispatch.js off the sandboxed workflow
+// runtime and onto the worker layer. The sandboxed dispatcher ferried every
+// operation through agent() calls; this module performs the same operations
+// directly: crew-api.js via execFile (argv, never shell), filesystem reads
+// via node:fs, and the inline scripts the workflow used to ferry through the
+// agent run as plain functions.
+//
+// Decision logic (eligibility, retry caps, simultaneity, playtest rotation)
+// is copied verbatim from the workflow — the two implementations must agree
+// exactly during the Piece 1 shadow period.
+//
+// Substrate (DESIGN-v2 Piece 1):
+// - Per-call timeouts on every execFile (EXEC_TIMEOUT_MS).
+// - Error taxonomy: TRANSPORT_TIMEOUT / TRANSPORT_ERROR / TRANSPORT_PARSE /
+//   CONFIG. Transport failures are the orchestrator's fault, never the
+//   task's — they fail the tick, not the task.
+// - worker_runs ledger: the run records start/finish via the
+//   record-worker-run crew-api command (identity minted SQLite-side).
+// - Determinism: no Date.now(), Math.random(), or new Date() in decision
+//   paths — enforced by tests/determinism.test.js (G3).
+// - Claims carry executor: "worker" (the sandboxed workflow tags "sandbox").
+//
+// Usage:
+//   node lib/crew-dispatch-worker.js --crew-home <path> [--registry-text <json>]
+//       [--read-only] [--max-tasks-per-poll <n>]
+//
+//   --read-only  Shadow mode: compute claims but perform no writes — no
+//                parks, no playtest filing, no completions, no ack, no
+//                reservations, no decision logs. The worker_runs row is
+//                still recorded (observability, not task state).
+//
+// Output: one JSON object on stdout:
+//   { status, message, claims, partial, would_file_playtest, run_id }
+// Exit 0 on success (even with zero claims); exit 1 on transport/config
+// failure with { ok:false, error, code } on stdout.
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readFileSync, readdirSync, readlinkSync, appendFileSync } from "node:fs";
+import { join, basename, resolve } from "node:path";
+
+const execFileAsync = promisify(execFile);
+
+// ── Error taxonomy ──────────────────────────────────────────────────
+// TRANSPORT_*: the orchestrator's fault — fail the tick, never the task.
+// CONFIG: bad invocation — fail closed before touching anything.
+function transportError(code, message) {
+  const err = new Error(message);
+  err.code = code;
+  return err;
+}
+const EXEC_TIMEOUT_MS = 30000;
+
+// ── Args ────────────────────────────────────────────────────────────
+function printHelp() {
+  console.log(`Usage: node lib/crew-dispatch-worker.js --crew-home <path> [--registry-text <json>] [--read-only] [--max-tasks-per-poll <n>]
+
+Worker-layer dispatcher (Piece 1 of the sandbox exit). Reads the board,
+determines eligible tasks, and returns structured launch claims.
+
+  --crew-home <path>       Crew home directory (required).
+  --registry-text <json>   Workflow registry JSON text. When omitted, read
+                           from <crewHome>/workflows/registry.json.
+  --read-only              Shadow mode: compute claims, perform no writes.
+  --max-tasks-per-poll <n> Override the per-poll task cap (default 6).
+
+Output: JSON { status, message, claims, partial, would_file_playtest, run_id }.
+Exit 0 on success; exit 1 on transport/config failure.`);
+}
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") { out.help = true; }
+    else if (a === "--crew-home") { out.crewHome = argv[++i]; }
+    else if (a === "--registry-text") { out.registryText = argv[++i]; }
+    else if (a === "--read-only") { out.readOnly = true; }
+    else if (a === "--max-tasks-per-poll") { out.maxTasksPerPoll = argv[++i]; }
+    else { throw transportError("CONFIG", "unknown argument: " + a); }
+  }
+  return out;
+}
+
+// ── Logging ─────────────────────────────────────────────────────────
+// log() goes to stderr — stdout carries exactly one JSON object.
+function log(msg) {
+  process.stderr.write(String(msg) + "\n");
+}
+
+// ── crew-api via execFile (argv, never shell) ────────────────────────
+let CREW_HOME = null;
+let CREW_API = null;
+
+async function runApi(command, argsObj, opts = {}) {
+  const timeout = opts.timeout || EXEC_TIMEOUT_MS;
+  const args = ["--crew-home", CREW_HOME, command];
+  if (argsObj !== undefined) args.push("--json", JSON.stringify(argsObj));
+  let stdout;
+  try {
+    ({ stdout } = await execFileAsync("node", [CREW_API, ...args], {
+      timeout,
+      maxBuffer: 16 * 1024 * 1024,
+    }));
+  } catch (e) {
+    if (e.killed) {
+      throw transportError("TRANSPORT_TIMEOUT",
+        `crew-api ${command} timed out after ${timeout}ms`);
+    }
+    throw transportError("TRANSPORT_ERROR",
+      `crew-api ${command} failed: ${(e.message || String(e)).slice(0, 300)}`);
+  }
+  return stdout;
+}
+
+function parseApiJson(stdout, command) {
+  try {
+    return JSON.parse(stdout);
+  } catch (e) {
+    throw transportError("TRANSPORT_PARSE",
+      `crew-api ${command} returned unparseable JSON: ${e.message}`);
+  }
+}
+
+// ── Pure functions (verbatim from workflows/crew-dispatch.js) ───────
+// These MUST stay byte-identical in behavior to the workflow's copies
+// for the Piece 1 shadow comparison to hold.
+
+function effectiveVisualProtocol(project) {
+  return !!project && project.visual_protocol === true;
+}
+
+function parseRegistryText(text) {
+  if (text === undefined || text === null) {
+    return { ok: false, reason: "registryText is missing" };
+  }
+  if (typeof text !== "string") {
+    return { ok: false, reason: "registryText is not a string" };
+  }
+  try {
+    return { ok: true, registry: JSON.parse(text) };
+  } catch (e) {
+    return { ok: false, reason: "registryText is not valid JSON: " + e.message };
+  }
+}
+
+function validateRegistry(reg) {
+  var wfNames = ["standard", "bugfix", "chore", "docs", "upgrade"];
+  if (!reg || typeof reg !== "object" || Array.isArray(reg)) {
+    return { ok: false, reason: "registry is missing or not an object" };
+  }
+  for (var i = 0; i < wfNames.length; i++) {
+    var wf = reg[wfNames[i]];
+    if (!wf || typeof wf !== "object") {
+      return { ok: false, reason: "workflow '" + wfNames[i] + "' is missing or not an object" };
+    }
+    if (!Array.isArray(wf.steps)) {
+      return { ok: false, reason: "workflow '" + wfNames[i] + "' has no steps array" };
+    }
+    for (var j = 0; j < wf.steps.length; j++) {
+      if (!wf.steps[j] || typeof wf.steps[j].name !== "string") {
+        return { ok: false, reason: "workflow '" + wfNames[i] + "' step " + j + " has no name" };
+      }
+    }
+    if (typeof wf.reworkTarget !== "string") {
+      return { ok: false, reason: "workflow '" + wfNames[i] + "' has no reworkTarget string" };
+    }
+    var stepNames = {};
+    for (var j = 0; j < wf.steps.length; j++) {
+      stepNames[wf.steps[j].name] = true;
+    }
+    if (!stepNames[wf.reworkTarget]) {
+      return { ok: false, reason: "workflow '" + wfNames[i] + "' reworkTarget '" + wf.reworkTarget + "' names no step" };
+    }
+  }
+  return { ok: true };
+}
+
+function parseBoardJson(boardReturn) {
+  if (typeof boardReturn === "string") {
+    try {
+      return JSON.parse(boardReturn);
+    } catch (e) {
+      throw new Error("parseBoardJson: read-board stdout is not valid JSON: " + e.message);
+    }
+  }
+  if (boardReturn !== null && typeof boardReturn === "object") {
+    return boardReturn;
+  }
+  throw new Error(
+    "parseBoardJson: expected the read-board return to be a raw stdout string or a parsed board object, got " +
+    (boardReturn === null ? "null" : typeof boardReturn)
+  );
+}
+
+function extractJsonObject(raw) {
+  if (raw !== null && typeof raw === "object") return raw;
+  if (typeof raw !== "string") {
+    throw new Error("extractJsonObject: expected a string or object, got " +
+      (raw === null ? "null" : typeof raw));
+  }
+  try { return JSON.parse(raw.trim()); } catch (e) { /* fall through to scan */ }
+  var start = raw.indexOf("{");
+  while (start !== -1) {
+    var end = matchJsonBrace(raw, start);
+    if (end !== -1) {
+      try { return JSON.parse(raw.slice(start, end + 1)); } catch (e2) { /* keep scanning */ }
+    }
+    start = raw.indexOf("{", start + 1);
+  }
+  throw new Error("extractJsonObject: no parseable JSON object found in agent output");
+}
+
+function matchJsonBrace(s, start) {
+  var depth = 0, inStr = false, esc = false;
+  for (var i = start; i < s.length; i++) {
+    var ch = s[i];
+    if (inStr) {
+      if (esc) esc = false;
+      else if (ch === "\\") esc = true;
+      else if (ch === "\"") inStr = false;
+    } else if (ch === "\"") {
+      inStr = true;
+    } else if (ch === "{") {
+      depth++;
+    } else if (ch === "}") {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+
+function projectTaskRecord(t) {
+  if (!t || typeof t !== "object") return null;
+  var ls = (t.latest_session && typeof t.latest_session === "object") ? t.latest_session : null;
+  var retry = (t.retry && typeof t.retry === "object") ? t.retry : null;
+  var cf = retry ? retry.consecutive_failures : undefined;
+  var rsr = retry ? retry.rejections_since_reset : undefined;
+  return {
+    id: t.id,
+    title: t.title,
+    description: t.description,
+    state: t.state,
+    project: t.project,
+    workflow: t.workflow,
+    blocked: t.blocked,
+    deps: Array.isArray(t.deps) ? t.deps.slice() : [],
+    priority: t.priority,
+    next_phase: (typeof t.next_phase === "string" && t.next_phase.length > 0) ? t.next_phase : null,
+    latest_session: ls ? { id: ls.id, status: ls.status, step: ls.step, notes: ls.notes } : null,
+    retry: {
+      consecutive_failures: (typeof cf === "number" && cf >= 0) ? cf : 0,
+      rejections_since_reset: (typeof rsr === "number" && rsr >= 0) ? rsr : 0
+    }
+  };
+}
+
+function unwrapBoardResult(boardResult) {
+  var boardData = boardResult;
+  if (boardData && typeof boardData === 'object' && typeof boardData.stdout === 'string' && !Array.isArray(boardData.ready_tasks)) {
+    try {
+      var parsed = JSON.parse(boardData.stdout);
+      if (parsed && typeof parsed === 'object') {
+        boardData = parsed;
+      }
+    } catch (e) { /* fall through */ }
+  }
+  if (boardData && typeof boardData === 'object' && !Array.isArray(boardData.ready_tasks)) {
+    if (boardData.data && typeof boardData.data === 'object' && Array.isArray(boardData.data.ready_tasks)) {
+      boardData = boardData.data;
+    } else if (boardData.result && typeof boardData.result === 'object') {
+      var inner = boardData.result;
+      if (inner.data && typeof inner.data === 'object' && Array.isArray(inner.data.ready_tasks)) {
+        boardData = inner.data;
+      } else if (Array.isArray(inner.ready_tasks)) {
+        boardData = inner;
+      }
+    }
+  }
+  if (boardData && typeof boardData === 'object' && typeof boardData.result === 'string' && !Array.isArray(boardData.ready_tasks)) {
+    var parsedResult = null, resultParsed = false;
+    try {
+      parsedResult = JSON.parse(boardData.result);
+      resultParsed = true;
+    } catch (e) { /* fall through */ }
+    if (resultParsed) {
+      if (Array.isArray(parsedResult)) {
+        boardData.ready_tasks = parsedResult;
+      } else if (parsedResult && typeof parsedResult === 'object') {
+        return unwrapBoardResult(parsedResult);
+      }
+    }
+  }
+  if (boardData && typeof boardData === 'object' && typeof boardData.ready_tasks === 'string') {
+    try {
+      var parsedReadyTasks = JSON.parse(boardData.ready_tasks);
+      if (Array.isArray(parsedReadyTasks)) {
+        boardData.ready_tasks = parsedReadyTasks;
+      } else if (parsedReadyTasks && typeof parsedReadyTasks === 'object') {
+        return unwrapBoardResult(parsedReadyTasks);
+      }
+    } catch (e) { /* fall through */ }
+  }
+  if (!boardData || typeof boardData !== 'object' || !Array.isArray(boardData.ready_tasks)) {
+    throw new Error(
+      "unwrapBoardResult: unknown board envelope — expected ready_tasks at top level, " +
+      "in .data, in .result (object or JSON string), in .result.data, or as a JSON string of a ready_tasks array " +
+      "or of a whole board object. Got keys: " +
+      (boardData && typeof boardData === 'object' ? Object.keys(boardData).join(",") : typeof boardData)
+    );
+  }
+  return boardData;
+}
+
+const PLAYTEST_PREFIX = "Idle playtest: ";
+
+function isPlaytestTask(t) {
+  return !!t && typeof t.title === "string" && t.title.indexOf(PLAYTEST_PREFIX) === 0;
+}
+
+function parseJourneys(md) {
+  var journeys = [];
+  if (!md || !String(md).trim()) return journeys;
+  var lines = String(md).split("\n");
+  var cur = null;
+  for (var i = 0; i < lines.length; i++) {
+    var m = lines[i].match(/^##\s+(.+?)\s*$/);
+    if (m) {
+      if (cur) { cur.body = cur.body.trim(); journeys.push(cur); }
+      cur = { name: m[1], body: "" };
+    } else if (cur) {
+      cur.body += lines[i] + "\n";
+    }
+  }
+  if (cur) { cur.body = cur.body.trim(); journeys.push(cur); }
+  return journeys.filter(function (j) { return j.name.length > 0; });
+}
+
+function configInt(cfg, key, fallback) {
+  var n = parseInt(cfg[key], 10);
+  return isNaN(n) ? fallback : n;
+}
+
+function decideRetry(consecutiveFailures, maxFailures) {
+  if (!(maxFailures > 0)) return "retry";
+  if (typeof consecutiveFailures !== "number" || consecutiveFailures < 0) return "retry";
+  return consecutiveFailures >= maxFailures ? "park" : "retry";
+}
+
+function buildPlaytestDescription(journey, personaName, personaFile, maxFilings, crewHome) {
+  var filingRule = maxFilings === 0
+    ? "File no follow-up tasks on this run (max_filings is 0). Note anything you find in your summary instead."
+    : "File follow-up tasks for real issues you find: at most " + maxFilings + " on this run (max_filings). If you find more, note the extras in your summary.";
+  var body = journey.body.length > 3000 ? journey.body.slice(0, 3000) + "\n[truncated]" : journey.body;
+  return (
+    "IDLE PLAYTEST — this task carries no code change. You are Hazel, code-blind QA.\n" +
+    "\n" +
+    "Assignment: journey \"" + journey.name + "\" as the \"" + personaName + "\" persona.\n" +
+    "Persona file: " + crewHome + "/.orchestration/personas/" + personaFile + " — read it first and wear that perspective for the whole run.\n" +
+    "\n" +
+    "Journey:\n" + body + "\n" +
+    "\n" +
+    "Rules:\n" +
+    "- Walk the journey end to end from a user's perspective, wearing the persona.\n" +
+    "- Use the normal QA surface for this project (the published artifact's own user interface for artifact projects; read-only dashboard API checks otherwise). Note: there is currently no agent-callable visual-inspection tool (artifact_inspect was removed by the platform 2026-09-14; artifact.inspect is malfunction diagnosis, not a substitute) — judge only what you can observe directly.\n" +
+    "- There is no code change under test: skip change-verification steps (provenance / publish checks) and judge only what you observe.\n" +
+    "- " + filingRule + "\n" +
+    "- File via the existing createtask action with filed_by \"hazel\": set workflow to \"standard\" when the fix is clear feature work, or omit workflow (untriaged) when unsure — triage routes untriaged filings to bugfix/feature as usual.\n"
+  ).slice(0, 4800);
+}
+
+// ── Inline scripts (were node -e ferries in the workflow) ──────────
+// Tick-release identity log: one append-only line per dispatcher run in
+// $CREW_HOME/.tick-releases.jsonl. seq is the non-empty line count + 1;
+// file order is the proof (no wall-clock).
+function writeTickRelease(crewHome) {
+  const release = basename(resolve(crewHome, readlinkTarget(join(crewHome, "current"))));
+  const file = join(crewHome, ".tick-releases.jsonl");
+  let count = 0;
+  try {
+    const lines = readFileSync(file, "utf8").split("\n");
+    for (const l of lines) { if (l.trim() !== "") count++; }
+  } catch (e) { /* missing file: count stays 0 */ }
+  const line = JSON.stringify({ seq: count + 1, release });
+  appendFileSync(file, line + "\n");
+  return line;
+}
+
+function readlinkTarget(p) {
+  // Minimal readlink for the release symlink; throws on failure.
+  return readlinkSync(p);
+}
+
+function countNonEmptyLines(file) {
+  let count = 0;
+  try {
+    const lines = readFileSync(file, "utf8").split("\n");
+    for (const l of lines) { if (l.trim() !== "") count++; }
+  } catch (e) { /* missing file: count stays 0 */ }
+  return count;
+}
+
+// Shadow evidence (Piece 1, 2026-09-26): in --read-only mode the worker
+// dispatcher appends one line per run to $CREW_HOME/.dispatch-shadow.jsonl.
+// The line carries the normalized claim set the worker WOULD have launched,
+// plus tick_seq_before — the .tick-releases line count BEFORE this tick's
+// authoritative dispatcher runs. The authoritative decision line pairs
+// mechanically: decision.tick_seq === shadow.tick_seq_before + 1 (the
+// sandbox dispatcher writes its tick-release line, then its decision).
+// lib/compare-dispatch-shadow.js performs the pairing and the verdict;
+// no agent ever transcribes claims.
+function writeShadowEvidence(crewHome, evidence) {
+  if (!evidence || !Array.isArray(evidence.claims)) {
+    throw new Error("bad shadow evidence payload");
+  }
+  const file = join(crewHome, ".dispatch-shadow.jsonl");
+  const seq = countNonEmptyLines(file) + 1;
+  const tickSeqBefore = countNonEmptyLines(join(crewHome, ".tick-releases.jsonl"));
+  const line = JSON.stringify({
+    seq, mode: "shadow", tick_seq_before: tickSeqBefore,
+    run_id: evidence.run_id || null,
+    claims: evidence.claims,
+    board: evidence.board || null, skipped: evidence.skipped || {},
+    partial: !!evidence.partial,
+  });
+  appendFileSync(file, line + "\n");
+  return line;
+}
+
+// Dispatch-decision log: one append-only line per completed tick in
+// $CREW_HOME/.dispatch-decisions.jsonl. tick_seq couples to the
+// .tick-releases line for the same poll.
+function writeDispatchDecision(crewHome, decision) {
+  if (!decision || typeof decision.decision !== "string" || !Array.isArray(decision.launched)) {
+    throw new Error("bad decision payload");
+  }
+  const release = basename(resolve(crewHome, readlinkTarget(join(crewHome, "current"))));
+  const file = join(crewHome, ".dispatch-decisions.jsonl");
+  let count = 0;
+  try {
+    const lines = readFileSync(file, "utf8").split("\n");
+    for (const l of lines) { if (l.trim() !== "") count++; }
+  } catch (e) { /* missing file */ }
+  let tickSeq = 0;
+  try {
+    const tlines = readFileSync(join(crewHome, ".tick-releases.jsonl"), "utf8").split("\n");
+    for (const l of tlines) { if (l.trim() !== "") tickSeq++; }
+  } catch (e) { /* missing file */ }
+  const line = JSON.stringify({
+    seq: count + 1, tick_seq: tickSeq, release,
+    decision: decision.decision, launched: decision.launched,
+    completed: decision.completed || [], parked: decision.parked || [],
+    board: decision.board || null, skipped: decision.skipped || {},
+    partial: !!decision.partial,
+  });
+  appendFileSync(file, line + "\n");
+  return line;
+}
+
+// ── Main ────────────────────────────────────────────────────────────
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) { printHelp(); return; }
+
+  const crewHome = args.crewHome;
+  if (!crewHome) throw transportError("CONFIG", "--crew-home is required");
+  CREW_HOME = crewHome;
+  CREW_API = join(crewHome, "current", "lib", "crew-api.js");
+  const readOnly = !!args.readOnly;
+  const MAX_TASKS_PER_POLL = args.maxTasksPerPoll ? parseInt(args.maxTasksPerPoll, 10) : 6;
+
+  // worker_runs ledger: record the run start (identity minted SQLite-side).
+  let runId = null;
+  try {
+    const startOut = await runApi("record-worker-run", { phase: "dispatch", status: "running" });
+    runId = parseApiJson(startOut, "record-worker-run").id;
+  } catch (e) {
+    // The ledger is observability — a ledger failure must not fail dispatch.
+    log("WARNING: worker_runs start record failed: " + e.message);
+  }
+  const finishRun = async (status, error) => {
+    if (runId === null || runId === undefined) return;
+    try {
+      await runApi("record-worker-run", { id: runId, phase: "dispatch", status, error: error || null });
+    } catch (e) {
+      log("WARNING: worker_runs finish record failed: " + e.message);
+    }
+  };
+
+  try {
+    const result = await dispatch({ readOnly, MAX_TASKS_PER_POLL, registryText: args.registryText, runId });
+    await finishRun("completed", null);
+    console.log(JSON.stringify(result));
+  } catch (e) {
+    await finishRun("failed", (e.message || String(e)).slice(0, 500));
+    const code = e.code || "TRANSPORT_ERROR";
+    console.log(JSON.stringify({ ok: false, error: e.message || String(e), code }));
+    process.exit(1);
+  }
+}
+
+async function dispatch(opts) {
+  const { readOnly, MAX_TASKS_PER_POLL, registryText, runId } = opts;
+  const crewHome = CREW_HOME;
+
+  // ── Registry ──────────────────────────────────────────────────
+  let registryResult = null;
+  const registryTextResult = parseRegistryText(
+    registryText !== undefined ? registryText : readRegistryFile(crewHome)
+  );
+  if (registryTextResult.ok) {
+    registryResult = registryTextResult.registry;
+  } else if (registryText !== undefined && registryText !== null) {
+    log("WARNING: " + registryTextResult.reason + " — failing closed (no slow load on the worker layer)");
+    throw transportError("CONFIG", "registry: " + registryTextResult.reason);
+  }
+  // On the worker layer there is no slow agent load: the registry file is
+  // read directly from disk. A missing/unusable registry fails closed.
+  const registryCheck = validateRegistry(registryResult);
+  if (!registryCheck.ok) {
+    throw transportError("CONFIG", "registry failed shape validation (" + registryCheck.reason + ")");
+  }
+
+  const WORKFLOWS = {};
+  const BUILD_STEPS = {};
+  const wfNames = ["standard", "bugfix", "chore", "docs", "upgrade"];
+  for (const wfName of wfNames) {
+    const wfData = registryResult[wfName];
+    WORKFLOWS[wfName] = wfData.steps.map((s) => s.name);
+    BUILD_STEPS[wfName] = wfData.reworkTarget;
+  }
+
+  // ── 1. Read the board (2 attempts, like the workflow) ─────────
+  let boardReturn = null;
+  let boardReadError = null;
+  for (let readAttempt = 1; readAttempt <= 2; readAttempt++) {
+    try {
+      const stdout = await runApi("get-dispatch-state");
+      parseBoardJson(stdout); // parse eagerly so a malformed ferry retries
+      boardReturn = stdout;
+      boardReadError = null;
+      break;
+    } catch (readErr) {
+      boardReadError = readErr;
+      log("WARNING: read-board attempt " + readAttempt + " failed (" +
+        (readErr && readErr.message ? readErr.message : readErr) + ")" +
+        (readAttempt < 2 ? " — retrying" : " — attempts exhausted"));
+      boardReturn = null;
+    }
+  }
+  if (boardReturn === null) {
+    throw transportError("TRANSPORT_ERROR",
+      "read-board: all 2 attempts failed: " +
+      (boardReadError && boardReadError.message ? boardReadError.message : boardReadError));
+  }
+
+  const boardData = unwrapBoardResult(parseBoardJson(boardReturn));
+  const allTasks = boardData.ready_tasks.map(projectTaskRecord).filter((t) => t !== null);
+  const config = boardData.config || {};
+  const projects = boardData.projects || [];
+
+  const reservedTaskIds = new Set((boardData.reservations || []).map((r) => r.task_id));
+  if (reservedTaskIds.size > 0) {
+    log("Reservations: skipping " + reservedTaskIds.size + " task(s) with an active dispatch reservation");
+  }
+
+  const DEFAULT_PROJECT = projects.length > 0 ? projects[0].id : "";
+
+  const quiescedProjects = {};
+  for (const p of projects) { if (p.quiesced) quiescedProjects[p.id] = true; }
+
+  const projectSimultaneity = {};
+  for (const p of projects) {
+    const rawSim = Number(p.simultaneity);
+    projectSimultaneity[p.id] = isNaN(rawSim) ? 2 : rawSim;
+  }
+  const rawGlobal = Number(config.simultaneity);
+  const globalSimultaneity = isNaN(rawGlobal) ? 1 : rawGlobal;
+
+  const PROJECTS = {};
+  for (const proj of projects) {
+    PROJECTS[proj.id] = {
+      repo_path: proj.repo_path,
+      deploy_type: proj.deploy_type,
+      deploy_slug: proj.deploy_slug,
+      description: proj.description,
+      environment_type: proj.environment_type || null,
+      versioned_build: !!proj.versioned_build,
+      version_file: proj.version_file || null,
+    };
+  }
+
+  log("Board: " + allTasks.length + " active tasks, quiesced=" + Object.keys(quiescedProjects).join(","));
+
+  // ── 2. Eligibility (verbatim decision logic) ──────────────────
+  const eligible = [];
+  const retryCandidates = [];
+  const rejectionCandidates = [];
+  const decisionSkipped = {};
+  const countSkipped = (reason) => { decisionSkipped[reason] = (decisionSkipped[reason] || 0) + 1; };
+
+  const MAX_CONSECUTIVE_FAILURES = configInt(config, "maxConsecutiveFailures", 3);
+  const MAX_CONSECUTIVE_REJECTIONS = configInt(config, "maxConsecutiveRejections", 2);
+
+  const qaStepIndex = (workflowName) => {
+    const steps = WORKFLOWS[workflowName] || WORKFLOWS.standard;
+    const idx = steps.indexOf("QA");
+    return idx >= 0 ? idx : 0;
+  };
+
+  for (const task of allTasks) {
+    if (task.blocked) { countSkipped("blocked"); continue; }
+    if (reservedTaskIds.has(task.id)) {
+      countSkipped("reserved");
+      log("Skipped \"" + task.title + "\" — active dispatch reservation (workflow launched, claim pending)");
+      continue;
+    }
+    const taskProject = task.project || DEFAULT_PROJECT;
+    if (quiescedProjects[taskProject]) {
+      countSkipped("quiesced");
+      log("Skipped \"" + task.title + "\" — project " + taskProject + " is quiesced");
+      continue;
+    }
+    const taskProjCfg = PROJECTS[taskProject];
+    if (!taskProjCfg || !taskProjCfg.repo_path) {
+      countSkipped("no_repo");
+      log("Skipped \"" + task.title + "\" — project " + taskProject + " has no repo_path configured");
+      continue;
+    }
+
+    const latest = task.latest_session;
+    const workflow = task.workflow || "standard";
+    const steps = WORKFLOWS[workflow] || WORKFLOWS.standard;
+
+    if (task.next_phase) {
+      if (task.state !== "todo" && task.state !== "in_progress") {
+        countSkipped("next_phase_state");
+        log("Skipped \"" + task.title + "\" — next_phase \"" + task.next_phase + "\" set but state is " + task.state + "; left set for inspection");
+        continue;
+      }
+      if (latest && latest.status === "running") { countSkipped("in_flight"); continue; }
+      const npIdx = steps.indexOf(task.next_phase);
+      if (npIdx < 0) {
+        countSkipped("next_phase_bad_step");
+        log("Skipped \"" + task.title + "\" — next_phase \"" + task.next_phase + "\" not in " + workflow + " step registry; left set for a corrected recover-task");
+        continue;
+      }
+      eligible.push({ task, startStep: npIdx, reason: "next_phase", workflow, nextPhase: task.next_phase });
+      continue;
+    }
+
+    if (task.state === "todo") {
+      const todoStart = isPlaytestTask(task) ? qaStepIndex(task.workflow || "standard") : 0;
+      eligible.push({ task, startStep: todoStart, reason: "new", workflow });
+      continue;
+    }
+
+    if (task.state !== "in_progress") { countSkipped("terminal_state"); continue; }
+    if (!latest) {
+      eligible.push({ task, startStep: 0, reason: "no_session", workflow });
+      continue;
+    }
+    if (latest.status === "running") { countSkipped("in_flight"); continue; }
+
+    if (latest.status === "completed") {
+      const stepName = latest.step || "";
+      const stepIndex = steps.indexOf(stepName);
+      if (stepIndex < 0) {
+        countSkipped("unknown_step");
+        log("Skipped \"" + task.title + "\" — step \"" + stepName + "\" not in " + workflow + " step registry");
+        continue;
+      }
+      const nextIndex = stepIndex + 1;
+      if (nextIndex >= steps.length) {
+        eligible.push({ task, action: "complete", workflow });
+      } else {
+        eligible.push({ task, startStep: nextIndex, reason: "next_step", workflow });
+      }
+      continue;
+    }
+
+    if (latest.status === "rejected") {
+      const buildStepName = BUILD_STEPS[workflow] || "Build";
+      const buildIdx = steps.indexOf(buildStepName);
+      if (buildIdx >= 0) {
+        rejectionCandidates.push({ task, startStep: buildIdx, reason: "rework", workflow, rejectionNotes: latest.notes || "" });
+      }
+      continue;
+    }
+
+    if (latest.status === "failed" || latest.status === "timed_out" || latest.status === "stalled") {
+      const failedStep = latest.step || "";
+      const retryIdx = steps.indexOf(failedStep);
+      if (retryIdx < 0) {
+        countSkipped("unknown_step");
+        log("Skipped \"" + task.title + "\" — step \"" + failedStep + "\" not in " + workflow + " step registry");
+        continue;
+      }
+      retryCandidates.push({ task, startStep: retryIdx, reason: "retry", workflow, failedStep });
+      continue;
+    }
+  }
+
+  // ── 2a. Retry cap and rejection budget ────────────────────────
+  const parkJobs = [];
+  for (const rc of retryCandidates) {
+    const retryState = (rc.task && rc.task.retry) || null;
+    const consecutiveFailures = retryState ? retryState.consecutive_failures : undefined;
+    if (typeof consecutiveFailures !== "number" || consecutiveFailures < 0) {
+      log("WARNING: invalid retry state for \"" + rc.task.title + "\" (consecutive_failures=" + String(consecutiveFailures) + ") — retrying, cap unenforced");
+    } else if (retryState == null) {
+      log("WARNING: no explicit retry state for \"" + rc.task.title + "\" — retrying (dashboard predates retry field)");
+    }
+    if (decideRetry(consecutiveFailures, MAX_CONSECUTIVE_FAILURES) === "park") {
+      parkJobs.push({ task: rc.task, message: ("Parked: " + rc.failedStep + " failed " + consecutiveFailures + " consecutive times (cap " + MAX_CONSECUTIVE_FAILURES + ")").slice(0, 1000) });
+    } else {
+      eligible.push({ task: rc.task, startStep: rc.startStep, reason: "retry", workflow: rc.workflow });
+    }
+  }
+  for (const jc of rejectionCandidates) {
+    const jcRetryState = (jc.task && jc.task.retry) || null;
+    const rejectionsSinceReset = jcRetryState ? jcRetryState.rejections_since_reset : undefined;
+    if (typeof rejectionsSinceReset !== "number" || rejectionsSinceReset < 0) {
+      log("WARNING: invalid retry state for \"" + jc.task.title + "\" (rejections_since_reset=" + String(rejectionsSinceReset) + ") — reworking, budget unenforced");
+    } else if (jcRetryState == null) {
+      log("WARNING: no explicit retry state for \"" + jc.task.title + "\" — reworking (dashboard predates retry field)");
+    }
+    if (decideRetry(rejectionsSinceReset, MAX_CONSECUTIVE_REJECTIONS) === "park") {
+      parkJobs.push({ task: jc.task, message: ("Parked: " + rejectionsSinceReset + " rejections since reset (budget " + MAX_CONSECUTIVE_REJECTIONS + ") — needs human review").slice(0, 1000) });
+    } else {
+      eligible.push({ task: jc.task, startStep: jc.startStep, reason: "rework", workflow: jc.workflow, rejectionNotes: jc.rejectionNotes });
+    }
+  }
+
+  // ── Parks (skipped in read-only) ──────────────────────────────
+  const parkedTaskIds = [];
+  if (!readOnly && parkJobs.length > 0) {
+    for (const pj of parkJobs) {
+      log("Parking \"" + pj.task.title + "\" — " + pj.message);
+      try {
+        await runApi("park-task", { task_id: pj.task.id, message: pj.message });
+        parkedTaskIds.push(pj.task.id);
+      } catch (parkErr) {
+        log("WARNING: park-task failed for " + pj.task.id + " (" + parkErr.message + ") — task remains retryable");
+      }
+    }
+    log("Parked " + parkedTaskIds.length + "/" + parkJobs.length + " task(s)");
+  } else if (parkJobs.length > 0) {
+    log("Read-only: would park " + parkJobs.length + " task(s), skipping");
+  }
+
+  log("Eligible: " + eligible.length + " tasks (" + retryCandidates.length + " retry candidates)");
+
+  // ── 2b. Idle playtesting ─────────────────────────────────────
+  let wouldFilePlaytest = false;
+  let playtestTitle = null;
+  if (eligible.length === 0) {
+    const ptProject = DEFAULT_PROJECT;
+    let ptArmed = true;
+    let ptWhy = "";
+    if (!ptProject) { ptArmed = false; ptWhy = "no default project"; }
+    if (ptArmed && quiescedProjects[ptProject]) { ptArmed = false; ptWhy = "project " + ptProject + " is quiesced"; }
+    if (ptArmed) {
+      for (const gt of allTasks) {
+        if (isPlaytestTask(gt) && (gt.state === "todo" || gt.state === "in_progress")) {
+          ptArmed = false; ptWhy = "playtest already outstanding: " + gt.id;
+          break;
+        }
+      }
+    }
+    let ptJourneys = [];
+    if (ptArmed) {
+      ptJourneys = parseJourneys(config["playtest." + ptProject + ".journeys"]);
+      if (ptJourneys.length === 0) { ptArmed = false; ptWhy = "no journeys roster for project " + ptProject + " (unarmed)"; }
+    }
+    let ptPersonas = [];
+    if (ptArmed) {
+      try {
+        ptPersonas = readdirSync(join(crewHome, ".orchestration", "personas"))
+          .filter((f) => typeof f === "string" && f.slice(-3).toLowerCase() === ".md")
+          .sort();
+      } catch (e) {
+        ptPersonas = [];
+      }
+      if (ptPersonas.length === 0) { ptArmed = false; ptWhy = "no persona files in " + crewHome + "/.orchestration/personas"; }
+    }
+
+    if (ptArmed) {
+      const J = ptJourneys.length;
+      const P = ptPersonas.length;
+      const jc = configInt(config, "playtest." + ptProject + ".journey_cursor", 0);
+      const pc = configInt(config, "playtest." + ptProject + ".persona_cursor", 0);
+      const pti = ((jc % J) + J) % J;
+      const ppi = ((pc % P) + P) % P;
+      const ptJourney = ptJourneys[pti];
+      const ptPersonaFile = ptPersonas[ppi];
+      const ptPersonaName = ptPersonaFile.replace(/\.md$/i, "");
+      const nextJ = (pti + 1) % J;
+      const nextP = (nextJ === 0) ? (ppi + 1) % P : ppi;
+      let maxFilings = configInt(config, "playtest." + ptProject + ".max_filings", 5);
+      if (maxFilings < 0) maxFilings = 5;
+
+      playtestTitle = (PLAYTEST_PREFIX + ptJourney.name + " as " + ptPersonaName).slice(0, 160);
+      const ptDesc = buildPlaytestDescription(ptJourney, ptPersonaName, ptPersonaFile, maxFilings, crewHome);
+
+      if (readOnly) {
+        wouldFilePlaytest = true;
+        log("Read-only: would file idle playtest \"" + playtestTitle + "\", skipping");
+      } else {
+        try {
+          await runApi("update-config", { key: "playtest." + ptProject + ".journey_cursor", value: String(nextJ) });
+          await runApi("update-config", { key: "playtest." + ptProject + ".persona_cursor", value: String(nextP) });
+          const createOut = await runApi("create-task", {
+            title: playtestTitle, description: ptDesc,
+            project: ptProject, workflow: "standard", filed_by: "hazel",
+          });
+          const createParsed = parseApiJson(createOut, "create-task");
+          const taskId = createParsed && createParsed.task ? createParsed.task.id : undefined;
+          if (taskId) {
+            // Witness re-read: the task must be observed in todo state.
+            let ptWitnessOk = false;
+            try {
+              const ptBoardOut = await runApi("get-dispatch-state");
+              const ptBoard = unwrapBoardResult(parseBoardJson(ptBoardOut));
+              const ptTasks = (ptBoard.ready_tasks || []).map(projectTaskRecord).filter((t) => t !== null);
+              ptWitnessOk = ptTasks.some((t) => t.id === taskId && t.state === "todo");
+            } catch (e) {
+              log("Playtest witness re-read failed (" + e.message + ") — task not verified, skipping eligible");
+            }
+            if (ptWitnessOk) {
+              eligible.push({
+                task: { id: taskId, title: playtestTitle, description: ptDesc, project: ptProject, workflow: "standard", state: "todo" },
+                startStep: qaStepIndex("standard"),
+                reason: "playtest",
+                workflow: "standard",
+              });
+              log("Filed idle playtest \"" + playtestTitle + "\" [" + ptProject + "] (witness observed todo)");
+            } else {
+              log("Idle playtest task " + taskId + " not observed in todo state on re-read — skipping eligible (fail-closed)");
+            }
+          } else {
+            log("Idle playtest filing failed — cursors already advanced, assignment skipped");
+          }
+        } catch (e) {
+          log("WARNING: playtest filing failed: " + e.message);
+        }
+      }
+    } else {
+      log("Idle playtest not armed: " + ptWhy);
+    }
+  }
+
+  // ── 3. Simultaneity + per-poll cap ────────────────────────────
+  const results = [];
+  let partial = false;
+  {
+    const inFlightByProject = {};
+    for (const ctask of allTasks) {
+      if (ctask.state === "in_progress" && ctask.latest_session && ctask.latest_session.status === "running") {
+        const cp = ctask.project || DEFAULT_PROJECT;
+        inFlightByProject[cp] = (inFlightByProject[cp] || 0) + 1;
+      }
+    }
+    const toProcess = [];
+    for (const eitem of eligible) {
+      const ep = eitem.task.project || DEFAULT_PROJECT;
+      const limit = (ep in projectSimultaneity) ? projectSimultaneity[ep] : globalSimultaneity;
+      const current = inFlightByProject[ep] || 0;
+      if (current < limit) {
+        toProcess.push(eitem);
+        inFlightByProject[ep] = current + 1;
+      } else {
+        decisionSkipped["at_limit"] = (decisionSkipped["at_limit"] || 0) + 1;
+        log("Skipped \"" + eitem.task.title + "\" — project " + ep + " at simultaneity limit (" + limit + ")");
+      }
+    }
+    if (toProcess.length > MAX_TASKS_PER_POLL) {
+      const deferred = toProcess.length - MAX_TASKS_PER_POLL;
+      log("Deferring " + deferred + " task(s) to next poll (per-poll cap " + MAX_TASKS_PER_POLL + ")");
+      toProcess.splice(MAX_TASKS_PER_POLL);
+      partial = true;
+    }
+
+    const WORKFLOW_DIR = join(crewHome, "workflows");
+    for (const item of toProcess) {
+      const itask = item.task;
+      const iworkflow = item.workflow;
+      const isteps = WORKFLOWS[iworkflow] || WORKFLOWS.standard;
+
+      if (item.action === "complete") {
+        if (readOnly) {
+          log("Read-only: would complete task " + itask.id + ", skipping");
+          results.push({ task_id: itask.id, action: "completed" });
+          continue;
+        }
+        await runApi("update-task", { id: itask.id, state: "done" });
+        await runApi("log-event", { task_id: itask.id, type: "completed", message: "All workflow steps complete." });
+        results.push({ task_id: itask.id, action: "completed" });
+        continue;
+      }
+
+      const nextStepName = isteps[item.startStep];
+      const scriptPath = join(WORKFLOW_DIR, iworkflow + ".js");
+      const taskProject = itask.project || DEFAULT_PROJECT;
+      const projectCfg = PROJECTS[taskProject] || PROJECTS[DEFAULT_PROJECT];
+      const launchArgs = {
+        task_id: itask.id,
+        task_title: itask.title || "",
+        task_description: itask.description || "",
+        start_step_index: item.startStep,
+        rejection_notes: item.rejectionNotes || "",
+        project_config: projectCfg,
+        project_id: taskProject,
+        crewHome: crewHome,
+        visual_protocol: effectiveVisualProtocol(projectCfg),
+        resolved_workflow: iworkflow,
+        workflow_was_null: (itask.workflow == null),
+        next_phase: item.nextPhase || null,
+      };
+      log("Recommended " + iworkflow + " for \"" + itask.title + "\" [" + taskProject + "] at step " + nextStepName);
+      // executor tag (Piece 1, semantics settled 2026-09-26): `executor`
+      // names the layer that COMPUTED the recommendation, not the layer
+      // that launched it. In Piece 1 the sandboxed dispatcher remains the
+      // only launch authority and the worker dispatcher runs --read-only,
+      // so no executor:"worker" claim is ever launched; the tag is
+      // forward-looking provenance the Piece-2 router will key on. Do not
+      // read it as "this executed on the worker layer."
+      results.push({ task_id: itask.id, workflow: iworkflow, step: nextStepName, action: "recommended", scriptPath, args: launchArgs, executor: "worker" });
+    }
+  }
+
+  // ── 4. Acknowledge (skipped in read-only) ──────────────────────
+  if (!readOnly) {
+    await runApi("acknowledge-poll");
+  } else {
+    log("Read-only: skipping acknowledge-poll");
+  }
+
+  // ── 4b. Tick release-identity log (skipped in read-only) ───────
+  if (!readOnly) {
+    try {
+      writeTickRelease(crewHome);
+    } catch (e) {
+      log("WARNING: tick release-identity log write failed (tick continues): " + e.message);
+    }
+  }
+
+  let recommended = [];
+  const seenClaims = {};
+  for (const r of results) {
+    if (r.action !== "recommended") continue;
+    if (seenClaims[r.task_id]) {
+      log("WARNING: dropped duplicate claim for task " + r.task_id + " within this run (kept first)");
+      continue;
+    }
+    seenClaims[r.task_id] = true;
+    recommended.push(r);
+  }
+  const completed = results.filter((r) => r.action === "completed");
+
+  // ── Reservations (skipped in read-only) ────────────────────────
+  if (readOnly) {
+    // Shadow evidence: the claim set we WOULD have launched, machine-
+    // written for the post-tick comparator. Never touches reservations,
+    // the poll ack, or the tick-release/decision logs.
+    try {
+      writeShadowEvidence(crewHome, {
+        run_id: runId,
+        claims: recommended.map((r) => ({ task_id: r.task_id, workflow: r.workflow, step: r.step })),
+        board: { seen: allTasks.length, eligible: eligible.length },
+        skipped: decisionSkipped,
+        partial,
+      });
+    } catch (e) {
+      log("WARNING: shadow evidence write failed (tick continues): " + e.message);
+    }
+  }
+  if (!readOnly && recommended.length > 0) {
+    const acquired = [];
+    for (const rec of recommended) {
+      try {
+        const reserveOut = await runApi("reserve-dispatch", {
+          task_id: rec.task_id,
+          run_id: "pending-dispatch",
+          workflow: rec.workflow,
+        });
+        const reserveParsed = extractJsonObject(parseApiJson(reserveOut, "reserve-dispatch"));
+        if (reserveParsed && reserveParsed.acquired) {
+          log("Reservation acquired for task " + rec.task_id.slice(0, 8) + " (claim-task is authoritative)");
+          acquired.push(rec);
+        } else {
+          log("SKIPPED task " + rec.task_id.slice(0, 8) + " — reservation not acquired (another dispatcher owns it)");
+        }
+      } catch (e) {
+        log("SKIPPED task " + rec.task_id.slice(0, 8) + " — reservation failed: " + e.message);
+      }
+    }
+    recommended = acquired;
+  } else if (recommended.length > 0) {
+    log("Read-only: would reserve " + recommended.length + " task(s), skipping");
+  }
+
+  // ── 4c. Dispatch-decision log (skipped in read-only) ───────────
+  const launchedRecs = recommended.map((r) => ({ task_id: r.task_id, workflow: r.workflow, step: r.step }));
+  const decisionObj = {
+    decision: launchedRecs.length > 0 ? "launch" : "stand_down",
+    launched: launchedRecs,
+    completed: completed.map((r) => r.task_id),
+    parked: parkedTaskIds,
+    board: { seen: allTasks.length, eligible: eligible.length },
+    skipped: decisionSkipped,
+    partial,
+  };
+  if (!readOnly) {
+    try {
+      writeDispatchDecision(crewHome, decisionObj);
+    } catch (e) {
+      log("WARNING: dispatch-decision log write failed (tick continues): " + e.message);
+    }
+  }
+
+  let msg = "Dispatch complete.";
+  if (recommended.length > 0) {
+    msg += " Recommended: " + recommended.map((r) => r.workflow + "/" + r.step + " for " + r.task_id).join(", ") + ".";
+  }
+  if (completed.length > 0) {
+    msg += " Completed: " + completed.map((r) => r.task_id).join(", ") + ".";
+  }
+  if (partial) { msg += " (partial: per-poll cap deferred tasks)"; }
+  if (eligible.length === 0) { msg = "No tasks ready."; }
+
+  return {
+    status: "ok",
+    message: msg,
+    claims: recommended,
+    partial,
+    would_file_playtest: wouldFilePlaytest,
+    playtest_title: playtestTitle,
+    run_id: runId,
+  };
+}
+
+function readRegistryFile(crewHome) {
+  try {
+    return readFileSync(join(crewHome, "workflows", "registry.json"), "utf8");
+  } catch (e) {
+    return null;
+  }
+}
+
+main().catch((e) => {
+  const code = e.code || "TRANSPORT_ERROR";
+  console.log(JSON.stringify({ ok: false, error: e.message || String(e), code }));
+  process.exit(1);
+});