muse-crew 0.16.0 → 0.17.0

package/API.md

@@ -133,6 +133,20 @@ Records a builder's refusal report (0.14.6). Mechanically requires the EXACT ver
 
 Returns `{ "ok": true, "publish_attempt" }`. The ack scan consumes refusal reports (terminal `publish: publish-refused`); positive acknowledgements come only from the on-disk version receipt.
 
+### `record-worker-run`
+
+Records a worker-layer execution in the `worker_runs` ledger (Piece 1, 2026-09-26). Identity is minted SQLite-side: a `start` call (no `id`) inserts a `running` row and returns its integer id; a `finish` call (`id` + terminal `status`) completes it. Terminal rows are immutable (R-2) — a finish against a non-running row is a silent no-op returning `{ "ok": true, "noop": true }`. `executor` is fixed at `'worker'` by the schema default.
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `id` | integer | on finish | SQLite-minted on start |
+| `task_id` | uuid or null | no | Optional correlation; null for dispatch runs |
+| `phase` | string | yes | e.g. `dispatch` |
+| `status` | `running` \| `completed` \| `failed` | yes | Start must pass `running`; finish must pass a terminal status |
+| `error` | string or null | no | Failure detail on `failed` |
+
+Bad transitions (start with an `id`, finish without one, finish with `running`, missing `phase`) throw usage errors (exit 2). Returns `{ "ok": true, "id" }` on start and `{ "ok": true, "finished": true }` on finish. Orphan note: a dispatcher killed between start and finish leaves a `running` row — readers treat a `running` row with no live dispatcher as stale, never as success.
+
 ### `record-version-ack`
 
 Stamps a version acknowledgement (0.14.6). The version must name an issued attempt for the task/commit.

package/lib/AGENTS.md

@@ -10,6 +10,9 @@ Shipped library: ESM JavaScript CLIs and import-safe modules, shell scripts for
 
 - `build-registry.js` — deterministic extractor that generates `workflows/registry.json` (workflow step registry) from the workflow files' `meta` blocks at release time; invoked by `crew-release.sh` deploy
 - `crew-api.js` — the crew-owned task-service API (dependency inversion, 2026-09-11): a zero-dependency Node CLI implementing the API.md contract against `$CREW_HOME/crew-state.db` (schema in `schema.sql`). Workflows call it through their agents' shell; the dashboard delegates to it. All state-machine invariants live as CHECK constraints in the schema, never in client prose. Includes the `record-phase` composite (session + event in one transaction; 2026-09-21 optionally carries a structured Review verdict payload — validated at the API boundary, written to the `verdicts` table in the same transaction, session-keyed first-write-wins idempotency — plus the `get-verdicts` read surface) and a one-time `migrate` import from a dashboard app.db. Active-release resolution is split in two (room #15): `resolveActiveReleaseName` (symlink-only — writers like the initial-provenance stamp record the active release without proving they are it) and `resolveActiveRelease` (symlink + self-path cross-check — verifiers like `scan-ack-pending` refuse to stamp claims when the running code isn't the active release's own). Provenance is per-project (2026-09-18, room #15 blocker 8): nullable `provenance_*` columns on the projects row, a single `stampProvenance()` writer, `set-provenance`/`get-provenance` require `project_id` (no silent global fallback), and a watermarked openDb backfill that attributes the legacy `config.provenance.*` triple to exactly-one ancestor match — never fabricated, otherwise deferred.
