muse-crew 0.14.3 → 0.14.5

package/lib/crew-api.js

@@ -30,6 +30,13 @@ import { execFileSync } from "node:child_process";
 import { DatabaseSync } from "node:sqlite";
 import { homedir } from "node:os";
 import { classifySurface } from "./classify-surface.js";
+// Terminal-note vocabulary (D7, 2026-09-19): the scan's terminal branch
+// consults this closed registry instead of an inline pattern list, so a
+// recognized terminal note is skipped as terminal with its meaning —
+// never as unrecognized. Pin-adjacent: every runtime-relative dependency
+// of crew-api.js is pinned in the workflows' pinLifecycle (PIN_BASENAMES),
+// mechanically verified by tests/pin-closure.test.js.
+import { matchTerminalPublishNote, TERMINAL_NOTE_MEANINGS } from "./publish-note-vocabulary.js";
 
 // ---------------------------------------------------------------------------
 // Errors
@@ -1704,10 +1711,10 @@ function derivePublishUnknownAttempt(db, crewHome, taskId, requireLatest = false
 }
 
 // The unknown-recovery state machine reads two note shapes: the machine's
-// own "publish: <transition>" notes, and the workflow's initial
+// own "publish: <transition>" notes, and the workflow's legacy (pre-2026-09-20)
 // "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.
+// marker, 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%')`;
 
@@ -1721,22 +1728,35 @@ function latestPublishNote(db, taskId) {
   ).get(taskId) || null;
 }
 
-// The trigger anchor for an unknown attempt: the OLDEST "submitted" ledger
-// entry for the same attempt (the trigger issuance). Oldest binds the trigger
-// instant — verify-publish.js and the decision doc bind oldest; binding newest
-// misclassifies builds that complete between issuance and receipt (A2/R2/O4).
-// 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.
+// The trigger anchor for an unknown attempt: the ISSUER-WRITTEN "submitted"
+// ledger entry for the same attempt (2026-09-20, one-party worker-owned
+// publish: only the session-carrying tick worker performs issuance, and it
+// stamps its writes issuer="tick-worker"). The workflow never issues and
+// never writes "submitted" — a workflow-written "submitted" (issuer absent,
+// the pre-one-party shape) is a phantom claim and must NOT bind. Within one
+// attempt the anchor is the OLDEST by ts (D1: the bound instant is
+// issued_at || ts, the same fallback verify-publish.js uses).
+// 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) {
+  // D1 (2026-09-19; entry_kind cut 2026-09-20; issuer anchor 2026-09-20):
+  // the anchor is the OLDEST tick-worker "submitted" entry by ts and the
+  // bound instant is its issued_at || ts — the same fallback
+  // verify-publish.js uses. A "submitted" without issuer (the retired
+  // workflow write) is not an issuance and never binds.
+  const matches = [];
   for (let i = 0; i < entries.length; i++) {
     const e = entries[i];
-    if (e.outcome === "submitted" && e.commit === commit &&
+    if (e.outcome === "submitted" && e.issuer === "tick-worker" &&
+        e.commit === commit &&
         (e.attempt || null) === (attempt || null)) {
-      return e;
+      matches.push(e);
     }
   }
-  return null;
+  matches.sort((a, b) => (a.ts || "").localeCompare(b.ts || ""));
+  return matches[0] || null;
 }
 
 // The unknown ledger entry's detail says whether the trigger went out.
