muse-crew 0.17.2 → 0.17.3

package/lib/bugfix/phases/reproduce.js

@@ -0,0 +1,254 @@
+// lib/bugfix/phases/reproduce.js — Bugfix Reproduce phase (worker layer).
+//
+// Hazel re-runs the bug at the bug's own layer with the terminal transcript
+// protocol, then issues a machine-readable verdict. Derived from
+// workflows/bugfix.js (the Bugfix Reproduce step).
+//
+// Contract:
+//   - Read: Triage layer (durable marker; falls back to task row
+//     `bug_layer`), task row (title, description), project surface
+//     (artifact | terminal | unclassified).
+//   - The phase is skipped when the bug is non-experiential... — no:
+//     Reproduce runs for every bug that reaches it. (Capture skips; Reproduce
+//     does not.)
+//   - Layer routing (source-faithful):
+//       artifact + terminal surface → terminal transcript protocol
+//       artifact + artifact/unclassified surface → rendered page flow
+//       engine → engine/CLI instructions
+//       docs → docs/CLI instructions
+//   - Wrong-layer guard (engine/docs only): fail closed if the attempt
+//     created new see-act frames, or if the pre-attempt baseline is
+//     unavailable.
+//   - Verdict: mechanical extraction with bounded re-ask; exhaustion is an
+//     operational FAILED (retryable), not a rejection.
+//   - Valid FAIL → record `rejected`, then park for PM attention
+//     ("Reproduction failed — needs PM attention"). Never advances.
+//   - Valid PASS → advance to Map.
+//   - The OODA agent writes verdict.md, transcript, and the OODA attempt
+//     log into the repro evidence dir.
+//
+// Phase I/O contract (Phase D):
+//   read:  bug_layer marker | task.bug_layer, task title/description,
+//          project surface classification
+//   write: session (completed | rejected), event (completed | rejected),
+//          park row (on FAIL)
+//   out:   ADVANCE → Map | PARK (on FAIL) | FAILED (guard / verdict
+//          exhaustion / transport)
+
+import { readdirSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+import {
+  runWorkBoundary, recordPhase, buildEventPreamble, summarizeReport,
+  ensureClaimed, log, resolveLayer, parkTask, crewCmdString,
+} from "../../workflow-lib.js";
+
+export const PHASE = { name: "Reproduce", identity: "hazel" };
+
+// reproEvidenceDir — the OODA agent's evidence directory. Matches the
+// source's reproEvidenceDir exactly.
+function reproEvidenceDir(env) {
+  return join(env.crewHome, "task-evidence", env.taskId, "repro");
+}
+
+// listReproFrames — the see-act frame listing for the wrong-layer guard.
+// Returns an array of frame filenames, or null when the directory cannot
+// be read. A missing directory means no frames exist (matches the source's
+// `|| echo NONE` → empty-list behavior).
+function listReproFrames(env) {
+  var dir = reproEvidenceDir(env);
+  var files;
+  try {
+    files = readdirSync(dir);
+  } catch (e) {
+    if (e && e.code === "ENOENT") return [];
+    return null;
+  }
+  return files.filter(function (f) { return /-(shot|click|scroll|type)-/.test(f); });
+}
+
+// guardMarkerPath — durable attempt-scoped storage for the pre-spawn frame
+// baseline. The worker layer is stateless across NEED_SPAWN re-entries (the
+// driver re-invokes the phase in a fresh process), so the snapshot must live
+// on disk, written BEFORE the first spawn and never replaced after the agent
+// runs.
+function guardMarkerPath(env) {
+  return join(reproEvidenceDir(env), ".guard-before.json");
+}
+
+function readGuardMarker(env) {
+  try {
+    return JSON.parse(readFileSync(guardMarkerPath(env), "utf8"));
+  } catch (e) {
+    return null;
+  }
+}
+
+function writeGuardMarker(env, marker) {
+  var p = guardMarkerPath(env);
+  try { mkdirSync(dirname(p), { recursive: true }); } catch (e) { /* best effort */ }
+  writeFileSync(p, JSON.stringify(marker));
+}
+
+// buildInstructions — the four layer-routed instruction variants,
+// verbatim from workflows/bugfix.js (variable references remapped to
+// ctx.env; logic and prose unchanged). ctx: { env, state }.
+export function buildInstructions(ctx) {
+  var env = ctx.env;
+  var reproLayer = ctx.reproLayer || "artifact";
+  if (reproLayer !== "engine" && reproLayer !== "docs") {
+      if (env.surfaceTerminal) {
+        var instructions = "Reproduce the bug from a user's perspective — by USING the CLI, not by reading source code. You are CODE-BLIND — do NOT read source code.\n" +
+        "This project's user-facing surface is a terminal: a command-line interface. Read the shared UX bar FIRST: " + env.uxDoctrinePath + " — it is what correct CLI behavior looks like.\n" +
+        "a. Work in the project checkout at " + env.repoPath + " — that exact checkout, not any other copy of the project on disk. Drive the CLI the way a user would: start with --help to discover the surface, then the commands the bug report implicates.\n" +
+        "b. Bounded CLI loop, at most 8 commands: drive the CLI to TRIGGER the reported bug. For EVERY command, save a transcript file under " + env.crewHome + "/task-evidence/" + env.taskId + "/repro/ named 01-<slug>.txt, 02-<slug>.txt, ... — each transcript holds the exact command line, its stdout, its stderr, and its exit code. Never invent output: a transcript you did not run is not evidence.\n" +
+        "c. After EVERY command, append it to the OODA report: node " + env.crewHome + "/current/lib/append-ooda-step.js --log " + env.crewHome + "/task-evidence/" + env.taskId + "/repro/ooda-log.jsonl --attempt \"1\" --step <N> --action terminal --exit <exit-code> --transcript <the transcript file you saved> --observation \"<1-2 sentences: what the command showed and what you concluded>\" — the script requires --transcript for terminal actions and rejects --screenshot (there is nothing to see). Steps are strictly monotonic: your first step is --step 1, then 2, 3, ... If you run the loop again (a new idea, after a restart), that run is --attempt \"2\": attempts never overwrite, they accumulate. Your observation is the payload — say what the output showed and what it means, not just what you ran. A command you ran but did not log is invisible to everyone after you. If the CLI will not run at all (missing runtime, broken install), log ONE step with --exit 3, --observation \"NOT POSSIBLE: <reason>\" and a transcript holding the failed invocation, then fall back to the data-level investigation at the end.\n" +
+        "Data-level fallback (only if the CLI loop above is NOT POSSIBLE): run in shell and read the stdout JSON:\n" + crewCmdString(env, "get-state", {}) + "\n" +
+        "This returns current sessions, events, and tasks — capture concrete evidence from the data you retrieve.\n" +
+        "Report your reproduction steps and evidence as plain prose.\n" +
+        "End your report with exactly one line: VERDICT: PASS if you reproduced the reported bug (your transcripts show the reported misbehavior), VERDICT: FAIL if you could not. --expected names the bug as reported (its CLI manifestation); --actual names what your commands actually showed. Checks you could not run are evidence gaps, not silent drops: name every one in --missing. First ensure the OODA log exists even if you logged zero steps (touch " + env.crewHome + "/task-evidence/" + env.taskId + "/repro/ooda-log.jsonl — an empty log is honest, an absent one is a broken report). Also write the same verdict machine-readably: node " + env.crewHome + "/current/lib/write-ooda-verdict.js --dir " + env.crewHome + "/task-evidence/" + env.taskId + "/repro/ --attempt \"1\" --verdict <PASS|FAIL|NOT_POSSIBLE> --summary \"<one line>\" --expected \"<the bug as reported — its CLI manifestation>\" --actual \"<what your commands actually showed>\" --missing '[\"honest evidence gap, if any\"]' [--reason \"<why it failed — REQUIRED and non-empty when verdict is FAIL or NOT_POSSIBLE; the script rejects a reason-less negative verdict with exit 2>\"] — this writes verdict.json (the latest verdict) and appends to verdicts.jsonl (the append-only ledger: every attempt's verdict is preserved, never overwritten). A FAIL or NOT_POSSIBLE verdict without a machine-readable --reason cannot be written — state the reason.";
+      } else {
+        instructions = "Reproduce the bug from a user's perspective — by USING the artifact, not by reading data. You are CODE-BLIND — do NOT read source code.\n" +
+      "You have a see-act driver: " + env.crewHome + "/current/lib/see-act.js (a node script; one browser action per invocation; it prints one JSON line to stdout). It launches its own Chromium through a self-contained loopback proxy — the ONLY url you may give it is the local artifact server you start below. Never point it at any other URL.\n" +
+      "Actions: aria | shot [--out <png>] [--full] | click [--out <png>] --selector <css> | scroll [--out <png>] --y <pixels|bottom> | type [--out <png>] --selector <css> --text <text>. Add --viewport mobile for a 390x844 frame. The JSON reports console_errors — treat any as a defect signal. Exit code 3 with not_possible set (a \"NOT POSSIBLE: <reason>\" string) means this environment cannot drive a browser: report NOT POSSIBLE: <reason> and fall back to the data-level investigation at the end.\n" +
+      "a. Verify the built artifact exists: test -d ~/workspace/ts-spaces/" + env.publishSlug + "/client/dist && test -f ~/workspace/ts-spaces/" + env.publishSlug + "/server/dist/actions.js — if either is missing, report NOT POSSIBLE: built artifact not present at ~/workspace/ts-spaces/" + env.publishSlug + " and fall back to the data-level investigation.\n" +
+      "b. Start the local artifact server detached with a log file, then poll the log for readiness (single shell invocation): CREW_HOME=" + env.crewHome + " setsid nohup node " + env.crewHome + "/current/lib/serve-artifact.js --space-dir ~/workspace/ts-spaces/" + env.publishSlug + " --port 0 --tag " + env.taskId + "-repro > /tmp/repro-server-" + env.taskId + ".log 2>&1 < /dev/null & for i in $(seq 1 30); do grep -q READY /tmp/repro-server-" + env.taskId + ".log && break; sleep 1; done; grep -o 'READY port=[0-9]*' /tmp/repro-server-" + env.taskId + ".log | cut -d= -f2 — the printed number is <N>. If no READY appears, report NOT POSSIBLE: local artifact server did not start (see /tmp/repro-server-" + env.taskId + ".log) and fall back to the data-level investigation.\n" +
+      "c. Bounded see-act loop, at most 8 steps: drive the artifact to TRIGGER the reported bug. Prefix EVERY see-act invocation with SEE_ACT_ARCHIVE_DIR=" + env.crewHome + "/task-evidence/" + env.taskId + "/repro/ (shell env vars do not persist between your commands, so prefix each one) — every screenshot is then archived automatically as 001-shot-desktop.png, 002-click-desktop.png, ..., so no frame can be lost. Omit --out; the JSON's screenshot field is the path to READ with your read tool (you can see images).\n" +
+        "c2. After EVERY see-act invocation, append it to the OODA report: node " + env.crewHome + "/current/lib/append-ooda-step.js --log " + env.crewHome + "/task-evidence/" + env.taskId + "/repro/ooda-log.jsonl --attempt \"1\" --step <N> --action <aria|shot|click|scroll|type> --exit <exit-code> --screenshot <screenshot-from-JSON> --observation \"<1-2 sentences: what the frame showed and what you concluded>\" (omit --screenshot for aria). Steps are strictly monotonic: your first step is --step 1, then 2, 3, ... — the script rejects anything else. If you run the loop again (a new idea, after a restart), that run is --attempt \"2\": attempts never overwrite, they accumulate. Your observation is the payload — say what you saw and what it means, not just what you did. A step you ran but did not log is invisible to everyone after you. If the server stops responding mid-loop (curl --max-time 3 http://localhost:<N>/ fails), restart it per (b).\n" +
+"c2b. IMAGE TOOLS (when a raw screenshot is not enough evidence): python3 " + env.crewHome + "/current/lib/edit-image.py crop --in <frame.png> --out <crop.png> --region x,y,w,h — pixel-exact crop; zoom --factor <f> --center x,y — pixel-crisp zoom back to the original frame size; label --text \"<caption>\" — caption bar; nup --cols 2 --in <a.png> --in <b.png> --labels \"before|after\" — side-by-side grid. Deterministic, no network. Log each with --action crop|zoom|label|nup, --attempt \"1\", and --screenshot <the derivative you READ>. For rich compositions (before/after with real typography, annotated callouts), write an HTML page and render it: node " + env.crewHome + "/current/lib/render-html.js --in <page.html> --out <composed.png> [--width 1200] — headless Chromium, hermetic (remote assets are blocked and fail the render), deterministic; log with --action compose and --screenshot <the composition you READ>. Derivatives supplement, never replace: keep the source frame archived and name it in --args. READ every derivative you log — an unread image is not evidence.\n" +
+        "c3. Start with: SEE_ACT_ARCHIVE_DIR=" + env.crewHome + "/task-evidence/" + env.taskId + "/repro/ node " + env.crewHome + "/current/lib/see-act.js --url http://localhost:<N>/ aria — read the JSON, log the step. Then: SEE_ACT_ARCHIVE_DIR=" + env.crewHome + "/task-evidence/" + env.taskId + "/repro/ node " + env.crewHome + "/current/lib/see-act.js --url http://localhost:<N>/ shot — READ the screenshot, log the step. Act on what you see: click, scroll, type, then re-observe, logging each step. Prefer aria (cheap text) to find controls; screenshot when the view changes and for your final verdict frames (one desktop, one mobile). If a click exits non-zero, do NOT retry the same ref blindly: re-run aria first (refs go stale between invocations), then click the fresh ref exactly once. If it still fails, log the failure and move on — a flaky control is a finding, not a loop.\n" +
+        "d. One action per invocation, fresh browser each time: anything reachable by (navigate, one action) is testable — e.g. clicking any tab or button from the landing page. Sequences needing prior in-page state (open a dialog, then confirm it) are not; if the bug needs such a sequence, report NOT POSSIBLE for that part and reproduce what you can.\n" +
+      "e. Every frame you captured is already archived under " + env.crewHome + "/task-evidence/" + env.taskId + "/repro/ and indexed in ooda-log.jsonl — that log plus the frames is your OODA report for this reproduction. A frame you did not read is not evidence. Loading, error, or blank frames never reproduce anything.\n" +
+      "f. Kill ONLY the server you started: pkill -f 'serve-artifact[.]js.*--tag " + env.taskId + "-repro' — never another task's server. (The [.] keeps pkill from matching its own command line.) Do not leave it running.\n" +
+      "Data-level fallback (only if the browser loop above is NOT POSSIBLE): run in shell and read the stdout JSON:\n" + crewCmdString(env, "get-state", {}) + "\n" +
+      "This returns current sessions, events, and tasks — capture concrete evidence from the data you retrieve.\n" +
+      "Report your reproduction steps and evidence as plain prose.\n" +
+      "End your report with exactly one line: VERDICT: PASS if you reproduced the reported bug (your frames show the reported misbehavior), VERDICT: FAIL if you could not. --expected names the bug as reported (its visible manifestation); --actual names what your frames actually showed. Checks you could not run are evidence gaps, not silent drops: name every one in --missing. First ensure the OODA log exists even if you logged zero steps (touch " + env.crewHome + "/task-evidence/" + env.taskId + "/repro/ooda-log.jsonl — an empty log is honest, an absent one is a broken report). Also write the same verdict machine-readably: node " + env.crewHome + "/current/lib/write-ooda-verdict.js --dir " + env.crewHome + "/task-evidence/" + env.taskId + "/repro/ --attempt \"1\" --verdict <PASS|FAIL|NOT_POSSIBLE> --summary \"<one line>\" --expected \"<the bug as reported — its visible manifestation>\" --actual \"<what your frames actually showed>\" --missing '[\"honest evidence gap, if any\"]' [--reason \"<why it failed — REQUIRED and non-empty when verdict is FAIL or NOT_POSSIBLE; the script rejects a reason-less negative verdict with exit 2>\"] — this writes verdict.json (the latest verdict) and appends to verdicts.jsonl (the append-only ledger: every attempt's verdict is preserved, never overwritten). A FAIL or NOT_POSSIBLE verdict without a machine-readable --reason cannot be written — state the reason.";
+      }
+    } else if (reproLayer === "engine") {
+      instructions = "REPRODUCE AT THE BUG'S LAYER. Triage classified this bug as layer: engine — it lives in the crew's own machinery (workflows, lib scripts, shell scripts, tests, scheduler), not in the rendered artifact. Reproduce it deterministically with shell commands in the repo checkout at " + env.repoPath + " — that exact checkout, not any other copy of the project on disk. You are NOT code-blind here: reading source to find the failing mechanism is expected.\n" +
+      "Do NOT start an artifact server. Do NOT invoke see-act.js or any browser loop — the experiential loop is for artifact-layer bugs only, and driving it here fails the phase loudly. If you cannot reproduce without a browser, say so and FAIL with a reason naming the layer you tried.\n" +
+      "Reproduce with the commands that match the bug: run the failing script directly, re-run the failing test suite (bash tests/run.sh), grep the workflow source, query scheduler/crew state via the crew API. Concrete evidence only: the command lines you ran, their verbatim stdout, and their exit codes.\n" +
+      "Report your reproduction steps and evidence as plain prose.\n" +
+      "End your report with exactly one line: VERDICT: PASS if you reproduced the reported bug (your command output shows the reported misbehavior), VERDICT: FAIL if you could not. --expected names the bug as reported; --actual names what your commands actually showed. Checks you could not run are evidence gaps, not silent drops: name every one in --missing. Also write the same verdict machine-readably: node " + env.crewHome + "/current/lib/write-ooda-verdict.js --dir " + env.crewHome + "/task-evidence/" + env.taskId + "/repro/ --attempt \"1\" --verdict <PASS|FAIL|NOT_POSSIBLE> --summary \"<one line>\" --expected \"<the bug as reported>\" --actual \"<what your commands actually showed>\" --missing '[\"honest evidence gap, if any\"]' [--reason \"<why it failed — REQUIRED and non-empty when verdict is FAIL or NOT_POSSIBLE; the script rejects a reason-less negative verdict with exit 2>\"] — this writes verdict.json (the latest verdict) and appends to verdicts.jsonl (the append-only ledger: every attempt's verdict is preserved, never overwritten). A FAIL or NOT_POSSIBLE verdict without a machine-readable --reason cannot be written — state the reason.";
+    } else {
+      instructions = "REPRODUCE AT THE BUG'S LAYER. Triage classified this bug as layer: docs — a documentation gap or error. Reproduce it by reading the file, not the browser: open the document in the repo checkout at " + env.repoPath + " (that exact checkout, not any other copy of the project on disk) and verify the reported gap or error is actually there (a missing section, a stale instruction, a wrong claim). Quote the exact lines you found — or their absence.\n" +
+      "Do NOT start an artifact server. Do NOT invoke see-act.js or any browser loop — the experiential loop is for artifact-layer bugs only, and driving it here fails the phase loudly. If you cannot verify the gap without a browser, say so and FAIL with a reason naming the layer you tried.\n" +
+      "Report your findings as plain prose: what the document says today versus what it should say.\n" +
+      "End your report with exactly one line: VERDICT: PASS if you confirmed the reported docs gap, VERDICT: FAIL if you could not. Also write the same verdict machine-readably: node " + env.crewHome + "/current/lib/write-ooda-verdict.js --dir " + env.crewHome + "/task-evidence/" + env.taskId + "/repro/ --attempt \"1\" --verdict <PASS|FAIL|NOT_POSSIBLE> --summary \"<one line>\" --expected \"<the bug as reported>\" --actual \"<what the document actually says>\" --missing '[\"honest evidence gap, if any\"]' [--reason \"<why it failed — REQUIRED and non-empty when verdict is FAIL or NOT_POSSIBLE; the script rejects a reason-less negative verdict with exit 2>\"] — this writes verdict.json (the latest verdict) and appends to verdicts.jsonl (the append-only ledger: every attempt's verdict is preserved, never overwritten). A FAIL or NOT_POSSIBLE verdict without a machine-readable --reason cannot be written — state the reason.";
+    }
+
+  
+  return instructions;
+}
+
+// recordGuardFailure — the wrong-layer / baseline-unavailable closeout:
+// operational FAILED (retryable), session "failed". Matches the source's
+// BLOCKED control semantics in the composed vocabulary (the checkpoint's
+// "operational FAILED").
+async function recordGuardFailure(env, state, kind, detail) {
+  var reason = kind === "baseline-unavailable"
+    ? "Reproduce wrong-layer guard baseline unavailable for task " + env.taskId + " — failing closed for retry"
+    : "Reproduce wrong-layer guard tripped for task " + env.taskId + ": see-act frames created during this attempt on a " + kind + "-layer bug (" + detail + ")";
+  log(reason);
+  await recordPhase(env, {
+    task_id: env.taskId,
+    session: {
+      id: state.activeSessionId, task_id: env.taskId, identity: PHASE.identity,
+      step: PHASE.name, status: "failed",
+      notes: "Reproduce wrong-layer guard: " + kind + (detail ? " (" + detail + ")" : ""),
+    },
+    event: { task_id: env.taskId, type: "failed", message: reason },
+  });
+  return { type: "FAILED", reason: reason, detail: detail || kind };
+}
+
+export async function runPhase(ctx) {
+  var env = ctx.env, state = ctx.state;
+  // The bug's layer routes the reproduction protocol. resolveLayer is the
+  // worker-layer equivalent of the source's layer marker resolution.
+  var reproLayer = await resolveLayer(env, state);
+  ctx.reproLayer = reproLayer;
+  log("Reproduce dispatching at the bug's layer for task " + env.taskId + ": " + reproLayer);
+
+  // Wrong-layer guard baseline (engine/docs only). The snapshot is taken
+  // BEFORE the first spawn and persisted in a durable marker file: the
+  // worker layer is stateless across NEED_SPAWN re-entries (each is a fresh
+  // driver invocation), so an in-memory baseline would be lost. The marker
+  // is never replaced after the agent runs — a fresh visit (first entry or
+  // dispatcher retry, both with no active session yet) takes a new snapshot;
+  // a NEED_SPAWN re-entry (active session already claimed) reuses it.
+  var guardApplicable = (reproLayer === "engine" || reproLayer === "docs");
+  var guardBefore = null; // null: not applicable, or baseline unavailable
+  if (guardApplicable) {
+    if (!state.activeSessionId) {
+      var snap = listReproFrames(env);
+      writeGuardMarker(env, snap === null ? { unavailable: true } : { frames: snap });
+      guardBefore = snap;
+      log("Reproduce guard baseline for task " + env.taskId + ": " +
+        (snap === null ? "unavailable — guard will fail closed" : snap.length + " pre-existing frame(s)"));
+    } else {
+      var marker = readGuardMarker(env);
+      if (marker && !marker.unavailable && Array.isArray(marker.frames)) {
+        guardBefore = marker.frames;
+      }
+      // else: marker missing or baseline unavailable — guardBefore stays
+      // null and the guard fails closed below.
+    }
+  }
+
+  var claimed = await ensureClaimed(env, state, PHASE);
+  if (claimed.type !== "CLAIMED") return claimed;
+
+  var boundary = await runWorkBoundary(env, state, {
+    phase: PHASE.name,
+    identity: PHASE.identity,
+    instructions: buildInstructions(ctx),
+    eventPreamble: buildEventPreamble(env, PHASE.name),
+    crewApiLine: true,
+    verdictStep: true,
+  });
+  if (boundary.type !== "BOUNDARY_DONE") return boundary;
+
+  var workerText = boundary.workerText;
+  var verdictPassed = boundary.verdictPassed === true;
+
+  // Wrong-layer guard (engine/docs only): only frames created during THIS
+  // attempt fail the guard — pre-existing frames are the baseline. A
+  // missing or unreadable baseline fails closed (fail-closed for retry).
+  if (guardApplicable) {
+    var after = listReproFrames(env);
+    if (guardBefore === null || after === null) {
+      return await recordGuardFailure(env, state, "baseline-unavailable", "");
+    }
+    var beforeSet = {};
+    for (var i = 0; i < guardBefore.length; i++) beforeSet[guardBefore[i]] = true;
+    var newFrames = [];
+    for (var j = 0; j < after.length; j++) {
+      if (!beforeSet[after[j]]) newFrames.push(after[j]);
+    }
+    if (newFrames.length > 0) {
+      return await recordGuardFailure(env, state, reproLayer, newFrames.slice(0, 5).join(", ").slice(0, 300));
+    }
+    log("Reproduce wrong-layer guard passed: no see-act frames from this attempt on " + reproLayer + "-layer task " + env.taskId);
+  }
+
+  // Closeout: record the session and event, then route. A valid FAIL is a
+  // rejection (the bug does not reproduce) followed by a park for PM
+  // attention — it never advances. A valid PASS advances to Map.
+  var status = verdictPassed ? "completed" : "rejected";
+  var summary = summarizeReport(workerText);
+  await recordPhase(env, {
+    task_id: env.taskId,
+    session: {
+      id: state.activeSessionId, task_id: env.taskId, identity: PHASE.identity,
+      step: PHASE.name, status: status, notes: summary,
+    },
+    event: { task_id: env.taskId, type: status, identity: PHASE.identity, message: "Reproduce " + status + " by " + PHASE.identity },
+  });
+
+  if (!verdictPassed) {
+    log("Reproduction failed for task " + env.taskId + " — parking for PM attention");
+    return await parkTask(env, "Reproduction failed — needs PM attention");
+  }
+  return { type: "ADVANCE", next: "Map" };
+}

package/lib/bugfix/phases/review.js

@@ -0,0 +1,292 @@
+// lib/bugfix/phases/review.js — Bugfix Review phase (worker layer).
+//
+// Cass reviews the task branch cold against Mara's spec. Derived from
+// workflows/bugfix.js (the Bugfix Review step).
+//
+// Contract:
+//   - Read: task branch state (mechanical git classification, re-done on
+//     every entry); accepted Build report (durable session notes:
+//     repo_diff:none claim, release decision); package.json version state
+//     (npm only, mechanical).
+//   - Mechanical gates (Cass never dispatched):
+//       * version-touched (npm): branch changed package.json `version`.
+//       * empty-no-work without a repo_diff:none claim: no change to review.
+//     Both synthesize a workflow-authored FAIL report flowing through the
+//     same verdict/closeout path as a real FAIL.
+//   - Branch classification and version check are direct lifecycle-script
+//     invocations (worker-layer equivalent of the source's agent ferry);
+//     unparseable/instrument failure retries in place (2x), exhaustion
+//     parks honestly (never asserts a positive claim from unparseable
+//     output).
+//   - Cass's instructions carry the branch-state-specific exam rule and the
+//     release-decision validation (npm only).
+//   - Structured verdict record: step, attempt (rework round), reviewer
+//     ("workflow" on mechanical FAIL), verdict, review_basis, grounds.
+//   - Rejection: shared Review/QA budget (spec.reworkPhases). Budget
+//     exhausted → park (worktree preserved). Otherwise REWIND to Build.
+//   - PASS → Integrate.
+//
+// Phase I/O contract (Phase D):
+//   read:  git branch state, Build session notes (completed), package.json
+//          version state (npm)
+//   write: session (completed | rejected), event (completed | rejected),
+//          verdict row, park row (budget/instrument exhaustion)
+//   out:   ADVANCE → Integrate | REWIND → Build | PARK |
+//          NEED_SPAWN / STANDBY / FAILED (boundary)
+
+import {
+  runWorkBoundary, recordPhase, buildEventPreamble, summarizeReport,
+  ensureClaimed, log, latestSessionNotes, crewApi, lifecycle,
+  lifecycleEnvPrefix, parkTask,
+} from "../../workflow-lib.js";
+import {
+  parseClassifyFerry, parseVersionFerry, extractReleaseDecision, extractVerdict,
+} from "../../extract.js";
+
+export const PHASE = { name: "Review", identity: "cass" };
+
+var MAX_REWORK = 2;
+
+// buildInstructions — verbatim from workflows/bugfix.js (variable
+// references remapped; logic and prose unchanged).
+// ctx: { env, mapperSpec, releaseDecisionText, releaseDecision,
+//        alreadyMergedSha, reviewChangeExam, reviewBranchRule }.
+export function buildInstructions(ctx) {
+  var env = ctx.env;
+  var instructions = "Review independently and cold. You have NOT seen any reasoning from the builder.\nDo NOT access the task dashboard, event log, or any comments. Your review is based solely on the spec and the code.\n\n" +
+      (ctx.mapperSpec ? "MAPPER'S SPEC (the builder was asked to implement exactly this):\n" + ctx.mapperSpec + "\n\n" : "Read the spec (from the task description or spec files under " + env.crewHome + "/).\n\n") +
+      ctx.reviewChangeExam +
+      "You can also read specific files in the worktree at:\n" +
+      env.worktreeHint + "/\n\n" +
+      "Check quality, correctness, and spec compliance.\n" +
+      (env.surfaceTerminal ? "TERMINAL UX REVIEW: judge the CLI surface against " + env.uxDoctrinePath + " — help accuracy, error quality, exit codes, output clarity. Reject when the bar is not met.\n" : "") +
+      (env.surfaceArtifact ? "ARTIFACT UX REVIEW: judge the rendered surface against " + env.uxDoctrinePath + " — alignment, spacing, hierarchy, composition, balance, finish, correctness. Reject when the bar is not met.\n" : "") +
+      "Check that public-affecting changes have matching public doc updates (API.md or the published API contract). If the docs are missing or inaccurate, report what is stale, then end your report with exactly this line: VERDICT: FAIL.\n" +
+      ctx.reviewBranchRule +
+      (env.publishType === "npm" ? "PACKAGE VERSION: this project publishes to the npm registry, and versions are assigned at publish time — never in branches.\n" +
+      "MECHANICAL FACT (computed by the workflow from git — never by a reviewer): the task branch did not change package.json's `version` field. A branch that touches `version` fails Review mechanically before any reviewer is dispatched, so this is settled — do not re-check it.\n" +
+      "The accepted Build report declares: " + ctx.releaseDecisionText + ". " +
+      (ctx.releaseDecision
+        ? "Validate this decision against the change: release must be 'yes' when the change is consumer-observable and 'no' when internal-only; the version_bump scope must fit the change (patch for fixes, minor for new behavior, major for breaking changes). If the decision is wrong or mis-scoped, report your notes, then end with exactly this line: VERDICT: FAIL."
+        : "The decision is missing or malformed — report 'Build report must end with release: yes|no and (when release is yes) version_bump: patch|minor|major lines', then end with exactly this line: VERDICT: FAIL.") + "\n" : "") +
+      "Write your review as plain prose — findings, then decision. End your report with exactly one line: VERDICT: PASS if the work passes, VERDICT: FAIL if it fails.";
+
+  
+  return instructions;
+}
+
+// releaseDecisionText — the human-readable release decision (source:
+// releaseDecisionText).
+function releaseDecisionText(rd) {
+  if (!rd) return "no machine-readable release decision from the Build report";
+  return "release: " + rd.release + (rd.version_bump ? ", version_bump: " + rd.version_bump : " (no version_bump line)");
+}
+
+// classifyBranch — mechanical branch-state classification via the lifecycle
+// script, run directly (worker-layer equivalent of the source's agent
+// ferry). Retries in place on unparseable/instrument failure (2 retries);
+// exhaustion returns {ok:false} and the caller parks honestly.
+async function classifyBranch(env) {
+  var lastErr = "";
+  for (var attempt = 0; attempt <= 2; attempt++) {
+    var stdout, stderr;
+    try {
+      var res = await lifecycle(env, "classify-branch", [env.taskId]);
+      stdout = res.stdout; stderr = res.stderr;
+    } catch (e) {
+      lastErr = "classifier call failed: " + String((e && e.message) || e).slice(0, 120);
+      if (attempt < 2) log("classify-branch instrument failure (" + lastErr + ") — retrying in place (attempt " + (attempt + 1) + " of 2)");
+      continue;
+    }
+    var parsed = parseClassifyFerry({ stdout: stdout, stderr: stderr });
+    if (parsed.state !== null) {
+      if (parsed.diagField !== null) {
+        log("classify-branch DIAG pin (" + parsed.diagField + " field): " + parsed.diagText);
+      } else {
+        log("classify-branch: no DIAG: record-scan counter returned (scan unverifiable)");
+      }
+      return { ok: true, state: parsed.state };
+    }
+    lastErr = parsed.failReason;
+    if (attempt < 2) log("classify-branch unparseable (" + lastErr + ") — retrying in place (attempt " + (attempt + 1) + " of 2)");
+  }
+  return { ok: false, reason: lastErr };
+}
+
+// checkVersion — mechanical package.json `version` check (npm only), same
+// direct-execution shape as classifyBranch.
+async function checkVersion(env) {
+  var lastErr = "";
+  for (var attempt = 0; attempt <= 2; attempt++) {
+    var stdout;
+    try {
+      var res = await lifecycle(env, "version-check", [env.taskId]);
+      stdout = res.stdout;
+    } catch (e) {
+      lastErr = "version-check call failed: " + String((e && e.message) || e).slice(0, 120);
+      if (attempt < 2) log("version-check instrument failure (" + lastErr + ") — retrying in place (attempt " + (attempt + 1) + " of 2)");
+      continue;
+    }
+    var parsed = parseVersionFerry({ stdout: stdout });
+    if (parsed.versionState !== null) return { ok: true, state: parsed.versionState };
+    lastErr = parsed.failReason;
+    if (attempt < 2) log("version-check unparseable (" + lastErr + ") — retrying in place (attempt " + (attempt + 1) + " of 2)");
+  }
+  return { ok: false, reason: lastErr };
+}
+
+export async function runPhase(ctx) {
+  var env = ctx.env, state = ctx.state;
+
+  var claimed = await ensureClaimed(env, state, PHASE);
+  if (claimed.type !== "CLAIMED") return claimed;
+
+  // 1. Branch classification — re-done on EVERY Review entry (rework
+  // rewinds here and the branch changed between rounds).
+  var bc = await classifyBranch(env);
+  if (!bc.ok) {
+    return await parkTask(env, "Branch state unclassifiable after 2 instrument retries (" + bc.reason + ") — the classifier instrument failed, not the branch. Human attention needed: inspect the task branch directly to determine its state — no trustworthy branch classification was produced.");
+  }
+  var branchState = bc.state;
+  var alreadyMergedSha = null;
+  if (branchState.indexOf("already-merged:") === 0) {
+    alreadyMergedSha = branchState.slice("already-merged:".length);
+    log("Branch state already-merged: " + alreadyMergedSha + " (DIAG pin present — tripwire satisfied) — Cass reviews the frozen merge diff");
+  } else {
+    log("Branch state: " + branchState);
+  }
+
+  // 2. Accepted Build report facts (durable session notes).
+  var buildNotes = await latestSessionNotes(env, "Build", "completed");
+  var buildClaimedNoDiff = /repo_diff:\s*none/im.test(buildNotes);
+  var releaseDecision = extractReleaseDecision(buildNotes);
+
+  // 3. package.json `version` check (npm only) — mechanical git fact.
+  var versionTouched = false;
+  if (env.publishType === "npm") {
+    var vc = await checkVersion(env);
+    if (!vc.ok) {
+      return await parkTask(env, "package.json `version` state unclassifiable after 2 instrument retries (" + vc.reason + ") — the version-check instrument failed, not the branch. Human attention needed: inspect the task branch directly to determine its state — no trustworthy version classification was produced.");
+    }
+    versionTouched = (vc.state === "touched");
+    log("Review: package.json `version` " + (versionTouched ? "touched by the branch — mechanical FAIL, Cass not dispatched" : "untouched — mechanical check clean"));
+  }
+
+  // 4. Mechanical FAIL gate — Cass is never dispatched; the synthetic
+  // report flows through the same verdict/closeout path as a real FAIL.
+  var mechanicalFailReason = versionTouched ? "version-touched"
+    : (branchState === "empty-no-work" && !buildClaimedNoDiff ? "empty-no-work" : null);
+  var mechanicalReviewFail = (mechanicalFailReason !== null);
+
+  var workerText;
+  var verdictPassed;
+  if (mechanicalReviewFail) {
+    log("Review: " + mechanicalFailReason + " — mechanical FAIL, Cass not dispatched");
+    workerText =
+      "MECHANICAL REVIEW VERDICT (written by the workflow — no reviewer was dispatched).\n" +
+      (mechanicalFailReason === "version-touched"
+        ? "Package.json `version` (checked by the workflow from git): the task branch changed the `version` field. Versions are assigned at publish time — never in branches. Remove the version change.\n"
+        : "Branch state (classified by the workflow from git): empty-no-work — the task branch has no commits ahead of the integration target, " +
+          "no task-attributed merge on the target was verified, " +
+          "and the accepted Build report declared no `repo_diff: none` deliverable. " +
+          "No change was reviewed because there is no change to review. The branch is empty and no task-attributed merge was verified.\n") +
+      "Worktree: " + env.worktreeHint + "\n" +
+      "Recovery: commit the deliverable on the task branch in the worktree above and re-run Review. If the deliverable is genuinely runtime state outside the repo, declare `repo_diff: none` in the Build report instead of leaving the branch empty without a declaration.\n" +
+      "VERDICT: FAIL";
+    verdictPassed = false;
+  } else {
+    // 5. Branch-state-specific exam rule (verbatim from source).
+    var reviewChangeExam, reviewBranchRule;
+    if (branchState === "has-work") {
+      reviewChangeExam =
+        "Examine the code changes by running:\n" +
+        lifecycleEnvPrefix(env) + env.lifecycle + " inspect " + env.taskId + "\n\n" +
+        "The inspect output is authoritative: it prints the task branch's actual tip commit (TIP) and every commit ahead of the integration target (inspect prints the target name). Base your review ONLY on this output — do NOT run git log yourself to pick commits, and do NOT discuss commit hashes from any other source (they may come from stale rework rounds or a different repo).\n\n";
+      reviewBranchRule =
+        "MECHANICAL FACT (computed by the workflow from git — never by a reviewer): branch state = has-work. The branch has commits ahead of the integration target. Review their content; branch emptiness is settled and is not yours to judge.\n";
+    } else if (branchState.indexOf("already-merged:") === 0) {
+      reviewChangeExam =
+        "The change under review is the frozen merge " + alreadyMergedSha + " — it is already on the integration target (see MECHANICAL FACT below). Examine it by running:\n" +
+        "cd " + env.repoPath + " && git diff " + alreadyMergedSha + "^1 " + alreadyMergedSha + "\n\n" +
+        "That first-parent diff is the frozen, attributable change. Base your review ONLY on this diff — do NOT run git log to pick commits, and do NOT discuss commit hashes from any other source (they may come from stale rework rounds or a different repo).\n\n";
+      reviewBranchRule =
+        "MECHANICAL FACT (computed by the workflow from git — never by a reviewer): branch state = already-merged:" + alreadyMergedSha + ". The deliverable landed on the integration target via this task's own prior merge " + alreadyMergedSha + " (verified ancestor of the integration target). The branch is empty by design — emptiness is settled fact, not a finding.\n";
+    } else if (buildClaimedNoDiff) {
+      reviewChangeExam =
+        "The branch has no commits ahead of the integration target (see MECHANICAL FACT below) — there is no diff to examine. Judge the Build report's `repo_diff: none` claim on its plausibility.\n\n";
+      reviewBranchRule =
+        "MECHANICAL FACT (computed by the workflow from git — never by a reviewer): the branch has no commits ahead of the integration target and no task-attributed merge on the target was verified; the Build report declares `repo_diff: none` (no repo change). Approve ONLY if the task's deliverable is plausibly runtime state (e.g. a cron definition, scheduler change, or dashboard/config state created outside the repo). Otherwise report 'no commits ahead of the integration target and no plausible runtime-state deliverable — the branch is empty and no task-attributed merge was verified', then end your report with exactly this line: VERDICT: FAIL.\n";
+    } else {
+      reviewChangeExam = "";
+      reviewBranchRule = "";
+    }
+    ctx.mapperSpec = await latestSessionNotes(env, "Map", "completed");
+    ctx.releaseDecisionText = releaseDecisionText(releaseDecision);
+    ctx.releaseDecision = releaseDecision;
+    ctx.alreadyMergedSha = alreadyMergedSha;
+    ctx.reviewChangeExam = reviewChangeExam;
+    ctx.reviewBranchRule = reviewBranchRule;
+
+    var boundary = await runWorkBoundary(env, state, {
+      phase: PHASE.name,
+      identity: PHASE.identity,
+      instructions: buildInstructions(ctx),
+      eventPreamble: buildEventPreamble(env, PHASE.name),
+      crewApiLine: true,
+      verdictStep: true,
+    });
+    if (boundary.type !== "BOUNDARY_DONE") return boundary;
+    workerText = boundary.workerText;
+    verdictPassed = boundary.verdictPassed === true;
+  }
+
+  // 6. Review basis (structured, for the verdict row and session notes).
+  var reviewBasis = mechanicalReviewFail ? "mechanical-fail" :
+    branchState.indexOf("already-merged:") === 0 ? "frozen-merge:" + alreadyMergedSha :
+    branchState === "has-work" ? "branch-diff" : "runtime-state-none";
+  var reviewBasisNote;
+  if (mechanicalReviewFail) {
+    reviewBasisNote = "REVIEW_BASIS: none — mechanical FAIL (" + mechanicalFailReason + "), no reviewer dispatched";
+  } else if (branchState.indexOf("already-merged:") === 0) {
+    reviewBasisNote = "REVIEW_BASIS: frozen merge " + alreadyMergedSha + " — reviewed via git diff " + alreadyMergedSha + "^1 " + alreadyMergedSha;
+  } else if (branchState === "has-work") {
+    reviewBasisNote = "REVIEW_BASIS: branch diff — reviewed via inspect output (task branch vs integration target)";
+  } else {
+    reviewBasisNote = "REVIEW_BASIS: runtime-state-none — no repo change; plausibility of Build's repo_diff: none claim";
+  }
+
+  // 7. Closeout with the structured verdict record.
+  var status = verdictPassed ? "completed" : "rejected";
+  var summary = reviewBasisNote + "\n" + summarizeReport(workerText);
+  await recordPhase(env, {
+    task_id: env.taskId,
+    session: {
+      id: state.activeSessionId, task_id: env.taskId, identity: PHASE.identity,
+      step: PHASE.name, status: status, notes: summary,
+    },
+    event: {
+      task_id: env.taskId, type: status, identity: PHASE.identity,
+      message: "Review " + status + " by " + PHASE.identity,
+    },
+    verdict: {
+      step: "Review",
+      attempt: state.reworkCount,
+      reviewer: mechanicalReviewFail ? "workflow" : PHASE.identity,
+      verdict: verdictPassed ? "PASS" : "FAIL",
+      review_basis: reviewBasis,
+      grounds: workerText,
+    },
+  });
+
+  if (!verdictPassed) {
+    // Shared Review/QA rework budget (spec.reworkPhases): state.reworkCount
+    // is the count BEFORE this rejection; the new count would be +1.
+    if (state.reworkCount >= MAX_REWORK) {
+      log("Shared rework budget exhausted for task " + env.taskId + " — worktree preserved at " + env.worktreePreservedHint + " for manual inspection");
+      return await parkTask(env, "Exceeded shared rework budget (" + MAX_REWORK + " total rework attempts across Review and QA) after Review rejection. Worktree preserved.");
+    }
+    log("Review rejected — bouncing to Build (rework #" + (state.reworkCount + 1) + " of " + MAX_REWORK + ")");
+    return { type: "REWIND", next: "Build" };
+  }
+  return { type: "ADVANCE", next: "Integrate" };
+}

package/lib/bugfix/phases/triage.js

@@ -0,0 +1,69 @@
+// lib/bugfix/phases/triage.js — Triage (sage) phase module (sandbox exit,
+// Phase D). Import-safe: no side effects on import, bare `node` exits 0.
+//
+// Reads: task/project/surface facts, claim/session context.
+// Writes: completed/rejected session + event; the machine-read
+// `experiential: yes|no` marker line, the optional `terminal_targets:`
+// line, and the machine-read `layer: artifact|engine|docs` line. The
+// durable cross-run handoff is the Triage session notes (Reproduce
+// resolves the layer from them; Capture/QA resolve experiential).
+// Transitions: ADVANCE → Capture (a rejected Triage still advances; only
+// Review, Integrate, and Publish have special failure paths).
+
+import {
+  runWorkBoundary, recordPhase, buildEventPreamble, summarizeReport,
+  closeoutPassed, ensureClaimed, log,
+} from "../../workflow-lib.js";
+import { extractExperiential, extractLayer } from "../../extract.js";
+
+export const PHASE = { name: "Triage", identity: "sage" };
+
+// buildInstructions — pure function of ctx. Verbatim from
+// workflows/bugfix.js (Triage branch): the standard triage prompt plus the
+// bugfix workflow assignment and the LAYER FLAG block.
+export function buildInstructions(ctx) {
+  var env = ctx.env;
+  return "Validate the task against the project's repo at " + env.repoPath + " — that exact checkout, not any other copy of the project on disk. If you run git commands, cd " + env.repoPath + " first.\nCheck clarity, note dependencies, confirm the bugfix workflow assignment.\nIf the task needs decomposition, note that in your assessment.\nReport back in plain prose — what you found.\nEXPERIENTIAL FLAG: does this task change anything a user can directly observe in the project's user-facing surface? " + env.surfaceTriageDesc + " For an artifact surface that means rendered and visible — pages, components, styles, layout, copy, visual states. For a terminal surface it means the CLI experience — command output, help text, flags, error messages, defaults. The shared UX bar is " + (env.uxDoctrinePath ? env.uxDoctrinePath + " — flag experiential when the task touches anything it covers." : "not classified for this project — flag experiential when the task touches anything user-observable in the surface described above.") + " If yes it is experiential and gets baseline evidence (plus an experiential verdict where the workflow has a QA phase). For terminal-surface tasks also declare the CLI surface to exercise: end your report with a line `terminal_targets: <comma-separated CLI commands/flags>` (machine-read; optional — falls back to the task description). End your report with exactly one line on its own, lowercase, unrephrased: experiential: yes — or experiential: no. This line is machine-read.\nLAYER FLAG: classify the bug's layer — where the reported misbehavior lives. artifact: user-facing behavior of the project's rendered artifact (something a user sees or clicks). engine: the crew's own machinery — workflows, lib scripts, shell scripts, tests, scheduler. docs: a documentation gap or error. End your report with exactly one line on its own, lowercase, unrephrased: layer: artifact — or layer: engine — or layer: docs. This line is machine-read. If the bug genuinely spans layers, pick the layer where reproduction must happen and note the ambiguity in prose.";
+}
+
+export async function runPhase(ctx) {
+  var env = ctx.env, state = ctx.state;
+  var claimed = await ensureClaimed(env, state, PHASE);
+  if (claimed.type !== "CLAIMED") return claimed;
+
+  var boundary = await runWorkBoundary(env, state, {
+    phase: PHASE.name, identity: PHASE.identity,
+    instructions: buildInstructions(ctx),
+    eventPreamble: buildEventPreamble(env, PHASE.name),
+    crewApiLine: true, verdictStep: false,
+  });
+  if (boundary.type !== "BOUNDARY_DONE") return boundary;
+
+  // Triage is not a verdict step: producing output means passed.
+  var passed = closeoutPassed(boundary);
+  var workerText = boundary.workerText;
+  var summary = summarizeReport(workerText);
+  var status = passed ? "completed" : "rejected";
+  await recordPhase(env, {
+    task_id: env.taskId,
+    session: { id: state.activeSessionId, task_id: env.taskId, identity: PHASE.identity, step: PHASE.name, status: status, notes: summary },
+    event: { task_id: env.taskId, type: status, identity: PHASE.identity, message: PHASE.name + " " + status + " by " + PHASE.identity },
+  });
+  if (!passed) {
+    // A rejected Triage still advances; the rejection is recorded.
+    log("Triage rejected for task " + env.taskId + " — advancing");
+    return { type: "ADVANCE", next: "Capture", experiential: null };
+  }
+  // Stash the terminal targets and the bug layer run-locally (both are
+  // re-derivable from the Triage session notes' marker lines on a resumed
+  // run — the layer marker survives in the notes via extractMarkerLines).
+  var ttm = /^terminal_targets:\s*(.+)/im.exec(workerText || "");
+  state.memo.terminalTargets = ttm ? ttm[1].trim().slice(0, 300) : "";
+  var layer = extractLayer(workerText);
+  state.memo.layerResolved = layer || "artifact";
+  log("Triage complete for task " + env.taskId + " (layer: " + state.memo.layerResolved + ")");
+  return {
+    type: "ADVANCE", next: "Capture",
+    experiential: extractExperiential(workerText),
+  };
+}