muse-crew 0.14.6 → 0.14.7

package/lib/crew-api.js

@@ -338,6 +338,74 @@ function openDb(crewHome) {
     }
     // Legacy global-provenance backfill (watermarked, runs at most once).
     backfillProjectProvenance(db);
+    // Migration: cascade-park columns on tasks (room #26 blocker 36,
+    // 2026-09-21). A parked dep strands its todo dependents with zero
+    // telemetry; parking a task now cascade-parks them with structured
+    // attribution on the parked state (park_reason='dep_parked' +
+    // park_dep_id). Same idempotent PRAGMA-check pattern; ADD COLUMN
+    // without a default leaves existing rows NULL ("ordinary park", never
+    // fabricated). The pairing invariant lives in crew-api.js — SQLite
+    // forbids cross-column CHECKs on ADD COLUMN (verified live: "error in
+    // table after add column: no such column").
+    const taskCols = db.prepare("PRAGMA table_info(tasks)").all();
+    if (!taskCols.some((c) => c.name === "park_reason")) {
+      try {
+        db.exec("ALTER TABLE tasks ADD COLUMN park_reason TEXT CHECK (park_reason IS NULL OR park_reason = 'dep_parked')");
+      } catch (e) {
+        // Another process may have added it concurrently; ignore duplicate-column errors.
+        if (!/duplicate column name/i.test(e.message)) throw e;
+      }
+    }
+    if (!taskCols.some((c) => c.name === "park_dep_id")) {
+      try {
+        db.exec("ALTER TABLE tasks ADD COLUMN park_dep_id TEXT");
+      } catch (e) {
+        // Another process may have added it concurrently; ignore duplicate-column errors.
+        if (!/duplicate column name/i.test(e.message)) throw e;
+      }
+    }
+    // Migration: structured verdict records (room #26 blocker 33,
+    // 2026-09-21). Review verdict grounds were destroyed by the 2000-char
+    // session-note truncation — a park on a verified-correct implementation
+    // was unauditable. record-phase now optionally carries the full grounds
+    // and writes them here, uncapped, in the same transaction as the session
+    // note. CREATE TABLE IF NOT EXISTS is natively idempotent (no PRAGMA
+    // dance needed, race-safe). One verdict per recording session
+    // (UNIQUE(session_id)): a re-recorded phase for the same session is the
+    // same evidence, so the first write wins and rows are never revised; a
+    // new Review execution claims a new session and gets its own row. New
+    // table: no backfill — pre-migration verdicts are unrecoverable, which
+    // is the point of this fix.
+    db.exec(`CREATE TABLE IF NOT EXISTS verdicts (
+      id         TEXT PRIMARY KEY,
+      task_id    TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+      step       TEXT NOT NULL,
+      attempt    INTEGER NOT NULL CHECK (attempt >= 0),
+      reviewer   TEXT NOT NULL,
+      verdict    TEXT NOT NULL CHECK (verdict IN ('PASS','FAIL','INDETERMINATE')),
+      grounds    TEXT NOT NULL,
+      summary    TEXT NOT NULL,
+      session_id TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      UNIQUE(session_id)
+    )`);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_verdicts_task ON verdicts(task_id)`);
+    // Migration: review_basis on verdicts (room #26 blocker 34 redesign,
+    // 2026-09-21). The workflows were already sending review_basis in the
+    // verdict payload and the tests pinned "verdict row carries
+    // review_basis", but validateVerdictPayload dropped it and the table had
+    // no column — the structured basis never landed. Same idempotent
+    // PRAGMA-check pattern as the cascade-park columns; NULL for legacy
+    // rows (unclassified), never fabricated.
+    const verdictCols = db.prepare("PRAGMA table_info(verdicts)").all();
+    if (!verdictCols.some((c) => c.name === "review_basis")) {
+      try {
+        db.exec("ALTER TABLE verdicts ADD COLUMN review_basis TEXT");
+      } catch (e) {
+        // Another process may have added it concurrently; ignore duplicate-column errors.
+        if (!/duplicate column name/i.test(e.message)) throw e;
+      }
+    }
   }
   return db;
 }
@@ -397,6 +465,9 @@ function mapTask(row, taskStates = new Map()) {
     deps,
     filed_by: row.filed_by,
     retry_reset_at: row.retry_reset_at,
+    // Room #26 blocker 36: cascade-park attribution (NULL = ordinary park).
+    park_reason: row.park_reason ?? null,
+    park_dep_id: row.park_dep_id ?? null,
     blocked: deps.some((id) => taskStates.get(id) !== "done"),
     created_at: row.created_at,
     updated_at: row.updated_at,
@@ -434,6 +505,135 @@ function mapEvent(row) {
   };
 }
 
+// Room #26 blocker 33 (2026-09-21): structured, non-lossy verdict records.
+// The session note is truncated at 2000 chars by workflow design; the
+// verdict row carries the full grounds, uncapped.
+function mapVerdict(row) {
+  if (!row) return null;
+  return {
+    id: row.id,
+    task_id: row.task_id,
+    step: row.step,
+    attempt: row.attempt,
+    reviewer: row.reviewer,
+    verdict: row.verdict,
+    grounds: row.grounds,
+    review_basis: row.review_basis ?? null,
+    summary: row.summary,
+    session_id: row.session_id,
+    created_at: row.created_at,
+  };
+}
+
+// RUN-CLOSEOUT ON PARK (room #26 blocker 37, 2026-09-21). Park never
+// closed workflow_runs rows — every park entry point left the task's open
+// rows at 'running' forever. Every park path closes the task's open rows to
+// the given terminal status in the same transaction as the park.
+function closeWorkflowRuns(db, taskId, terminalStatus) {
+  const r = db.prepare(
+    `UPDATE workflow_runs SET status = ?, completed_at = datetime('now')
+     WHERE task_id = ? AND status = 'running'`
+  ).run(terminalStatus, taskId);
+  return Number(r.changes);
+}
+
+// CASCADE-PARK (room #26 blocker 36, 2026-09-21). Park every todo task that
+// depends on any id in parkedIds, with structured attribution on the
+// existing 'parked' state (park_reason='dep_parked', park_dep_id=<the parked
+// dep>) — never a new state, never silent todo, never auto-waived. Then
+// repeat to a fixpoint: a newly parked dependent strands its own
+// dependents. Only todo tasks cascade — an in_progress task's running
+// workflow owns its verdict, so it stays in flight. Emits one 'blocked'
+// event per cascade-parked task, naming the dependent and the parked dep.
+// Returns the list of {id, dep_id} pairs parked.
+function cascadeDepParks(db, parkedIds, timestamp) {
+  const cascaded = [];
+  const frontier = [...parkedIds];
+  const seen = new Set(parkedIds);
+  const parkStmt = db.prepare(
+    `UPDATE tasks SET state = 'parked', park_reason = 'dep_parked', park_dep_id = ?, updated_at = ?
+     WHERE id = ?`);
+  const settleStmt = db.prepare(
+    `UPDATE agent_sessions SET status = 'failed', ended_at = ?
+     WHERE task_id = ? AND status = 'running'`);
+  const eventStmt = db.prepare(
+    `INSERT INTO events (id, type, task_id, identity, message, timestamp)
+     VALUES (?, 'blocked', ?, NULL, ?, ?)`);
+  while (frontier.length > 0) {
+    const parkedId = frontier.shift();
+    const todoRows = db.prepare("SELECT id, deps FROM tasks WHERE state = 'todo'").all();
+    for (const row of todoRows) {
+      if (seen.has(row.id)) continue;
+      if (!parseDeps(row.deps).includes(parkedId)) continue;
+      parkStmt.run(parkedId, timestamp, row.id);
+      settleStmt.run(timestamp, row.id);
+      // Room #26 blocker 37: a cascade-parked dependent may carry a stale
+      // 'running' workflow_runs row (crashed prior run, requeued to todo) —
+      // close it with the park, in the same transaction. Every park path
+      // reaches its dependents through this function, so this one site
+      // covers park-task, update-task, retry-platform-failure, and the
+      // tick reconciliation sweep.
+      closeWorkflowRuns(db, row.id, "parked");
+      eventStmt.run(uuid(), row.id,
+        `dep-parked: ${row.id} parked — dep ${parkedId} is parked; ` +
+        `re-release ${parkedId} or waive this task via update-task to resume`,
+        timestamp);
+      seen.add(row.id);
+      cascaded.push({ id: row.id, dep_id: parkedId });
+      frontier.push(row.id);
+    }
+  }
+  return cascaded;
+}
+
+// RELEASE (room #26 blocker 36, 2026-09-21). When a task leaves 'parked'
+// for any non-parked state, its cascade-parked dependents' contingency is
+// lifted: re-evaluate each. If another of the dependent's deps is still
+// parked, re-attribute the park to that dep (stays parked — never
+// auto-waived past a parked dep); otherwise return it to todo with the
+// attribution cleared. Then repeat to a fixpoint: a dependent returned to
+// todo lifts the contingency of ITS cascade-parked dependents — the release
+// cascades exactly as far as the park did. Emits one 'blocked' event per
+// touched dependent. Returns the list of {id, action, dep_id} outcomes.
+function releaseDepParks(db, releasedId, timestamp) {
+  const outcomes = [];
+  const frontier = [releasedId];
+  const seen = new Set([releasedId]);
+  const depStmt = db.prepare(
+    `SELECT id, deps FROM tasks
+     WHERE state = 'parked' AND park_reason = 'dep_parked' AND park_dep_id = ?`);
+  const stateOf = db.prepare("SELECT state FROM tasks WHERE id = ?");
+  const eventStmt = db.prepare(
+    `INSERT INTO events (id, type, task_id, identity, message, timestamp)
+     VALUES (?, 'blocked', ?, NULL, ?, ?)`);
+  while (frontier.length > 0) {
+    const relId = frontier.shift();
+    for (const row of depStmt.all(relId)) {
+      if (seen.has(row.id)) continue;
+      seen.add(row.id);
+      const otherParked = parseDeps(row.deps).find(
+        (d) => d !== relId && stateOf.get(d)?.state === "parked");
+      if (otherParked) {
+        db.prepare("UPDATE tasks SET park_dep_id = ?, updated_at = ? WHERE id = ?")
+          .run(otherParked, timestamp, row.id);
+        eventStmt.run(uuid(), row.id,
+          `dep-parked: ${row.id} still parked — attribution moved from ${relId} to ${otherParked} (still parked)`,
+          timestamp);
+        outcomes.push({ id: row.id, action: "reattributed", dep_id: otherParked });
+      } else {
+        db.prepare("UPDATE tasks SET state = 'todo', park_reason = NULL, park_dep_id = NULL, updated_at = ? WHERE id = ?")
+          .run(timestamp, row.id);
+        eventStmt.run(uuid(), row.id,
+          `dep-released: ${row.id} returned to todo — dep ${relId} is no longer parked`,
+          timestamp);
+        outcomes.push({ id: row.id, action: "returned_todo" });
+        frontier.push(row.id);
+      }
+    }
+  }
+  return outcomes;
+}
+
 // Retry counting, ported verbatim from the dashboard's retry.ts.
 function countConsecutiveFailures(sessions, retryResetAt) {
   const latest = sessions[0];
@@ -566,6 +766,23 @@ commands["get-dispatch-state"] = (db) => {
      WHERE status = 'running' AND datetime(COALESCE(last_heartbeat, started_at)) < datetime('now', '-1 hour')`
   ).run();
 
