muse-crew 0.17.2 → 0.17.3

package/lib/chore/spawn-vocab.js

@@ -0,0 +1,87 @@
+// lib/chore/spawn-vocab.js — closed vocabularies for the production spawn
+// bridge (sandbox exit, chore pilot Piece 2, 2026-09-26).
+//
+// Import-safe: pure constants, no I/O, no clock, no randomness. Single
+// source of truth shared by lib/spawn-step.js, lib/reap-spawns.js, and the
+// spawn-ledger commands in lib/crew-api.js.
+//
+// The frozen creative spawn kinds (DESIGN-chore-pilot.md §1): work-agent,
+// verdict-reask, evidence-gatherer. Unknown kinds fail closed at the bridge.
+
+export const SPAWN_KINDS = Object.freeze([
+  "work-agent",
+  "verdict-reask",
+  "evidence-gatherer",
+]);
+
+// Terminal outcome vocabulary for the worker_runs.result JSON. Both writers
+// (spawn-step post, reap-spawns.js) enforce this closed set fail-closed: a
+// row may only leave 'running' with one of these outcomes. The 3-state
+// status CHECK (running|completed|failed) is unchanged — kill states live
+// here, in the result JSON, never as new statuses.
+export const CLOSED_OUTCOMES = Object.freeze([
+  "completed", // spawn returned; typed result in the payload
+  "synthetic", // no-spawn branch: workflow-authored prose, extracted identically
+  "transport_timeout", // agent did not return within timeout_ms
+  "transport_error", // the spawn itself failed
+  "transport_empty", // agent returned blank text
+  "transport_parse", // verdict unrecoverable after the task-domain reask budget
+  "killed_confirmed", // timeout + machine-verified dead
+  "killed_by_reaper", // reaper closed an already-dead child
+  "orphaned_unkillable", // child believed alive but unkillable
+  "orphaned_unverified", // child liveness unverifiable; no kill attempted
+  "transport_failed", // terminal transport failure (unrecoverable)
+]);
+
+export function isClosedOutcome(outcome) {
+  return typeof outcome === "string" && CLOSED_OUTCOMES.includes(outcome);
+}
+
+// Outcomes that count toward the per-task consecutive transport-failure
+// budget (DESIGN-chore-pilot.md §4): terminal TRANSPORT_TIMEOUT /
+// TRANSPORT_ERROR / TRANSPORT_PARSE equivalents, orphaned_*,
+// killed_by_reaper, and terminal reask failures. Reset by any completed
+// non-transport row for the task.
+export const TRANSPORT_FAILURE_OUTCOMES = Object.freeze([
+  "transport_timeout",
+  "transport_error",
+  "transport_empty",
+  "transport_parse",
+  "killed_confirmed",
+  "killed_by_reaper",
+  "orphaned_unkillable",
+  "orphaned_unverified",
+  "transport_failed",
+]);
+
+export function isTransportFailureOutcome(outcome) {
+  return typeof outcome === "string" && TRANSPORT_FAILURE_OUTCOMES.includes(outcome);
+}
+
+// Per-kind attempt caps, mirroring the chore workflow's bounded loops:
+// work-agent 3 attempts (t0-t2), verdict-reask 2 attempts (180s each).
+// evidence-gatherer has no chore site; 3 is the work-agent analog —
+// revisit when the kind gets its Piece 4 contract.
+export const MAX_ATTEMPTS = Object.freeze({
+  "work-agent": 3,
+  "verdict-reask": 2,
+  "evidence-gatherer": 3,
+});
+
+// Consecutive transport failures for one task before the bridge refuses
+// new spawns (the task parks instead of burning attempts).
+export const TRANSPORT_BUDGET_CAP = 5;
+
+// Platform tick kill: the tick worker is killed at 90m. A spawn's timeout
+// must leave headroom for post-processing and the driver loop, so the
+// tick never dies mid-spawn-wait.
+export const TICK_KILL_MS = 90 * 60 * 1000;
+export const SPAWN_HEADROOM_MS = 10 * 60 * 1000;
+export const MAX_TIMEOUT_MS = TICK_KILL_MS - SPAWN_HEADROOM_MS;
+export const MIN_TIMEOUT_MS = 60 * 1000;
+
+// Reaper: a running row is reapable once it has been past its timeout_ms
+// for longer than this margin (slow-post / clock-skew grace). Unknown kill
+// states keep the row running — it may only leave 'running' with a closed
+// outcome.
+export const REAP_MARGIN_MS = 5 * 60 * 1000;