+- `crew-dispatch-worker.js` — worker-layer port of the sandboxed dispatch dispatcher (Piece 1, 2026-09-26): full-privilege Node, reads the board through crew-api.js via execFile (argv only, no shell), reproduces the eligibility / retry / reservation / playtest / tick-release / dispatch-decision logic, and tags every claim `executor: "worker"`. In Piece 1 it runs `--read-only` as the tick's shadow BEFORE the authoritative sandboxed dispatcher — both read the same board state; the shadow never mutates it, never launches, never writes the tick-release or dispatch-decision logs. Appends its own shadow evidence line to `$CREW_HOME/.dispatch-shadow.jsonl` (machine-written, no agent transcription). Claims are recommendations only: `executor` names the layer that computed the recommendation, not the layer that launched it — in Piece 1 no `executor: "worker"` claim is ever launched.
+- `compare-dispatch-shadow.js` — mechanical shadow verdict (Piece 1, 2026-09-26): pairs each `.dispatch-shadow.jsonl` line with the authoritative `.dispatch-decisions.jsonl` line for the same tick (`decision.tick_seq === shadow.tick_seq_before + 1` — the shadow runs first, the sandbox dispatcher then writes its tick-release line and its decision) and compares the sorted `task_id|workflow|step` claim triples, ignoring `executor`. Emits `SHADOW_MATCH` / `SHADOW_DIVERGE` (names the differing triples) / `SHADOW_UNPAIRED` (decision missing — the authoritative dispatcher died) and appends the verdict to `$CREW_HOME/.dispatch-shadow-verdicts.jsonl`; idempotent (already-verdict shadows are skipped). Exit 0 on a verdict — divergence is evidence for the cutover review, not a tick failure; exit 2 on usage/IO errors.
+- `spawn-boundary.js` — fail-closed spawn-bounds validator (Piece 1, 2026-09-26): import-safe ESM, `validateSpawnBounds()` requires prompt/schema co-location, cwd inside the workdir, rejection of cwd inside crew state/observer paths or crewHome, and rejection of sensitive env-key patterns; throws `BOUNDS_REJECTED`. Bare module execution exits 0 (release entry-gate contract). The production spawn/request wrapper is Piece-3 work; this is only the validator.
 - `schema.sql` — the crew-owned state schema: projects, tasks, poll_state, config, agent_sessions, events. Vocabularies enforced by CHECK constraints; `rejected` is a valid event type (the 2026-09-11 crash was a stored session whose event was rejected). Column names match the historical dashboard tables for a verbatim migration.
 - `crew-release.sh` — immutable release manager: deploy, rollback, prune
 - `merge-lock.sh` — serialized merge lock for concurrent agents: time-based holder lease (bug 2fc8f52f — an unexpired lease is held regardless of process liveness; only an expired lease may be broken). Requires both `CREW_REPO` and `CREW_HOME` (fail closed: BLOCKED, exit 2 when either is unset). Lock file is key=value: task_id, opaque holder identity (never a PID), acquired_at epoch, lease_seconds (default 600, override via MERGE_LOCK_LEASE_SECONDS). acquire/refresh/release/status/force-release; holder-only refresh and release; every op appends to $CREW_HOME/.merge-lock.log. Stale-lease breaks serialize on a sidecar `$LOCK_FILE.flock` with an in-critical-section lease re-read (R-B1, 2026-09-21); refresh rewrites via temp-file + atomic rename so readers never see a torn file, and takes the same sidecar flock with an identity-only re-check inside the critical section — a reclaim always changes `task_id`, so identity alone closes the clobber (no expiry check on refresh: a long build that outran the lease legitimately revives its lock); release takes the same flock with the identity re-check inside (review pass 2, 2026-09-21) so a release can never `rm` a reclaimer's fresh lock.