+  // Reconcile stranded dependents (room #26 blocker 36, 2026-09-21): park-time
+  // cascades catch new parks, but a legacy or raced row can still sit todo
+  // with a parked dep — and then it would sit forever with zero telemetry.
+  // Every dispatcher tick parks any todo task whose dep is currently
+  // parked, so no task sits todo with a parked dep for more than one tick.
+  // Idempotent (only todo tasks transition, and they stop being todo),
+  // and event-free for tasks already attributed — cascadeDepParks only
+  // writes for newly parked tasks. Same write-on-read precedent as the
+  // zombie-session sweep above.
+  {
+    const parkedIds = db
+      .prepare("SELECT id FROM tasks WHERE state = 'parked'")
+      .all()
+      .map((r) => r.id);
+    if (parkedIds.length > 0) cascadeDepParks(db, parkedIds, now());
+  }
+
   const taskRows = db.prepare("SELECT * FROM tasks").all();
   const projectRows = db.prepare("SELECT * FROM projects ORDER BY display_name").all();
   const configRows = db.prepare("SELECT key, value FROM config WHERE key <> 'simultaneity'").all();
@@ -770,6 +987,13 @@ commands["update-task"] = (db, args, ctx) => {
   const timestamp = now();
   const patch = {};
   setRetryResetAtForTransition(patch, current.state, args.state, timestamp);
+  // Room #26 blocker 36: leaving 'parked' clears this task's own cascade
+  // attribution — the parked->todo waiver is an explicit operator decision
+  // (the task returns todo with blocked=true until its deps are done).
+  if (current.state === "parked" && args.state !== undefined && args.state !== "parked") {
+    patch.park_reason = null;
+    patch.park_dep_id = null;
+  }
   if (args.title !== undefined) {
     const t = args.title.trim();
     if (t.length < 1 || t.length > 200) throw usageError("title must be 1-200 chars.");
@@ -802,6 +1026,21 @@ commands["update-task"] = (db, args, ctx) => {
         `INSERT INTO events (id, type, task_id, identity, message, timestamp)
          VALUES (?, ?, ?, NULL, ?, ?)`
       ).run(uuid(), type, args.id, `Moved \u201c${patch.title ?? current.title}\u201d to ${args.state.replace("_", " ")}.`, timestamp);
+      // Room #26 blocker 36: the dep is no longer parked, so re-evaluate
+      // cascade-parked dependents — their contingency is lifted.
+      if (current.state === "parked" && args.state !== "parked") {
+        releaseDepParks(db, args.id, timestamp);
+      }
+      // Room #26 blocker 36: an operator parking a dep strands its todo
+      // dependents with zero telemetry — cascade-park them in the same
+      // transaction, under the same attribution contract as park-task.
+      if (args.state === "parked" && current.state !== "parked") {
+        // Blocker 37: an operator parking an in-flight task must close its
+        // open workflow_runs rows in the same transaction — park-task and
+        // retry-platform-failure already do; this path was the gap.
+        closeWorkflowRuns(db, args.id, "parked");
+        cascadeDepParks(db, [args.id], timestamp);
+      }
     }
     db.exec("COMMIT");
   } catch (e) { db.exec("ROLLBACK"); throw e; }
