muse-crew 0.13.3 → 0.14.1

package/lib/crew-api.js

@@ -17,6 +17,7 @@
 //   get-project, kill-switch, get-config, update-config,
 //   set-provenance, get-provenance, acknowledge-poll,
 //   scan-verification-pending, resolve-publish-unknown,
+//   scan-publish-unknown, record-unknown-classification, record-retry-recheck,
 //   record-phase (composite), migrate (one-time import)
 //
 // Output is JSON on stdout. Errors are JSON on stderr.
@@ -1513,6 +1514,7 @@ commands["scan-verification-pending"] = (db, args, ctx) => {
 
   const toVerify = [];
   const reconciled = [];
+  const deferred = []; // not-before in the future (unknown-recovery retry) — claimed by a later tick
 
   db.exec("BEGIN");
   try {
@@ -1570,7 +1572,23 @@ commands["scan-verification-pending"] = (db, args, ctx) => {
       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})\)/);
+      // Attempt binding (2026-09-18, blocker 4): the verifier must select the
+      // submitted ledger entry for the exact (task_id, commit, attempt) —
+      // not just (task_id, commit) — or a retry's trigger is indistinguishable
+      // from the original's.
+      const attemptMatch = req.message.match(/attempt=([^\s]+)/);
+      const attempt = attemptMatch ? attemptMatch[1] : null;
       if (!commit) continue; // malformed request: cannot verify mechanically, leave parked