@@ -1887,10 +1907,16 @@ commands["resolve-publish-unknown"] = (db, args, ctx) => {
 //     "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: publish-requested" (one-party   → atomic 1h claim → intent bucket: the tick issues
+//     intent, 2026-09-20 blocker 22)            the edit directly in its own turn (no child).
+//                                             An issuer-written "submitted" already present →
+//                                             mirror verification-requested, NEVER re-issue.
+//   "publish: publish-intent-claimed …"        → unexpired: skip (a tick owns it); expired:
+//                                             re-claim → intent (the tick runs the
+//                                             manifest-freshness check first)
+//   terminal notes (the closed registry in   → terminal; skipped with the
+//     lib/publish-note-vocabulary.js — the     reason named, never
+//     scan names the recognized note)          "unrecognized"
 //   "publish: verification-requested"         → already routed; ignored (the verification scan owns it)
 //
 // Unknown parks whose trigger was never issued (preflight/toolcheck
@@ -1907,9 +1933,11 @@ commands["scan-publish-unknown"] = (db, args, ctx) => {
 
   const waiting = [];
   const due = [];
+  const intent = [];
   const retryDue = [];
   const mirrored = [];
   const skipped = [];
+  const requeued = []; // F-A4: stale-base intents re-queued to the workflow's Publish
 
   const skip = (taskId, state, reason) => skipped.push({ task_id: taskId, state, ...(reason ? { reason } : {}) });
 
@@ -1925,7 +1953,9 @@ commands["scan-publish-unknown"] = (db, args, ctx) => {
       return;
     }
     const trigger = findTriggerEntry(derived.entries, derived.commit, derived.attempt);
-    if (!trigger || !trigger.ts) {
+    // D1 (2026-09-19): the anchor instant is the trigger-issuance instant
+    // (issued_at), not the ledger-write instant (ts) — issued_at || ts.
+    if (!trigger || !(trigger.issued_at || 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;
@@ -1959,7 +1989,7 @@ commands["scan-publish-unknown"] = (db, args, ctx) => {
     }
     due.push({
       task_id: taskId, commit: derived.commit, base,
-      trigger_ts: trigger.ts, park_ts: parkNote.timestamp,
+      trigger_ts: trigger.issued_at || trigger.ts, park_ts: parkNote.timestamp,
       slug: derived.slug, repo_path: derived.repoPath,
       project_id: derived.projectId, claim_expiry: expiry,
       ledger_path: derived.ledgerPath,
@@ -1972,6 +2002,160 @@ commands["scan-publish-unknown"] = (db, args, ctx) => {
     });
   };
 
+  // One-party publish intent (2026-09-20, blocker 22): the workflow parks at
+  // intent — the merged change is staged as a checksummed diff and issuance
+  // belongs to the session-carrying tick worker (no child — blocker 22
+  // proved children cannot reach artifact_edit). The intent ledger entry
+  // (outcome "publish-intent", issuer "workflow") is the durable anchor: the
+  // tick verifies the staged diff's sha256 against it and regenerates from
+  // base..commit when the file is missing. reclaimed=true when a previous
+  // tick's claim expired: the tick runs the manifest-freshness check before
+  // issuing, because the dead tick may have issued and died before
+  // recording it — a re-claim never blindly re-issues.
+  const claimForIntent = (taskId, intentNote, reclaimed, anchorNote) => {
+    const m = intentNote.message.match(/publish: publish-requested\s+([0-9a-f]{40})\s+(\S+)/);
+    if (!m) {
+      skip(taskId, "intent-note-unparseable",
+        "the publish-requested note carries no commit hash — stays parked for human attention");
+      return;
+    }
+    const commit = m[1];
+    const task = db.prepare("SELECT id, state, project FROM tasks WHERE id = ?").get(taskId);
+    if (!task || task.state !== "parked") {
+      skip(taskId, "not-parked", `task is not parked (state=${task && task.state}) — the intent claim requires a parked task`);
+      return;
+    }
+    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) {
+      skip(taskId, "no-deploy-slug", "project has no deploy_slug — stays parked for human attention");
+      return;
+    }
+    // (2026-09-20, critic-0145 F-R5) A null repo_path fails closed at
+    // emission: the tick can neither regenerate nor verify the diff. The
+    // task stays parked for human attention — no claim, no tick work.
+    const repoPath = project && project.repo_path;
+    if (!repoPath) {
+      skip(taskId, "no-repo-path",
+        "project has no repo_path — the intent diff cannot be regenerated or verified; fails closed at emission; stays parked for human attention");
+      return;
+    }
+    const ledgerPath = join(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) {
+      skip(taskId, "ledger-unreadable", `cannot read publish ledger: ${e.message} — stays parked for human attention`);
+      return;
+    }
+    // Latest intent wins: a reworked task re-parks a fresh intent.
+    const intentEntry = [...entries].reverse().find((e) => e.outcome === "publish-intent") || null;
+    if (!intentEntry) {
+      skip(taskId, "no-intent-entry",
+        "no publish-intent ledger entry for this task — the intent anchor is missing; stays parked for human attention");
+      return;
+    }
+    if (intentEntry.commit !== commit) {
+      skip(taskId, "intent-commit-mismatch",
+        `intent ledger entry commits ${intentEntry.commit} but the park note names ${commit} — stays parked for human attention`);
+      return;
+    }
+    if (typeof intentEntry.diff_path !== "string" || !intentEntry.diff_path ||
+        !/^[0-9a-f]{64}$/.test(intentEntry.diff_sha256 || "")) {
+      skip(taskId, "intent-diff-unusable",
+        "the intent entry carries no usable diff_path/diff_sha256 — stays parked for human attention");
+      return;
+    }
+    // The tick died after issuing but before mirroring: an issuer-written
+    // "submitted" for this commit+attempt exists. NEVER re-issue — mirror
+    // the missing verification request and let content verification be the
+    // arbiter (the same rule as the retry-intended crash window).
+    const issued = entries.some((e) =>
+      e.outcome === "submitted" && e.issuer === "tick-worker" &&
+      e.commit === commit && (e.attempt || null) === (intentEntry.attempt || null));
+    if (issued) {
+      writePublishNote(db, taskId,
+        `publish: verification-requested ${commit} attempt=${intentEntry.attempt} — mirrored by scan-publish-unknown: a tick-worker issuance entry exists 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, attempt: intentEntry.attempt || null, not_before: null, reason: "intent-issued-without-mirror" });
+      return;
+    }
+    // Freshness CAS: the latest publish: note must still be the note we
+    // branched on — for a first claim that is the intent note; for a
+    // re-claim it is the expired claim note.
+    const fresh = latestPublishNote(db, taskId);
+    if (!fresh || !anchorNote || fresh.message !== anchorNote.message) { skip(taskId, "raced"); return; }
+    const manifestBefore = (intentEntry.manifest_before && typeof intentEntry.manifest_before === "object")
+      ? intentEntry.manifest_before : null;
+    const claimedAt = new Date(nowMs).toISOString();
+    const expiry = new Date(nowMs + claimLeaseMs).toISOString();
+    writePublishNote(db, taskId,
+      `publish: publish-intent-claimed ${expiry} — ${taskId} parked at publish intent for ${commit}; claimed for direct issuance by the session-carrying tick worker (1-hour lease).`,
+      claimedAt);
+    // The classifier-base convention: last verified publish, or the empty
+    // tree on a first publish — the tick needs it to regenerate the diff
+    // byte-identically when the staged file is missing. A query error is
+    // not "no provenance" — fail closed.
+    let base;
+    try {
+      const prov = db.prepare("SELECT provenance_source_commit FROM projects WHERE id = ?").get(project.id);
+      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;
+    }
+    // (2026-09-20, critic-0145 F-A4) The intent's recorded base must match
+    // stamped provenance: another publish may have landed after the intent
+    // was staged. A stale base means the staged diff is against a superseded
+    // base — re-queue the task (next_phase routes it straight back to the
+    // workflow's Publish, which re-prepares the intent against the new base);
+    // never issue the stale diff. Legacy intents with no recorded base
+    // re-queue exactly once, then re-prepare with a base.
+    const intentBase = (typeof intentEntry.base === "string" && /^[0-9a-f]{40}$/.test(intentEntry.base))
+      ? intentEntry.base : null;
+    if (!intentBase || intentBase !== base) {
+      writePublishNote(db, taskId,
+        `publish: publish-base-stale ${commit} — the intent's staged diff was computed against base ` +
+        `${intentBase ? intentBase.slice(0, 7) : "(none recorded)"} but stamped provenance now reads ` +
+        `${base.slice(0, 7)}; issuing the stale diff risks a spurious content-mismatch. Re-queued: ` +
+        `the workflow's Publish re-prepares the intent against the new base.`,
+        claimedAt);
+      db.prepare("UPDATE tasks SET next_phase = 'Publish', state = 'in_progress', updated_at = ? WHERE id = ?")
+        .run(now(), taskId);
+      requeued.push({ task_id: taskId, intent_base: intentBase, provenance_base: base });
+      return;
+    }
+    // (2026-09-20, critic-0145 F-R3) Re-claim with no manifest baseline: the
+    // tick could neither prove a dead tick's issuance nor safely re-issue —
+    // fail closed with a terminal human-attention park; never blind-issue,
+    // never loop indefinitely.
+    if (reclaimed && !manifestBefore) {
+      writePublishNote(db, taskId,
+        `publish: intent-unverifiable ${commit} — one-party intent terminal: this re-claim arrived with ` +
+        `no pre-issuance manifest baseline, so the freshness comparison is unperformable; the tick can ` +
+        `neither prove a dead tick's issuance nor safely re-issue. Parked for human attention.`,
+        claimedAt);
+      skip(taskId, "terminal",
+        "re-claimed intent with a null manifest baseline — 'publish: intent-unverifiable'; parked for human attention");
+      return;
+    }
+    intent.push({
+      task_id: taskId, commit, attempt: intentEntry.attempt || null,
+      slug, repo_path: repoPath,
+      project_id: project.id, ledger_path: ledgerPath, base,
+      diff_path: intentEntry.diff_path, diff_sha256: intentEntry.diff_sha256,
+      manifest_before: manifestBefore,
+      claimed_at: claimedAt, claim_expiry: expiry, reclaimed,
+    });
+  };
+
   const parked = db.prepare(`SELECT id AS task_id FROM tasks WHERE state = 'parked'`).all();
 
   db.exec("BEGIN");
@@ -1989,11 +2173,13 @@ commands["scan-publish-unknown"] = (db, args, ctx) => {
       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");
+      // Terminal states — the machine never revisits these. The vocabulary is
+      // explicit state (lib/publish-note-vocabulary.js); a recognized terminal
+      // note is skipped as terminal with its meaning, never as unrecognized.
+      const terminalNote = matchTerminalPublishNote(msg);
+      if (terminalNote) {
+        skip(taskId, "terminal",
+          `recognized terminal note '${terminalNote}' — ${TERMINAL_NOTE_MEANINGS[terminalNote]}`);
         continue;
       }
       // Already routed into the verification pipeline — the verification
@@ -2065,12 +2251,31 @@ commands["scan-publish-unknown"] = (db, args, ctx) => {
           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,
+          trigger_ts: (retryTrigger && (retryTrigger.issued_at || retryTrigger.ts)) || null,
           manifest_before: (retryTrigger && retryTrigger.manifest_before &&
             typeof retryTrigger.manifest_before === "object") ? retryTrigger.manifest_before : null,
         });
         continue;
       }
+      // One-party publish intent (2026-09-20, blocker 22): the workflow
+      // parked at intent; the session-carrying tick worker issues the edit
+      // directly from the intent bucket — no child, no trigger.
+      if (has("publish: publish-intent-claimed")) {
+        const m = msg.match(/publish: publish-intent-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-issuance. Re-derive from the
+        // original intent note and re-claim — the re-claiming tick runs the
+        // manifest-freshness check before issuing, never blindly re-issues.
+        const intentNote = notes.find((n) => n.message.includes("publish: publish-requested"));
+        if (!intentNote) { skip(taskId, "no-intent-note", "expired intent claim with no publish-requested note in history"); continue; }
+        claimForIntent(taskId, intentNote, true, latest);
+        continue;
+      }
+      if (has("publish: publish-requested")) {
+        claimForIntent(taskId, latest, false, latest);
+        continue;
+      }
       // A previous tick claimed this task for classification.
       // A previous tick claimed this task for classification.
       if (has("publish: unknown-recovery-claimed")) {
@@ -2106,7 +2311,243 @@ commands["scan-publish-unknown"] = (db, args, ctx) => {
     db.exec("COMMIT");
   } catch (e) { db.exec("ROLLBACK"); throw e; }
 
-  return { waiting, due, retry_due: retryDue, mirrored, skipped };
+  return { waiting, due, intent, retry_due: retryDue, mirrored, skipped, requeued };
+};
+
+// One-party intent issuance record (2026-09-20, blocker 22). The
+// session-carrying tick worker issues the artifact_edit DIRECTLY in its own
+// turn (no child — blocker 22 proved children cannot reach artifact_edit)
+// and ferries the outcome here. Code decides: every note and ledger line
+// the outcome implies is written here, atomically, never free-formed by
+// the tick.
+//
+// Args: { task_id, claim_expiry, edit_outcome, refusal_text?, freshness_evidence? } where
+// edit_outcome is "accepted" (the direct artifact_edit call completed
+// without error and without an explicit refusal — and ONLY then; tool
+// unavailable, timeout, or any ambiguous result is not accepted and is
+// never recorded here, the tick logs it and lets the claim expire),
+// "recovered" (a re-claiming tick ran lib/check-intent-freshness.js and the
+// manifest advanced past the intent's baseline — the dead tick issued and
+// died before recording it), or "refused" (the platform explicitly refused
+// the edit).
+//
+// The claim_expiry is a compare-and-swap: the record lands only while the
+// latest publish: note is still this tick's intent claim. A stale tick (its
+// claim expired and a newer tick re-claimed) gets { recorded: false } and
+// writes nothing.
+//
+// Routing:
+//   accepted / recovered → issuer-written "submitted" ledger entry
+//     (issuer "tick-worker"; issued_at = the command's clock — the upper
+//     bound on issuance — for "accepted"; for "recovered", the dead tick's
+//     original claim time — the earliest matching publish-intent-claimed
+//     note for this commit — which lower-bounds the unobserved issuance
+//     instant, 2026-09-20 critic-0145 F-O1) + the tick's freshness evidence
+//     recorded on the "recovered" entry + mirrored
+//     `publish: verification-requested` (the verification scan claims it).
+//   refused             → issuer-written "rejected" ledger entry carrying
+//     the platform's refusal text + terminal `publish: publish-refused`
+//     (parked for human attention — no re-issue, no park-unknown).
+//
+// A "recovered" record without machine freshness evidence is refused: pass
+// freshness_evidence (the check-intent-freshness.js JSON, advanced:true) —
+// an unproven recovery is not recorded (2026-09-20 critic-0145 F-O3/F-R2).
+commands["record-intent-issuance"] = (db, args, ctx) => {
+  const taskId = args.task_id;
+  const claimExpiry = args.claim_expiry;
+  const editOutcome = args.edit_outcome;
+  if (!taskId) throw usageError("task_id is required.");
+  if (!claimExpiry) throw usageError("claim_expiry is required.");
+  if (!["accepted", "recovered", "refused"].includes(editOutcome)) {
+    throw usageError(`unknown edit outcome: ${editOutcome}.`);
+  }
+
+  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: publish-intent-claimed") ||
+        !latest.message.includes(claimExpiry)) {
+      db.exec("ROLLBACK");
+      return { recorded: false, reason: "claim no longer current — another tick owns this task" };
+    }
+    // The intent anchor: the workflow's issuer-written intent entry.
+    const task = db.prepare("SELECT id, project FROM tasks WHERE id = ?").get(taskId);
+    const project = task && db.prepare("SELECT id, deploy_slug FROM projects WHERE id = ?").get(task.project);
+    const slug = project && project.deploy_slug;
+    if (!slug) {
+      db.exec("ROLLBACK");
+      return { recorded: false, reason: "project has no deploy_slug" };
+    }
+    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) {
+      db.exec("ROLLBACK");
+      return { recorded: false, reason: `cannot read publish ledger: ${e.message}` };
+    }
+    const intentEntry = [...entries].reverse().find((e) => e.outcome === "publish-intent") || null;
+    if (!intentEntry || !/^[0-9a-f]{40}$/.test(intentEntry.commit || "")) {
+      db.exec("ROLLBACK");
+      return { recorded: false, reason: "no usable publish-intent ledger entry for this task" };
+    }
+    const ts = now();
+    const commit = intentEntry.commit;
+    const attempt = intentEntry.attempt || null;
+    // (2026-09-20, critic-0145 F-O1) A recovered issuance's instant is
+    // unobserved, but it is LOWER-BOUNDED by the dead tick's original
+    // claim: the earliest publish-intent-claimed note for this commit (not
+    // the reclaimer's later claim). Binding issued_at to that time keeps
+    // the verifier's staleness check honest — the old null fell back to
+    // the recovery record's later timestamp and made a genuine
+    // already-completed build look stale.
+    let recoveredIssuedAt = null;
+    if (editOutcome === "recovered") {
+      const deadClaim = db.prepare(
+        `SELECT timestamp FROM events
+         WHERE task_id = ? AND type = 'note' AND message LIKE '%publish: publish-intent-claimed%'
+           AND message LIKE ?
+         ORDER BY timestamp ASC LIMIT 1`
+      ).get(taskId, `%${commit}%`);
+      recoveredIssuedAt = (deadClaim && deadClaim.timestamp) || null;
+    }
+    // (2026-09-20, critic-0145 F-O3/F-R2) A recovery must carry machine
+    // evidence: the check-intent-freshness.js JSON with advanced:true. An
+    // unproven recovery is not recorded — the command fails the call so the
+    // tick cannot write an honest-looking "recovered" on prose.
+    let freshnessEvidence = null;
+    if (editOutcome === "recovered") {
+      const ev = args.freshness_evidence;
+      const evObj = typeof ev === "string" ? (() => { try { return JSON.parse(ev); } catch { return null; } })() : ev;
+      if (!evObj || typeof evObj !== "object" || evObj.ok !== true || evObj.advanced !== true) {
+        throw usageError("recovered requires freshness_evidence — the check-intent-freshness.js JSON with advanced:true.");
+      }
+      freshnessEvidence = evObj;
+    }
+    const ledgerLine = {
+      ts, task_id: taskId, workflow: "intent-issuance", slug,
+      commit, attempt, agent_id: null, applied_report: null,
+      issuer: "tick-worker",
+      diff_sha256: intentEntry.diff_sha256 || null,
+      manifest_before: intentEntry.manifest_before || null,
+      freshness_evidence: freshnessEvidence,
+    };
+    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.issued_at = null;
+      ledgerLine.detail = `platform refused the directly-issued edit: ${refusalText}`;
+      // 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} — the platform refused the issued edit (${refusalText}). No re-issue; parked for human attention.`;
+    } else {
+      ledgerLine.outcome = "submitted";
+      ledgerLine.issued_at = editOutcome === "accepted" ? ts : recoveredIssuedAt;
+      ledgerLine.detail = editOutcome === "accepted"
+        ? "edit issued directly by the session-carrying tick worker (one-party publish)"
+        : `recovered: the manifest advanced past the intent's baseline (freshness evidence recorded) — the dead tick issued and died before recording it; issuance attributed to the dead tick, issued_at lower-bounded by the dead tick's original claim at ${recoveredIssuedAt || "unknown"}`;
+      note = `publish: verification-requested ${commit} attempt=${attempt} — issued directly by the session-carrying tick worker (one-party publish). Waiting on the manual read-back in docs/publish-verification.md.`;
+    }
+    try {
+      appendFileSync(ledgerPath, JSON.stringify(ledgerLine) + "\n");
+    } catch (e) {
+      db.exec("ROLLBACK");
+      return { recorded: false, reason: `cannot append publish ledger: ${e.message}` };
+    }
+    writePublishNote(db, taskId, note, ts);
+    db.exec("COMMIT");
+    return { recorded: true, edit_outcome: editOutcome, task_id: taskId, commit, note };
+  } catch (e) { db.exec("ROLLBACK"); throw e; }
+};
+
+// Record a one-party intent as unissuable (2026-09-20, critic-0145 F-O2).
+// The session-carrying tick worker calls this when the staged diff cannot
+// be (re)generated byte-identically — the staged file is missing and
+// compute-publish-diff --commit fails, or the regenerated hash does not
+// match the intent's diff_sha256. Code decides: the terminal
+// `publish: publish-unissuable` note and an issuer-written ledger entry
+// (outcome "unissuable", issuer "tick-worker") are written here,
+// atomically, never free-formed by the tick.
+//
+// Args: { task_id, claim_expiry, reason } where reason is a short
+// machine-readable cause (missing-staged-diff, diff-unregenerable,
+// hash-mismatch-after-regeneration).
+//
+// The claim_expiry is a compare-and-swap: the record lands only while the
+// latest publish: note is still this tick's intent claim. A stale tick gets
+// { recorded: false } and writes nothing. The terminal note means the scan
+// never re-claims — no hourly reclaim loop on an unissuable diff.
+commands["record-intent-unissuable"] = (db, args, ctx) => {
+  const taskId = args.task_id;
+  const claimExpiry = args.claim_expiry;
+  const reason = String(args.reason || "").split("\n")[0].slice(0, 200);
+  if (!taskId) throw usageError("task_id is required.");
+  if (!claimExpiry) throw usageError("claim_expiry is required.");
+  if (!reason) throw usageError("reason is required.");
+
+  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: publish-intent-claimed") ||
+        !latest.message.includes(claimExpiry)) {
+      db.exec("ROLLBACK");
+      return { recorded: false, reason: "claim no longer current — another tick owns this task" };
+    }
+    const task = db.prepare("SELECT id, project FROM tasks WHERE id = ?").get(taskId);
+    const project = task && db.prepare("SELECT id, deploy_slug FROM projects WHERE id = ?").get(task.project);
+    const slug = project && project.deploy_slug;
+    if (!slug) {
+      db.exec("ROLLBACK");
+      return { recorded: false, reason: "project has no deploy_slug" };
+    }
+    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) {
+      db.exec("ROLLBACK");
+      return { recorded: false, reason: `cannot read publish ledger: ${e.message}` };
+    }
+    const intentEntry = [...entries].reverse().find((e) => e.outcome === "publish-intent") || null;
+    if (!intentEntry || !/^[0-9a-f]{40}$/.test(intentEntry.commit || "")) {
+      db.exec("ROLLBACK");
+      return { recorded: false, reason: "no usable publish-intent ledger entry for this task" };
+    }
+    const ts = now();
+    const commit = intentEntry.commit;
+    const attempt = intentEntry.attempt || null;
+    const ledgerLine = {
+      ts, task_id: taskId, workflow: "intent-issuance", slug,
+      commit, attempt, agent_id: null, applied_report: null,
+      issuer: "tick-worker", outcome: "unissuable", issued_at: null,
+      diff_sha256: intentEntry.diff_sha256 || null,
+      manifest_before: intentEntry.manifest_before || null,
+      detail: `intent diff unissuable: ${reason} — the staged diff cannot be (re)generated byte-identically; parked for human attention`,
+    };
+    try {
+      appendFileSync(ledgerPath, JSON.stringify(ledgerLine) + "\n");
+    } catch (e) {
+      db.exec("ROLLBACK");
+      return { recorded: false, reason: `cannot append publish ledger: ${e.message}` };
+    }
+    // Terminal: "publish: publish-unissuable" is registered in
+    // lib/publish-note-vocabulary.js (the closed registry — the writer-side
+    // guard pattern from D7).
+    const note = `publish: publish-unissuable ${commit} — the intent's staged diff cannot be (re)generated byte-identically (${reason}). Never re-claim, never loop; parked for human attention.`;
+    writePublishNote(db, taskId, note, ts);
+    db.exec("COMMIT");
+    return { recorded: true, task_id: taskId, commit, note };
+  } catch (e) { db.exec("ROLLBACK"); throw e; }
 };
 
 // Record the unknown-recovery classifier's decision (2026-09-18, blocker
@@ -2802,6 +3243,17 @@ function main() {
   }
 }
 
+const CREW_API_USAGE =
+  "usage: node crew-api.js --crew-home <path> <command> [--json <json>] [flags...]\n" +
+  "the crew-owned task-service API (API.md): every state-machine invariant lives in the schema.\n" +
+  "run with a command and no --help for command-specific usage; exit 0 ok · 2 usage · 3 not found · 4 conflict/guard";
+
+// --help: before required-arg parsing (shebang⇔CLI contract).
+if (process.argv.slice(2).includes("--help")) {
+  console.log(CREW_API_USAGE);
+  process.exit(0);
+}
+
 try {
   main();
 } catch (e) {