@@ -971,6 +1210,14 @@ commands["list-reservations"] = (db) => {
 commands["record-run-start"] = (db, args) => {
   if (!args.task_id) throw usageError("task_id is required.");
   if (!args.workflow) throw usageError("workflow is required.");
+  // A terminal task (parked, done) can never gain a new run: a stale agent
+  // retrying a start against a task that was parked/done since would
+  // resurrect it in the run timeline (2026-09-21 R-2). todo/in_progress
+  // starts stay allowed — telemetry may record before the self-claim.
+  const taskState = db.prepare("SELECT state FROM tasks WHERE id = ?").get(args.task_id);
+  if (taskState && (taskState.state === "parked" || taskState.state === "done")) {
+    throw usageError("task " + args.task_id + " is " + taskState.state + "; cannot start a workflow run.");
+  }
   // The workflow doesn't know its platform run_id; the telemetry run_id is
   // minted here (SQLite-side) so workflow JS never touches randomness.
   const runId = args.run_id || uuid();
@@ -1021,9 +1268,12 @@ commands["record-run-end"] = (db, args) => {
   if (!["completed", "failed", "parked", "timed_out"].includes(status)) {
     throw usageError("status must be completed, failed, parked, or timed_out.");
   }
+  // Terminal runs are immutable: a late run-end can never rewrite a run
+  // the park/fail paths already closed (2026-09-21 R-2). Only a run still
+  // in 'running' may transition; unknown run_ids match nothing (as before).
   db.prepare(
     `UPDATE workflow_runs SET status = ?, completed_at = datetime('now')
-     WHERE run_id = ?`
+     WHERE run_id = ? AND status = 'running'`
   ).run(status, args.run_id);
   return { ok: true, run_id: args.run_id, status };
 };
@@ -1176,8 +1426,15 @@ commands["retry-platform-failure"] = (db, args) => {
           `INSERT INTO events (id, type, task_id, identity, message, timestamp)
            VALUES (?, 'note', ?, NULL, ?, ?)`
         ).run(uuid(), failure.task_id, "Parked: " + msg, ts);
+        // Room #26 blocker 37: park never closed workflow_runs rows — an open
+        // 'running' row would sit forever. Close them to 'parked' in the
+        // same transaction.
+        const closedRuns = closeWorkflowRuns(db, failure.task_id, "parked");
+        // Room #26 blocker 36: the parked dep's todo dependents strand with
+        // zero telemetry otherwise — cascade-park them in the same transaction.
+        const cascadeParked = cascadeDepParks(db, [failure.task_id], ts);
         db.exec("COMMIT");
-        return { ok: true, action: "parked", reason: "max retries exceeded", retry_count: failure.retry_count, settled_sessions: Number(settled.changes) };
+        return { ok: true, action: "parked", reason: "max retries exceeded", retry_count: failure.retry_count, settled_sessions: Number(settled.changes), closed_workflow_runs: closedRuns, cascade_parked: cascadeParked };
       } catch (e) {
         db.exec("ROLLBACK");
         throw e;
@@ -1275,12 +1532,21 @@ commands["park-task"] = (db, args) => {
            notes = notes || ' Parked: ' || ?
        WHERE task_id = ? AND status = 'running'`
     ).run(timestamp, message.slice(0, 500), task.id);
+    // Room #26 blocker 37: park never closed workflow_runs rows — an open
+    // 'running' row would sit forever. Close them to 'parked' in the same
+    // transaction (park is the designed terminal state for the run too).
+    const closedRuns = closeWorkflowRuns(db, task.id, "parked");
+    // Room #26 blocker 36: cascade-park todo dependents in the same
+    // transaction — a parked dep strands them with zero telemetry otherwise.
+    const cascadeParked = cascadeDepParks(db, [task.id], timestamp);
     db.exec("COMMIT");
     const taskStates = new Map(db.prepare("SELECT id, state FROM tasks").all().map((r) => [r.id, r.state]));
     return {
       ok: true,
       task: mapTask({ ...task, state: "parked", updated_at: timestamp }, taskStates),
       settled_sessions: Number(settled.changes),
+      closed_workflow_runs: closedRuns,
+      cascade_parked: cascadeParked,
     };
   } catch (e) { db.exec("ROLLBACK"); throw e; }
 };
@@ -1324,7 +1590,9 @@ commands["recover-task"] = (db, args, ctx) => {
   const note = (args.updated_description ?? "").trim().slice(0, 5000);
   db.exec("BEGIN");
   try {
-    db.prepare("UPDATE tasks SET next_phase = ?, state = ?, updated_at = ? WHERE id = ?")
+    // Room #26 blocker 36: recovery out of 'parked' clears this task's own
+    // cascade attribution and re-evaluates cascade-parked dependents.
+    db.prepare("UPDATE tasks SET next_phase = ?, state = ?, park_reason = NULL, park_dep_id = NULL, updated_at = ? WHERE id = ?")
       .run(targetPhase, newState, timestamp, task.id);
     db.prepare(
       `INSERT INTO events (id, type, task_id, identity, message, timestamp)
@@ -1334,11 +1602,14 @@ commands["recover-task"] = (db, args, ctx) => {
       (task.state !== newState ? ` (state ${task.state} -> ${newState})` : "") +
       (note ? `. ${note}` : ""),
       timestamp);
+    if (task.state === "parked" && newState !== "parked") {
+      releaseDepParks(db, task.id, timestamp);
+    }
     db.exec("COMMIT");
   } catch (e) { db.exec("ROLLBACK"); throw e; }
   const taskStates = new Map(db.prepare("SELECT id, state FROM tasks").all().map((r) => [r.id, r.state]));
   return {
-    task: mapTask({ ...task, next_phase: targetPhase, state: newState, updated_at: timestamp }, taskStates),
+    task: mapTask({ ...task, next_phase: targetPhase, state: newState, park_reason: null, park_dep_id: null, updated_at: timestamp }, taskStates),
     valid_phases: stepNames,
   };
 };
@@ -1921,12 +2192,36 @@ commands["record-intent-issuance"] = (db, args, ctx) => {
   if (!["accepted", "refused"].includes(editOutcome)) {
     throw usageError(`unknown edit outcome: ${editOutcome}.`);
   }
+  // Reclaimed-claim receipt guard (2026-09-21 R-3): a reclaimed claim
+  // means a previous tick died mid-issuance and may have issued the edit
+  // without recording it. The tick worker MUST run the step-2 receipt
+  // check and report its outcome explicitly: "different" (receipt
+  // readable but differs from this attempt's version), "unreadable"
+  // (receipt missing or unreadable — NOT proof the edit did not land), or
+  // "match" (receipt equals this attempt's version — the edit landed;
+  // acknowledge it via record-version-ack, never re-issue). A missing or
+  // unknown receipt_check on a reclaimed claim is a usage error; "match"
+  // refuses to record (fail closed, no write) so a landed edit is never
+  // re-issued. Non-reclaimed claims take no receipt_check.
+  const reclaimed = args.reclaimed === true || args.reclaimed === "true";
+  const receiptCheck = args.receipt_check;
+  if (reclaimed) {
+    if (!["different", "unreadable", "match"].includes(receiptCheck)) {
+      throw usageError("receipt_check is required for a reclaimed claim (one of: different, unreadable, match).");
+    }
+  } else if (receiptCheck !== undefined && receiptCheck !== null) {
+    throw usageError("receipt_check is only valid for a reclaimed claim.");
+  }
 
   db.exec("BEGIN");
   try {
     const pre = resolveClaimedIntent(db, ctx, taskId, claimExpiry);
     if (!pre.ok) { db.exec("ROLLBACK"); return { recorded: false, reason: pre.reason }; }
     const { slug, ledgerPath, intentEntry, commit } = pre;
+    if (reclaimed && receiptCheck === "match") {
+      db.exec("ROLLBACK");
+      return { recorded: false, reason: "receipt already matches the claimed version — the edit landed; acknowledge via record-version-ack, never re-issue" };
+    }
     const publishAttempt = intentEntry.publish_attempt;
     const version = intentEntry.version;
     if (!Number.isInteger(publishAttempt) || publishAttempt < 1 ||
@@ -1942,19 +2237,22 @@ commands["record-intent-issuance"] = (db, args, ctx) => {
       issuer: "tick-worker",
       diff_sha256: intentEntry.diff_sha256 || null,
       issued_at: editOutcome === "accepted" ? ts : null,
+      receipt_check: reclaimed ? receiptCheck : null,
     };
     let note;
     if (editOutcome === "refused") {
       const refusalText = String(args.refusal_text || "no refusal text recorded").split("\n")[0].slice(0, 500);
       ledgerLine.outcome = "rejected";
-      ledgerLine.detail = `platform refused the directly-issued edit: ${refusalText}`;
+      ledgerLine.detail = `platform refused the directly-issued edit: ${refusalText}` +
+        (reclaimed ? ` (reclaimed claim; step-2 receipt check was '${receiptCheck}')` : "");
       // Terminal: parked for human attention. "publish: publish-refused"
       // is registered in lib/publish-note-vocabulary.js (the closed
       // registry — the writer-side guard pattern from D7).
       note = `publish: publish-refused ${commit} attempt=${publishAttempt} — the platform refused the issued edit (${refusalText}). No re-issue; parked for human attention.`;
     } else {
       ledgerLine.outcome = "submitted";
-      ledgerLine.detail = "edit issued directly by the session-carrying tick worker (one-party publish); the staged diff carried the per-attempt version receipt";
+      ledgerLine.detail = "edit issued directly by the session-carrying tick worker (one-party publish); the staged diff carried the per-attempt version receipt" +
+        (reclaimed ? `; reclaimed claim, step-2 receipt check was '${receiptCheck}' (a differing or unreadable receipt is not proof the prior attempt's edit did not land)` : "");
       note = `publish: edit-issued ${commit} attempt=${publishAttempt} version=${version} — issued directly by the session-carrying tick worker (one-party publish). The acknowledgement scan owns the task from here: exact version string, 30-minute window.`;
     }
     try {
@@ -2446,6 +2744,67 @@ commands["record-publish-note"] = (db, args) => {
   writePublishNote(db, taskId, note);
   return { ok: true, task_id: taskId, verb };
 };
+
+// STRUCTURED VERDICT RECORDS (room #26 blocker 33, 2026-09-21). Review
+// verdict grounds were destroyed by the 2000-char session-note truncation —
+// a park on a verified-correct implementation was unauditable. record-phase
+// optionally carries the full grounds (`args.verdict`); they are validated
+// at the API boundary and written to the verdicts table in the same
+// transaction as the session note + event, so the lossless record can never
+// be missing when the note exists. One verdict per recording session: a
+// re-recorded phase for the same session is the same evidence, so the first
+// write wins (ON CONFLICT DO NOTHING) and rows are never revised. A new
+// Review execution claims a new session, so rework rounds and dispatcher
+// retries each get their own row.
+const VERDICT_RECORD_STEPS = ["Review"];
+const VERDICT_VALUES = ["PASS", "FAIL", "INDETERMINATE"];
+const MAX_VERDICT_GROUNDS = 1000000;
+
+function validateVerdictPayload(taskId, verdict, sessionRow) {
+  if (typeof verdict !== "object" || verdict === null)
+    throw usageError("verdict must be an object.");
+  const { step, attempt, reviewer, verdict: value, grounds, review_basis } = verdict;
+  if (!VERDICT_RECORD_STEPS.includes(step))
+    throw usageError(`verdict step must be one of: ${VERDICT_RECORD_STEPS.join(", ")}.`);
+  if (!Number.isInteger(attempt) || attempt < 0)
+    throw usageError("verdict attempt must be a non-negative integer.");
+  if (typeof reviewer !== "string" || reviewer.trim().length < 1 || reviewer.length > 200)
+    throw usageError("verdict reviewer is required (1-200 chars).");
+  if (!VERDICT_VALUES.includes(value))
+    throw usageError(`verdict must be one of: ${VERDICT_VALUES.join(", ")}.`);
+  if (typeof grounds !== "string" || grounds.length < 1 || grounds.length > MAX_VERDICT_GROUNDS)
+    throw usageError(`verdict grounds are required (1-${MAX_VERDICT_GROUNDS} chars).`);
+  // Room #26 blocker 34 (redesign): the structured review basis — what the
+  // review actually examined. NULL when the review was not branch-classified
+  // (docs.js path). Shape-pinned at the API boundary: a lowercase kind tag,
+  // optionally qualified by a 40-hex merge sha (frozen-merge:<sha>).
+  let reviewBasis = null;
+  if (review_basis !== undefined && review_basis !== null) {
+    // Exact closed set (blocker 34 redesign, 2026-09-21): the workflows emit
+    // only branch-diff, mechanical-fail, runtime-state-none, or
+    // frozen-merge:<40-hex-sha>. A broad regex would accept fabricated kinds.
+    if (typeof review_basis !== "string" ||
+        !/^(branch-diff|mechanical-fail|runtime-state-none|frozen-merge:[0-9a-f]{40})$/.test(review_basis))
+      throw usageError("verdict review_basis must be null or one of 'branch-diff', 'mechanical-fail', 'runtime-state-none', 'frozen-merge:<40-hex-sha>'.");
+    reviewBasis = review_basis;
+  }
+  return {
+    id: uuid(),
+    task_id: taskId,
+    step,
+    attempt,
+    reviewer: reviewer.trim(),
+    verdict: value,
+    grounds,
+    review_basis: reviewBasis,
+    // summary is derived from the session note actually recorded — one
+    // source of truth, never a second caller-supplied truncation.
+    summary: sessionRow.notes,
+    session_id: sessionRow.id,
+    created_at: now(),
+  };
+}
+
 commands["record-phase"] = (db, args) => {
   if (!args.task_id) throw usageError("task_id is required.");
   requireTask(db, args.task_id);
@@ -2481,6 +2840,13 @@ commands["record-phase"] = (db, args) => {
     id: uuid(), type: event.type, task_id: args.task_id,
     identity: event.identity ?? sessionRow.identity, message, timestamp,
   };
+  // Blocker 33: validate the optional structured verdict BEFORE the
+  // transaction — a malformed payload fails the whole phase record (fail
+  // closed), never a silently dropped verdict.
+  const verdictRow = args.verdict == null
+    ? null
+    : validateVerdictPayload(args.task_id, args.verdict, sessionRow);
+  let recordedVerdict = null;
   db.exec("BEGIN");
   try {
     db.prepare(
@@ -2497,9 +2863,39 @@ commands["record-phase"] = (db, args) => {
     db.prepare(
       `INSERT INTO events (id, type, task_id, identity, message, timestamp)
        VALUES (@id, @type, @task_id, @identity, @message, @timestamp)`).run(eventRow);
+    // Blocker 33: the verdict lands in the same transaction as the session
+    // note + event — the lossless record can never be missing when the note
+    // exists. Idempotency is session-keyed: a re-recorded phase for the
+    // same session is the same evidence (first write wins, never revised);
+    // a new Review execution claims a new session and gets its own row.
+    if (verdictRow) {
+      const verdictInsert = db.prepare(
+        `INSERT INTO verdicts (id, task_id, step, attempt, reviewer, verdict,
+          grounds, review_basis, summary, session_id, created_at)
+         VALUES (@id, @task_id, @step, @attempt, @reviewer, @verdict,
+          @grounds, @review_basis, @summary, @session_id, @created_at)
+         ON CONFLICT(session_id) DO NOTHING`).run(verdictRow);
+      recordedVerdict = verdictInsert.changes === 1
+        ? verdictRow
+        : db.prepare(
+            `SELECT * FROM verdicts WHERE session_id = ?`).get(verdictRow.session_id);
+    }
     db.exec("COMMIT");
   } catch (e) { db.exec("ROLLBACK"); throw e; }
-  return { session: mapSession(sessionRow), event: mapEvent(eventRow) };
+  return { session: mapSession(sessionRow), event: mapEvent(eventRow),
+    verdict: mapVerdict(recordedVerdict) };
+};
+
+// Blocker 33 read surface: all structured verdict records for a task,
+// ordered by recording time (rework rounds and retries accumulate as
+// separate rows, never overwrite).
+commands["get-verdicts"] = (db, args) => {
+  if (!args.task_id) throw usageError("task_id is required.");
+  requireTask(db, args.task_id);
+  const rows = db.prepare(
+    `SELECT * FROM verdicts WHERE task_id = ? ORDER BY created_at ASC`
+  ).all(args.task_id);
+  return { verdicts: rows.map(mapVerdict) };
 };
 
 // Initial provenance stamp (2026-09-16, clean-room task ada95b71): the first