muse-crew 0.7.10 → 0.7.12

package/lib/crew-api.js

@@ -12,17 +12,18 @@
 //
 // Commands (kebab-case) map to API.md actions:
 //   get-dispatch-state, get-state, create-task, update-task, claim-task,
-//   park-task, recover-task, upsert-session, log-event, get-events,
+//   park-task, recover-task, consume-next-phase, upsert-session, log-event, get-events,
 //   create-project, update-project, delete-project, list-projects,
 //   get-project, kill-switch, get-config, update-config,
 //   set-provenance, get-provenance, acknowledge-poll,
+//   scan-verification-pending, resolve-publish-unknown,
 //   record-phase (composite), migrate (one-time import)
 //
 // Output is JSON on stdout. Errors are JSON on stderr.
 // Exit codes: 0 ok · 2 usage/validation · 3 not found · 4 conflict/guard.
 
-import { readFileSync, existsSync, statSync } from "node:fs";
-import { join, resolve, sep } from "node:path";
+import { readFileSync, existsSync, statSync, readlinkSync, readdirSync, appendFileSync } from "node:fs";
+import { join, resolve, sep, basename } from "node:path";
 import { randomUUID } from "node:crypto";
 import { DatabaseSync } from "node:sqlite";
 import { homedir } from "node:os";
@@ -259,6 +260,53 @@ function workflowExists(crewHome, slug) {
   );
 }
 