package/lib/compare-dispatch-shadow.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// lib/compare-dispatch-shadow.js — shadow verdict for the Piece-1 sandbox exit.
+//
+// Pairs the worker dispatcher's read-only shadow evidence
+// ($CREW_HOME/.dispatch-shadow.jsonl) with the authoritative sandbox
+// dispatcher's decision ($CREW_HOME/.dispatch-decisions.jsonl) and emits a
+// mechanical verdict. No agent transcribes claims; both sides are
+// machine-written JSONL.
+//
+// Pairing: shadow.tick_seq_before + 1 === decision.tick_seq. The shadow runs
+// first in the tick (before the sandbox dispatcher writes its tick-release
+// line and its decision), so the authoritative decision for the same board
+// state is the first decision line with tick_seq exactly one past the
+// shadow's observed count.
+//
+// Match predicate: the sorted claim triples task_id|workflow|step are
+// identical. The executor tag is excluded by construction (both sides are
+// normalized to the triple before comparing). Reservation outcomes are NOT
+// compared — the shadow skips reservations; a sandbox reservation failure
+// surfaces as a DIVERGE with the differing triples named, which is honest
+// evidence, not a false alarm.
+//
+// Usage: node compare-dispatch-shadow.js --crew-home <path>
+// Prints one of SHADOW_MATCH / SHADOW_DIVERGE / SHADOW_UNPAIRED /
+// SHADOW_NO_EVIDENCE and appends the verdict to
+// $CREW_HOME/.dispatch-shadow-verdicts.jsonl. Exit 0 on a verdict (even a
+// diverge — divergence is evidence, not a failure); exit 2 on usage or IO
+// errors.
+
+import { readFileSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+
+function usage() {
+  console.log("Usage: node compare-dispatch-shadow.js --crew-home <path>");
+  console.log("");
+  console.log("Pairs the latest shadow evidence line with the authoritative");
+  console.log("dispatch decision for the same tick and emits a verdict.");
+  process.exit(0);
+}
+
+const argv = process.argv.slice(2);
+if (argv.includes("--help") || argv.includes("-h")) usage();
+let crewHome = null;
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i] === "--crew-home" && i + 1 < argv.length) crewHome = argv[++i];
+}
+if (!crewHome) {
+  console.error("compare-dispatch-shadow: --crew-home <path> is required");
+  process.exit(2);
+}
+
+function readJsonl(file) {
+  let lines = [];
+  try {
+    lines = readFileSync(file, "utf8").split("\n");
+  } catch (e) {
+    return [];
+  }
+  const out = [];
+  for (const l of lines) {
+    if (l.trim() === "") continue;
+    try { out.push(JSON.parse(l)); } catch (e) { /* skip corrupt lines loudly below */ }
+  }
+  return out;
+}
+
+function normalizeClaims(list) {
+  return (list || [])
+    .map((c) => `${c.task_id}|${c.workflow}|${c.step}`)
+    .sort();
+}
+
+function emit(verdict) {
+  const file = join(crewHome, ".dispatch-shadow-verdicts.jsonl");
+  let seq = 0;
+  try {
+    const lines = readFileSync(file, "utf8").split("\n");
+    for (const l of lines) { if (l.trim() !== "") seq++; }
+  } catch (e) { /* missing file */ }
+  const line = JSON.stringify({ seq: seq + 1, ...verdict });
+  try {
+    appendFileSync(file, line + "\n");
+  } catch (e) {
+    console.error("compare-dispatch-shadow: verdict write failed: " + e.message);
+    process.exit(2);
+  }
+  return { seq: seq + 1, ...verdict };
+}
+
+const shadows = readJsonl(join(crewHome, ".dispatch-shadow.jsonl")).filter((l) => l.mode === "shadow");
+if (shadows.length === 0) {
+  console.log("SHADOW_NO_EVIDENCE no shadow lines yet");
+  process.exit(0);
+}
+const shadow = shadows[shadows.length - 1];
+
+const decisions = readJsonl(join(crewHome, ".dispatch-decisions.jsonl"));
+const verdicts = readJsonl(join(crewHome, ".dispatch-shadow-verdicts.jsonl"));
+const done = new Set(verdicts.map((v) => v.shadow_seq));
+const pending = shadows.filter((s) => !done.has(s.seq));
+
+if (pending.length === 0) {
+  console.log(`SHADOW_CURRENT all ${shadows.length} shadow line(s) already have verdicts`);
+  process.exit(0);
+}
+
+let matched = 0, diverged = 0, unpaired = 0;
+for (const shadow of pending) {
+  const wantTickSeq = (shadow.tick_seq_before || 0) + 1;
+  const decision = decisions.find((d) => d.tick_seq === wantTickSeq);
+
+  if (!decision) {
+    emit({ verdict: "unpaired", shadow_seq: shadow.seq, want_tick_seq: wantTickSeq });
+    console.log(`SHADOW_UNPAIRED shadow_seq=${shadow.seq} want_tick_seq=${wantTickSeq} (authoritative decision not yet written)`);
+    unpaired++;
+    continue;
+  }
+
+  const shadowClaims = normalizeClaims(shadow.claims);
+  const decisionClaims = normalizeClaims(decision.launched);
+  const isMatch =
+    shadowClaims.length === decisionClaims.length &&
+    shadowClaims.every((c, i) => c === decisionClaims[i]);
+
+  const onlyShadow = shadowClaims.filter((c) => !decisionClaims.includes(c));
+  const onlyDecision = decisionClaims.filter((c) => !shadowClaims.includes(c));
+
+  emit({
+    verdict: isMatch ? "match" : "diverge",
+    shadow_seq: shadow.seq,
+    decision_seq: decision.seq,
+    tick_seq: decision.tick_seq,
+    shadow_claims: shadowClaims,
+    decision_claims: decisionClaims,
+    only_shadow: onlyShadow,
+    only_decision: onlyDecision,
+    shadow_partial: !!shadow.partial,
+    decision_partial: !!decision.partial,
+  });
+
+  if (isMatch) {
+    console.log(`SHADOW_MATCH shadow_seq=${shadow.seq} decision_seq=${decision.seq} claims=${shadowClaims.length}`);
+    matched++;
+  } else {
+    console.log(`SHADOW_DIVERGE shadow_seq=${shadow.seq} decision_seq=${decision.seq} only_shadow=[${onlyShadow.join(",")}] only_decision=[${onlyDecision.join(",")}]`);
+    diverged++;
+  }
+}
+console.log(`SHADOW_SUMMARY matched=${matched} diverged=${diverged} unpaired=${unpaired}`);
+process.exit(0);

