muse-crew 0.17.2 → 0.17.3

package/lib/workflow-driver.js

@@ -0,0 +1,605 @@
+#!/usr/bin/env node
+// lib/workflow-driver.js — the generic workflow driver (composition
+// machinery, Phase B, 2026-09-26): a mechanical extraction of the driver
+// core from lib/chore-run.js, parameterized by a workflow spec instead of
+// hardcoded phases.
+//
+// The tick worker invokes this once per tick for a dispatched task:
+//   node lib/workflow-driver.js --spec <path> --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.
+//
+// The spec (lib/workflow-spec.js) declares composition: ordered phases,
+// named transitions, guard references. Phase modules are loaded by dynamic
+// import from the spec's module refs and must export PHASE + runPhase.
+// The driver never imports phase modules by name — module refs come from
+// the spec. (Runtime helpers still come from chore's phase-lib;
+// generalizing that library is Phase C/D work.)
+//
+// PROTOCOL NOTE (from chore-run.js, 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 { dirname, resolve } from "node:path";
+
+import { loadSpec, phaseModuleUrl } from "./workflow-spec.js";
+// Runtime helpers (Phase B generalized, Phase D): the run environment, pin
+// lifecycle, guards, and parking live in the workflow-neutral library.
+// Workflow-specific runtime values (project description fallback, prompt
+// template directory) arrive declaratively through the spec — the driver
+// stays free of workflow-shaped conditionals.
+import {
+  deriveRunEnv, pinLifecycle, parsePinListing, PIN_BASENAMES,
+  deriveReworkCount, projectGuard, parkTask,
+} from "./workflow-lib.js";
+
+// 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/workflow-driver.js --spec <path> --crew-home <dir> --task-id <id> --tick-seq <n> [options]",
+  "",
+  "Runs one task through the phases declared by a workflow spec JSON.",
+  "Stateless per invocation; stdout is exactly one JSON frame (NEED_SPAWN | WAIT | DONE).",
+  "",
+  "Required:",
+  "  --spec <path>       workflow spec JSON (see lib/workflow-spec.js)",
+  "  --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 (must name a spec phase)",
+  "  --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; must match the spec)",
+  "  --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 = {
+    spec: null, 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 === "--spec") o.spec = argv[++i];
+    else 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.spec) throw new Error("--spec is required.");
+  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;
+  // --start-step values come from the spec: validated after spec load.
+  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;
+}
+
+// Load the spec's phase modules by dynamic import. Each module must export
+// PHASE (the phase definition, incl. identity for the project guard) and
+// runPhase (the phase runner). Returns {name: {def, run}}.
+async function loadPhases(spec, specPath) {
+  var phases = {};
+  for (var i = 0; i < spec.phases.length; i++) {
+    var entry = spec.phases[i];
+    var mod;
+    try {
+      mod = await import(phaseModuleUrl(specPath, entry.module));
+    } catch (e) {
+      throw new Error("phase \"" + entry.name + "\": cannot load module " + entry.module + ": " + errText(e));
+    }
+    if (!mod.PHASE || typeof mod.PHASE !== "object" || Array.isArray(mod.PHASE) || typeof mod.runPhase !== "function") {
+      throw new Error("phase \"" + entry.name + "\": module must export PHASE (object) and runPhase (function).");
+    }
+    phases[entry.name] = { def: mod.PHASE, run: mod.runPhase };
+  }
+  return phases;
+}
+
+// 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);
+}
+
+// displayName — the spec's workflow name with an initial capital, for
+// human-facing messages (matches chore-run.js's "Chore" capitalization).
+function displayName(spec) {
+  var w = spec.workflow || "";
+  return w.charAt(0).toUpperCase() + w.slice(1);
+}
+
+// ── Run telemetry (fire-and-forget: never crashes the invocation) ───────
+// The worker layer's counterpart to the old record-run-start/end. One row
+// per run (phase = spec workflow name, 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, spec) {
+  try {
+    var existing = await pinnedApi(env, "get-worker-run", { task_id: env.taskId, phase: spec.workflow });
+    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: spec.workflow, 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, spec, 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: spec.workflow, 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 the last spec phase already completed
+// (closeout), or {done} for nothing-to-do. Throws on unresolvable state
+// (fail closed).
+function deriveStartPhase(task, sessions, args, spec) {
+  var order = spec.phaseNames;
+  if (task.next_phase) {
+    if (order.indexOf(task.next_phase) === -1) {
+      throw new Error("task next_phase \"" + task.next_phase + "\" is not a " + displayName(spec) + " phase — left set for human inspection.");
+    }
+    return task.next_phase;
+  }
+  if (args.startStep) return args.startStep;
+  if (sessions.length === 0) return order[0];
+  var latest = sessions[sessions.length - 1];
+  var step = latest.step;
+  if (latest.status === "running") {
+    if (order.indexOf(step) === -1) throw new Error("running session has unknown step \"" + step + "\" — failing closed.");
+    return step;
+  }
+  if (latest.status === "completed") {
+    var idx = order.indexOf(step);
+    if (idx === -1) throw new Error("completed session has unknown step \"" + step + "\" — failing closed.");
+    if (idx + 1 >= order.length) return null; // last phase completed: closeout
+    return order[idx + 1];
+  }
+  if (latest.status === "rejected") {
+    // Rework routing (dispatcher parity in the chore port): a rejected
+    // session resumes at the spec's declared rework entry point. The
+    // rework target is workflow knowledge, so it lives in the spec —
+    // undeclared is unresolvable, and unresolvable fails closed.
+    if (!spec.rejectedResume) {
+      throw new Error("latest session is rejected but the spec declares no rejectedResume — failing closed.");
+    }
+    return spec.rejectedResume;
+  }
+  if (latest.status === "failed" || latest.status === "timed_out" || latest.status === "stalled") {
+    if (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, spec) {
+  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 " + spec.workflow + " workflow steps complete." });
+  } catch (e) {
+    log("closeout log-event failed (non-fatal): " + errText(e));
+  }
+  log(displayName(spec) + " 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, spec, 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 the boolean from extractExperiential;
+      // null leaves any prior value).
+      if (result.experiential === true) state.experiential = true;
+      else if (result.experiential === false) state.experiential = false;
+      // Map-gate bounce counter (Standard): a REWIND to Capture needs fresh
+      // spawn keys on the re-visit. Only Capture reads this, and Capture is
+      // never re-visited via rework REWINDs, so incrementing on every REWIND
+      // is safe.
+      if (result.type === "REWIND") state.gateBounceCount = (state.gateBounceCount || 0) + 1;
+      if (result.next === null || result.next === undefined) return await doCloseout(env, spec);
+      if (spec.phaseNames.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, spec);
+      return null;
+    }
+    default:
+      throw new Error("phase " + phaseName + " returned unknown result type \"" + result.type + "\" — failing closed.");
+  }
+}
+
+async function runDriver(args, spec) {
+  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);
+
+  // Workflow-declared runtime values (spec-driven, no workflow conditionals):
+  // the project description fallback and the prompt-template directory,
+  // resolved against the spec file's directory (phaseModuleUrl's rule).
+  var specPromptsDir = spec.promptsDir
+    ? resolve(dirname(resolve(args.spec)), spec.promptsDir)
+    : undefined;
+  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,
+    projectDescFallback: spec.projectDescFallback || undefined,
+    promptsDir: specPromptsDir,
+  });
+
+  // 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 tasks for the spec's workflow.
+  if (resolvedWorkflow && resolvedWorkflow !== spec.workflow) {
+    throw new Error("task workflow is \"" + resolvedWorkflow + "\" but the spec declares \"" + spec.workflow + "\" — refusing.");
+  }
+  // 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 phases = await loadPhases(spec, args.spec);
+
+  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, spec),
+    gateBounceCount: 0,
+    isFirstClaimVisit: sessions.length === 0,
+    nextPhaseRouted: task.next_phase || null,
+    experiential: undefined,
+    memo: {},
+  };
+
+  var runId = await openRunTelemetry(env, spec);
+
+  var frame;
+  try {
+    frame = await driveLoop(env, state, args, spec, phases, 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, spec, 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, spec, phases, task, sessions) {
+  var taskId = env.taskId;
+  var start = deriveStartPhase(task, sessions, args, spec);
+  if (start === null) return await doCloseout(env, spec);
+
+  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, spec, 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 spec;
+  try {
+    spec = loadSpec(args.spec);
+    if (args.startStep !== null && spec.phaseNames.indexOf(args.startStep) === -1) {
+      throw new Error("--start-step must be one of: " + spec.phaseNames.join("|") + ".");
+    }
+  } catch (e) {
+    process.stderr.write(USAGE + "\n\nError: " + errText(e) + "\n");
+    process.exit(2);
+  }
+  var frame;
+  try {
+    frame = await runDriver(args, spec);
+  } 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/workflow-driver.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);
+  });
+}