muse-crew 0.17.2 → 0.17.3

package/lib/chore/phase-lib.js

@@ -0,0 +1,885 @@
+// lib/chore/phase-lib.js — shared deterministic operations for the
+// worker-layer chore phase modules (sandbox exit, Piece 2).
+//
+// Import-safe: no side effects on import, bare `node` exits 0. All I/O goes
+// through execFile with argv only (never shell, never bare exec) or through
+// the pinned crew-api CLI. No creative-boundary calls anywhere in this file — the only
+// crossings are NEED_SPAWN results returned to the driver.
+//
+// The ctx contract (see lib/chore/CONTRACT.md):
+//   ctx.env   — static run config (paths, task facts, project config)
+//   ctx.state — derived per-pass scalars (phase, session, counters, handoffs)
+
+import { execFile } from "node:child_process";
+import {
+  readFileSync, writeFileSync, appendFileSync, mkdirSync,
+  copyFileSync, chmodSync, existsSync, statSync, readlinkSync, readdirSync,
+} from "node:fs";
+import { join, dirname, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  extractVerdict, extractMarkerLines, parseToolSignals,
+  extractReleaseDecision, extractWorktree, extractExperiential,
+} from "./extract.js";
+import { buildTransportRetryTrailer } from "./prompts/trailers.js";
+import { workKeyBase, workRetryKey, verdictReaskKey, attemptKey } from "./spawn-keys.js";
+
+const LIB_DIR = dirname(fileURLToPath(import.meta.url));
+export const PROMPTS_DIR = join(LIB_DIR, "prompts");
+
+// Workflow log line. Phase modules prefix with their step name, mirroring
+// the source's log() call sites.
+export function log(message) {
+  console.log(message);
+}
+
+// ── argv-only command runner ────────────────────────────────────────────
+// execFile, never shell. Rejects with an Error carrying .stdout/.stderr/.code.
+export function runCmd(argv, opts) {
+  var o = opts || {};
+  return new Promise(function (resolve, reject) {
+    execFile(argv[0], argv.slice(1), {
+      cwd: o.cwd,
+      env: o.env,
+      encoding: "utf8",
+      maxBuffer: 16 * 1024 * 1024,
+      timeout: o.timeout_ms || 300000,
+    }, function (err, stdout, stderr) {
+      if (err) {
+        var e = new Error(
+          "command failed: " + argv[0] + " " + argv.slice(1).join(" ") +
+          " (code " + err.code + (err.killed ? ", killed" : "") + "): " +
+          String(stderr || stdout || err.message).slice(0, 500)
+        );
+        e.stdout = String(stdout || "");
+        e.stderr = String(stderr || "");
+        e.code = err.code;
+        reject(e);
+        return;
+      }
+      resolve({ stdout: String(stdout || ""), stderr: String(stderr || "") });
+    });
+  });
+}
+
+// ── Pinned crew-api caller ──────────────────────────────────────────────
+// Mirrors spawn-step.js callCrewApi: node <pinned-api> --crew-home <home>
+// <command> --json '<args>'. Throws with the CLI's stderr on failure.
+export async function crewApi(env, command, args) {
+  var argv = ["node", env.crewApiPinned, "--crew-home", env.crewHome, command];
+  if (args !== undefined) argv.push("--json", JSON.stringify(args));
+  var out;
+  try {
+    out = await runCmd(argv);
+  } catch (e) {
+    throw new Error("crew-api " + command + " failed: " + (e.stderr || e.message).slice(0, 500));
+  }
+  try {
+    return JSON.parse(out.stdout);
+  } catch (e) {
+    throw new Error("crew-api " + command + " returned unparseable JSON");
+  }
+}
+
+// ── Pinned script runners ───────────────────────────────────────────────
+// The lifecycle and merge-lock scripts take CREW_HOME/CREW_REPO in the
+// environment (LIFECYCLE_ENV in the source). argv only, never shell.
+function scriptEnv(env) {
+  return Object.assign({}, process.env, {
+    CREW_HOME: env.crewHome,
+    CREW_REPO: env.repoPath,
+  });
+}
+
+export function lifecycle(env, subcommand, args) {
+  return runCmd([env.lifecycle, subcommand].concat(args || []), { env: scriptEnv(env) });
+}
+
+export function mergeLock(env, subcommand, args) {
+  return runCmd([env.mergeLock, subcommand].concat(args || []), { env: scriptEnv(env) });
+}
+
+// ── Crew API conveniences ───────────────────────────────────────────────
+
+export async function logEvent(env, entry) {
+  return crewApi(env, "log-event", entry);
+}
+
+export async function recordPhase(env, payload) {
+  return crewApi(env, "record-phase", payload);
+}
+
+export async function getEvents(env, taskId, limit) {
+  var args = { task_id: taskId };
+  if (limit !== undefined) args.limit = limit;
+  var res = await crewApi(env, "get-events", args);
+  return (res && res.events) || [];
+}
+
+export async function getSpawnRow(env, key) {
+  try {
+    var res = await crewApi(env, "get-spawn-row", { spawn_key: key });
+    return (res && res.row) || null;
+  } catch (e) {
+    if (/not found/i.test(e.message)) return null;
+    throw e;
+  }
+}
+
+// ── Pin lifecycle scripts (pure Node — no shell, no agent) ─────────────
+// Verbatim port of the pinLifecycle courier's shell: mkdir -p RUN_LIB,
+// copy the 11 pinned scripts, chmod +x the three executables. Returns the
+// basenames present (parsePinListing of an ls -1 equivalent).
+const PIN_FILES = [
+  ["lib/worktree-lifecycle.sh", "worktree-lifecycle.sh", true],
+  ["lib/merge-lock.sh", "merge-lock.sh", true],
+  ["lib/publish-npm.sh", "publish-npm.sh", true],
+  ["current/lib/crew-api.js", "crew-api.js", false],
+  ["lib/schema.sql", "schema.sql", false],
+  ["current/lib/compute-publish-diff.js", "compute-publish-diff.js", false],
+  ["current/lib/classify-surface.js", "classify-surface.js", false],
+  ["current/lib/publish-note-vocabulary.js", "publish-note-vocabulary.js", false],
+  ["current/lib/qa-deploy.mjs", "qa-deploy.mjs", false],
+  ["current/lib/serve-artifact.js", "serve-artifact.js", false],
+  ["current/lib/qa-db.js", "qa-db.js", false],
+];
+
+export const PIN_BASENAMES = PIN_FILES.map(function (f) { return f[1]; });
+
+export function pinLifecycle(env) {
+  mkdirSync(env.runLib, { recursive: true });
+  var present = [];
+  for (var i = 0; i < PIN_FILES.length; i++) {
+    var src = join(env.crewHome, PIN_FILES[i][0]);
+    var dst = join(env.runLib, PIN_FILES[i][1]);
+    copyFileSync(src, dst);
+    if (PIN_FILES[i][2]) chmodSync(dst, 0o755);
+    present.push(PIN_FILES[i][1]);
+  }
+  return present;
+}
+
+// parsePinListing — basenames from a pin/verify listing. Verbatim from
+// workflows/chore.js (byte-identical across standard/bugfix/chore).
+export function parsePinListing(result) {
+  return (result && result.listing ? result.listing : "").split("\n").map(function (s) { return s.trim(); }).filter(function (s) { return s.length > 0; });
+}
+
+// ── Spawn-boundary plumbing ─────────────────────────────────────────────
+// Bounds for a creative-spawn pre request. owner_tick_seq is filled by the
+// driver (the only writer that knows the tick).
+export function buildSpawnBounds(env, kind) {
+  return {
+    prompt_file: join(PROMPTS_DIR, kind === "work-agent" ? "work-agent.js" : kind + ".js"),
+    schema_file: join(PROMPTS_DIR, kind + ".schema.json"),
+    cwd: env.repoPath,
+    env: {},
+    workdir: env.repoPath,
+    crewHome: env.crewHome,
+  };
+}
+
+// NEED_SPAWN result. The driver fills owner_tick_seq and posts the pre
+// request to the spawn bridge; the phase resumes on the next pass.
+export function needSpawn(request) {
+  return { type: "NEED_SPAWN", request: request };
+}
+
+// workRequest — a work-agent pre request for the boundary. Every prompt
+// param is declared (P1); the trailer is a pure function of the prior
+// transport failure.
+export function workRequest(env, state, spec) {
+  var trailer = spec.trailer || "";
+  return {
+    key: spec.key,
+    kind: "work-agent",
+    task_id: env.taskId,
+    phase: spec.phase,
+    identity: spec.identity,
+    timeout_ms: 3600000,
+    bounds: buildSpawnBounds(env, "work-agent"),
+    prompt_params: {
+      identity: spec.identity,
+      orch_path: env.orchPath,
+      task_title: env.taskTitle,
+      task_description: env.taskDescription,
+      task_id: env.taskId,
+      step_name: spec.phase,
+      instructions: spec.instructions,
+      crew_api: spec.crewApiLine === false ? "" : env.crewApiPinned,
+      event_preamble: spec.eventPreamble,
+      transport_retry_trailer: trailer,
+    },
+  };
+}
+
+// reaskRequest — a verdict-reask pre request. Always reads from the work
+// report's own content (never copies a VERDICT line).
+export function reaskRequest(env, state, spec) {
+  return {
+    key: spec.key,
+    kind: "verdict-reask",
+    task_id: env.taskId,
+    phase: spec.phase,
+    identity: "verdict-reask",
+    timeout_ms: 180000,
+    bounds: buildSpawnBounds(env, "verdict-reask"),
+    prompt_params: {
+      step_name: spec.phase,
+      worker_text: spec.workerText,
+    },
+  };
+}
+
+// ── Spawn session text ──────────────────────────────────────────────────
+// Reads the pinned session file the bridge wrote for a completed spawn.
+// Returns null on any read/parse failure (treated as unusable output).
+export function readSessionText(env, key) {
+  try {
+    var raw = readFileSync(join(env.crewHome, ".spawn-sessions", key + ".json"), "utf8");
+    var obj = JSON.parse(raw);
+    return typeof obj.text === "string" ? obj.text : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+// ── Boundary internals ──────────────────────────────────────────────────
+// Terminal rows are the bridge's closed vocabulary (lib/crew-api.js
+// CLOSED_OUTCOMES): completed, synthetic, transport_timeout, transport_error,
+// transport_empty, transport_parse, killed_confirmed, killed_by_reaper,
+// orphaned_unkillable, orphaned_unverified, transport_failed. A row whose
+// status is still "running" is not terminal — the boundary stands by.
+function isTerminalRow(row) {
+  return !!row && row.status !== "running";
+}
+
+// classifyRow — maps a terminal spawn-ledger row to the source work loop's
+// attempt lanes. Returns one of:
+//   {lane: "report", text}      completed with usable session text
+//   {lane: "no-tools"}          report says artifact_tools: missing
+//   {lane: "no-transport"}      report says shell_transport: unavailable
+//   {lane: "empty"}             no usable text (blank/transport_empty)
+//   {lane: "threw", error}      transport_error / kills / other failures
+function classifyRow(env, key, row) {
+  // The outcome lives in the result JSON's closed vocabulary (there is no
+  // outcome column — record-spawn-close stores it inside result).
+  var outcome = null;
+  try {
+    var res = row.result ? JSON.parse(row.result) : null;
+    outcome = (res && typeof res.outcome === "string") ? res.outcome : null;
+  } catch (e) { /* keep null */ }
+  if (outcome === "completed" || outcome === "synthetic") {
+    var text = readSessionText(env, key);
+    if (text === null || text.trim().length === 0) return { lane: "empty" };
+    var signals = parseToolSignals(text);
+    if (signals.artifactTools === "missing") return { lane: "no-tools", text: text };
+    if (signals.shellTransport === "unavailable") return { lane: "no-transport", text: text };
+    return { lane: "report", text: text };
+  }
+  if (outcome === "transport_empty") return { lane: "empty" };
+  var errDetail = "";
+  try {
+    var res2 = row.result ? JSON.parse(row.result) : null;
+    errDetail = (res2 && res2.error) || "";
+  } catch (e) { /* keep empty */ }
+  if (outcome === "transport_error") {
+    return { lane: "threw", error: String(errDetail).replace(/"/g, "'").slice(0, 160) };
+  }
+  // Kills, timeouts, orphans, and unknown terminal outcomes are transport
+  // failures the source loop would have seen as a thrown worker call.
+  return { lane: "threw", error: String(outcome + (errDetail ? ": " + errDetail : "")).replace(/"/g, "'").slice(0, 160) };
+}
+
+// describeWorkAgentFailure — honest classification of a work-agent call that
+// yielded no usable report, with the per-attempt evidence preserved in the
+// session notes. Verbatim from workflows/chore.js (returns
+// {notes, eventMessage, blockedReason, message}).
+export function describeWorkAgentFailure(stepName, identity, attempts) {
+  var parts = [];
+  for (var i = 0; i < attempts.length; i++) {
+    var a = attempts[i];
+    parts.push("attempt " + (i + 1) + "/" + attempts.length + ": " +
+      (a.threw ? "threw '" + a.error + "'" : "returned " + a.outcome));
+  }
+  var detail = parts.join("; ").replace(/"/g, "'").slice(0, 400);
+  var anyThrow = false;
+  for (var j = 0; j < attempts.length; j++) {
+    if (attempts[j].threw) { anyThrow = true; break; }
+  }
+  if (anyThrow) {
+    return {
+      notes: "Work agent produced no machine-readable report after " + attempts.length + " attempts; runtime discarded the output (" + detail + ")",
+      eventMessage: stepName + " work agent produced no machine-readable report after " + attempts.length + " attempts — phase failed, dispatcher will retry",
+      blockedReason: stepName + " work agent produced no machine-readable report after " + attempts.length + " attempts",
+      message: "The " + identity + " agent's output could not be machine-read (" + attempts.length + " attempts exhausted); the runtime discarded the raw output before the workflow could see it. Surviving evidence: " + detail
+    };
+  }
+  return {
+    notes: "Work agent returned no usable output after " + attempts.length + " attempts (" + detail + ")",
+    eventMessage: stepName + " work agent returned no usable output after " + attempts.length + " attempts — phase failed, dispatcher will retry",
+    blockedReason: stepName + " work agent returned no usable output",
+    message: "The " + identity + " agent returned no usable output after " + attempts.length + " attempts (" + detail + ")."
+  };
+}
+
+// buildFailureAttempts — source-shaped workAttempts entries from the terminal
+// ledger rows, for describeWorkAgentFailure.
+export async function buildFailureAttempts(env, state, phase) {
+  var suffix = state.reworkCount > 0 ? "-r" + state.reworkCount : "";
+  var keys = [
+    workKeyBase(env.taskId, phase, state.reworkCount),
+    workRetryKey(env.taskId, phase, suffix, 1),
+    workRetryKey(env.taskId, phase, suffix, 2),
+  ];
+  var attempts = [];
+  for (var i = 0; i < keys.length; i++) {
+    var row = await getSpawnRow(env, keys[i]);
+    if (!row || !isTerminalRow(row)) continue;
+    var c = classifyRow(env, keys[i], row);
+    if (c.lane === "report") continue;
+    if (c.lane === "threw") {
+      attempts.push({ threw: true, error: c.error, outcome: "" });
+    } else if (c.lane === "empty") {
+      attempts.push({ threw: false, error: "", outcome: "blank string" });
+    } else if (c.lane === "no-tools") {
+      attempts.push({ threw: false, error: "", outcome: "missing-artifact-tools" });
+    } else if (c.lane === "no-transport") {
+      attempts.push({ threw: false, error: "", outcome: "unavailable-shell-transport" });
+    }
+  }
+  if (attempts.length === 0) {
+    attempts.push({ threw: false, error: "", outcome: "no record" });
+  }
+  return attempts;
+}
+
+// ── The shared creative boundary ────────────────────────────────────────
+// Verbatim port of the source phase work loop (work-agent attempts,
+// transport-retry trailers, deterministic verdict extraction, bounded
+// verdict re-ask). It consumes terminal spawn-ledger rows instead of
+// in-process worker calls; it never spawns itself. The driver acts on
+// NEED_SPAWN/STANDBY and re-invokes the phase on the next pass.
+// spec: {phase, identity, instructions, eventPreamble, crewApiLine}
+// Returns:
+//   {type: "NEED_SPAWN", request}   — post this pre via the spawn bridge
+//   {type: "STANDBY", reason}       — a spawn is still running; wait
+//   {type: "BOUNDARY_DONE", workerText, verdictPassed}
+//   {type: "FAILED", reason, detail} — failure recorded; the run stops
+export async function runWorkBoundary(env, state, spec) {
+  var phase = spec.phase, identity = spec.identity;
+  var suffix = state.reworkCount > 0 ? "-r" + state.reworkCount : "";
+  var workKeys = [
+    workKeyBase(env.taskId, phase, state.reworkCount),
+    workRetryKey(env.taskId, phase, suffix, 1),
+    workRetryKey(env.taskId, phase, suffix, 2),
+  ];
+  var attempts = [];
+  var workerText = null;
+  for (var i = 0; i < workKeys.length; i++) {
+    var row = await getSpawnRow(env, workKeys[i]);
+    if (!row) {
+      // The driver has not posted this attempt yet. Attempt 0 carries no
+      // trailer; retries carry the trailer derived from the previous
+      // attempt's failure mode (source: retryReason).
+      var trailer = "";
+      if (i > 0) {
+        var prev = attempts[i - 1];
+        var retryReason = prev.threw ? "discarded"
+          : prev.outcome === "missing-artifact-tools" ? "no-tools"
+          : prev.outcome === "unavailable-shell-transport" ? "no-transport"
+          : "empty";
+        trailer = buildTransportRetryTrailer(phase, env.repoPath, env.taskId, i, retryReason);
+        log(phase + " work agent transport retry " + i + " of 2 — requesting spawn " + workKeys[i]);
+      }
+      return needSpawn(workRequest(env, state, {
+        key: workKeys[i], phase: phase, identity: identity,
+        instructions: spec.instructions, eventPreamble: spec.eventPreamble,
+        crewApiLine: spec.crewApiLine, trailer: trailer,
+      }));
+    }
+    if (!isTerminalRow(row)) {
+      return { type: "STANDBY", reason: phase + " work attempt " + (i + 1) + " of 3 still running (" + workKeys[i] + ")", key: workKeys[i] };
+    }
+    var c = classifyRow(env, workKeys[i], row);
+    if (c.lane === "report") {
+      if (i > 0) log(phase + " work agent transport retry " + i + " returned a machine-readable report");
+      workerText = c.text;
+      break;
+    }
+    if (c.lane === "threw") {
+      attempts.push({ threw: true, error: c.error, outcome: "" });
+      log(phase + " work agent attempt " + (i + 1) + " of 3 threw: " + c.error);
+    } else if (c.lane === "empty") {
+      attempts.push({ threw: false, error: "", outcome: "blank string" });
+      log(phase + " work agent attempt " + (i + 1) + " of 3 returned no usable output (blank string) — retrying with a fresh key");
+    } else if (c.lane === "no-tools") {
+      attempts.push({ threw: false, error: "", outcome: "missing-artifact-tools" });
+      log(phase + " work agent attempt " + (i + 1) + " of 3 reported artifact_tools: missing — retrying with a fresh launch");
+    } else {
+      attempts.push({ threw: false, error: "", outcome: "unavailable-shell-transport" });
+      log(phase + " work agent attempt " + (i + 1) + " of 3 reported shell_transport: unavailable — retrying with a fresh launch");
+    }
+  }
+
+  if (typeof workerText !== "string" || !workerText.trim()) {
+    // All three attempts exhausted with no usable report — the phase fails
+    // for dispatcher retry (session "failed", NOT "blocked": blocked
+    // sessions are never picked up again).
+    var failure = describeWorkAgentFailure(phase, identity, attempts);
+    var notes = failure.notes + " If the step's work is actually complete, the task can be re-launched from " + phase + ".";
+    log(phase + " " + notes + " — marking failed for retry");
+    await recordPhase(env, {
+      task_id: env.taskId,
+      session: { id: state.activeSessionId, task_id: env.taskId, identity: identity, step: phase, status: "failed", notes: notes },
+      event: { task_id: env.taskId, type: "failed", message: failure.eventMessage },
+    });
+    return { type: "FAILED", reason: failure.blockedReason, detail: failure.message };
+  }
+
+  // Verdict derivation (deterministic): for VERDICT_STEPS (Build, Review,
+  // Integrate, Publish) the workflow owns the verdict — extracted by regex
+  // from the report text, never by an agent. A missing/malformed verdict
+  // gets a bounded mechanical re-ask before the phase fails closed. For
+  // non-verdict steps (Triage, Capture, Map) the worker producing output
+  // means the step passed.
+  var verdictPassed = null;
+  if (spec.verdictStep) {
+  var verdict = extractVerdict(workerText);
+  if (!verdict.ok) {
+    log(phase + " verdict line missing or ambiguous (" + verdict.count + " trailing-window matches) — attempting bounded re-ask");
+    var reasked = await runVerdictReask(env, state, phase, workerText);
+    if (reasked.type === "NEED_SPAWN" || reasked.type === "STANDBY") return reasked;
+    if (reasked.ok) {
+      verdict = reasked.verdict;
+    } else {
+      log(phase + " verdict re-ask exhausted — marking failed for retry");
+      await recordPhase(env, {
+        task_id: env.taskId,
+        session: { id: state.activeSessionId, task_id: env.taskId, identity: identity, step: phase, status: "failed", notes: "Worker report had no single unambiguous VERDICT: PASS/FAIL line (bounded re-ask exhausted)" },
+        event: { task_id: env.taskId, type: "failed", message: phase + " verdict line missing or ambiguous, re-ask exhausted — phase failed, dispatcher will retry" },
+        // Room #26 blocker 33: INDETERMINATE verdict record — the report
+        // could not be read at all, but its full text is still preserved
+        // as grounds. Review-scoped; other verdict steps keep the
+        // existing failed-session behavior with no verdict row.
+        verdict: (phase === "Review" ? {
+          step: "Review",
+          attempt: state.reworkCount,
+          reviewer: identity,
+          verdict: "INDETERMINATE",
+          grounds: workerText,
+        } : null),
+      });
+      return {
+        type: "FAILED",
+        reason: phase + " worker report had no single unambiguous VERDICT: PASS/FAIL line (bounded re-ask exhausted)",
+        detail: "The " + identity + " agent's work may be valid — its report did not declare a verdict the workflow could read, and two bounded re-ask attempts could not transcribe one. The report is preserved in the workflow log.",
+      };
+    }
+  }
+  verdictPassed = verdict.passed;
+  }
+  return { type: "BOUNDARY_DONE", workerText: workerText, verdictPassed: verdictPassed };
+}
+
+// runVerdictReask — the bounded mechanical verdict re-ask (source:
+// reaskVerdict). The re-ask judges the report's own content; it never
+// copies a VERDICT line. Consumes the two verdict-reask keys' terminal
+// rows. Returns {type:"NEED_SPAWN"|"STANDBY"} for the driver, or
+// {ok: true, verdict} / {ok: false} once the budget is resolved.
+export async function runVerdictReask(env, state, phase, workerText) {
+  var suffix = state.reworkCount > 0 ? "-r" + state.reworkCount : "";
+  for (var attempt = 1; attempt <= 2; attempt++) {
+    var key = verdictReaskKey(env.taskId, phase, suffix, attempt);
+    var row = await getSpawnRow(env, key);
+    if (!row) {
+      return needSpawn(reaskRequest(env, state, { key: key, phase: phase, workerText: workerText }));
+    }
+    if (!isTerminalRow(row)) {
+      return { type: "STANDBY", reason: phase + " verdict re-ask attempt " + attempt + " of 2 still running (" + key + ")", key: key };
+    }
+    var text = readSessionText(env, key);
+    var verdict = extractVerdict(text || "");
+    if (verdict.ok) {
+      log(phase + " verdict re-ask attempt " + attempt + " recovered verdict: " + (verdict.passed ? "PASS" : "FAIL"));
+      return { ok: true, verdict: verdict };
+    }
+    log(phase + " verdict re-ask attempt " + attempt + " produced no readable verdict (" + verdict.count + " trailing-window matches)");
+  }
+  return { ok: false };
+}
+
+// ── Closeout assembly ───────────────────────────────────────────────────
+// summarizeReport — the step-result summary: the full report text (capped
+// at 2000 chars minus marker space) plus the machine-readable marker lines
+// re-attached. Verbatim from the source's stepResult.summary construction.
+// opts: {markerLines} for the Publish npm target-version block (the
+// TARGET_VERSION line plus the skipped:/published: line); the source's
+// exact 2000 - markerLines - workerMarkers - 2 slice is reproduced.
+export function summarizeReport(workerText, opts) {
+  var workerMarkers = extractMarkerLines(workerText);
+  var text = workerText || "Step completed";
+  if (opts && opts.markerLines) {
+    var markerLines = opts.markerLines;
+    return text.slice(0, 2000 - markerLines.length - workerMarkers.length - 2) + "\n" + markerLines + (workerMarkers ? "\n" + workerMarkers : "");
+  }
+  return text.slice(0, 2000 - workerMarkers.length - 1) + (workerMarkers ? "\n" + workerMarkers : "");
+}
+
+// buildEventPreamble — the CONTEXT preamble the agent runs to fetch its own
+// event history. Review is cold by design and Publish receives its release
+// decision deterministically, so both get "".
+export function buildEventPreamble(env, phase) {
+  if (phase === "Review" || phase === "Publish") return "";
+  return "CONTEXT: First, fetch this task's event history for background.\n" +
+    "Run in shell and return the stdout verbatim:\n" + crewCmdString(env, "get-events", { task_id: env.taskId }) + "\n" +
+    "The returned events are filtered to this task. They contain notes and decisions from prior phases.\n\n";
+}
+
+// ── Claim protocol (driver-level) ───────────────────────────────────────
+// claimFirst — the run's first claim: task → in_progress (+ workflow when
+// the dispatcher launched it null), claim, then clear the reservation ONLY
+// when the claim succeeded. Verbatim from the source's CLAIM block.
+export async function claimFirst(env, state, step) {
+  var taskId = env.taskId;
+  var updateArgs = { id: taskId, state: "in_progress" };
+  if (env.workflowWasNull && env.resolvedWorkflow) updateArgs.workflow = env.resolvedWorkflow;
+  await crewApi(env, "update-task", updateArgs);
+  var claimArgs = {
+    task_id: taskId, identity: step.identity, step: step.name,
+    notes: step.name + " step started",
+  };
+  if (state.nextPhaseRouted) claimArgs.expected_next_phase = state.nextPhaseRouted;
+  var claim = await crewApi(env, "claim-task", claimArgs);
+  if (!claim || !claim.claimed) return { claimed: false };
+  await crewApi(env, "clear-reservation", { task_id: taskId });
+  return { claimed: true, session_id: claim.session_id };
+}
+
+// claimStep — per-phase claim (no reservation clearing; the first claim
+// consumed it). Verbatim from the source's phase-transition claim block.
+export async function claimStep(env, state, step) {
+  var notes = step.name + " step started" + (state.reworkCount > 0 ? " (rework #" + state.reworkCount + ")" : "");
+  var claim = await crewApi(env, "claim-task", {
+    task_id: env.taskId, identity: step.identity, step: step.name, notes: notes,
+  });
+  // A lost claim race returns claimed:false (no session_id). That is the
+  // claim-as-gate: stand down, never proceed with an undefined session.
+  if (claim.claimed === false || !claim.session_id) {
+    return { stand_down: true, reason: "claim-task lost the race for " + step.name + " (claimed:false)" };
+  }
+  return { session_id: claim.session_id };
+}
+
+// ── Project guard (driver-level) ────────────────────────────────────────
+// projectGuard — when the task's project changed mid-run, the run is stale:
+// record the phase as failed and clean up, so the dispatcher re-launches
+// from Build with the new project context. Verbatim from the source.
+export async function projectGuard(env, state, step) {
+  if (!env.projectId) return { ok: true };
+  var st = await crewApi(env, "get-state", { events_limit: 1 });
+  var tasks = (st && st.tasks) || [];
+  var task = null;
+  for (var i = 0; i < tasks.length; i++) {
+    if (tasks[i].id === env.taskId) { task = tasks[i]; break; }
+  }
+  var currentProject = (task && task.project) ? task.project : env.projectId;
+  if (currentProject === env.projectId) return { ok: true };
+  var abortMessage = "Task project changed mid-run from '" + env.projectId + "' to '" + currentProject + "' — aborting stale run. The dispatcher will re-launch from " + "Build" + " with the new project context.";
+  await recordPhase(env, {
+    task_id: env.taskId,
+    session: { task_id: env.taskId, identity: step.identity, step: "Build", status: "failed", notes: abortMessage + " Rebuild from the Map session notes in the task's event history." },
+    event: { task_id: env.taskId, type: "failed", identity: step.identity, message: abortMessage },
+  });
+  // The source ran cleanup via the agent with a CLEANUP-output contract;
+  // the worker layer runs it directly (argv only) and lets a throw abort
+  // the run the same way the source's agent throw would.
+  await lifecycle(env, "cleanup", [env.taskId]);
+  return { ok: false, reason: abortMessage };
+}
+
+// ── Cross-cutting reads ─────────────────────────────────────────────────
+// resolveExperiential — "yes" | "no" | "unknown". The driver's per-pass
+// experiential seed (from the Triage typed result) wins; otherwise the
+// Triage session notes are read once per pass and memoized (all three
+// outcomes, so a missing marker never re-fires the lookup).
+export async function resolveExperiential(env, state) {
+  if (state.memo.experientialResolved !== undefined) return state.memo.experientialResolved;
+  var result;
+  if (state.experiential === true) result = "yes";
+  else if (state.experiential === false) result = "no";
+  else {
+    try {
+      var st = await crewApi(env, "get-state", { events_limit: 1 });
+      var sessions = (st && st.sessions) || [];
+      var triage = null;
+      for (var i = 0; i < sessions.length; i++) {
+        var s = sessions[i];
+        if (s.task_id === env.taskId && s.step === "Triage" && s.status === "completed") {
+          if (!triage || String(s.started_at || "") > String(triage.started_at || "")) triage = s;
+        }
+      }
+      var marker = extractExperiential((triage && triage.notes) || "");
+      result = marker === null ? "unknown" : (marker ? "yes" : "no");
+    } catch (e) {
+      log("resolveExperiential: crew-api call failed (" + (e && e.message ? e.message : e) + ") — treating as unknown");
+      result = "unknown";
+    }
+  }
+  state.memo.experientialResolved = result;
+  return result;
+}
+
+// baselineStatus — reads the task's note events for the exact protocol
+// prefixes (explicit state, never English matching). Returns
+// {baseline_found, baseline_kind, baseline_refs, requested_count, evidence_count}.
+export async function baselineStatus(env) {
+  var result = {
+    baseline_found: false, baseline_kind: null, baseline_refs: [],
+    requested_count: 0, evidence_count: 0,
+  };
+  try {
+    var events = await getEvents(env, env.taskId);
+    var latestBaseline = null;
+    for (var i = 0; i < events.length; i++) {
+      var msg = String((events[i] && events[i].message) || "");
+      if (msg.indexOf("baseline: captured") === 0 || msg.indexOf("baseline: none") === 0) {
+        result.evidence_count++;
+        if (!latestBaseline) latestBaseline = msg;
+      } else if (msg.indexOf("baseline: requested") === 0) {
+        result.requested_count++;
+      }
+    }
+    if (latestBaseline) {
+      result.baseline_found = true;
+      result.baseline_kind = latestBaseline.indexOf("baseline: captured") === 0 ? "captured" : "none";
+      var refMatch = /refs:\s*([^\n]+)/.exec(latestBaseline);
+      if (refMatch) {
+        result.baseline_refs = refMatch[1].split(",").map(function (s) { return s.trim(); }).filter(function (s) { return s.length > 0; });
+      }
+    }
+  } catch (e) {
+    log("baselineStatus: crew-api call failed (" + (e && e.message ? e.message : e) + ") — treating as no evidence");
+  }
+  return result;
+}
+
+// deriveReworkCount — cross-tick rework count: the number of "rejected"
+// events on the task. getEvents already returns [] when there are no
+// events, so a fresh task starts at 0 without any fallback here.
+// Derivation failure is a transport failure: this MUST throw, never
+// default — a swallowed error would collide attempt keys (stale
+// spawn-report pickup) and bypass the MAX_REWORK cap.
+export async function deriveReworkCount(env) {
+  var events = await getEvents(env, env.taskId, 100);
+  var n = 0;
+  for (var i = 0; i < events.length; i++) {
+    if (events[i] && events[i].type === "rejected") n++;
+  }
+  return n;
+}
+
+
+// ── Terminal cleanup & parking ──────────────────────────────────────────
+// terminalCleanup — the run's last act at every park/fail boundary: two
+// direct attempts at terminal-cleanup, then the backstop log line. The
+// source's agent return-shape nuance is preserved: the second attempt is
+// only skipped when the first returned a non-blank string.
+export async function terminalCleanup(env) {
+  var taskId = env.taskId;
+  for (var attempt = 0; attempt < 2; attempt++) {
+    try {
+      var out = await lifecycle(env, "terminal-cleanup", [taskId]);
+      if (typeof out.stdout === "string" && out.stdout.trim().length > 0) return;
+    } catch (e) {
+      log("terminal-cleanup attempt " + (attempt + 1) + " of 2 failed: " + (e && e.message ? e.message : e));
+    }
+  }
+  log("terminal-cleanup backstop: both attempts failed; worktree/branch state may need manual review for task " + taskId);
+}
+
+// parkTask — parks the task for human attention (message capped at 1000
+// chars), then runs terminal cleanup. The driver owns telemetryEnd.
+export async function parkTask(env, reason) {
+  var taskId = env.taskId;
+  log("Parking task " + taskId + " for human attention: " + reason);
+  var parkMessage = ("Parked: " + reason).slice(0, 1000);
+  try {
+    await crewApi(env, "park-task", { task_id: taskId, message: parkMessage });
+  } catch (e) {
+    log("PARK FAILED for task " + taskId + ": " + (e && e.message ? e.message : e));
+    await terminalCleanup(env);
+    return { type: "PARK_FAILED", reason: "park failed: " + reason };
+  }
+  await terminalCleanup(env);
+  return { type: "PARK", reason: reason };
+}
+
+// recordPublishLedger — the append-only publish outcome ledger
+// ($CREW_HOME/.publish-ledger/<publish-slug>.jsonl), ported to direct
+// Node file I/O (the source ran it through a courier agent's shell; the
+// bytes on disk are identical). Field-for-field identical to the source.
+// Non-fatal: a write failure logs and returns false, exactly like the
+// source's catch. P4 is preserved: entry.commit is referenced at the
+// early artifact-publish rows BEFORE its `var` declaration, so it is
+// undefined there and serializes as commit: null.
+export async function recordPublishLedger(env, entry) {
+  var taskId = env.taskId;
+  try {
+    var ledgerDir = join(env.crewHome, ".publish-ledger");
+    mkdirSync(ledgerDir, { recursive: true });
+    // The source substituted `date -u +%Y-%m-%dT%H:%M:%SZ` via sed; the
+    // port runs the same command directly.
+    var tsOut = await runCmd(["date", "-u", "+%Y-%m-%dT%H:%M:%SZ"]);
+    var line = JSON.stringify({
+      ts: String(tsOut.stdout || "").trim(),
+      task_id: taskId,
+      workflow: env.resolvedWorkflow || "unknown",
+      slug: env.publishSlug,
+      commit: entry.commit || null,
+      attempt: entry.attempt || null,
+      agent_id: entry.agent_id || null,
+      applied_report: entry.applied_report || null,
+      manifest_before: entry.manifest_before || null,
+      outcome: entry.outcome,
+      detail: entry.detail || "",
+      // D1 (2026-09-19): issued_at = upper bound on the trigger-issuance
+      // instant (null when no trigger); ts = ledger-write instant.
+      issued_at: entry.issued_at || null,
+      // (2026-09-20, one-party worker-owned publish) issuer = which party
+      // wrote the entry ("workflow" for the intent entry, "tick-worker" for
+      // the worker's own issuance); diff_path/diff_sha256 locate the
+      // checksummed diff the worker issues. The workflow never writes an
+      // issuance ("submitted") entry — it did not issue.
+      issuer: entry.issuer || null,
+      diff_path: entry.diff_path || null,
+      diff_sha256: entry.diff_sha256 || null,
+      base: entry.base || null,
+      // (0.14.6) Numeric publication attempt + the attempt's deterministic
+      // version. Attempt 1 is staged here by the workflow; attempts 2-3 are
+      // staged by scan-ack-pending's re-issue path with fresh versions.
+      publish_attempt: entry.publish_attempt || null,
+      version: entry.version || null,
+    });
+    appendFileSync(join(ledgerDir, env.publishSlug + ".jsonl"), line + "\n");
+    log("Noted publish outcome '" + entry.outcome + "' for task " + taskId + " in ledger");
+    return true;
+  } catch (e) {
+    log("Publish ledger: write failed for task " + taskId + " (non-fatal, observability only): " + (e && e.message ? e.message : e));
+    return false;
+  }
+}
+
+// ── Instruction-string helpers ──────────────────────────────────────────
+// crewCmdString — the pinned crew-api CLI invocation for agent
+// instructions. Verbatim port of the source's crewCmd (which used the
+// pinned CREW_API after the pin step).
+export function crewCmdString(env, command, args) {
+  var json = JSON.stringify(args || {}).replace(/'/g, "'\\''");
+  return "node " + env.crewApiPinned + " --crew-home " + env.crewHome + " " + command + " --json '" + json + "'";
+}
+
+// lifecycleEnvPrefix — the "CREW_HOME=... CREW_REPO=... " prefix baked
+// into every lifecycle invocation the agents run (source: LIFECYCLE_ENV).
+export function lifecycleEnvPrefix(env) {
+  return "CREW_HOME=" + env.crewHome + " CREW_REPO=" + env.repoPath + " ";
+}
+
+// latestSessionNotes — the notes of the latest session for this task with
+// the given step+status ("" when none). Cross-phase handoffs (mapper spec,
+// rejection notes, release decision, repo_diff:none claim) are re-derived
+// from durable session notes so a run survives tick boundaries.
+export async function latestSessionNotes(env, step, status) {
+  var st = await crewApi(env, "get-state", { events_limit: 1 });
+  var sessions = (st && st.sessions) || [];
+  var best = null;
+  for (var i = 0; i < sessions.length; i++) {
+    var s = sessions[i];
+    if (s.task_id === env.taskId && s.step === step && s.status === status) {
+      if (!best || String(s.started_at || "") > String(best.started_at || "")) best = s;
+    }
+  }
+  return best ? (best.notes || "") : "";
+}
+
+// verifyPin — the pre-Publish pin guard's mechanical check: every
+// PIN_BASENAMES entry present in the run lib.
+export function verifyPin(env) {
+  var names;
+  try {
+    names = readdirSync(env.runLib);
+  } catch (e) {
+    return { ok: false, missing: PIN_BASENAMES.slice() };
+  }
+  var missing = PIN_BASENAMES.filter(function (b) { return names.indexOf(b) === -1; });
+  return { ok: missing.length === 0, missing: missing };
+}
+
+// deriveRunEnv — the static per-run environment, derived once by the
+// driver from the dispatch inputs and the project config. All surface /
+// path / title derivations are verbatim from workflows/chore.js.
+export function deriveRunEnv(o) {
+  var publishType = o.projectConfig.deploy_type || "";
+  var envType = o.projectConfig.environment_type || null;
+  var surfaceArtifact = (publishType === "artifact" || envType === "artifact");
+  var surfaceTerminal = (!surfaceArtifact && envType === "terminal");
+  var surfaceTriageDesc = surfaceArtifact
+    ? "This project's user-facing surface is artifact: a rendered web UI."
+    : surfaceTerminal
+      ? "This project's user-facing surface is terminal: a command-line interface."
+      : "This project's user-facing surface is unclassified (environment_type not set): judge by what a user would directly observe.";
+  var uxDoctrinePage = surfaceTerminal ? "terminal-ux.md" : (surfaceArtifact ? "artifact-ux.md" : null);
+  return {
+    crewHome: o.crewHome, repoPath: o.repoPath, orchPath: o.orchPath, runLib: o.runLib,
+    lifecycle: o.lifecycle, mergeLock: o.mergeLock, publishNpm: o.publishNpm, computeDiff: o.computeDiff,
+    releaseScript: o.crewHome + "/crew-release.sh",
+    crewApi: o.crewApi, crewApiPinned: o.crewApiPinned,
+    taskId: o.taskId, taskTitle: o.taskTitle, taskDescription: o.taskDescription,
+    projectId: o.projectId, publishType: publishType,
+    publishSlug: o.projectConfig.deploy_slug || "",
+    projectDesc: o.projectConfig.description || "React + TypeScript web dashboard (client/src/, server/src/, drizzle/)",
+    surfaceArtifact: surfaceArtifact, surfaceTerminal: surfaceTerminal,
+    surfaceTriageDesc: surfaceTriageDesc,
+    uxDoctrinePath: uxDoctrinePage ? o.crewHome + "/current/docs/" + uxDoctrinePage : null,
+    visualProtocolAvailable: o.visualProtocol === true,
+    workflowWasNull: !!o.workflowWasNull, resolvedWorkflow: o.resolvedWorkflow || null,
+    worktreeHint: o.repoPath + "/.worktrees/" + o.taskId,
+    worktreePreservedHint: ".worktrees/" + o.taskId,
+    taskBranch: "task/" + o.taskId,
+    safeTitle: String(o.taskTitle || "").replace(/"/g, "'").replace(/\\/g, "\\\\").replace(/`/g, "'"),
+  };
+}
+
+// closeoutPassed — the deterministic closeout rule: for verdict steps the
+// verdict decides; for non-verdict steps (Triage, Capture, Map) the worker
+// producing output means the step passed.
+export function closeoutPassed(boundaryResult) {
+  return boundaryResult.verdictPassed !== null ? boundaryResult.verdictPassed === true : true;
+}
+
+// ensureClaimed — the phase claim protocol. Claims once per phase visit;
+// on resume passes the driver passes the persisted activeSessionId and the
+// claim is skipped. A lost first-claim race stands down quietly.
+export async function ensureClaimed(env, state, phase) {
+  if (state.activeSessionId) return { type: "CLAIMED", session_id: state.activeSessionId };
+  if (state.isFirstClaimVisit) {
+    var first = await claimFirst(env, state, phase);
+    if (!first.claimed) {
+      log(phase.name + " lost the claim race for task " + env.taskId + " — standing down quietly");
+      return { type: "STAND_DOWN", reason: "lost claim race for task " + env.taskId };
+    }
+    state.activeSessionId = first.session_id;
+    // Blocker 46: the first claim happens exactly once per run. Later
+    // phases in the same run go through claimStep (a fresh per-phase
+    // session), never a second first-claim.
+    state.isFirstClaimVisit = false;
+    return { type: "CLAIMED", session_id: first.session_id };
+  }
+  var step = await claimStep(env, state, phase);
+  if (step.stand_down) {
+    log(phase.name + " lost the claim race for task " + env.taskId + " — standing down quietly");
+    return { type: "STAND_DOWN", reason: step.reason };
+  }
+  state.activeSessionId = step.session_id;
+  return { type: "CLAIMED", session_id: step.session_id };
+}