+      // not-before (2026-09-18, blocker 15): the unknown-recovery retry
+      // protocol mirrors verification-requested with a not-before so the
+      // re-triggered build gets 20 minutes to land before the verification
+      // scan may claim it. Absent = verify immediately (backward compatible).
+      const nbMatch = req.message.match(/not-before=([0-9T:.\-Z+]+)/);
+      const notBeforeMs = nbMatch ? Date.parse(nbMatch[1]) : NaN;
+      if (notBeforeMs > nowMs) {
+        deferred.push({ task_id: row.task_id, commit, not_before: nbMatch[1] });
+        continue;
+      }
       db.prepare(
         `INSERT INTO events (id, type, task_id, identity, message, timestamp)
          VALUES (?, 'note', ?, NULL, ?, ?)`
@@ -1578,6 +1596,7 @@ commands["scan-verification-pending"] = (db, args, ctx) => {
       toVerify.push({
         task_id: row.task_id,
         commit: commit,
+        attempt: attempt,
         build_agent_id: buildMatch ? buildMatch[1] : null,
         project_id: row.project_id,
         repo_path: row.repo_path,
@@ -1588,7 +1607,7 @@ commands["scan-verification-pending"] = (db, args, ctx) => {
     }
     db.exec("COMMIT");
   } catch (e) { db.exec("ROLLBACK"); throw e; }
-  return { to_verify: toVerify, reconciled };
+  return { to_verify: toVerify, reconciled, deferred };
 };
 
 // Recovery contract for publish attempts parked with an UNKNOWN outcome
@@ -1605,20 +1624,31 @@ commands["scan-verification-pending"] = (db, args, ctx) => {
 // 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);
+// ---------------------------------------------------------------------------
+// Shared publish-unknown attempt derivation (2026-09-18, blocker 15).
+//
+// The publish-unknown recovery state machine (scan-publish-unknown, the
+// manual resolve-publish-unknown, record-unknown-classification) all start
+// from the same durable anchors: the parked task, its project's deploy_slug,
+// and the latest publish ledger entry for the task, which must be outcome
+// "unknown" with a usable commit hash. This helper reads those anchors once
+// so the three commands cannot drift apart.
+//
+// Returns { ok: true, task, slug, repoPath, projectId, commit, attempt,
+//            unknownEntry, unknownTs, ledgerPath, entries }
+// or { ok: false, reason } — the reason strings are the manual command's
+// exact messages (pinned by tests/resolve-publish-unknown.test.js).
+// ---------------------------------------------------------------------------
+function derivePublishUnknownAttempt(db, crewHome, taskId, requireLatest = false) {
   const task = db.prepare("SELECT id, state, project FROM tasks WHERE id = ?").get(taskId);
+  if (!task) return { ok: false, reason: "unknown task" };
   if (task.state !== "parked") {
-    return { resolved: false, reason: `task is not parked (state=${task.state})` };
+    return { ok: false, reason: `task is not parked (state=${task.state})` };
   }
-  const project = db.prepare("SELECT deploy_slug FROM projects WHERE id = ?").get(task.project);
+  const project = db.prepare("SELECT id, deploy_slug, repo_path 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");
+  if (!slug) return { ok: false, reason: "project has no deploy_slug" };
+  const ledgerPath = join(crewHome, ".publish-ledger", slug + ".jsonl");
   let entries = [];
   try {
     entries = readFileSync(ledgerPath, "utf8").split("\n")
@@ -1626,19 +1656,119 @@ commands["resolve-publish-unknown"] = (db, args, ctx) => {
       .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)" };
+    return { ok: false, reason: `cannot read publish ledger: ${e.message}` };
+  }
+  if (entries.length === 0) return { ok: false, reason: "no publish ledger entries for this task" };
+  // 2026-09-18, should-fix 6: for crash recovery (requireLatest=false),
+  // derive by the most recent unknown attempt, not the ledger tail. Retry
+  // or observability entries appended after the unknown must not break
+  // recovery. For manual resolve (requireLatest=true), the unknown must be
+  // the latest entry.
+  let unknownEntry = null;
+  if (requireLatest) {
+    // Strict mode: latest entry must be unknown.
+    const latest = entries[entries.length - 1];
+    if (latest.outcome === "unknown-resolved") {
+      return { ok: false, reason: "already resolved (unknown-resolved ledger entry present)" };
+    }
+    if (latest.outcome !== "unknown") {
+      return { ok: false, reason: `latest ledger outcome is '${latest.outcome}', not unknown` };
+    }
+    unknownEntry = latest;
+  } else {
+    // Lenient mode: find the most recent unknown, skipping later non-unknown
+    // entries (retry, observability). If an unknown-resolved follows the
+    // unknown, the attempt is resolved.
+    for (let i = entries.length - 1; i >= 0; i--) {
+      const e = entries[i];
+      if (e.outcome === "unknown-resolved") {
+        return { ok: false, reason: "already resolved (unknown-resolved ledger entry present)" };
+      }
+      if (e.outcome === "unknown") {
+        unknownEntry = e;
+        break;
+      }
+    }
+    if (!unknownEntry) {
+      return { ok: false, reason: "no unresolved unknown ledger entry for this task" };
+    }
   }
-  if (latest.outcome !== "unknown") {
-    return { resolved: false, reason: `latest ledger outcome is '${latest.outcome}', not unknown` };
+  if (!unknownEntry.commit || !/^[0-9a-f]{40}$/.test(unknownEntry.commit)) {
+    return { ok: false, reason: "unknown ledger entry carries no usable commit hash" };
   }
-  if (!latest.commit || !/^[0-9a-f]{40}$/.test(latest.commit)) {
-    return { resolved: false, reason: "unknown ledger entry carries no usable commit hash" };
+  return {
+    ok: true, task, slug, repoPath: (project && project.repo_path) || null, projectId: project.id,
+    commit: unknownEntry.commit, attempt: unknownEntry.attempt || null,
+    unknownEntry, unknownTs: unknownEntry.ts || null, ledgerPath, entries,
+  };
+}
+
+// The unknown-recovery state machine reads two note shapes: the machine's
+// own "publish: <transition>" notes, and the workflow's initial
+// "Publish outcome unknown …" park note — which carries no "publish:"
+// marker (composeUnattributedParkReason), so the prefilter must match it
+// explicitly. LIKE is ASCII case-insensitive in SQLite.
+const PUBLISH_NOTE_PREFILTER =
+  `(message LIKE '%publish:%' OR message LIKE '%publish outcome unknown%')`;
+
+// Latest publish: note for a task (the unknown-recovery state machine's
+// state), or null when the task has no publish notes yet.
+function latestPublishNote(db, taskId) {
+  return db.prepare(
+    `SELECT message, timestamp FROM events
+     WHERE task_id = ? AND type = 'note' AND ${PUBLISH_NOTE_PREFILTER}
+     ORDER BY timestamp DESC LIMIT 1`
+  ).get(taskId) || null;
+}
+
+// The trigger anchor for an unknown attempt: the "submitted" ledger entry
+// for the same attempt, recorded when the trigger went out. Returns the
+// entry or null. A null means the trigger instant is unknowable (or the
+// trigger was never issued) — classification cannot run; the task stays
+// parked for human attention. Fail closed, never guess the anchor.
+function findTriggerEntry(entries, commit, attempt) {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const e = entries[i];
+    if (e.outcome === "submitted" && e.commit === commit &&
+        (e.attempt || null) === (attempt || null)) {
+      return e;
+    }
   }
+  return null;
+}
+
+// The unknown ledger entry's detail says whether the trigger went out.
+// Unknown parks from preflight/toolcheck inconclusives never issued the
+// trigger ("the trigger was NOT issued") — there is no dropped edit to
+// recover, so the unknown-recovery machine must not classify or retry them.
+function triggerWasIssued(unknownEntry) {
+  const detail = String((unknownEntry && unknownEntry.detail) || "");
+  return !/trigger was NOT issued|no trigger issued/i.test(detail);
+}
+
+function writePublishNote(db, taskId, message, ts) {
+  db.prepare(
+    `INSERT INTO events (id, type, task_id, identity, message, timestamp)
+     VALUES (?, 'note', ?, 'crew', ?, ?)`
+  ).run(uuid(), taskId, message, ts || now());
+}
+
+commands["resolve-publish-unknown"] = (db, args, ctx) => {
+  const taskId = args.task_id;
+  if (!taskId) throw usageError("task_id is required.");
+  requireTask(db, taskId);
+  // Shared attempt anchors (2026-09-18, blocker 15): the task must be
+  // parked, the project must carry a deploy_slug, and the latest publish
+  // ledger entry for the task must be outcome "unknown" with a usable
+  // commit. derivePublishUnknownAttempt keeps the exact reason strings the
+  // recovery contract pins (tests/resolve-publish-unknown.test.js).
+  // requireLatest=true: resolve is a manual action on the current state —
+  // a later non-unknown entry means the state has moved on.
+  const derived = derivePublishUnknownAttempt(db, ctx.crewHome, taskId, true);
+  if (!derived.ok) return { resolved: false, reason: derived.reason };
+  const slug = derived.slug;
+  const ledgerPath = derived.ledgerPath;
+  const latest = derived.unknownEntry;
 
   // The publish window: Integrate completion -> the unknown-outcome park.
   // Nothing else touches the artifact during Publish, so an audit dir
@@ -1733,6 +1863,431 @@ commands["resolve-publish-unknown"] = (db, args, ctx) => {
   return { resolved: true, task_id: taskId, commit: latest.commit, evidence_dir: evidenceDir, audit_report_ok: auditOk };
 };
 
+// Cron unknown-recovery scan (2026-09-18, blocker 15). Runs in cron Step 4.5
+// BEFORE scan-verification-pending, so a task the classifier verifies (or
+// the retry protocol re-triggers) is claimed by the verification scan on
+// the same tick.
+//
+// The note is the state machine; this command is the only writer of its
+// transitions. The tick ferries classifier decisions and retry steps — code
+// decides every state change. One atomic transaction per scan: claims,
+// mirrors, and terminal notes all land together or not at all.
+//
+//   latest publish: note                      this scan
+//   "Publish outcome unknown…"                now < park+30m → waiting (no claim, log only)
+//                                             else → atomic 1h claim → due, with classifier inputs
+//   "publish: unknown-recovery-claimed …"     unexpired → skip (a tick owns it)
+//                                             expired → re-claim → due (the tick died mid-classification)
+//   "publish: dropped …"                      budget spent (retry-issued in history) → terminal
+//                                               publish: ambiguous … retry-budget-exhausted
+//                                             else → retry_due (the tick runs the retry protocol)
+//   "publish: retry-intended …" w/o            → mirror publish: verification-requested
+//     "publish: retry-issued"                   (not-before = intended+20m); NEVER re-trigger here
+//   "publish: retry-issued" w/o mirrored      → mirror the missing publish: verification-requested
+//     verification-requested
+//   "publish: ambiguous …" / "publish:        → terminal; ignored
+//     retry-superseded" / "publish:
+//     retry-refused" / "publish: verified" /
+//     "publish: superseded"
+//   "publish: verification-requested"         → already routed; ignored (the verification scan owns it)
+//
+// Unknown parks whose trigger was never issued (preflight/toolcheck
+// inconclusives) or whose submitted ledger entry is missing have no
+// knowable trigger anchor: the scan leaves them parked for human attention.
+// Fail closed, never guess.
+commands["scan-publish-unknown"] = (db, args, ctx) => {
+  const crewHome = ctx.crewHome;
+  const nowMs = Date.now();
+  const quiesceMs = 30 * 60 * 1000;    // design §1.4e: never trust a read before the park is 30m old
+  const claimLeaseMs = 60 * 60 * 1000;  // one hour — survives a dead tick, does not block the next one
+  const retrySettleMs = 20 * 60 * 1000; // a re-triggered build gets 20m before verification may claim it
+  const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+
+  const waiting = [];
+  const due = [];
+  const retryDue = [];
+  const mirrored = [];
+  const skipped = [];
+
+  const skip = (taskId, state, reason) => skipped.push({ task_id: taskId, state, ...(reason ? { reason } : {}) });
+
+  // Shared tail of the unknown branches: derive anchors, check the trigger
+  // went out, find the trigger anchor, write the atomic claim, emit the
+  // classifier inputs. parkNote is the /publish outcome unknown/i note.
+  const claimForClassification = (taskId, notes, parkNote) => {
+    const derived = derivePublishUnknownAttempt(db, crewHome, taskId);
+    if (!derived.ok) { skip(taskId, "derive-failed", derived.reason); return; }
+    if (!triggerWasIssued(derived.unknownEntry)) {
+      skip(taskId, "trigger-never-issued",
+        "the unknown ledger entry records that the trigger was never issued — no dropped edit to recover; stays parked for human attention");
+      return;
+    }
+    const trigger = findTriggerEntry(derived.entries, derived.commit, derived.attempt);
+    if (!trigger || !trigger.ts) {
+      skip(taskId, "no-trigger-anchor",
+        "no submitted ledger entry for this attempt — the trigger instant is unknowable; stays parked for human attention");
+      return;
+    }
+    // Atomic claim: the note IS the claim, written inside this transaction
+    // only while the latest publish: note is still the expected one (the
+    // caller re-checks freshness before invoking this).
+    const expiry = new Date(nowMs + claimLeaseMs).toISOString();
+    writePublishNote(db, taskId,
+      `publish: unknown-recovery-claimed ${expiry} — ${taskId} parked unknown at ${parkNote.timestamp}; claimed for classification (1-hour lease).`,
+      new Date(nowMs).toISOString());
+    // Classifier base: the last verified publish, or the empty tree when
+    // nothing is stamped yet (a first publish) — same convention as the
+    // Step 4.5 read-back sensor.
+    // 2026-09-18, should-fix 4: provenance query failures fail CLOSED —
+    // the empty tree is valid only when there is truly no provenance value.
+    // A query error (locked DB, I/O failure) is not "no provenance"; skip
+    // the task so the next scan retries.
+    let base;
+    try {
+      const prov = db.prepare("SELECT provenance_source_commit FROM projects WHERE id = ?").get(derived.projectId);
+      if (prov && /^[0-9a-f]{40}$/.test(prov.provenance_source_commit)) {
+        base = prov.provenance_source_commit;
+      } else {
+        base = EMPTY_TREE; // truly no provenance value: first publish
+      }
+    } catch (e) {
+      skip(taskId, "provenance-query-failed",
+        `provenance lookup failed (${e.message.slice(0, 200)}); failing closed — the next scan retries`);
+      return;
+    }
+    due.push({
+      task_id: taskId, commit: derived.commit, base,
+      trigger_ts: trigger.ts, park_ts: parkNote.timestamp,
+      slug: derived.slug, repo_path: derived.repoPath,
+      project_id: derived.projectId, claim_expiry: expiry,
+      ledger_path: derived.ledgerPath,
+      // Pre-trigger manifest baseline (design §1.9): the workflow snapshots
+      // the manifest before the trigger into the submitted ledger entry; the
+      // classifier's verified path compares the current manifest against it.
+      // Null when the workflow predates the capture (fail closed downstream).
+      manifest_before: (trigger.manifest_before && typeof trigger.manifest_before === "object")
+        ? trigger.manifest_before : null,
+    });
+  };
+
+  const parked = db.prepare(`SELECT id AS task_id FROM tasks WHERE state = 'parked'`).all();
+
+  db.exec("BEGIN");
+  try {
+    for (const row of parked) {
+      const taskId = row.task_id;
+      const notes = db.prepare(
+        `SELECT message, timestamp FROM events
+         WHERE task_id = ? AND type = 'note' AND ${PUBLISH_NOTE_PREFILTER}
+         ORDER BY timestamp DESC LIMIT 40`
+      ).all(taskId);
+      if (notes.length === 0) continue;
+      const latest = notes[0];
+      const msg = latest.message;
+      const has = (s) => msg.includes(s);
+      const historyHas = (s) => notes.some((n) => n.message.includes(s));
+
+      // Terminal states — the machine never revisits these.
+      if (has("publish: ambiguous") || has("publish: retry-superseded") ||
+          has("publish: retry-refused") || has("publish: verified") ||
+          has("publish: superseded")) {
+        skip(taskId, "terminal");
+        continue;
+      }
+      // Already routed into the verification pipeline — the verification
+      // scan owns it from here.
+      if (has("publish: verification-requested")) {
+        skip(taskId, "routed-to-verification");
+        continue;
+      }
+      // A retry went out but the mirrored verification request is missing
+      // (the tick died between the two writes). Mirror it now — the retry is
+      // at least one tick old, so no not-before is needed.
+      if (has("publish: retry-issued")) {
+        if (historyHas("publish: verification-requested")) { skip(taskId, "raced"); continue; }
+        const derived = derivePublishUnknownAttempt(db, crewHome, taskId);
+        if (!derived.ok) { skip(taskId, "derive-failed", derived.reason); continue; }
+        writePublishNote(db, taskId,
+          `publish: verification-requested ${derived.commit} attempt=${derived.attempt} — mirrored by scan-publish-unknown: the retry was issued without a mirrored request (the tick died between the writes). Waiting on the manual read-back in docs/publish-verification.md.`);
+        mirrored.push({ task_id: taskId, commit: derived.commit, attempt: derived.attempt, not_before: null, reason: "retry-issued-without-mirror" });
+        continue;
+      }
+      // A retry-intended note with no retry-issued: the tick died mid-retry
+      // and the trigger may or may not have gone out. NEVER re-trigger here —
+      // route to the verification pipeline and let content verification be
+      // the arbiter (design §1.5 R3).
+      if (has("publish: retry-intended")) {
+        if (historyHas("publish: verification-requested")) { skip(taskId, "raced"); continue; }
+        const derived = derivePublishUnknownAttempt(db, crewHome, taskId);
+        if (!derived.ok) { skip(taskId, "derive-failed", derived.reason); continue; }
+        const m = msg.match(/publish: retry-intended\s+[0-9a-f]{40}\s+(\S+)/);
+        const intendedMs = m ? Date.parse(m[1]) : NaN;
+        const notBefore = new Date(Math.max(nowMs, (intendedMs > 0 ? intendedMs : nowMs) + retrySettleMs)).toISOString();
+        writePublishNote(db, taskId,
+          `publish: verification-requested ${derived.commit} attempt=${derived.attempt} not-before=${notBefore} — mirrored by scan-publish-unknown: a retry-intended note exists without retry-issued (the tick died mid-retry), so the trigger may or may not have gone out; never re-triggering here, content verification is the arbiter. Waiting on the manual read-back in docs/publish-verification.md.`);
+        mirrored.push({ task_id: taskId, commit: derived.commit, attempt: derived.attempt, not_before: notBefore, reason: "retry-intended-without-retry-issued" });
+        continue;
+      }
+      // Classified as dropped and awaiting the retry protocol. Exactly one
+      // retry, enforced from note events (design §1.5): a retry-issued
+      // anywhere in this task's history spends the budget — including a
+      // retry for an earlier unknown attempt on a reworked task. When the
+      // budget is spent the drop is terminal: ambiguous, human attention.
+      if (has("publish: dropped")) {
+        const derived = derivePublishUnknownAttempt(db, crewHome, taskId);
+        if (!derived.ok) { skip(taskId, "derive-failed", derived.reason); continue; }
+        if (historyHas("publish: retry-issued")) {
+          writePublishNote(db, taskId,
+            `publish: ambiguous ${derived.commit} — retry budget exhausted: a publish retry was already issued for this task in an earlier attempt; not retrying blind. Parked for human attention.`);
+          try {
+            appendFileSync(derived.ledgerPath, JSON.stringify({
+              ts: now(), task_id: taskId, workflow: "unknown-recovery", slug: derived.slug,
+              commit: derived.commit, attempt: derived.attempt, agent_id: null,
+              applied_report: null, outcome: "unknown-classified",
+              detail: "retry budget exhausted — ambiguous, terminal",
+            }) + "\n");
+          } catch (e) { /* best-effort observability */ }
+          continue;
+        }
+        // Retry budget free: queue the retry protocol. The tick needs the
+        // classifier base to regenerate the publish diff byte-identically
+        // (compute-publish-diff.js --base), so ferry it from provenance.
+        // The in-lock re-check also needs the trigger anchor and the
+        // pre-trigger manifest baseline (design §1.9).
+        const retryProv = db.prepare(
+          `SELECT provenance_source_commit FROM projects WHERE id = ?`
+        ).get(derived.projectId);
+        const retryBase = (retryProv && retryProv.provenance_source_commit) || EMPTY_TREE;
+        const retryTrigger = findTriggerEntry(derived.entries, derived.commit, derived.attempt);
+        retryDue.push({
+          task_id: taskId, commit: derived.commit, attempt: derived.attempt,
+          slug: derived.slug, repo_path: derived.repoPath, project_id: derived.projectId,
+          ledger_path: derived.ledgerPath, base: retryBase,
+          trigger_ts: (retryTrigger && retryTrigger.ts) || null,
+          manifest_before: (retryTrigger && retryTrigger.manifest_before &&
+            typeof retryTrigger.manifest_before === "object") ? retryTrigger.manifest_before : null,
+        });
+        continue;
+      }
+      // A previous tick claimed this task for classification.
+      // A previous tick claimed this task for classification.
+      if (has("publish: unknown-recovery-claimed")) {
+        const m = msg.match(/publish: unknown-recovery-claimed\s+(\S+)/);
+        const expiryMs = m ? Date.parse(m[1]) : NaN;
+        if (expiryMs > 0 && nowMs <= expiryMs) { skip(taskId, "claimed"); continue; }
+        // Expired claim: the tick died mid-classification. Re-derive from
+        // the original unknown note and re-claim.
+        const parkNote = notes.find((n) => /publish outcome unknown/i.test(n.message));
+        if (!parkNote) { skip(taskId, "no-unknown-note", "expired claim with no unknown park note in history"); continue; }
+        const fresh = latestPublishNote(db, taskId);
+        if (!fresh || fresh.message !== msg) { skip(taskId, "raced"); continue; }
+        claimForClassification(taskId, notes, parkNote);
+        continue;
+      }
+      // The initial unknown park note. Quiescence first: the classifier must
+      // never read a manifest younger than 30 minutes past the park.
+      if (/publish outcome unknown/i.test(msg)) {
+        const parkMs = Date.parse(latest.timestamp);
+        if (!(parkMs > 0) || nowMs < parkMs + quiesceMs) {
+          waiting.push({ task_id: taskId, parked_at: latest.timestamp });
+          continue;
+        }
+        // Re-check freshness inside the transaction: the latest publish:
+        // note must still be this unknown note.
+        const fresh = latestPublishNote(db, taskId);
+        if (!fresh || fresh.message !== msg) { skip(taskId, "raced"); continue; }
+        claimForClassification(taskId, notes, latest);
+        continue;
+      }
+      skip(taskId, "unrecognized-publish-note");
+    }
+    db.exec("COMMIT");
+  } catch (e) { db.exec("ROLLBACK"); throw e; }
+
+  return { waiting, due, retry_due: retryDue, mirrored, skipped };
+};
+
+// Record the unknown-recovery classifier's decision (2026-09-18, blocker
+// 15). The tick ferries: it runs lib/classify-publish-absence.js for each
+// scan-publish-unknown "due" entry and passes the classifier's JSON here.
+// Code decides: every note the decision implies is written here, atomically,
+// never free-formed by the tick.
+//
+// Args: { task_id, claim_expiry, decision } where decision is the
+// classifier's { ok, decision, reasons, details } JSON.
+//
+// The claim_expiry is a compare-and-swap: the record lands only while the
+// latest publish: note is still this tick's claim. A stale tick (its claim
+// expired and a newer tick re-claimed) gets { recorded: false } and writes
+// nothing.
+//
+// Routing (design §1.4/§1.5):
+//   verified          → publish: verification-requested (no not-before: the
+//                       content is already the new state) + unknown-resolved
+//                       ledger entry; the verification scan claims it.
+//   provably-dropped  → publish: dropped (the next scan queues the retry
+//                       protocol). No ledger resolution — the attempt is
+//                       still logically unknown.
+//   applied-not-built / ambiguous
+//                     → publish: ambiguous (terminal) + unknown-classified
+//                       ledger entry. Parked for human attention.
+//   deferred          → no note: the claim expires and the next scan
+//                       re-claims. A deferred classification is not a verdict.
+//   superseded        → publish: superseded (terminal) + unknown-classified
+//                       ledger entry. HEAD moved; recovery aborted.
+commands["record-unknown-classification"] = (db, args, ctx) => {
+  const taskId = args.task_id;
+  const claimExpiry = args.claim_expiry;
+  const decision = args.decision;
+  if (!taskId) throw usageError("task_id is required.");
+  if (!claimExpiry) throw usageError("claim_expiry is required.");
+  if (!decision || typeof decision !== "object") throw usageError("decision is required (the classifier's JSON).");
+  const verdict = decision.decision;
+  const valid = ["verified", "provably-dropped", "applied-not-built", "ambiguous", "deferred", "superseded"];
+  if (!valid.includes(verdict)) throw usageError(`unknown classifier decision: ${verdict}.`);
+
+  db.exec("BEGIN");
+  try {
+    // CAS: the latest publish: note must still be this tick's claim.
+    const latest = latestPublishNote(db, taskId);
+    if (!latest || !latest.message.includes("publish: unknown-recovery-claimed") ||
+        !latest.message.includes(claimExpiry)) {
+      db.exec("ROLLBACK");
+      return { recorded: false, reason: "claim no longer current — another tick owns this task" };
+    }
+    const derived = derivePublishUnknownAttempt(db, ctx.crewHome, taskId);
+    if (!derived.ok) {
+      db.exec("ROLLBACK");
+      return { recorded: false, reason: derived.reason };
+    }
+    const reasons = Array.isArray(decision.reasons) ? decision.reasons.join("; ") : "";
+    const ts = now();
+
+    const appendLedger = (outcome, detail) => {
+      try {
+        appendFileSync(derived.ledgerPath, JSON.stringify({
+          ts, task_id: taskId, workflow: "unknown-recovery", slug: derived.slug,
+          commit: derived.commit, attempt: derived.attempt, agent_id: null,
+          applied_report: null, outcome, detail,
+        }) + "\n");
+      } catch (e) { /* best-effort observability */ }
+    };
+
+    if (verdict === "deferred") {
+      // No note: the claim expires, the next scan re-claims and retries the
+      // classification. A deferred classification is explicitly not a verdict.
+      db.exec("COMMIT");
+      return { recorded: true, decision: verdict, task_id: taskId, note: "deferred — claim left to expire" };
+    }
+
+    let note;
+    if (verdict === "verified") {
+      note = `publish: verification-requested ${derived.commit} attempt=${derived.attempt} — unknown-recovery classifier verified the content already shows the new state (${reasons}); routed without re-trigger. Waiting on the manual read-back in docs/publish-verification.md.`;
+      writePublishNote(db, taskId, note, ts);
+      appendLedger("unknown-resolved",
+        `classifier verified: content shows the new state; routed to parent verification without re-trigger (${reasons})`);
+    } else if (verdict === "provably-dropped") {
+      note = `publish: dropped ${derived.commit} — unknown-recovery classifier: the trigger went out and the platform provably dropped the edit (${reasons}); queued for the retry protocol.`;
+      writePublishNote(db, taskId, note, ts);
+      // No ledger resolution: the attempt is still logically unknown until
+      // the retry protocol journals its outcome.
+    } else if (verdict === "superseded") {
+      note = `publish: superseded ${derived.commit} — unknown-recovery classifier: HEAD moved past the attempt commit (${reasons}); recovery aborted. Parked for human attention.`;
+      writePublishNote(db, taskId, note, ts);
+      appendLedger("unknown-classified", `classifier superseded — terminal (${reasons})`);
+    } else {
+      // applied-not-built, ambiguous: the classifier could not prove the
+      // drop. Terminal — parked for human attention, never retried blind.
+      note = `publish: ambiguous ${derived.commit} — unknown-recovery classifier could not prove the edit was dropped (${verdict}: ${reasons}); not retrying blind. Parked for human attention.`;
+      writePublishNote(db, taskId, note, ts);
+      appendLedger("unknown-classified", `classifier ${verdict} — terminal, no retry (${reasons})`);
+    }
+    db.exec("COMMIT");
+    return { recorded: true, decision: verdict, task_id: taskId, note };
+  } catch (e) { db.exec("ROLLBACK"); throw e; }
+};
+
+// Retry-protocol re-check routing (2026-09-18, blocker 15). The tick runs
+// the retry protocol from inside the merge lock; its pre-trigger content
+// re-read (lib/classify-publish-absence.js) can come back something other
+// than provably-dropped. This command routes that decision — code-owned, so
+// the tick never free-forms the state machine.
+//
+// Args: { task_id, decision } where decision is the classifier's JSON
+//   ({ ok:true, decision, reasons, details }).
+// CAS: the latest publish: note must still be "publish: dropped" — the merge
+// lock is the mutual exclusion; the CAS is the backstop against a tick that
+// died after another writer moved the state.
+//
+//   verified            → publish: verification-requested (content is
+//                         present now; no not-before) + unknown-resolved
+//                         ledger entry.
+//   provably-dropped    → no-op: the tick proceeds with the retry.
+//   applied-not-built / ambiguous → publish: ambiguous (terminal).
+//   superseded          → publish: superseded (terminal).
+//   deferred            → no-op: the drop note stays latest; the next scan
+//                         re-queues the protocol and re-reads.
+commands["record-retry-recheck"] = (db, args, ctx) => {
+  const crewHome = ctx?.crewHome;
+  if (!crewHome) throw usageError("crewHome is required (internal context).");
+  const taskId = String(args?.task_id ?? "").trim();
+  if (!taskId) throw usageError("task_id is required.");
+  const decision = args?.decision;
+  if (!decision || typeof decision !== "object" || decision.ok !== true) {
+    throw usageError("decision is required — pass the classifier's JSON (ok:true).");
+  }
+  const valid = ["verified", "provably-dropped", "applied-not-built", "ambiguous", "deferred", "superseded"];
+  if (!valid.includes(decision.decision)) {
+    throw usageError(`unknown classifier decision: ${decision.decision}.`);
+  }
+  requireTask(db, taskId);
+  const derived = derivePublishUnknownAttempt(db, crewHome, taskId);
+  if (!derived.ok) throw usageError(`cannot derive the unknown attempt: ${derived.reason}.`);
+  const latest = latestPublishNote(db, taskId);
+  if (!latest || !latest.message.includes("publish: dropped")) {
+    return {
+      recorded: false,
+      reason: "latest publish: note is no longer publish: dropped — another writer moved the state; recorded nothing.",
+    };
+  }
+  const d = decision.decision;
+  const reasons = Array.isArray(decision.reasons) ? decision.reasons.join("; ") : "";
+  const commit = derived.commit;
+  if (d === "provably-dropped" || d === "deferred") {
+    // No state change: the tick proceeds (dropped) or the next scan
+    // re-queues the protocol (deferred).
+    return { recorded: false, reason: `re-check decision ${d}: no state change; the drop note stands.` };
+  }
+  if (d === "verified") {
+    writePublishNote(db, taskId,
+      `publish: verification-requested ${commit} attempt=${derived.attempt} — unknown-recovery retry re-check: the content is present now, so no retry was needed. Waiting on the manual read-back in docs/publish-verification.md.`);
+    try {
+      appendFileSync(derived.ledgerPath, JSON.stringify({
+        ts: now(), task_id: taskId, workflow: "unknown-recovery", slug: derived.slug,
+        commit, attempt: derived.attempt, agent_id: null, applied_report: null,
+        outcome: "unknown-resolved",
+        detail: `retry re-check verified (was: ${reasons})`,
+      }) + "\n");
+    } catch (e) { /* best-effort observability */ }
+    return { recorded: true, decision: d, routed: "verification-requested" };
+  }
+  // applied-not-built / ambiguous → terminal; superseded → terminal.
+  const terminal = d === "superseded" ? "superseded" : "ambiguous";
+  const noteBody = terminal === "superseded"
+    ? `publish: superseded ${commit} — unknown-recovery retry re-check: the retry target moved (${reasons}); not retrying a stale commit. Parked for human attention.`
+    : `publish: ambiguous ${commit} — unknown-recovery retry re-check: ${reasons}; not retrying blind. Parked for human attention.`;
+  writePublishNote(db, taskId, noteBody);
+  try {
+    appendFileSync(derived.ledgerPath, JSON.stringify({
+      ts: now(), task_id: taskId, workflow: "unknown-recovery", slug: derived.slug,
+      commit, attempt: derived.attempt, agent_id: null, applied_report: null,
+      outcome: "unknown-classified",
+      detail: `retry re-check ${d}: terminal (${reasons})`,
+    }) + "\n");
+  } catch (e) { /* best-effort observability */ }
+  return { recorded: true, decision: d, routed: terminal };
+};
+
 // 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
@@ -2070,6 +2625,14 @@ commands["update-config"] = (db, args) => {
 // projects carries N independent publish bases, and stamping one project
 // never touches another's row.
 function stampProvenance(db, { project_id, source_commit, crew_release, published_at, task_id }) {
+  // task_id invariant (2026-09-19 REVIEW): task_id is set by every REAL
+  // publish (lib/verify-publish.js and the workflow provenance-refresh paths)
+  // and is null for initial stamps (tryStampInitialProvenance) and for
+  // publish-base advances (lib/advance-publish-base.js). So
+  // provenance.task_id != null ⟺ a real publish has stamped this project.
+  // lib/advance-publish-base.js relies on this to deterministically refuse to
+  // move a publish's base. Keep it true: any new real-publish path must pass
+  // its task_id; anything that is not a publish must leave it null.
   const pid = String(project_id ?? "").trim();
   if (!pid) throw usageError("project_id is required — pass the project's id (see list-projects).");
   requireProject(db, pid);