package/lib/crew-api.js

@@ -1314,6 +1314,37 @@ commands["record-run-end"] = (db, args) => {
   return { ok: true, run_id: args.run_id, status };
 };
 
+// record-worker-run: upsert a worker-layer orchestration run (Piece 1,
+// 2026-09-26). The worker layer's counterpart to record-run-start/end.
+// Args: { id?, phase, task_id?, status, error? }
+// - status "running" without id: INSERTs a row (id assigned by SQLite —
+//   worker JS never mints identity, see G3), returns { ok, id }.
+// - status "completed"|"failed" with id: UPDATEs that row's status,
+//   error, and ended_at (only from 'running'; terminal rows are
+//   immutable, same R-2 rule as record-run-end), returns { ok, id }.
+// - Anything else is a usage error. task_id is optional (the dispatcher
+//   run is not tied to one task).
+commands["record-worker-run"] = (db, args) => {
+  if (!args.phase) throw usageError("phase is required.");
+  const status = args.status || "running";
+  if (!["running", "completed", "failed"].includes(status)) {
+    throw usageError("status must be running, completed, or failed.");
+  }
+  if (status === "running") {
+    if (args.id !== undefined && args.id !== null) throw usageError("id must not be set when starting a run.");
+    const row = db.prepare(
+      `INSERT INTO worker_runs (task_id, phase, status) VALUES (?, ?, 'running') RETURNING id`
+    ).get(args.task_id || null, args.phase);
+    return { ok: true, id: row.id, status: "running" };
+  }
+  if (args.id === undefined || args.id === null) throw usageError("id is required to finish a run.");
+  db.prepare(
+    `UPDATE worker_runs SET status = ?, error = ?, ended_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+     WHERE id = ? AND status = 'running'`
+  ).run(status, args.error || null, args.id);
+  return { ok: true, id: args.id, status };
+};
+
 commands["get-run-timeline"] = (db, args) => {
   if (!args.run_id && !args.task_id) throw usageError("run_id or task_id is required.");
   let runs;