package/lib/chore-run.js

@@ -0,0 +1,538 @@
+#!/usr/bin/env node
+// lib/chore-run.js — the Chore driver loop: the worker-layer port of
+// workflows/chore.js (sandbox-exit Piece 3, 2026-09-26).
+//
+// The tick worker invokes this once per tick for a dispatched Chore task:
+//   node lib/chore-run.js --crew-home H --task-id T --tick-seq N [options]
+//
+// Per-boundary stateless invocation. Stdout carries EXACTLY ONE JSON line:
+//   {"type":"NEED_SPAWN","request":{...}} — post the request via the spawn
+//       bridge (spawn-step.js pre), then re-invoke when it lands.
+//   {"type":"WAIT","reason":..,"key":..,"phase":..} — a spawn is in flight;
+//       re-invoke when the spawn row goes terminal.
+//   {"type":"DONE","outcome":..,"task_id":..} — outcome is one of
+//       completed | failed | parked | park-failed | stood-down.
+//
+// PROTOCOL NOTE (2026-09-26): the frozen design named only NEED_SPAWN and
+// DONE. WAIT is a deliberate third frame, not a silent expansion. When a
+// spawn is already posted and running, re-emitting NEED_SPAWN would instruct
+// the launcher to post a duplicate (record-spawn-open refuses with
+// duplicate_running, forcing the launcher to interpret the refusal as
+// "wait" — decision logic leaking out of the driver). Emitting DONE would
+// lie about the run being over. WAIT keeps the single-decision-point
+// contract: the driver decides, the launcher only posts and re-invokes.
+// Flagged for cutover review; the design doc is amended only on approval.
+// All logs go to stderr. All run state is derived from Crew API reads
+// (tasks, sessions, events, spawn-ledger rows) — there is no run-state
+// file anywhere. A derivation failure is a transport failure: the driver
+// fails closed with DONE/failed, never a partial advance.
+//
+// Concurrency discipline (same as the old workflow): one invocation per
+// task at a time. The tick worker must not invoke this for a task with a
+// running session unless the previous invocation is known dead. A lost
+// claim race stands down quietly via the claim-as-gate.
+//
+// No wall-clock reads and no randomness in decision code (G3). Timestamps
+// are minted SQLite-side by crew-api.js.
+
+// Spawn-pre refusal codes that are PERMANENT (2026-09-26): the refusal fires
+// before any spawn-ledger row is opened, so re-deriving would emit an
+// identical NEED_SPAWN forever — no ledger state advances. The ferry
+// (chore-tick.js) reports these back via --pre-refusal and the driver
+// terminates instead of re-emitting NEED_SPAWN. DUPLICATE_RUNNING is the
+// legitimate re-drive case (a spawn is in flight; the next derivation
+// resolves to WAIT). This list must match TERMINAL_REFUSAL_CODES in
+// lib/chore-tick.js.
+const TERMINAL_REFUSAL_CODES = [
+  "BOUNDS_REJECTED",            // spawn bounds invalid (project misconfiguration) → PARK
+  "ATTEMPTS_EXHAUSTED",         // spawn attempts exhausted → FAILED
+  "TRANSPORT_BUDGET_EXHAUSTED", // consecutive transport failures exhausted → FAILED
+];
+
+import { rmSync, readdirSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { pathToFileURL } from "node:url";
+
+import {
+  deriveRunEnv, pinLifecycle, parsePinListing, PIN_BASENAMES,
+  deriveReworkCount, projectGuard, parkTask,
+} from "./chore/phase-lib.js";
+import { PHASE as TRIAGE, runPhase as triageRun } from "./chore/phases/triage.js";
+import { PHASE as CAPTURE, runPhase as captureRun } from "./chore/phases/capture.js";
+import { PHASE as MAP, runPhase as mapRun } from "./chore/phases/map.js";
+import { PHASE as BUILD, runPhase as buildRun } from "./chore/phases/build.js";
+import { PHASE as REVIEW, runPhase as reviewRun } from "./chore/phases/review.js";
+import { PHASE as INTEGRATE, runPhase as integrateRun } from "./chore/phases/integrate.js";
+import { PHASE as PUBLISH, runPhase as publishRun } from "./chore/phases/publish.js";
+
+var PHASES = {
+  Triage: { def: TRIAGE, run: triageRun },
+  Capture: { def: CAPTURE, run: captureRun },
+  Map: { def: MAP, run: mapRun },
+  Build: { def: BUILD, run: buildRun },
+  Review: { def: REVIEW, run: reviewRun },
+  Integrate: { def: INTEGRATE, run: integrateRun },
+  Publish: { def: PUBLISH, run: publishRun },
+};
+var PHASE_ORDER = ["Triage", "Capture", "Map", "Build", "Review", "Integrate", "Publish"];
+
+// Runaway guard: REWIND is self-resolving (Map→Capture writes the evidence
+// the gate needs; Review→Build is capped at 2 by the phase itself), so 20
+// phase iterations per invocation is far beyond any legitimate run.
+var MAX_PHASE_ITERATIONS = 20;
+
+var USAGE = [
+  "Usage: node lib/chore-run.js --crew-home <dir> --task-id <id> --tick-seq <n> [options]",
+  "",
+  "Runs one Chore task through the seven worker-layer phases (Triage → Publish).",
+  "Stateless per invocation; stdout is exactly one JSON frame (NEED_SPAWN | WAIT | DONE).",
+  "",
+  "Required:",
+  "  --crew-home <dir>   crew home directory",
+  "  --task-id <id>      task to run",
+  "  --tick-seq <n>      owning tick sequence (positive integer; fills spawn bounds)",
+  "",
+  "Options:",
+  "  --start-step <name>     resume at this phase (Triage|Capture|Map|Build|Review|Integrate|Publish)",
+  "  --project-id <id>       expected project (mid-run project-change guard)",
+  "  --visual-protocol       visual protocol available (overrides project default)",
+  "  --no-visual-protocol    visual protocol unavailable (overrides project default)",
+  "  --resolved-workflow <w> workflow name (defaults to the task's workflow)",
+  "  --workflow-was-null     the dispatcher did not specify a workflow",
+  "  --help                  print this usage",
+].join("\n");
+
+// --help is answered on stdout with exit 0 BEFORE required-argument parsing
+// (lib/AGENTS.md shebang⇔CLI contract) and before the stderr-log patch.
+var RAW_ARGS = process.argv.slice(2);
+if (RAW_ARGS.indexOf("--help") !== -1 || RAW_ARGS.indexOf("-h") !== -1) {
+  process.stdout.write(USAGE + "\n");
+  process.exit(0);
+}
+
+// From here on, all logs go to stderr: stdout carries exactly one JSON
+// frame. phase-lib's log() uses console.log, so it is rerouted here.
+console.log = function () {
+  process.stderr.write(Array.prototype.map.call(arguments, String).join(" ") + "\n");
+};
+console.info = console.log;
+
+function log(message) {
+  process.stderr.write(String(message) + "\n");
+}
+
+function parseArgs(argv) {
+  var o = {
+    crewHome: null, taskId: null, tickSeq: null, startStep: null,
+    projectId: null, visualProtocol: null, resolvedWorkflow: null,
+    workflowWasNull: false, preRefusal: null,
+  };
+  for (var i = 0; i < argv.length; i++) {
+    var a = argv[i];
+    if (a === "--crew-home") o.crewHome = argv[++i];
+    else if (a === "--task-id") o.taskId = argv[++i];
+    else if (a === "--tick-seq") o.tickSeq = argv[++i];
+    else if (a === "--start-step") o.startStep = argv[++i];
+    else if (a === "--project-id") o.projectId = argv[++i];
+    else if (a === "--visual-protocol") o.visualProtocol = true;
+    else if (a === "--no-visual-protocol") o.visualProtocol = false;
+    else if (a === "--resolved-workflow") o.resolvedWorkflow = argv[++i];
+    else if (a === "--workflow-was-null") o.workflowWasNull = true;
+    else if (a === "--pre-refusal") o.preRefusal = argv[++i];
+    else throw new Error("unknown argument: " + a);
+  }
+  if (!o.crewHome) throw new Error("--crew-home is required.");
+  if (!o.taskId) throw new Error("--task-id is required.");
+  if (o.tickSeq === null || o.tickSeq === undefined || o.tickSeq === "") throw new Error("--tick-seq is required.");
+  var n = Number(o.tickSeq);
+  if (!Number.isInteger(n) || n <= 0) throw new Error("--tick-seq must be a positive integer.");
+  o.tickSeq = n;
+  if (o.startStep !== null && PHASE_ORDER.indexOf(o.startStep) === -1) {
+    throw new Error("--start-step must be one of: " + PHASE_ORDER.join("|") + ".");
+  }
+  if (o.preRefusal !== null && TERMINAL_REFUSAL_CODES.indexOf(o.preRefusal) === -1) {
+    throw new Error("--pre-refusal must be one of: " + TERMINAL_REFUSAL_CODES.join("|") + ".");
+  }
+  return o;
+}
+
+// Bootstrap crew-api call: execFile argv only (no shell), against the
+// release's own crew-api.js. Used only until the pins are verified; every
+// decision-making call goes through the pinned copy.
+function bootstrapApi(crewHome, command, args) {
+  return new Promise(function (resolve, reject) {
+    var argv = ["node", crewHome + "/current/lib/crew-api.js", "--crew-home", crewHome, command];
+    if (args !== undefined) argv.push("--json", JSON.stringify(args));
+    execFile(argv[0], argv.slice(1), { timeout: 30000 }, function (err, stdout, stderr) {
+      if (err) { reject(new Error("crew-api " + command + " failed: " + String(stderr || err.message).slice(0, 500))); return; }
+      try { resolve(JSON.parse(String(stdout || ""))); }
+      catch (e) { reject(new Error("crew-api " + command + " returned unparseable JSON")); }
+    });
+  });
+}
+
+// Pinned crew-api call (post-pin): same argv shape, against RUN_LIB.
+function pinnedApi(env, command, args) {
+  return new Promise(function (resolve, reject) {
+    var argv = ["node", env.crewApiPinned, "--crew-home", env.crewHome, command];
+    if (args !== undefined) argv.push("--json", JSON.stringify(args));
+    execFile(argv[0], argv.slice(1), { timeout: 30000 }, function (err, stdout, stderr) {
+      if (err) { reject(new Error("crew-api " + command + " failed: " + String(stderr || err.message).slice(0, 500))); return; }
+      try { resolve(JSON.parse(String(stdout || ""))); }
+      catch (e) { reject(new Error("crew-api " + command + " returned unparseable JSON")); }
+    });
+  });
+}
+
+function errText(e) {
+  return (e && e.message) ? String(e.message) : String(e);
+}
+
+// ── Run telemetry (fire-and-forget: never crashes the invocation) ───────
+// The worker layer's counterpart to the old record-run-start/end. One row
+// per chore run (phase "chore", kind NULL); reused across invocations via
+// get-worker-run so a tick's re-invocation doesn't open a row per pass.
+async function openRunTelemetry(env) {
+  try {
+    var existing = await pinnedApi(env, "get-worker-run", { task_id: env.taskId, phase: "chore" });
+    if (existing && existing.row && existing.row.status === "running") return existing.row.id;
+  } catch (e) { /* no row yet — open one */ }
+  try {
+    var opened = await pinnedApi(env, "record-worker-run", { phase: "chore", task_id: env.taskId, status: "running" });
+    return (opened && opened.id) || null;
+  } catch (e) {
+    log("run telemetry open failed (non-fatal): " + errText(e));
+    return null;
+  }
+}
+
+async function closeRunTelemetry(env, runId, frame) {
+  if (runId === null || runId === undefined) return;
+  var status, error;
+  if (frame.outcome === "completed" || frame.outcome === "stood-down" || frame.outcome === "parked") {
+    status = "completed";
+    error = frame.outcome === "completed" ? null : frame.outcome + (frame.reason ? ": " + frame.reason : "");
+  } else {
+    status = "failed";
+    error = frame.reason || frame.outcome;
+  }
+  try {
+    await pinnedApi(env, "record-worker-run",
+      { id: runId, phase: "chore", status: status, error: error ? String(error).slice(0, 1000) : null });
+  } catch (e) {
+    log("run telemetry close failed (non-fatal): " + errText(e));
+  }
+}
+
+// ── Resume derivation ────────────────────────────────────────────────────
+// All state comes from Crew API reads. A derivation failure throws — the
+// caller fails closed (DONE/failed), never a partial advance.
+function taskSessions(allSessions, taskId) {
+  var out = [];
+  for (var i = 0; i < allSessions.length; i++) {
+    if (allSessions[i] && allSessions[i].task_id === taskId) out.push(allSessions[i]);
+  }
+  out.sort(function (a, b) { return String(a.started_at || "") < String(b.started_at || "") ? -1 : 1; });
+  return out;
+}
+
+// Returns a phase name, or null when Publish already completed (closeout),
+// or {done} for nothing-to-do. Throws on unresolvable state (fail closed).
+function deriveStartPhase(task, sessions, args) {
+  if (task.next_phase) {
+    if (PHASE_ORDER.indexOf(task.next_phase) === -1) {
+      throw new Error("task next_phase \"" + task.next_phase + "\" is not a Chore phase — left set for human inspection.");
+    }
+    return task.next_phase;
+  }
+  if (args.startStep) return args.startStep;
+  if (sessions.length === 0) return "Triage";
+  var latest = sessions[sessions.length - 1];
+  var step = latest.step;
+  if (latest.status === "running") {
+    if (PHASE_ORDER.indexOf(step) === -1) throw new Error("running session has unknown step \"" + step + "\" — failing closed.");
+    return step;
+  }
+  if (latest.status === "completed") {
+    var idx = PHASE_ORDER.indexOf(step);
+    if (idx === -1) throw new Error("completed session has unknown step \"" + step + "\" — failing closed.");
+    if (idx + 1 >= PHASE_ORDER.length) return null; // Publish completed: closeout
+    return PHASE_ORDER[idx + 1];
+  }
+  if (latest.status === "rejected") return "Build"; // rework routing (dispatcher parity)
+  if (latest.status === "failed" || latest.status === "timed_out" || latest.status === "stalled") {
+    if (PHASE_ORDER.indexOf(step) === -1) throw new Error("failed session has unknown step \"" + step + "\" — failing closed.");
+    return step; // dispatcher retry resumes the failed phase
+  }
+  throw new Error("latest session has unresolvable status \"" + latest.status + "\" — failing closed.");
+}
+
+async function doCloseout(env) {
+  var taskId = env.taskId;
+  // Source parity: mark the task done, log the completion event, clean up
+  // the pins. A failed mark fails closed (the task is not done); a failed
+  // completion event after a successful mark is logged but not fatal.
+  try {
+    await pinnedApi(env, "update-task", { id: taskId, state: "done" });
+  } catch (e) {
+    throw new Error("closeout update-task failed: " + errText(e));
+  }
+  try {
+    await pinnedApi(env, "log-event",
+      { task_id: taskId, type: "completed", message: "All chore workflow steps complete." });
+  } catch (e) {
+    log("closeout log-event failed (non-fatal): " + errText(e));
+  }
+  log("Chore run complete for task " + taskId);
+  return { type: "DONE", outcome: "completed", task_id: taskId };
+}
+
+// cleanupPins — the run's last filesystem act on success: remove the
+// per-task pin dir. Runs AFTER the telemetry close (the pinned crew-api.js
+// lives in the pin dir). Best-effort, never fails the run.
+async function cleanupPins(env) {
+  try {
+    rmSync(env.runLib, { recursive: true, force: true });
+  } catch (e) {
+    log("closeout pin cleanup failed (non-fatal): " + errText(e));
+  }
+}
+
+// Handle one phase result. Returns a frame (NEED_SPAWN | WAIT | DONE), or
+// null to continue the loop at result.next (ADVANCE/REWIND).
+async function handlePhaseResult(env, state, args, phaseName, result) {
+  var taskId = env.taskId;
+  switch (result.type) {
+    case "NEED_SPAWN": {
+      // Permanent pre refusal (2026-09-26): the spawn bridge refused this
+      // spawn before opening a ledger row, so re-emitting NEED_SPAWN would
+      // loop forever — no ledger state advances between derivations.
+      // The ferry reports the refusal via --pre-refusal; terminate here
+      // through the normal closeout (pins released, terminal task state
+      // written) instead of burning frame budget.
+      if (args.preRefusal && TERMINAL_REFUSAL_CODES.indexOf(args.preRefusal) !== -1) {
+        var refusalReason = "spawn pre permanently refused (" + args.preRefusal + ")";
+        if (args.preRefusal === "BOUNDS_REJECTED") {
+          // Operational misconfiguration (project bounds), not a task
+          // defect: park for a human to fix the project config and recover.
+          // parkTask writes the parked state and runs terminal cleanup;
+          // convert to the DONE frame here (the PARK case below assumes a
+          // phase already parked, which did not happen on this path).
+          var parked = await parkTask(env, refusalReason + ": spawn bounds invalid — fix the project configuration, then recover the task.");
+          if (parked.type === "PARK_FAILED") {
+            return { type: "DONE", outcome: "park-failed", task_id: taskId, phase: phaseName, reason: parked.reason };
+          }
+          return { type: "DONE", outcome: "parked", task_id: taskId, phase: phaseName, reason: parked.reason };
+        }
+        // Budget/attempt exhaustion is a task-level terminal failure: convert
+        // to the DONE frame directly (the FAILED case below assumes a phase
+        // result, which did not happen on this path).
+        return { type: "DONE", outcome: "failed", task_id: taskId, phase: phaseName,
+          reason: refusalReason + ": the task exhausted its spawn budget." };
+      }
+      var request = result.request || {};
+      request.bounds = request.bounds || {};
+      request.bounds.owner_tick_seq = args.tickSeq;
+      request.owner_tick_seq = args.tickSeq;
+      return { type: "NEED_SPAWN", request: request };
+    }
+    case "STANDBY": {
+      var wait = { type: "WAIT", reason: result.reason, phase: phaseName, task_id: taskId };
+      if (result.key) wait.key = result.key;
+      return wait;
+    }
+    case "STAND_DOWN":
+      return { type: "DONE", outcome: "stood-down", task_id: taskId, phase: phaseName, reason: result.reason };
+    case "PARK":
+      // parkTask already parked the task and ran terminal cleanup.
+      return { type: "DONE", outcome: "parked", task_id: taskId, phase: phaseName, reason: result.reason };
+    case "PARK_FAILED":
+      return { type: "DONE", outcome: "park-failed", task_id: taskId, phase: phaseName, reason: result.reason };
+    case "FAILED":
+      return { type: "DONE", outcome: "failed", task_id: taskId, phase: phaseName,
+        reason: result.reason, detail: result.detail };
+    case "ADVANCE":
+    case "REWIND": {
+      // The phase's typed result seeds the driver's experiential state
+      // (Triage ADVANCE carries it; null leaves any prior value).
+      if (result.experiential === "yes") state.experiential = true;
+      else if (result.experiential === "no") state.experiential = false;
+      if (result.next === null || result.next === undefined) return await doCloseout(env);
+      if (PHASE_ORDER.indexOf(result.next) === -1) {
+        throw new Error("phase " + phaseName + " returned unknown next phase \"" + result.next + "\" — failing closed.");
+      }
+      // Fresh per-phase claim for the next phase (source parity: one
+      // session per phase). Re-derive the rework count — a REWIND just
+      // wrote the rejected event this result was computed from.
+      state.activeSessionId = null;
+      state.reworkCount = await deriveReworkCount(env);
+      return null;
+    }
+    default:
+      throw new Error("phase " + phaseName + " returned unknown result type \"" + result.type + "\" — failing closed.");
+  }
+}
+
+async function runDriver(args) {
+  var crewHome = args.crewHome, taskId = args.taskId;
+
+  // Pin lifecycle first (pure fs — no crew-api needed). Persistent disk,
+  // NOT /tmp (tmpfs is wiped on cell reboot — canary b5efd1b1).
+  var runLib = crewHome + "/.pins/" + taskId;
+  var pinsOk = false;
+  try {
+    pinLifecycle({ crewHome: crewHome, runLib: runLib });
+    var listing = parsePinListing({ listing: readdirSync(runLib).join("\n") });
+    pinsOk = PIN_BASENAMES.every(function (b) { return listing.indexOf(b) !== -1; });
+  } catch (e) {
+    throw new Error("pin lifecycle failed: " + errText(e));
+  }
+
+  // Bootstrap reads (task + project) through the release's own crew-api.
+  var st = await bootstrapApi(crewHome, "get-state", { events_limit: 1 });
+  var task = null;
+  var tasks = (st && st.tasks) || [];
+  for (var i = 0; i < tasks.length; i++) if (tasks[i].id === taskId) { task = tasks[i]; break; }
+  if (!task) throw new Error("task " + taskId + " not found — failing closed.");
+  var project = await bootstrapApi(crewHome, "get-project", { id: task.project });
+  project = (project && project.project) || null;
+  if (!project || !project.id) throw new Error("project " + task.project + " not found — failing closed.");
+  var repoPath = project.repo_path || "";
+  if (!repoPath) throw new Error("Project '" + project.id + "' has no repo_path configured — failing closed.");
+
+  var visualProtocol = args.visualProtocol !== null ? args.visualProtocol : (project.visual_protocol === true);
+  var resolvedWorkflow = args.resolvedWorkflow || task.workflow || null;
+  var workflowWasNull = args.workflowWasNull || (!args.resolvedWorkflow && !task.workflow);
+
+  var env = deriveRunEnv({
+    crewHome: crewHome, taskId: taskId,
+    repoPath: repoPath, orchPath: crewHome + "/.orchestration", runLib: runLib,
+    lifecycle: runLib + "/worktree-lifecycle.sh",
+    mergeLock: runLib + "/merge-lock.sh",
+    publishNpm: runLib + "/publish-npm.sh",
+    computeDiff: runLib + "/compute-publish-diff.js",
+    crewApi: crewHome + "/current/lib/crew-api.js",
+    crewApiPinned: runLib + "/crew-api.js",
+    taskTitle: task.title, taskDescription: task.description,
+    projectId: task.project, projectConfig: project,
+    visualProtocol: visualProtocol,
+    workflowWasNull: workflowWasNull, resolvedWorkflow: resolvedWorkflow,
+  });
+
+  // The pins gate the run: an incomplete pin set parks the task for human
+  // attention (source parity), exactly like the source's pin-verification.
+  if (!pinsOk) {
+    var parked = await parkTask(env, "Pin verification failed — required lifecycle scripts missing from " + runLib);
+    if (parked.type === "PARK") return { type: "DONE", outcome: "parked", task_id: taskId, reason: parked.reason };
+    return { type: "DONE", outcome: "park-failed", task_id: taskId, reason: parked.reason };
+  }
+
+  // Nothing to do for terminal tasks.
+  if (task.state === "done" || task.state === "cancelled" || task.state === "parked") {
+    return { type: "DONE", outcome: "stood-down", task_id: taskId, reason: "task already " + task.state };
+  }
+  // The driver only runs Chore tasks.
+  if (resolvedWorkflow && resolvedWorkflow !== "chore") {
+    throw new Error("task workflow is \"" + resolvedWorkflow + "\", not chore — refusing to run the chore driver.");
+  }
+  // Optional launch-project guard (the tick worker passes the dispatch
+  // claim's project; the per-phase projectGuard re-checks it).
+  if (args.projectId && args.projectId !== task.project) {
+    throw new Error("task project changed from '" + args.projectId + "' to '" + task.project + "' — failing closed.");
+  }
+
+  var sessions = taskSessions((st && st.sessions) || [], taskId);
+  var running = null;
+  for (var s = 0; s < sessions.length; s++) {
+    if (sessions[s].status === "running") { running = sessions[s]; break; }
+  }
+  var state = {
+    activeSessionId: running ? running.id : null,
+    reworkCount: await deriveReworkCount(env),
+    isFirstClaimVisit: sessions.length === 0,
+    nextPhaseRouted: task.next_phase || null,
+    experiential: undefined,
+    memo: {},
+  };
+
+  var runId = await openRunTelemetry(env);
+
+  var frame;
+  try {
+    frame = await driveLoop(env, state, args, task, sessions);
+  } catch (e) {
+    var msg = errText(e);
+    // A mid-run terminal transition (done/cancelled under us) is a
+    // stand-down, not a failure.
+    var terminalRace = /already done|cancelled/i.test(msg);
+    frame = {
+      type: "DONE",
+      outcome: terminalRace ? "stood-down" : "failed",
+      task_id: taskId,
+      reason: (terminalRace ? "stood down: " : "driver error: ") + msg,
+    };
+  }
+  if (frame.type === "DONE") await closeRunTelemetry(env, runId, frame);
+  // Pin cleanup lands after the telemetry close: the pinned crew-api.js
+  // the close runs through lives inside the pin dir.
+  if (frame.type === "DONE" && frame.outcome === "completed") await cleanupPins(env);
+  return frame;
+}
+
+async function driveLoop(env, state, args, task, sessions) {
+  var taskId = env.taskId;
+  var start = deriveStartPhase(task, sessions, args);
+  if (start === null) return await doCloseout(env);
+
+  var current = start;
+  for (var iter = 0; iter < MAX_PHASE_ITERATIONS; iter++) {
+    var phase = PHASES[current];
+    var guard = await projectGuard(env, state, phase.def);
+    if (!guard.ok) {
+      return { type: "DONE", outcome: "failed", task_id: taskId, phase: current, reason: guard.reason };
+    }
+    var result = await phase.run({ env: env, state: state });
+    var frame = await handlePhaseResult(env, state, args, current, result);
+    if (frame) return frame;
+    current = result.next;
+  }
+  throw new Error("runaway guard: exceeded " + MAX_PHASE_ITERATIONS + " phase iterations — failing closed.");
+}
+
+async function main() {
+  var args;
+  try {
+    args = parseArgs(RAW_ARGS);
+  } catch (e) {
+    process.stderr.write(USAGE + "\n\nError: " + errText(e) + "\n");
+    process.exit(2);
+  }
+  var frame;
+  try {
+    frame = await runDriver(args);
+  } catch (e) {
+    // Even a catastrophic setup failure emits the one JSON frame.
+    frame = { type: "DONE", outcome: "failed", task_id: args.taskId || null, reason: "driver error: " + errText(e) };
+  }
+  process.stdout.write(JSON.stringify(frame) + "\n");
+}
+
+// Import-safe: no side effects on import. main() runs only on direct
+// execution; bare `node lib/chore-run.js` reports the usage error (exit 2),
+// matching the other lib CLIs.
+var isDirectExecution = false;
+try {
+  isDirectExecution = !!process.argv[1] &&
+    import.meta.url === pathToFileURL(process.argv[1]).href;
+} catch (e) { /* conservative: do not run */ }
+if (isDirectExecution) {
+  main().catch(function (e) {
+    try {
+      process.stdout.write(JSON.stringify({
+        type: "DONE", outcome: "failed", task_id: null,
+        reason: "driver error: " + errText(e),
+      }) + "\n");
+    } catch (e2) { /* stdout itself failed */ }
+    process.exit(1);
+  });
+}