+// Workflow step names for a slug, from the release registry when present,
+// falling back to the workflow file's own `export const meta` block (the
+// single source of truth the registry is built from). Returns null when the
+// workflow file cannot be found or parsed. Used by recover-task to validate
+// target_phase, and by the dispatcher-side contract tests.
+function workflowStepNames(crewHome, slug) {
+  if (!slug) return null;
+  const candidates = [
+    join(crewHome, "current", "workflows", "registry.json"),
+    join(crewHome, "workflows", "registry.json"),
+  ];
+  for (const regPath of candidates) {
+    try {
+      const reg = JSON.parse(readFileSync(regPath, "utf8"));
+      const entry = reg && reg[slug];
+      if (entry && Array.isArray(entry.steps)) {
+        const names = entry.steps.map((s) => s && s.name).filter((n) => typeof n === "string");
+        if (names.length > 0) return names;
+      }
+    } catch (e) { /* fall through to the meta-block parse */ }
+  }
+  const wfCandidates = [
+    join(crewHome, "current", "workflows", `${slug}.js`),
+    join(crewHome, "workflows", `${slug}.js`),
+  ];
+  for (const wfPath of wfCandidates) {
+    let source;
+    try { source = readFileSync(wfPath, "utf8"); } catch (e) { continue; }
+    const marker = "export const meta = ";
+    const start = source.indexOf(marker);
+    if (start < 0) continue;
+    const bodyStart = start + marker.length;
+    const end = source.indexOf("\n};", bodyStart);
+    if (end < 0) continue;
+    try {
+      // The meta block is a static literal (no function calls); evaluating
+      // the object literal in isolation is safe.
+      const meta = new Function("return (" + source.slice(bodyStart, end + 2) + ");")();
+      if (meta && Array.isArray(meta.steps)) {
+        const names = meta.steps.map((s) => s && s.name).filter((n) => typeof n === "string");
+        if (names.length > 0) return names;
+      }
+    } catch (e) { /* try the next candidate */ }
+  }
+  return null;
+}
+
 // Minimal git-repo validation (ported from the dashboard's validateRepoPath):
 // accepts a repo root (.git dir) or a linked worktree (.git file).
 function isGitRepoPath(p) {
@@ -535,6 +583,17 @@ commands["claim-task"] = (db, args) => {
   if (!args.task_id) throw usageError("task_id is required.");
   const identity = (args.identity ?? "").trim();
   if (identity.length < 1 || identity.length > 80) throw usageError("identity is required (1-80 chars).");
+  // ATOMIC NEXT_PHASE CONSUMPTION (2026-09-15): expected_next_phase is the
+  // routing the dispatcher launched this run for. When the claim wins, the
+  // matching next_phase is cleared in the SAME transaction as the winning
+  // session insert — there is no claim→consume window for a platform death
+  // to replay the routing through. The separate consume-next-phase command
+  // is retained only as an idempotent public helper (out-of-band recovery);
+  // workflows no longer call it.
+  const rawExpected = args.expected_next_phase;
+  const expectedNextPhase = (rawExpected === undefined || rawExpected === null) ? null : String(rawExpected).trim();
+  if (expectedNextPhase !== null && (expectedNextPhase.length < 1 || expectedNextPhase.length > 120))
+    throw usageError("expected_next_phase must be 1-120 chars when provided.");
   const task = requireTask(db, args.task_id);
   const project = requireProject(db, task.project);
   if (project.quiesced) throw conflict("This project is paused. Resume it before claiming tasks.");
@@ -552,23 +611,41 @@ commands["claim-task"] = (db, args) => {
     notes: (args.notes ?? "").trim().slice(0, 3000), caveats: "[]",
     last_heartbeat: now(),
   };
-  // Atomic: the partial unique index on (task_id) WHERE status='running'
-  // turns a duplicate claim into a no-op insert.
-  const info = db.prepare(
-    `INSERT INTO agent_sessions (id, task_id, identity, step, status, started_at,
-      ended_at, notes, caveats, last_heartbeat)
-     VALUES (@id, @task_id, @identity, @step, @status, @started_at,
-      @ended_at, @notes, @caveats, @last_heartbeat)
-     ON CONFLICT DO NOTHING`).run(row);
-  if (info.changes > 0) {
-    return { ok: true, claimed: true, session_id: row.id, session: mapSession({ ...row, failure_reason: null }) };
-  }
-  const existing = db.prepare(
-    `SELECT id FROM agent_sessions
-     WHERE task_id = ? AND status = 'running'
-     ORDER BY started_at DESC LIMIT 1`).get(args.task_id);
-  if (!existing) throw new CrewError("claim_unresolved", "Task claim could not be resolved. Please retry.", 4);
-  return { ok: true, claimed: false, reason: "already_claimed", existing_session_id: existing.id };
+  const timestamp = now();
+  db.exec("BEGIN");
+  try {
+    // Atomic: the partial unique index on (task_id) WHERE status='running'
+    // turns a duplicate claim into a no-op insert.
+    const info = db.prepare(
+      `INSERT INTO agent_sessions (id, task_id, identity, step, status, started_at,
+        ended_at, notes, caveats, last_heartbeat)
+       VALUES (@id, @task_id, @identity, @step, @status, @started_at,
+        @ended_at, @notes, @caveats, @last_heartbeat)
+       ON CONFLICT DO NOTHING`).run(row);
+    // Same transaction: only the claim winner consumes, and only when the
+    // stored routing still matches what the dispatcher launched on — a newer
+    // recover-task written in the race window survives untouched.
+    let nextPhaseConsumed = false;
+    if (info.changes > 0 && expectedNextPhase) {
+      const cleared = db.prepare(
+        "UPDATE tasks SET next_phase = NULL, updated_at = ? WHERE id = ? AND next_phase = ?"
+      ).run(timestamp, args.task_id, expectedNextPhase);
+      nextPhaseConsumed = cleared.changes > 0;
+    }
+    db.exec("COMMIT");
+    if (info.changes > 0) {
+      return { ok: true, claimed: true, session_id: row.id, session: mapSession({ ...row, failure_reason: null }),
+        next_phase_consumed: expectedNextPhase ? nextPhaseConsumed : undefined };
+    }
+    const existing = db.prepare(
+      `SELECT id FROM agent_sessions
+       WHERE task_id = ? AND status = 'running'
+       ORDER BY started_at DESC LIMIT 1`).get(args.task_id);
+    if (!existing) throw new CrewError("claim_unresolved", "Task claim could not be resolved. Please retry.", 4);
+    // Lost claim: the winner (or an earlier winner) owns next_phase
+    // consumption — a loser must never clear it.
+    return { ok: true, claimed: false, reason: "already_claimed", existing_session_id: existing.id };
+  } catch (e) { db.exec("ROLLBACK"); throw e; }
 };
 
 // Dispatch reservations: the cron worker creates one after launching a
@@ -844,6 +921,9 @@ commands["retry-platform-failure"] = (db, args) => {
   if (failure.retry_count >= maxRetries) {
     // Park the task — transient failures are not resolving.
     const task = db.prepare("SELECT * FROM tasks WHERE id = ?").get(failure.task_id);
+    if (task && task.state === "done") {
+      return { ok: true, action: "skipped", reason: "task already done — a platform retry never parks a done task", retry_count: failure.retry_count };
+    }
     if (task && task.state !== "parked") {
       const msg = "Platform workflow failed " + (failure.retry_count + 1) + "x: " +
         failure.error_message.substring(0, 200);
@@ -874,19 +954,47 @@ commands["retry-platform-failure"] = (db, args) => {
     }
     return { ok: true, action: "parked", reason: "max retries exceeded", retry_count: failure.retry_count, settled_sessions: 0 };
   }
-  // Clear reservation and re-queue for retry.
+  // Clear the reservation and re-queue for retry — preserving the task's
+  // phase. Canary 2026-09-15 (task 1d692d91): the old code forced
+  // state='todo', so a platform failure during QA restarted the entire
+  // workflow at Triage; Build reimplemented an already-merged and
+  // already-verified task and produced an unrequested variant. The
+  // dispatcher already resumes a failed/timed_out/stalled session at that
+  // session's own step — so the fix is to leave the task's state alone and
+  // settle the ghost session as 'stalled', letting the dispatcher resume at
+  // the failed phase instead of restarting at Triage. 'done' is never
+  // resurrected and 'parked' is never unparked: parked is the designed
+  // human decision point.
+  const retryTask = db.prepare("SELECT id, state FROM tasks WHERE id = ?").get(failure.task_id);
+  if (!retryTask) {
+    return { ok: true, action: "skipped", reason: "task not found" };
+  }
+  if (retryTask.state === "done") {
+    return { ok: true, action: "skipped", reason: "task already done — never resurrected by a platform retry" };
+  }
+  if (retryTask.state === "parked") {
+    return { ok: true, action: "skipped", reason: "task parked — the human decision point, never unparked by a platform retry" };
+  }
+  // The failed phase is the ghost session's step: the dispatcher resumes
+  // failed/timed_out/stalled sessions at that step. Capture it before
+  // settling so the requeue reports where the run will resume.
+  const ghost = db.prepare(
+    `SELECT step FROM agent_sessions WHERE task_id = ? AND status = 'running'
+     ORDER BY started_at DESC LIMIT 1`
+  ).get(failure.task_id);
   db.exec("BEGIN");
   try {
     db.prepare("DELETE FROM dispatch_reservations WHERE task_id = ?").run(failure.task_id);
     db.prepare(
-      "UPDATE tasks SET state = 'todo', updated_at = datetime('now') WHERE id = ? AND state != 'done'"
+      "UPDATE tasks SET updated_at = datetime('now') WHERE id = ?"
     ).run(failure.task_id);
     // Settle the ghost session atomically with the requeue: the platform
     // workflow is dead, but its agent_sessions row still says 'running' —
     // and the dispatcher skips any task whose latest session is running
     // (crew-dispatch.js "work in flight"). Without this, the requeued task
     // would sit until the 1-hour zombie-session sweep. 'stalled' is what
-    // the dispatcher already treats as a retry candidate.
+    // the dispatcher already treats as a retry candidate, resuming at the
+    // session's own step.
     const ts = new Date().toISOString();
     const settled = db.prepare(
       `UPDATE agent_sessions
@@ -904,6 +1012,8 @@ commands["retry-platform-failure"] = (db, args) => {
       ok: true,
       action: "requeued",
       task_id: failure.task_id,
+      state: retryTask.state,
+      resume_step: ghost ? ghost.step : null,
       retry_count: failure.retry_count + 1,
       settled_sessions: Number(settled.changes),
     };
@@ -950,41 +1060,77 @@ commands["recover-task"] = (db, args, ctx) => {
   const targetPhase = (args.target_phase ?? "").trim();
   if (targetPhase.length < 1 || targetPhase.length > 120) throw usageError("target_phase is required (1-120 chars).");
   const task = requireTask(db, args.task_id);
+  if (!task.workflow) throw conflict("This task does not have a workflow with selectable phases.");
+  if (!workflowExists(ctx.crewHome, task.workflow)) throw notFound("Workflow not found.");
+  // Validate the target against the workflow's own phase registry — an
+  // unknown phase fails closed here, never as a dispatcher skip or a
+  // workflow launched at the wrong step.
+  const stepNames = workflowStepNames(ctx.crewHome, task.workflow);
+  if (!stepNames) throw conflict(`Could not read the phase registry for workflow "${task.workflow}".`);
+  if (!stepNames.includes(targetPhase)) {
+    throw conflict(`Unknown phase "${targetPhase}" for workflow "${task.workflow}". Valid phases: ${stepNames.join(", ")}.`);
+  }
+  // Recovery intent, not a verdict: the latest session may be failed,
+  // timed_out, stalled — or absent entirely (the platform died before the
+  // first claim). A running session means work is in flight; completed,
+  // rejected, passed, and superseded sessions have their own normal paths
+  // (next step, rework) and are not recovery targets.
   const latest = db.prepare(
     `SELECT * FROM agent_sessions WHERE task_id = ? ORDER BY started_at DESC LIMIT 1`
   ).get(args.task_id);
-  if (!latest || !["failed", "timed_out"].includes(latest.status)) {
-    throw conflict("The latest session is not failed or timed out.");
+  if (latest && !["failed", "timed_out", "stalled"].includes(latest.status)) {
+    throw conflict(`The latest session is ${latest.status}; recover-task accepts only failed, timed_out, stalled, or no session.`);
   }
-  if (!task.workflow) throw conflict("This task does not have a workflow with selectable phases.");
-  if (!workflowExists(ctx.crewHome, task.workflow)) throw notFound("Workflow not found.");
+  if (["done", "cancelled"].includes(task.state)) {
+    throw conflict(`Task is ${task.state}; recovery applies to todo, in_progress, or parked tasks.`);
+  }
+  // No synthetic session: recovery intent must not consume retry budget.
+  // The dispatcher routes on tasks.next_phase directly (one-shot, consumed
+  // by the claiming workflow), so no failed-session marker is needed to
+  // make the task eligible.
   const timestamp = now();
-  const queued = {
-    id: uuid(), task_id: task.id,
-    identity: latest.identity, step: targetPhase, status: "failed",
-    started_at: timestamp, ended_at: timestamp,
-    notes: (args.updated_description ?? "").trim().slice(0, 5000),
-    caveats: "[]", failure_reason: null, last_heartbeat: timestamp,
-  };
+  const newState = (task.state === "parked" || task.state === "todo") ? "in_progress" : task.state;
+  const note = (args.updated_description ?? "").trim().slice(0, 5000);
   db.exec("BEGIN");
   try {
-    db.prepare("UPDATE tasks SET next_phase = ?, updated_at = ? WHERE id = ?")
-      .run(targetPhase, timestamp, task.id);
-    db.prepare("UPDATE agent_sessions SET ended_at = ? WHERE id = ?").run(timestamp, latest.id);
+    db.prepare("UPDATE tasks SET next_phase = ?, state = ?, updated_at = ? WHERE id = ?")
+      .run(targetPhase, newState, timestamp, task.id);
     db.prepare(
-      `INSERT INTO agent_sessions (id, task_id, identity, step, status, started_at,
-        ended_at, notes, caveats, failure_reason, last_heartbeat)
-       VALUES (@id, @task_id, @identity, @step, @status, @started_at,
-        @ended_at, @notes, @caveats, @failure_reason, @last_heartbeat)`).run(queued);
+      `INSERT INTO events (id, type, task_id, identity, message, timestamp)
+       VALUES (?, 'note', ?, 'recover-task', ?, ?)`
+    ).run(uuid(), task.id,
+      `Recovery: next phase set to ${targetPhase}` +
+      (task.state !== newState ? ` (state ${task.state} -> ${newState})` : "") +
+      (note ? `. ${note}` : ""),
+      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, updated_at: timestamp }, taskStates),
-    session: mapSession(queued),
+    task: mapTask({ ...task, next_phase: targetPhase, state: newState, updated_at: timestamp }, taskStates),
+    valid_phases: stepNames,
   };
 };
 
+// Retained as an idempotent public helper for out-of-band recovery tooling.
+// Workflows no longer call this: claim-task with expected_next_phase clears
+// the routed next_phase in the same transaction as the winning session
+// insert, so the old claim→consume death window is closed. The conditional
+// UPDATE keeps this exactly-once for any other caller: only the claim winner
+// clears, and only when the value still matches what the dispatcher routed
+// on — a newer recover-task written in the race window survives untouched.
+commands["consume-next-phase"] = (db, args) => {
+  if (!args.task_id) throw usageError("task_id is required.");
+  const expected = (args.expected ?? "").trim();
+  if (expected.length < 1 || expected.length > 120) throw usageError("expected is required (1-120 chars).");
+  requireTask(db, args.task_id);
+  const timestamp = now();
+  const info = db.prepare(
+    "UPDATE tasks SET next_phase = NULL, updated_at = ? WHERE id = ? AND next_phase = ?"
+  ).run(timestamp, args.task_id, expected);
+  return { consumed: info.changes > 0, task_id: args.task_id };
+};
+
 commands["upsert-session"] = (db, args) => {
   if (!args.task_id) throw usageError("task_id is required.");
   requireTask(db, args.task_id);
@@ -1063,6 +1209,284 @@ commands["get-events"] = (db, args) => {
   return { events: rows.map(mapEvent) };
 };
 
+// Parent publish verification: scan + atomic claim + reconcile.
+//
+// Finds parked tasks whose latest parent publish note is
+// "publish: verification-requested" (the publisher parks instead of
+// stamping, per docs/publish-verification.md) with no terminal parent
+// verdict and no unexpired verification claim. Each returned task is
+// ATOMICALLY claimed by logging a "publish: verification-claimed"
+// note-event with a lease expiry, so two concurrent scanners (or a
+// retrying tick) cannot start a second verification for the same task.
+// The claim is a note, not a state change: the task stays parked, so the
+// dispatcher never dispatches QA mid-verification.
+//
+// Also reconciles the verified-but-still-parked gap: a parked task whose
+// latest parent verdict is "publish: verified" is re-queued to in_progress
+// (the verdict was recorded but the re-queue was lost to a crash).
+// Failure verdicts are left parked for human attention (fail-closed).
+//
+// Returns { to_verify: [...], reconciled: [...] }.
+// Each to_verify entry: { task_id, commit, build_agent_id, project_id,
+// repo_path, deploy_slug, crew_release, claim_expires_at }.
+//
+// crew_release is resolved through the crew home's `current` symlink (the
+// immutable active release the release manager maintains) and cross-checked
+// against this code's own realpath (the release it is actually running
+// from). Unresolvable or disputed => throw fail-closed BEFORE the claim
+// transaction: provenance is never stamped with an unknown release.
+function resolveActiveRelease(crewHome) {
+  let linkTarget;
+  try {
+    linkTarget = readlinkSync(join(crewHome, "current"));
+  } catch (e) {
+    throw usageError(
+      `scan-verification-pending: cannot resolve the active release: ${join(crewHome, "current")} is not a readable symlink (${e.message}). Refusing to verify.`
+    );
+  }
+  const activeRelease = basename(resolve(crewHome, linkTarget));
+  const selfPath = new URL(import.meta.url).pathname;
+  const selfMatch = selfPath.match(/releases\/([^/]+)\/lib\/crew-api\.js$/);
+  if (!selfMatch) {
+    throw usageError(
+      `scan-verification-pending: running code is not inside a releases/<name>/lib path (${selfPath}). Refusing to verify.`
+    );
+  }
+  if (selfMatch[1] !== activeRelease) {
+    throw usageError(
+      `scan-verification-pending: running release ${selfMatch[1]} != active release ${activeRelease} (stale cron body or mid-deploy). Refusing to verify.`
+    );
+  }
+  return activeRelease;
+}
+commands["scan-verification-pending"] = (db, args, ctx) => {
+  const CLAIM_LEASE_MS = 60 * 60 * 1000; // 1 hour
+  const nowMs = Date.now();
+  const claimExpiry = new Date(nowMs + CLAIM_LEASE_MS).toISOString();
+  const releaseName = resolveActiveRelease(ctx.crewHome);
+
+  const parked = db.prepare(
+    `SELECT t.id AS task_id, t.project AS project_id,
+            p.repo_path AS repo_path, p.deploy_slug AS deploy_slug
+     FROM tasks t LEFT JOIN projects p ON p.id = t.project
+     WHERE t.state = 'parked'`
+  ).all();
+
+  const toVerify = [];
+  const reconciled = [];
+
+  db.exec("BEGIN");
+  try {
+    for (const row of parked) {
+      const notes = db.prepare(
+        `SELECT message, timestamp FROM events
+         WHERE task_id = ? AND type = 'note' AND message LIKE '%publish:%'
+         ORDER BY timestamp DESC LIMIT 20`
+      ).all(row.task_id);
+      if (notes.length === 0) continue;
+      const latest = notes[0].message;
+
+      // Reconcile first: verdict recorded but the re-queue was lost to a
+      // crash (verified-but-still-parked). Failure verdicts stay parked.
+      // Contained-string matching: the workflow's parkTask prepends
+      // "Parked: " to the reason, so a verification request is stored as
+      // "Parked: publish: verification-requested ..." (observed 2026-09-14).
+      // Prefix anchors would never match; see tests/verify-publish.test.js.
+      if (latest.includes("publish: verified")) {
+        db.prepare("UPDATE tasks SET state = 'in_progress', updated_at = ? WHERE id = ?")
+          .run(now(), row.task_id);
+        db.prepare(
+          `INSERT INTO events (id, type, task_id, identity, message, timestamp)
+           VALUES (?, 'note', ?, NULL, ?, ?)`
+        ).run(uuid(), row.task_id,
+          "publish: reconciled verified-but-parked -> in_progress (re-queue lost to a crash)",
+          now());
+        reconciled.push({ task_id: row.task_id });
+        continue;
+      }
+
+      // Terminal parent verdicts (anything the parent decided, except a
+      // fresh request, a procedural error, or an active claim) — never re-verify.
+      const isRequest = latest.includes("publish: verification-requested");
+      const isClaim = latest.includes("publish: verification-claimed");
+      // Procedural errors (worker botched the procedure, not a content
+      // failure) are retryable — treat like a fresh request. Content
+      // failures (verification-failed) stay terminal.
+      const isProceduralError = latest.includes("publish: verification-procedural-error");
+      if (!isRequest && !isClaim && !isProceduralError) continue; // failed / blocked / mismatch: terminal, fail-closed
+
+      if (isClaim) {
+        // Unexpired claim -> another verifier owns it. Expired -> re-claim below.
+        const m = latest.match(/publish: verification-claimed (\S+)/);
+        if (m && Date.parse(m[1]) > nowMs) continue;
+      }
+
+      // Candidate: find the original verification-requested note to extract
+      // the commit and build agent id (the latest note may be an expired claim
+      // or a procedural error).
+      const req = notes.find((n) => n.message.includes("publish: verification-requested"));
+      if (!req) continue;
+      const commitMatch = req.message.match(/verification-requested ([0-9a-f]{40})/);
+      // Fallback: procedural error note carries the commit too.
+      const procMatch = !commitMatch ? latest.match(/verification-procedural-error ([0-9a-f]{40})/) : null;
+      const commit = commitMatch ? commitMatch[1] : (procMatch ? procMatch[1] : null);
+      const buildMatch = req.message.match(/\(build ([0-9a-f-]{36})\)/);
+      if (!commit) continue; // malformed request: cannot verify mechanically, leave parked
+      db.prepare(
+        `INSERT INTO events (id, type, task_id, identity, message, timestamp)
+         VALUES (?, 'note', ?, NULL, ?, ?)`
+      ).run(uuid(), row.task_id, `publish: verification-claimed ${claimExpiry}`, now());
+      toVerify.push({
+        task_id: row.task_id,
+        commit: commit,
+        build_agent_id: buildMatch ? buildMatch[1] : null,
+        project_id: row.project_id,
+        repo_path: row.repo_path,
+        deploy_slug: row.deploy_slug,
+        crew_release: releaseName,
+        claim_expires_at: claimExpiry,
+      });
+    }
+    db.exec("COMMIT");
+  } catch (e) { db.exec("ROLLBACK"); throw e; }
+  return { to_verify: toVerify, reconciled };
+};
+
+// Recovery contract for publish attempts parked with an UNKNOWN outcome
+// (2026-09-14). The structured-output fallback parked the task because no
+// build could be observed — but the edit may still have gone through (the
+// in-flight-only fallback could not see a completed build; fixed
+// in-workflow the same day with the durable audit-dir check). When durable
+// evidence later shows the build DID complete — a platform audit directory
+// created inside the publish window (between Integrate completion and the
+// park event) — this action routes the task to the parent's independent
+// content verification WITHOUT re-issuing the edit and WITHOUT stamping
+// provenance. The original unknown ledger entry and park event are
+// preserved; the resolution is appended to the ledger and the event log.
+// The parent's read-back (docs/publish-verification.md) remains the real
+// verification and can still fail terminally. Never: blind retry, manual
+// stamp, silent state change.
+commands["resolve-publish-unknown"] = (db, args, ctx) => {
+  const taskId = args.task_id;
+  if (!taskId) throw usageError("task_id is required.");
+  requireTask(db, taskId);
+  const task = db.prepare("SELECT id, state, project FROM tasks WHERE id = ?").get(taskId);
+  if (task.state !== "parked") {
+    return { resolved: false, reason: `task is not parked (state=${task.state})` };
+  }
+  const project = db.prepare("SELECT deploy_slug FROM projects WHERE id = ?").get(task.project);
+  const slug = project && project.deploy_slug;
+  if (!slug) return { resolved: false, reason: "project has no deploy_slug" };
+
+  // The latest publish ledger entry for this task must be outcome "unknown".
+  const ledgerPath = join(ctx.crewHome, ".publish-ledger", slug + ".jsonl");
+  let entries = [];
+  try {
+    entries = readFileSync(ledgerPath, "utf8").split("\n")
+      .filter((l) => l.trim().length > 0)
+      .map((l) => JSON.parse(l))
+      .filter((e) => e.task_id === taskId);
+  } catch (e) {
+    return { resolved: false, reason: `cannot read publish ledger: ${e.message}` };
+  }
+  if (entries.length === 0) return { resolved: false, reason: "no publish ledger entries for this task" };
+  const latest = entries[entries.length - 1];
+  if (latest.outcome === "unknown-resolved") {
+    return { resolved: false, reason: "already resolved (unknown-resolved ledger entry present)" };
+  }
+  if (latest.outcome !== "unknown") {
+    return { resolved: false, reason: `latest ledger outcome is '${latest.outcome}', not unknown` };
+  }
+  if (!latest.commit || !/^[0-9a-f]{40}$/.test(latest.commit)) {
+    return { resolved: false, reason: "unknown ledger entry carries no usable commit hash" };
+  }
+
+  // The publish window: Integrate completion -> the unknown-outcome park.
+  // Nothing else touches the artifact during Publish, so an audit dir
+  // created inside this window belongs to this publish attempt.
+  const events = db.prepare(
+    "SELECT type, message, timestamp FROM events WHERE task_id = ? ORDER BY timestamp ASC"
+  ).all(taskId);
+  const integrateDone = [...events].reverse().find((e) =>
+    e.type === "completed" && /integrate completed/i.test(e.message || ""));
+  const parkEvent = [...events].reverse().find((e) =>
+    e.type === "note" && (e.message || "").includes("Publish outcome unknown"));
+  if (!integrateDone || !parkEvent) {
+    return { resolved: false, reason: "cannot determine publish window (missing integrate-completion or unknown-outcome park event)" };
+  }
+  const winStart = Date.parse(integrateDone.timestamp);
+  const winEnd = Date.parse(parkEvent.timestamp);
+  if (!(winStart < winEnd)) {
+    return { resolved: false, reason: "publish window is empty or inverted" };
+  }
+
+  // Audit dirs are named <UTC-timestamp>-<id>; the timestamp is the build's.
+  const auditsDir = join(homedir(), "workspace", "ts-spaces", slug, "audits");
+  let evidenceDirs = [];
+  try {
+    evidenceDirs = readdirSync(auditsDir).filter((name) => {
+      const m = /^(\d{4})-(\d{2})-(\d{2})T(\d{2})-(\d{2})-(\d{2})Z-/.exec(name);
+      if (!m) return false;
+      const t = Date.parse(`${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:${m[6]}Z`);
+      return t > winStart && t <= winEnd;
+    }).sort();
+  } catch (e) {
+    return { resolved: false, reason: `cannot list audit dirs: ${e.message}` };
+  }
+  if (evidenceDirs.length === 0) {
+    return { resolved: false, reason: "no audit build completed inside the publish window — still unknown" };
+  }
+  const evidenceDir = evidenceDirs[0];
+
+  // Corroboration, observation only: the audit harness's own verdict.
+  let auditOk = null;
+  try {
+    auditOk = JSON.parse(readFileSync(join(auditsDir, evidenceDir, "report.json"), "utf8")).ok === true;
+  } catch (e) { auditOk = null; }
+
+  const ts = now();
+  // The verification-requested note must sort strictly after the
+  // unknown-resolved note: scan-verification-pending reads the LATEST
+  // publish: note, and equal timestamps would leave the order undefined.
+  const tsLater = new Date(Date.parse(ts) + 1000).toISOString();
+  db.exec("BEGIN");
+  try {
+    db.prepare(
+      "INSERT INTO events (id, type, task_id, identity, message, timestamp) VALUES (?, 'note', ?, NULL, ?, ?)"
+    ).run(uuid(), taskId,
+      `publish: unknown-resolved ${latest.commit} (audit ${evidenceDir}, report ok=${auditOk}) — durable build evidence inside the publish window; routing to parent content verification. No re-trigger issued, no provenance stamped, original unknown outcome preserved.`,
+      ts);
+    // Mirror the workflow's verification-requested park note so
+    // scan-verification-pending claims it on the next tick.
+    db.prepare(
+      "INSERT INTO events (id, type, task_id, identity, message, timestamp) VALUES (?, 'note', ?, NULL, ?, ?)"
+    ).run(uuid(), taskId,
+      `Parked: publish: verification-requested ${latest.commit} (build agent_id unobserved) — recovered from publish-unknown via resolve-publish-unknown; durable evidence ${evidenceDir}. Parent: run docs/publish-verification.md.`,
+      tsLater);
+    db.prepare("UPDATE tasks SET state = 'parked', updated_at = ? WHERE id = ?").run(tsLater, taskId);
+    db.exec("COMMIT");
+  } catch (e) { db.exec("ROLLBACK"); throw e; }
+
+  // Append-only audit trail: the resolution lands in the ledger next to the
+  // original unknown entry (which is never rewritten).
+  try {
+    appendFileSync(ledgerPath, JSON.stringify({
+      ts: new Date(ts).toISOString(),
+      task_id: taskId,
+      workflow: latest.workflow || "unknown",
+      slug,
+      commit: latest.commit,
+      attempt: latest.attempt,
+      agent_id: null,
+      applied_report: null,
+      outcome: "unknown-resolved",
+      detail: `durable build evidence ${evidenceDir} (audit report ok=${auditOk}) inside publish window; routed to parent verification without re-trigger`,
+    }) + "\n");
+  } catch (e) { /* best-effort observability */ }
+
+  return { resolved: true, task_id: taskId, commit: latest.commit, evidence_dir: evidenceDir, audit_report_ok: auditOk };
+};
+
 // Composite: record a phase's session verdict AND its event in one
 // transaction. This is the operation that used to crash the workflow when the
 // two writes went to different contracts: the session stored, the event