muse-crew 0.17.2 → 0.17.3

package/lib/spawn-step.js

@@ -0,0 +1,572 @@
+#!/usr/bin/env node
+// lib/spawn-step.js — the production spawn wrapper (sandbox exit, chore
+// pilot Piece 2, 2026-09-26).
+//
+// Shebang CLI. --help answers with usage on stdout, exit 0.
+//
+// The bridge between the deterministic driver (chore-run.js derive) and
+// the tick worker's spawn tool. The tick worker never builds prompts or
+// touches the ledger directly — everything crosses this boundary.
+//
+//   pre  --request '<json>'
+//     Validate bounds+request, enforce the frozen kind vocabulary, check
+//     the duplicate-pre guard (M2), derive attempt_n (F5), enforce the
+//     per-kind attempt cap and the consecutive transport-failure budget,
+//     open the ledger row (crew-api record-spawn-open), build the prompt
+//     from the registered pure builder, mint the session path. Prints one
+//     JSON line on stdout:
+//       {prompt,cwd,env,timeout_ms,session_path,key,attempt_n,row_id}
+//     Exit non-zero = refused; stdout carries {error:{code,message}} with
+//     code in BOUNDS_REJECTED | DUPLICATE_RUNNING | ATTEMPTS_EXHAUSTED |
+//     TRANSPORT_BUDGET_EXHAUSTED.
+//
+//   post --session '<path>' [--key '<spawn_key>']
+//     Read the session file, classify per the routing order (extractors →
+//     reask signal → transport outcomes; kill states only with machine
+//     evidence — an unverified kill leaves the row running for the
+//     reaper), close the ledger row (crew-api record-spawn-close) with a
+//     closed-vocabulary outcome. Prints the typed result on stdout:
+//       {closed:true,row_id,status,outcome,...payload}
+//     or {closed:false,reason} when the row was left running.
+//
+// Session file schema (written by the tick worker):
+//   { key, child: {kind:"subagent",agent_id} | {kind:"os_pid",pid,start_time},
+//     outcome: "returned"|"timeout"|"spawn_error"|"synthetic",
+//     text?, error?, kill_evidence?: {verified_dead, method, detail} }
+// The tick worker records `child` immediately after spawning (so the
+// Step-0 reaper can find it) and the outcome when the spawn settles.
+// outcome "synthetic" is the P3 no-spawn branch: the workflow authored the
+// prose, no agent was spawned; it flows through the same extractors and
+// closes the row identically — the bridge never requires a spawn to
+// produce a typed result.
+//
+// The closed outcome vocabulary is enforced fail-closed here AND in
+// crew-api record-spawn-close: a row may only leave 'running' with a
+// CLOSED_OUTCOMES outcome. Agent output is data, never executable —
+// extractors parse it, nothing evals it.
+
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { validateSpawnBounds } from "./spawn-boundary.js";
+import {
+  SPAWN_KINDS,
+  MAX_ATTEMPTS,
+  TRANSPORT_BUDGET_CAP,
+  MAX_TIMEOUT_MS,
+  MIN_TIMEOUT_MS,
+  isClosedOutcome,
+} from "./chore/spawn-vocab.js";
+import {
+  extractVerdict,
+  extractMarkerLines,
+  parseToolSignals,
+  extractReleaseDecision,
+  extractWorktree,
+  extractExperiential,
+} from "./chore/extract.js";
+import { buildWorkPrompt } from "./chore/prompts/work-agent.js";
+import { buildVerdictReaskPrompt } from "./chore/prompts/verdict-reask.js";
+import { buildEvidenceGathererPrompt } from "./chore/prompts/evidence-gatherer.js";
+
+const LIB_DIR = dirname(fileURLToPath(import.meta.url));
+const CREW_API = join(LIB_DIR, "crew-api.js");
+const PROMPTS_DIR = join(LIB_DIR, "chore", "prompts");
+
+// Closed kind → (prompt module, schema file, builder). Unknown kinds fail
+// closed in pre. The request's bounds.prompt_file / bounds.schema_file must
+// equal these exact paths — a chore-run.js bug pointing at the wrong
+// builder is rejected, not silently honored.
+const KIND_REGISTRY = {
+  "work-agent": {
+    promptFile: join(PROMPTS_DIR, "work-agent.js"),
+    schemaFile: join(PROMPTS_DIR, "work-agent.schema.json"),
+    build: buildWorkPrompt,
+  },
+  "verdict-reask": {
+    promptFile: join(PROMPTS_DIR, "verdict-reask.js"),
+    schemaFile: join(PROMPTS_DIR, "verdict-reask.schema.json"),
+    build: buildVerdictReaskPrompt,
+  },
+  "evidence-gatherer": {
+    promptFile: join(PROMPTS_DIR, "evidence-gatherer.js"),
+    schemaFile: join(PROMPTS_DIR, "evidence-gatherer.schema.json"),
+    build: buildEvidenceGathererPrompt,
+  },
+};
+
+const USAGE = [
+  "usage: spawn-step.js pre --request '<json>'",
+  "       spawn-step.js post --session '<path>' [--key '<spawn_key>']",
+  "       spawn-step.js --help",
+  "",
+  "The production spawn wrapper: pre validates the typed spawn request,",
+  "opens the worker_runs ledger row, builds the prompt, and mints the",
+  "session path; post classifies the session file and closes the row with",
+  "a closed-vocabulary outcome. Refusal codes: BOUNDS_REJECTED |",
+  "DUPLICATE_RUNNING | ATTEMPTS_EXHAUSTED | TRANSPORT_BUDGET_EXHAUSTED.",
+].join("\n");
+
+function log(msg) {
+  process.stderr.write("[spawn-step] " + msg + "\n");
+}
+
+function printJson(obj) {
+  process.stdout.write(JSON.stringify(obj) + "\n");
+}
+
+function fail(code, message, extra) {
+  printJson({ error: Object.assign({ code, message }, extra || {}) });
+  process.exit(1);
+}
+
+function callCrewApi(crewHome, command, argsObj) {
+  const argv = ["--crew-home", crewHome, command];
+  if (argsObj !== undefined) argv.push("--json", JSON.stringify(argsObj));
+  let stdout;
+  try {
+    stdout = execFileSync("node", [CREW_API, ...argv], {
+      encoding: "utf8",
+      maxBuffer: 16 * 1024 * 1024,
+    });
+  } catch (e) {
+    const detail = (e.stderr && e.stderr.toString()) || e.message;
+    throw new Error("crew-api " + command + " failed: " + detail.slice(0, 500));
+  }
+  try {
+    return JSON.parse(stdout);
+  } catch (e) {
+    throw new Error("crew-api " + command + " returned unparseable JSON");
+  }
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+function requireNonEmptyString(v, name) {
+  if (typeof v !== "string" || v.length === 0) {
+    throw new Error("request." + name + " must be a non-empty string");
+  }
+  return v;
+}
+
+// ── pre ──────────────────────────────────────────────────────────────
+
+function validatePreRequest(req) {
+  if (!isPlainObject(req)) throw new Error("request must be a JSON object");
+  const key = requireNonEmptyString(req.key, "key");
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(key)) {
+    throw new Error("request.key must be [A-Za-z0-9_-], up to 128 chars");
+  }
+  const kind = requireNonEmptyString(req.kind, "kind");
+  if (!SPAWN_KINDS.includes(kind)) {
+    throw new Error("unknown spawn kind: " + kind + " (frozen vocabulary: " + SPAWN_KINDS.join(", ") + ")");
+  }
+  const taskId = requireNonEmptyString(req.task_id, "task_id");
+  const phase = requireNonEmptyString(req.phase, "phase");
+  requireNonEmptyString(req.identity, "identity");
+  if (!Number.isInteger(req.owner_tick_seq) || req.owner_tick_seq <= 0) {
+    throw new Error("request.owner_tick_seq must be a positive integer");
+  }
+  if (!Number.isInteger(req.timeout_ms) || req.timeout_ms < MIN_TIMEOUT_MS || req.timeout_ms > MAX_TIMEOUT_MS) {
+    throw new Error(
+      "request.timeout_ms must be an integer in [" + MIN_TIMEOUT_MS + ", " + MAX_TIMEOUT_MS + "]"
+    );
+  }
+  const bounds = req.bounds;
+  if (!isPlainObject(bounds)) throw new Error("request.bounds must be an object");
+  const promptFile = requireNonEmptyString(bounds.prompt_file, "bounds.prompt_file");
+  const schemaFile = requireNonEmptyString(bounds.schema_file, "bounds.schema_file");
+  // Closed kind→file mapping: the orchestrator declares its bounds, pre
+  // verifies they are exactly the registered files for the kind.
+  const reg = KIND_REGISTRY[kind];
+  if (resolve(promptFile) !== reg.promptFile) {
+    throw new Error("bounds.prompt_file is not the registered builder for kind '" + kind + "'");
+  }
+  if (resolve(schemaFile) !== reg.schemaFile) {
+    throw new Error("bounds.schema_file is not the registered schema for kind '" + kind + "'");
+  }
+  if (!isPlainObject(req.prompt_params)) throw new Error("request.prompt_params must be an object");
+  if (req.env !== undefined || bounds.env !== undefined) {
+    const env = bounds.env;
+    if (!isPlainObject(env)) throw new Error("bounds.env must be an object of string values");
+    for (const k of Object.keys(env)) {
+      if (typeof env[k] !== "string") throw new Error("bounds.env['" + k + "'] must be a string");
+    }
+  }
+  return { key, kind, taskId, phase, bounds, reg };
+}
+
+function checkFileReadable(path, what) {
+  try {
+    readFileSync(path, "utf8");
+  } catch (e) {
+    throw new Error(what + " not readable: " + path + " (" + e.message + ")");
+  }
+}
+
+// Close an opened ledger row as a refused open (transport_failed) so a
+// post-open pre failure never leaves a running row. Best-effort: if the
+// close itself fails, the Step-0 reaper owns the orphaned running row.
+function closeOpenedAsRefused(crewHome, rowId, kind, taskId, phase, attemptN, key, error) {
+  try {
+    callCrewApi(crewHome, "record-spawn-close", {
+      id: rowId,
+      status: "failed",
+      result: {
+        outcome: "transport_failed",
+        kind,
+        task_id: taskId,
+        phase,
+        attempt_n: attemptN,
+        spawn_key: key,
+        error,
+      },
+    });
+  } catch (closeErr) {
+    log("WARNING: failed to close refused row " + rowId + ": " + closeErr.message);
+  }
+}
+
+function cmdPre(requestJson) {
+  let req;
+  try {
+    req = JSON.parse(requestJson);
+  } catch (e) {
+    fail("BOUNDS_REJECTED", "request is not valid JSON: " + e.message);
+  }
+  let v;
+  try {
+    v = validatePreRequest(req);
+  } catch (e) {
+    fail("BOUNDS_REJECTED", e.message);
+  }
+  const { key, kind, taskId, phase, bounds, reg } = v;
+  const crewHome = bounds.crewHome;
+
+  // Bounds validation (fail closed) + prompt/schema existence + readability.
+  // A bad path is an orchestrator bug — rejected before attempts burn.
+  try {
+    validateSpawnBounds(bounds);
+    checkFileReadable(reg.promptFile, "prompt_file");
+    checkFileReadable(reg.schemaFile, "schema_file");
+  } catch (e) {
+    fail("BOUNDS_REJECTED", e.message);
+  }
+
+  // Ledger pre-flight: duplicate guard (M2), attempt derivation (F5),
+  // transport budget — all read-only, one crew-api call.
+  let assess;
+  try {
+    assess = callCrewApi(crewHome, "assess-spawn-pre", {
+      task_id: taskId,
+      phase,
+      kind,
+      spawn_key: key,
+    });
+  } catch (e) {
+    fail("BOUNDS_REJECTED", "ledger pre-flight failed: " + e.message);
+  }
+  if (assess.duplicate_running) {
+    fail("DUPLICATE_RUNNING", "a running ledger row already exists for spawn_key " + key, {
+      row_id: assess.duplicate_row_id,
+    });
+  }
+  if (assess.attempt_n > assess.max_attempts) {
+    fail("ATTEMPTS_EXHAUSTED", "attempt " + assess.attempt_n + " exceeds max_attempts=" + assess.max_attempts + " for kind '" + kind + "'", {
+      attempt_n: assess.attempt_n,
+      max_attempts: assess.max_attempts,
+    });
+  }
+  if (assess.transport_failures >= assess.budget_cap) {
+    fail("TRANSPORT_BUDGET_EXHAUSTED", "task " + taskId + " has " + assess.transport_failures + " consecutive transport failures (cap " + assess.budget_cap + ")", {
+      transport_failures: assess.transport_failures,
+      budget_cap: assess.budget_cap,
+    });
+  }
+
+  // Open the ledger row (re-checks the duplicate guard for race safety).
+  let opened;
+  try {
+    opened = callCrewApi(crewHome, "record-spawn-open", {
+      task_id: taskId,
+      phase,
+      spawn_key: key,
+      owner_tick_seq: req.owner_tick_seq,
+      kind,
+      timeout_ms: req.timeout_ms,
+    });
+  } catch (e) {
+    fail("BOUNDS_REJECTED", "ledger open failed: " + e.message);
+  }
+  if (opened && opened.ok === false && opened.refused === "duplicate_running") {
+    fail("DUPLICATE_RUNNING", "a running ledger row already exists for spawn_key " + key, {
+      row_id: opened.row_id,
+    });
+  }
+  if (!opened || !opened.ok || !opened.id) {
+    fail("BOUNDS_REJECTED", "ledger open returned an unexpected result");
+  }
+
+  // Build the prompt from the registered pure builder. A params bug is an
+  // orchestrator bug — rejected before the spawn burns.
+  let prompt;
+  try {
+    prompt = reg.build(req.prompt_params);
+  } catch (e) {
+    // The row was opened but the request is malformed: close it as a
+    // refused open so it never lingers as running.
+    closeOpenedAsRefused(crewHome, opened.id, kind, taskId, phase, assess.attempt_n, key,
+      "prompt build failed: " + e.message);
+    fail("BOUNDS_REJECTED", "prompt build failed: " + e.message);
+  }
+  if (typeof prompt !== "string" || prompt.length === 0) {
+    closeOpenedAsRefused(crewHome, opened.id, kind, taskId, phase, assess.attempt_n, key,
+      "prompt builder returned an empty prompt");
+    fail("BOUNDS_REJECTED", "prompt builder returned an empty prompt");
+  }
+
+  // Mint the session path and write the opened record. The tick worker
+  // records `child` here right after spawning, then the outcome.
+  const sessionDir = join(crewHome, ".spawn-sessions");
+  const sessionPath = join(sessionDir, key + ".json");
+  try {
+    mkdirSync(sessionDir, { recursive: true });
+    writeFileSync(
+      sessionPath,
+      JSON.stringify({
+        key,
+        kind,
+        task_id: taskId,
+        phase,
+        attempt_n: assess.attempt_n,
+        row_id: opened.id,
+        status: "spawn_pending",
+        opened_at: new Date().toISOString(),
+      }) + "\n",
+      "utf8"
+    );
+  } catch (e) {
+    closeOpenedAsRefused(crewHome, opened.id, kind, taskId, phase, assess.attempt_n, key,
+      "could not write session file: " + e.message);
+    fail("BOUNDS_REJECTED", "could not write session file: " + e.message);
+  }
+
+  log("pre ok: kind=" + kind + " task=" + taskId + " phase=" + phase + " attempt_n=" + assess.attempt_n + " row=" + opened.id);
+  printJson({
+    prompt,
+    cwd: bounds.cwd,
+    env: bounds.env || {},
+    timeout_ms: req.timeout_ms,
+    session_path: sessionPath,
+    key,
+    attempt_n: assess.attempt_n,
+    row_id: opened.id,
+  });
+  process.exit(0);
+}
+
+// ── post ─────────────────────────────────────────────────────────────
+
+function extractTypedResult(kind, text) {
+  const verdictRes = extractVerdict(text);
+  const base = {
+    verdict: verdictRes.ok ? (verdictRes.passed ? "PASS" : "FAIL") : null,
+    verdict_ok: verdictRes.ok,
+    tool_signals: parseToolSignals(text),
+    markers: extractMarkerLines(text),
+  };
+  if (kind === "verdict-reask" || kind === "evidence-gatherer") {
+    return base;
+  }
+  // work-agent (and the synthetic no-spawn branch): the full extraction.
+  base.worktree = extractWorktree(text);
+  base.release_decision = extractReleaseDecision(text);
+  base.experiential = extractExperiential(text);
+  return base;
+}
+
+function closeRow(crewHome, id, status, resultObj, errorNote) {
+  const outcome = resultObj.outcome;
+  if (!isClosedOutcome(outcome)) {
+    throw new Error("refusing to close with outcome outside the closed vocabulary: " + outcome);
+  }
+  const closed = callCrewApi(crewHome, "record-spawn-close", {
+    id,
+    status,
+    error: errorNote || null,
+    result: resultObj,
+  });
+  return closed;
+}
+
+function cmdPost(sessionPath, keyArg) {
+  let session;
+  try {
+    session = JSON.parse(readFileSync(sessionPath, "utf8"));
+  } catch (e) {
+    // No session, no outcome — the row stays running; the Step-0 reaper
+    // owns it. Post must not invent a result.
+    printJson({ closed: false, reason: "session_unreadable", detail: e.message });
+    process.exit(1);
+  }
+  const key = keyArg || session.key;
+  if (!key) {
+    printJson({ closed: false, reason: "session_unreadable", detail: "no spawn key" });
+    process.exit(1);
+  }
+  if (keyArg && session.key && keyArg !== session.key) {
+    printJson({ closed: false, reason: "key_mismatch", detail: "argv key != session key" });
+    process.exit(1);
+  }
+  // crewHome: the session file lives under <crewHome>/.spawn-sessions/.
+  const crewHome = resolve(sessionPath, "..", "..");
+  let rowRes;
+  try {
+    rowRes = callCrewApi(crewHome, "get-spawn-row", { spawn_key: key });
+  } catch (e) {
+    printJson({ closed: false, reason: "row_not_found", detail: e.message });
+    process.exit(1);
+  }
+  const row = rowRes.row;
+  if (row.status !== "running") {
+    // Idempotent: a duplicate post after the close is a no-op, not an error.
+    printJson({ closed: false, reason: "already_closed", row_id: row.id, status: row.status });
+    process.exit(0);
+  }
+  const kind = row.kind;
+  const common = {
+    kind,
+    task_id: row.task_id,
+    phase: row.phase,
+    attempt_n: null,
+    spawn_key: key,
+  };
+  try {
+    common.attempt_n = session.attempt_n || null;
+  } catch (e) { /* leave null */ }
+
+  const outcome = session.outcome;
+  let status;
+  let resultObj;
+
+  if (outcome === "synthetic") {
+    // P3 no-spawn branch: workflow-authored prose, no agent spawned. Same
+    // extractors, same close — the bridge never requires a spawn.
+    const text = typeof session.text === "string" ? session.text : "";
+    const typed = extractTypedResult(kind, text);
+    if (typed.verdict_ok) {
+      status = "completed";
+      resultObj = Object.assign({}, common, typed, { outcome: "synthetic" });
+    } else {
+      // Workflow-authored prose that fails extraction is an orchestrator
+      // bug — fail closed immediately (no reask for synthetic).
+      status = "failed";
+      resultObj = Object.assign({}, common, typed, {
+        outcome: "transport_parse",
+        error: "synthetic prose failed verdict extraction",
+      });
+    }
+  } else if (outcome === "returned") {
+    const text = typeof session.text === "string" ? session.text : "";
+    if (text.trim() === "") {
+      status = "failed";
+      resultObj = Object.assign({}, common, {
+        outcome: "transport_empty",
+        error: "agent returned blank text",
+      });
+    } else {
+      const typed = extractTypedResult(kind, text);
+      status = "completed";
+      resultObj = Object.assign({}, common, typed, { outcome: "completed" });
+      if (!typed.verdict_ok) {
+        // Verdict missing: the row still closes (the spawn is done). The
+        // driver sees needs_reask and runs the bounded verdict-reask loop
+        // — TRANSPORT_PARSE only after that budget is exhausted.
+        resultObj.needs_reask = true;
+      }
+    }
+  } else if (outcome === "timeout") {
+    const killEvidence = session.kill_evidence || {};
+    if (killEvidence.verified_dead === true) {
+      // Writer-is-verifier: the tick worker's machine liveness check
+      // proved the child dead. Close with the kill state.
+      status = "failed";
+      resultObj = Object.assign({}, common, {
+        outcome: "killed_confirmed",
+        kill_evidence: killEvidence,
+      });
+    } else {
+      // Unconfirmed kill: the row stays running. The cross-tick reaper is
+      // the verifier of record — post must not promote an unverified
+      // kill to a terminal state.
+      printJson({ closed: false, reason: "kill_unverified", row_id: row.id });
+      process.exit(0);
+    }
+  } else if (outcome === "spawn_error") {
+    status = "failed";
+    resultObj = Object.assign({}, common, {
+      outcome: "transport_error",
+      error: typeof session.error === "string" ? session.error : "spawn failed",
+    });
+  } else {
+    // Unknown session outcome — the tick worker wrote garbage. Terminal
+    // and safe (counts toward the transport budget), never guessed.
+    status = "failed";
+    resultObj = Object.assign({}, common, {
+      outcome: "transport_failed",
+      error: "unknown session outcome: " + String(outcome),
+    });
+  }
+
+  let closed;
+  try {
+    closed = closeRow(crewHome, row.id, status, resultObj);
+  } catch (e) {
+    printJson({ closed: false, reason: "close_failed", detail: e.message, row_id: row.id });
+    process.exit(1);
+  }
+  if (closed && closed.noop) {
+    printJson({ closed: false, reason: "already_closed", row_id: row.id });
+    process.exit(0);
+  }
+  log("post ok: row=" + row.id + " status=" + status + " outcome=" + resultObj.outcome);
+  printJson(Object.assign({ closed: true, row_id: row.id, status }, resultObj));
+  process.exit(0);
+}
+
+// ── main ─────────────────────────────────────────────────────────────
+
+function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+    process.stdout.write(USAGE + "\n");
+    process.exit(0);
+  }
+  const sub = argv[0];
+  if (sub === "pre") {
+    const ri = argv.indexOf("--request");
+    if (ri === -1 || !argv[ri + 1]) {
+      printJson({ error: { code: "BOUNDS_REJECTED", message: "pre requires --request '<json>'" } });
+      process.exit(1);
+    }
+    cmdPre(argv[ri + 1]);
+    return;
+  }
+  if (sub === "post") {
+    const si = argv.indexOf("--session");
+    if (si === -1 || !argv[si + 1]) {
+      printJson({ error: { code: "BOUNDS_REJECTED", message: "post requires --session '<path>'" } });
+      process.exit(1);
+    }
+    const ki = argv.indexOf("--key");
+    cmdPost(argv[si + 1], ki === -1 ? null : argv[ki + 1]);
+    return;
+  }
+  printJson({ error: { code: "BOUNDS_REJECTED", message: "unknown subcommand: " + sub } });
+  process.exit(1);
+}
+
+main();