muse-crew 0.13.3 → 0.14.0

package/docs/publish-unknown-recovery.md

@@ -0,0 +1,113 @@
+# Publish-unknown recovery (blocker 15, 2026-09-18)
+
+When a standard/bugfix Publish parks with "Publish outcome unknown", the
+artifact-edit trigger went out fire-and-forget and no receipt came back —
+async was planned for, receipt-less was not. The unknown-recovery loop
+closes that gap without re-issuing blindly.
+
+## The note is the state machine
+
+Recovery state lives in the task's `note` events, keyed on machine-written
+`publish: <transition>` markers. Deterministic code (`lib/crew-api.js`) owns
+every transition; the cron tick (Step 4.4) is only the ferry between the
+deterministic steps. The initial park note is the workflow's
+"Publish outcome unknown …" note (no `publish:` marker — the scan matches it
+explicitly); every transition after that is machine-written.
+
+State diagram (latest `publish:` note wins; history is the retry budget):
+
+```
+"Publish outcome unknown" park
+  (< 30m) ──waiting──> scan: waiting (leave alone)
+  (>= 30m) ──scan──> publish: unknown-recovery-claimed <expiry>   (1h lease)
+       │
+       ├─ tick runs lib/classify-publish-absence.js, then
+       │  record-unknown-classification (CAS on the claim expiry):
+       │
+       ├─ verified ──────────> publish: verification-requested <commit>
+       │                        (content IS present; Step 4.5 verifies;
+       │                         ledger: unknown-resolved)
+       ├─ provably-dropped ──> publish: dropped <commit>
+       │                        (queues the retry protocol, next tick)
+       ├─ applied-not-built / ambiguous ──> publish: ambiguous <commit>
+       │                        (terminal; ledger: unknown-classified)
+       ├─ superseded ────────> publish: superseded <commit>  (terminal)
+       └─ deferred ──────────> (no note; the claim expires; the next scan
+                                re-claims and re-classifies)
+```
+
+Retry protocol (Step 4.4, for `publish: dropped` with a free budget):
+
+```
+publish: dropped
+  ── tick: HEAD == commit? no ──> publish: retry-superseded (terminal)
+  ── tick: acquire merge lock publish-retry:<task> (600s); held ──> stop, retry next tick
+  ── tick: re-read content in the lock (classifier)
+       ├─ not provably-dropped ──> record-retry-recheck routes it
+       │    (verified → verification-requested; ambiguous → terminal;
+       │     superseded → terminal; deferred → no-op)
+       └─ provably-dropped ──> publish: retry-intended <commit> <ts>
+            ── trigger (same child shape as the first attempt)
+            ├─ ARTIFACT_EDIT_REFUSED ──> publish: retry-refused (terminal)
+            └─ no refusal ──> publish: retry-issued <commit>
+                 ──> publish: verification-requested <commit> not-before=<ts+20m>
+                     (Step 4.5 skips not-before entries until the window passes)
+                 ──> one -retry1 ledger entry (best-effort)
+            ── release the merge lock (every path)
+```
+
+Crash recovery (fail closed, never re-trigger blind):
+
+- `publish: retry-intended` without `retry-issued` → the next scan mirrors
+  `verification-requested` with `not-before=intended+20m`. The trigger may
+  or may not have gone out; content verification is the arbiter.
+- `publish: retry-issued` without a mirrored request → the next scan writes
+  the missing mirror.
+- Exactly one retry per task, enforced from note history: the scan emits
+  `retry_due` only when no `publish: retry-issued` exists in the task's
+  history — including a retry for an earlier unknown attempt on a reworked
+  task. When the budget is spent, the drop is terminal: `publish: ambiguous`.
+
+## Commands
+
+- `scan-publish-unknown` — the cron scan (Step 4.5 of the old numbering).
+  Returns `{ waiting, due, retry_due, mirrored, skipped }`. `due` entries
+  ferry the classifier inputs: `commit`, `trigger_ts` (from the `submitted`
+  ledger entry — never a time window), `park_ts`, `slug`, `repo_path`,
+  `base` (provenance `source_commit`, else the empty tree), and
+  `claim_expiry` for the record CAS. `retry_due` entries ferry the retry
+  inputs (`commit`, `attempt`, `slug`, `repo_path`, `base`, `ledger_path`).
+- `record-unknown-classification --json '{task_id, claim_expiry, decision}'`
+  — routes the classifier's decision; CAS on the claim expiry (a stale tick
+  records nothing).
+- `record-retry-recheck --json '{task_id, decision}'` — routes the retry
+  protocol's in-lock content re-read; CAS on latest being `publish: dropped`.
+- `resolve-publish-unknown` — the manual one-shot for a single parked task
+  (unchanged; the audit-window contract, not the classifier).
+
+## Classifier (lib/classify-publish-absence.js)
+
+Decides, from the task's repo and the platform's on-disk state, whether the
+dropped edit is proven:
+
+- `verified` — the content IS present (the platform applied it; the receipt
+  was the only thing lost). Never re-issue.
+- `provably-dropped` — the old source is live AND the manifest shows no
+  build since the trigger. Only this decision may retry.
+- `applied-not-built` — the new source is live but no build ran (the
+  trigger reached the platform but the build didn't). Ambiguous outcome,
+  terminal: a retry would double-apply.
+- `ambiguous` — the content check is inconclusive. Never retry blind.
+- `deferred` — not yet quiesced; re-check next tick.
+- `superseded` — HEAD moved past the attempt's commit. Terminal.
+
+The classifier's verified path requires the CURRENT manifest to be a new
+build identity: `built_at` advanced past the trigger AND `content_sha256`
+differs from the pre-trigger baseline the workflow snapshots into the
+submitted ledger entry (design §1.9 — defeats a replayed manifest). When
+the baseline is unavailable the classifier falls back to the time-based
+advance check and notes it; the Step 4.5 verifier (`lib/verify-publish.js`)
+is the strict gate and fails closed without a baseline before stamping.
+Build-in-flight is checked twice bracketing the content read via manifest
+state change (no mtime heuristics), and the suite carries add-only and
+removal-only regression fixtures.

package/lib/AGENTS.md

@@ -24,8 +24,10 @@ Shell scripts for the crew's infrastructure. Called by workflow scripts, cron, a
 - `ux-doctrine.js` — UX-surface doctrine page resolution (2026-09-17): the canonical map from `environment_type` to the crew's shared UX bar (`artifact` → `docs/artifact-ux.md`, `terminal` → `docs/terminal-ux.md`; null/unknown → no page). Pure and deterministic: `doctrinePage(env)`, `doctrinePath(crewHome, env)`, `doctrinePageExists(crewHome, env)`; CLI `--page <env>` / `--path <crewHome> <env>`. Workflows mirror the map inline (one line — the workflow runtime's relative-import support is unverified) and tests pin the mirror against this file.
 - `serve-artifact.js` — local server for a built TS space for experiential QA (2026-09-14): serves `<space-dir>/client/dist` statically and dispatches POST `*/actions` to the compiled server actions with a locally-built Ctx. Prints `READY port=<n>` then serves until killed. Read-only w.r.t. the space directory. Fidelity: the served client and action handlers are the artifact's own built code; the Ctx is locally built (privileged handlers run from the space's own `server/dist/privileged.js` when present; blobs are stored in a per-run temp dir and served back at `/__blobs/<key>`); environment is inherited from the caller. It is not the hosted runtime — tasks that cannot be judged under it must report `NOT POSSIBLE: <reason>`.
 - `readback-disk.js` — deterministic publish content sensor (2026-09-16): reads the on-disk tree the artifact is built/served from and emits the machine-readable findings block (`FILE:`/`ADDED:`/`REMOVED:`/`END_FILE`) that `verify-publish.js` judges. The primary sensor — the LLM-inspector path (`build-readback-request.js`) is manual-fallback only since `artifact_inspect` was removed by the platform 2026-09-14.
+- `publish-content.js` — shared ESM content-primitives for publish verification (2026-09-18, blocker 15): diff parsing (`parseDiff`), findings parsing (`parseFindings`), old-tree occurrence counting (`makeOldCounter`), and the discriminating-line / collision-exemption logic (`discriminatingLines`). Unifies `verify-publish.js` and the unknown-recovery classifier on one judgment so the two paths can never disagree about what a diff proves.
+- `classify-publish-absence.js` — deterministic six-way classifier for publish-parked UNKNOWN outcomes (2026-09-18, blocker 15): decides from durable signals only — the pre-trigger manifest baseline (captured by the workflow into the submitted ledger entry; design §1.9) vs the current manifest's `built_at`/`content_sha256`, `git diff <base> <commit>` discriminating lines against the on-disk source tree, and HEAD vs the publish commit. Outcomes: `provably-dropped` (source shows pre-edit state, manifest NOT advanced past the trigger, HEAD == commit, aged past quiesce — retry once), `verified` (manifest advanced past the trigger AND content_sha256 differs from the pre-trigger baseline — a new build identity, not a replayed manifest; falls back to the time-based advance check with a note when the baseline is absent, and the Step 4.5 verifier fails closed without a baseline), `applied-not-built` (platform build-emission failure; no retry — the 2026-09-12 re-trigger hazard), `ambiguous` (any inconclusive shape — no retry by design), `deferred` (build in flight — manifest changed during the content read, or built within the settle window — or park below quiesce; not a verdict, retry later), `superseded` (HEAD != commit — never retry the old commit). Retry budget is consumed by the classification itself, never by the edit attempt. Never reads the wall clock except for recovery timing; addition-only and removal-only diffs are vacuously satisfied on their empty side.
 - `build-readback-request.js` — builds the LLM-inspector read-back `verbatim_request` from the merge commit's diff (2026-09-14): carries the merged diff as the expected change and asks for an independent read of the artifact's actual source. Retained as the manual fallback; the deterministic `readback-disk.js` is the primary sensor.
-- `verify-publish.js` — mechanical publish verification judge (2026-09-14/16): certifies the read-back findings block against `git diff` (strict `FILE:`/`ADDED:`/`REMOVED:`/`END_FILE` parsing, every added line PRESENT / every removed line ABSENT, HEAD==commit supersession check) and only then stamps provenance. Binary files, mode-only changes, and fully-colliding added hunks fail closed as `unverifiable-content` (2026-09-16, critic findings 1/5) — they can never vacuously stamp. Content-mismatch, unreadable-result, superseded, and stamp failures exit 1 with `publish: verification-failed` and no stamp. Collision exemption (2026-09-15): a removed line occurring in the old tree strictly more times than the diff removes is exempt from ABSENT (zero discriminating power); computed from `git show <base>:<path>`, never the working tree.
+- `verify-publish.js` — mechanical publish verification judge (2026-09-14/16; shared primitives 2026-09-18): certifies the read-back findings block against `git diff` (strict `FILE:`/`ADDED:`/`REMOVED:`/`END_FILE` parsing, every discriminating added line PRESENT / every discriminating removed line ABSENT, HEAD==commit supersession check), then the design §1.9 manifest-freshness gate (current manifest `built_at` advanced past the trigger AND `content_sha256` differs from the workflow's pre-trigger baseline in the submitted ledger entry — a new build identity, not a replayed manifest; missing baseline fails closed), and only then stamps provenance. Diff parsing, findings parsing, and the collision-exemption rules come from the shared `lib/publish-content.js` (the unknown-recovery classifier's own judgment — one definition, never two). Binary files, mode-only changes, and fully-colliding added hunks fail closed as `unverifiable-content` (2026-09-16, critic findings 1/5) — they can never vacuously stamp. Content-mismatch, unreadable-result, superseded, and stamp failures exit 1 with `publish: verification-failed` and no stamp.
 - `update-watch.js` — deterministic automatic update watcher (2026-09-16, zero deps): `node update-watch.js --crew-home <path>` (missing arg → usage, exit 2; every other path exits 0). Watches the public npm registry (`npm view muse-crew version` pinned to `https://registry.npmjs.org/`) vs `crew-release.sh current` and files a `workflow: "upgrade"` task with `source: npm@<version>` when policy (`auto_update_crew`, `update_channel`) and channel gating allow; watches `git ls-remote origin HEAD` on the first `deploy_type=artifact` project vs `$CREW_HOME/.update-watch.json` and files a `workflow: "chore"` task carrying the mechanical dashboard-upgrade journey. Reads the `.crew-version` compatibility anchor at the new ref via `git fetch` + `git show <sha>:.crew-version` (never the working tree) and orders dashboard-led: a declared newer crew files the crew upgrade task FIRST and the dashboard task notes it follows the crew upgrade (declaration bypasses `update_channel`, not the `auto_update_crew=false` opt-out); a declared older crew skips the dashboard leg entirely as a human decision; a missing/invalid/unfetchable anchor fails open to the dashboard leg as today. Idempotency via the same state file (records at file time); check failures log to `$CREW_HOME/update-watch.log` and are never thrown. Safety: only files tasks — never deploys, never touches the artifact/config/scheduler. Run by the daily `crew-update-watch` cron through the `current` symlink (latest release); deliberately NOT in the lib-pinning `PIN_BASENAMES`.
 - `gitignore.js` — deterministic .gitignore management for crew-owned paths (2026-09-17): the crew touches exactly one user-owned file outside `.orchestration/` — the repo's `.gitignore`. `ensureGitignoreEntries(repoPath, entries)` creates the file when missing, appends missing entries (exact line match, no duplicates), preserves existing content byte-for-byte, and is idempotent. `describeGitignoreChange(repoPath, entries)` renders the exact diff for the setup consent conversation. Crew-owned entries: `.worktrees/`, `.orchestration/user/`. CLI: `--repo <path> [--dry-run]`.
 - `repo-orchestration.js` — repository-local `.orchestration/` scaffold (2026-09-17): `scaffoldRepoOrchestration(repoPath, crewRepoPath)` creates `$REPO/.orchestration/{workflows,identities,phases,user}/`, seeds workflows/identities/phases from the crew repo's platform defaults with no-clobber semantics (existing project customizations never overwritten), and writes a README in `user/` explaining it's for local config. Idempotent. CLI: `--repo <path> --crew-repo <path>`.

package/lib/classify-publish-absence.js

@@ -0,0 +1,451 @@
+#!/usr/bin/env node
+// classify-publish-absence.js — deterministic classifier for publish attempts
+// parked with an UNKNOWN outcome (blocker 15, Phase 1, 2026-09-18).
+//
+// The workflow's fire-and-forget trigger returns no receipt, so a parked
+// unknown means "the edit may or may not have gone through and the build
+// may or may not have run." This unit decides mechanically from durable
+// signals only — never from timing windows or audit-dir counting:
+//
+//   sensor findings (lib/readback-disk.js — the on-disk source read-back)
+//   × manifest (.space-build/manifest.json — built_at + content_sha256)
+//   × repo state (git diff base..commit, HEAD)
+//
+// Decisions (design-room19.md §1.4):
+//   verified            — manifest built_at advanced past the trigger AND
+//                         every discriminating added line PRESENT / removed
+//                         ABSENT (the build landed; route to parent
+//                         verification, which stamps).
+//   provably-dropped    — (a) every discriminating added line ABSENT,
+//                         (b) every discriminating removed line PRESENT,
+//                         (c) manifest built_at NOT advanced past trigger,
+//                         (d) no build in flight (checked twice, bracketing
+//                         the content read), (e) decision time ≥ park +
+//                         quiesce, (f) HEAD == commit. One safe retry.
+//   applied-not-built   — source PRESENT but manifest stale: the platform
+//                         started something but no build completed.
+//                         → ambiguous, park with the diagnosis, NO retry
+//                         (re-applying a possibly mid-apply diff is the
+//                         2026-09-12 hazard in a new coat).
+//   ambiguous           — partial-apply, binary/mode-only/rename diffs,
+//                         unreadable sensor, manifest-advanced-but-mismatched,
+//                         zero discriminating lines. Terminal, no retry.
+//   deferred            — trigger age < quiesce, or build in flight. No
+//                         budget consumed. Still in flight at park+2h → the
+//                         caller treats it as terminal (pathological).
+//   superseded          — HEAD != commit. Terminal, no retry (a retry would
+//                         regress a newer publish).
+//
+// "Discriminating" reuses lib/publish-content.js — the verifier's own
+// collision-exemption logic. Lines already in the old tree are
+// non-discriminating and ignored.
+//
+// Usage:
+//   node classify-publish-absence.js --repo-path <path> --commit <sha>
+//       --base <sha> --slug <slug> --trigger-ts <ISO> --park-ts <ISO>
+//       [--spaces-root <dir>] [--task-id <uuid>]
+//       [--quiesce-mins <n>] [--in-flight-window-mins <n>]
+//
+//   --manifest-before is the workflow's pre-trigger manifest snapshot
+//   (JSON {"built_at":<ISO|null>,"content_sha256":<hex|null>}, design §1.9).
+//   The verified path requires the current manifest's content_sha256 to
+//   differ from the baseline (a new build identity, not a replayed
+//   manifest). When the baseline is unavailable the classifier falls back
+//   to the time-based advance check and notes it; the Step 4.5 verifier
+//   (lib/verify-publish.js) is the strict gate and fails closed without a
+//   baseline before stamping.
+//
+// Exit 0 with the decision JSON on stdout for every decision (a decision
+// is data, not a failure). Exit 2 on usage/validation. Nothing is printed
+// to stdout on failure.
+
+import { execFileSync } from "node:child_process";
+import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import {
+  EMPTY_TREE,
+  parseDiff,
+  parseFindings,
+  makeOldCounter,
+  discriminatingLines,
+} from "./publish-content.js";
+
+function arg(name, required = true, def = null) {
+  const i = process.argv.lastIndexOf(name); // last occurrence wins
+  if (i < 0 || i + 1 >= process.argv.length) {
+    if (required && def === null) fail("usage", `${name} is required.`);
+    return def;
+  }
+  return process.argv[i + 1];
+}
+function fail(code, message) {
+  process.stderr.write(JSON.stringify({ ok: false, error: code, message }) + "\n");
+  process.exit(2);
+}
+
+const repoPath = arg("--repo-path");
+const commit = arg("--commit");
+const base = arg("--base");
+const slug = arg("--slug");
+const triggerTs = arg("--trigger-ts");
+const parkTs = arg("--park-ts");
+const spacesRoot = arg("--spaces-root", false, join(homedir(), "workspace", "ts-spaces"));
+const taskId = arg("--task-id", false, "classify");
+const quiesceMins = parseInt(arg("--quiesce-mins", false, "30"), 10);
+const inFlightWindowMins = parseInt(arg("--in-flight-window-mins", false, "15"), 10);
+// Pre-trigger manifest baseline (design §1.9), JSON-encoded. Optional —
+// the classifier falls back to the time-based check when absent.
+// 2026-09-18, should-fix 1: distinguish absent (legacy, no baseline) from
+// malformed (supplied but invalid) — malformed is ambiguous, not absent.
+// A valid baseline requires a parseable built_at timestamp and a 64-hex
+// content_sha256.
+let manifestBefore = null;
+let manifestBeforeMalformed = false;
+const manifestBeforeRaw = arg("--manifest-before", false, null);
+if (manifestBeforeRaw) {
+  try {
+    const parsed = JSON.parse(manifestBeforeRaw);
+    const builtAt = parsed && typeof parsed.built_at === "string" ? parsed.built_at : null;
+    const sha = parsed && typeof parsed.content_sha256 === "string" ? parsed.content_sha256 : null;
+    const builtAtMs = builtAt ? Date.parse(builtAt) : NaN;
+    const shaOk = sha && /^[0-9a-f]{64}$/.test(sha);
+    if (parsed && typeof parsed === "object" && builtAtMs > 0 && shaOk) {
+      manifestBefore = { built_at: builtAt, content_sha256: sha };
+    } else {
+      // Supplied but invalid: fail closed as ambiguous, not absent.
+      manifestBeforeMalformed = true;
+    }
+  } catch {
+    // Supplied but unparsable: fail closed as ambiguous, not absent.
+    manifestBeforeMalformed = true;
+  }
+}
+
+if (!/^[0-9a-f]{40}$/.test(commit)) fail("usage", "commit must be a 40-char hex sha.");
+if (!/^[0-9a-f]{40}$/.test(base)) fail("usage", "base must be a 40-char hex sha.");
+if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(slug)) fail("usage", "slug is not a safe artifact slug.");
+const triggerMs = Date.parse(triggerTs);
+const parkMs = Date.parse(parkTs);
+if (!(triggerMs > 0)) fail("usage", "trigger-ts is not a valid timestamp.");
+if (!(parkMs > 0)) fail("usage", "park-ts is not a valid timestamp.");
+if (!(quiesceMins > 0)) fail("usage", "quiesce-mins must be positive.");
+if (!(inFlightWindowMins > 0)) fail("usage", "in-flight-window-mins must be positive.");
+
+function decide(decision, reasons, details = {}) {
+  process.stdout.write(JSON.stringify({ ok: true, decision, reasons, details }) + "\n");
+  process.exit(0);
+}
+
+// Resolve the space dir with realpath containment (same rule as
+// readback-disk.js — the slug must not escape the spaces root).
+function resolveSpaceDir() {
+  try {
+    const rootReal = realpathSync(spacesRoot);
+    const candReal = realpathSync(join(spacesRoot, slug));
+    if (candReal !== rootReal && !candReal.startsWith(rootReal + "/")) return null;
+    return statSync(candReal).isDirectory() ? candReal : null;
+  } catch {
+    return null;
+  }
+}
+
+// (d) No build in flight. Signals, both heuristic but conservative:
+//   - manifest built_at within the window: a build just landed, the
+//     deployment may still be propagating;
+//   - any file under .space-build with mtime within the window: the
+//     platform is actively writing build output.
+// A build running longer than the window without touching .space-build is
+// pathological; the caller escalates to terminal at park+2h.
+// (d) Build-in-flight detection: the manifest is the platform's build
+// record. A build is "in flight" for our purposes if the manifest state
+// changes during the content read (a build landed mid-read — the read may
+// be torn) or if the manifest's built_at is within the settle window (a
+// build just completed; the working copy may still be settling). Checked
+// twice bracketing the content read (design §1.4d); the double check
+// bounds the residual window to the local disk-read duration. Directory
+// mtimes are NOT used — they cannot distinguish a running build from a
+// recently completed one, and the manifest is the honest record.
+function manifestState(spaceDir) {
+  const m = readManifest(spaceDir);
+  if (!m) return null;
+  return { built_at: m.built_at, content_sha256: m.content_sha256 };
+}
+function buildInFlight(spaceDir, nowMs, beforeState) {
+  const afterState = manifestState(spaceDir);
+  // State changed during the read → a build landed mid-read.
+  if (beforeState && afterState &&
+      (beforeState.built_at !== afterState.built_at ||
+       beforeState.content_sha256 !== afterState.content_sha256)) {
+    return { inFlight: true, afterState, reason: `manifest changed during the content read (before built_at=${beforeState.built_at}, after built_at=${afterState.built_at}) — the read may be torn` };
+  }
+  // Manifest built very recently → a build just completed; let it settle.
+  // 2026-09-18, should-fix 2: enforce 0 <= age < settleMs. A future built_at
+  // (negative age) is pathological — clock skew or corruption — and must not
+  // defer forever. It is ambiguous, not in-flight.
+  const settleMs = inFlightWindowMins * 60 * 1000;
+  const builtAtMs = afterState && afterState.built_at ? Date.parse(afterState.built_at) : NaN;
+  if (Number.isFinite(builtAtMs)) {
+    const ageMs = nowMs - builtAtMs;
+    if (ageMs < 0) {
+      return { inFlight: false, afterState, pathological: true, reason: `manifest built_at ${afterState.built_at} is in the future (age ${ageMs}ms) — pathological, not in-flight` };
+    }
+    if (ageMs < settleMs) {
+      return { inFlight: true, afterState, reason: `manifest built_at ${afterState.built_at} is within the ${inFlightWindowMins}min settle window — a build just completed` };
+    }
+  }
+  return { inFlight: false, afterState };
+}
+
+function readManifest(spaceDir) {
+  if (!spaceDir) return null;
+  try {
+    const m = JSON.parse(readFileSync(join(spaceDir, ".space-build", "manifest.json"), "utf8"));
+    return {
+      built_at: typeof m.built_at === "string" ? m.built_at : null,
+      content_sha256: typeof m.content_sha256 === "string" ? m.content_sha256 : null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+const nowMs = Date.now();
+const spaceDir = resolveSpaceDir();
+
+// (should-fix 1) Malformed supplied baseline → ambiguous, not absent.
+// A supplied --manifest-before that fails validation is evidence corruption,
+// not a legacy absent baseline. Fail closed.
+if (manifestBeforeMalformed) {
+  decide("ambiguous",
+    [`supplied --manifest-before failed validation (must be JSON with a parseable built_at and a 64-hex content_sha256)`],
+    { manifest_before_malformed: true });
+}
+
+// (e) Decision time ≥ park + quiesce. Too young → deferred, no budget
+// consumed, no timer advanced.
+if (nowMs < parkMs + quiesceMins * 60 * 1000) {
+  decide("deferred",
+    [`trigger age below quiesce: park ${parkTs}, quiesce ${quiesceMins}min`],
+    { park_ts: parkTs, quiesce_mins: quiesceMins });
+}
+
+// (d) First in-flight check, before the content read. Captures the
+// manifest state; the second check compares against it.
+const manifestBeforeRead = manifestState(spaceDir);
+let flight = buildInFlight(spaceDir, nowMs, null);
+// Pathological future timestamp → ambiguous, not deferred (should-fix 2).
+if (flight.pathological) {
+  decide("ambiguous",
+    [`manifest built_at is in the future (pathological): ${flight.reason}`],
+    { pathological_future_built_at: true, in_flight_reason: flight.reason });
+}
+if (flight.inFlight) {
+  if (nowMs > parkMs + 2 * 60 * 60 * 1000) {
+    decide("ambiguous",
+      [`build still in flight at park+2h (pathological): ${flight.reason}`],
+      { in_flight_reason: flight.reason });
+  }
+  decide("deferred", [`build in flight (pre-read check): ${flight.reason}`],
+    { in_flight_reason: flight.reason });
+}
+
+// The content read: the deterministic sensor on the platform's working copy.
+const sensorPath = join(new URL(".", import.meta.url).pathname, "readback-disk.js");
+let findingsText;
+try {
+  findingsText = execFileSync("node", [
+    sensorPath,
+    "--repo-path", repoPath,
+    "--commit", commit,
+    "--base", base,
+    "--slug", slug,
+    "--task-id", taskId,
+    "--spaces-root", spacesRoot,
+  ], { encoding: "utf8", maxBuffer: 8 * 1024 * 1024 });
+} catch (e) {
+  decide("ambiguous",
+    [`sensor unreadable: ${(e.stderr || e.message || "").toString().slice(0, 200)}`],
+    { sensor_failed: true });
+}
+
+// (d) Second in-flight check, bracketing the content read. Compares the
+// manifest state against the pre-read baseline; a change means a build
+// landed mid-read (the read may be torn). The double check bounds the
+// residual window to the local disk-read duration.
+flight = buildInFlight(spaceDir, Date.now(), manifestBeforeRead);
+// Pathological future timestamp → ambiguous, not deferred (should-fix 2).
+if (flight.pathological) {
+  decide("ambiguous",
+    [`manifest built_at is in the future (pathological, post-read): ${flight.reason}`],
+    { pathological_future_built_at: true, in_flight_reason: flight.reason });
+}
+if (flight.inFlight) {
+  decide("deferred", [`build in flight (post-read check): ${flight.reason}`],
+    { in_flight_reason: flight.reason });
+}
+
+// 2026-09-18, should-fix 3: use the manifest state already checked by the
+// post-read in-flight check (flight.afterState) — do NOT re-read the manifest
+// here. A third read reopens the TOCTOU window the double-check just closed.
+const manifest = flight.afterState;
+const manifestBuiltAtMs = manifest && manifest.built_at ? Date.parse(manifest.built_at) : NaN;
+const manifestAdvanced = Number.isFinite(manifestBuiltAtMs) && manifestBuiltAtMs > triggerMs;
+
+// The expected change, from git (never from anyone's report).
+if (base !== EMPTY_TREE) {
+  try {
+    execFileSync("git", ["-C", repoPath, "merge-base", "--is-ancestor", base, commit], { stdio: "ignore" });
+  } catch {
+    decide("ambiguous", [`base ${base} is not an ancestor of commit ${commit}`], {});
+  }
+}
+let diff;
+try {
+  diff = execFileSync("git", ["-C", repoPath, "diff", base, commit, "--"], {
+    encoding: "utf8", maxBuffer: 4 * 1024 * 1024,
+  });
+} catch (e) {
+  decide("ambiguous", [`git diff failed: ${e.message.slice(0, 200)}`], {});
+}
+if (!diff.trim()) {
+  decide("ambiguous", ["empty diff for commit — nothing to judge"], {});
+}
+const diffMap = parseDiff(diff);
+const oldCount = makeOldCounter(repoPath, base);
+const disc = discriminatingLines(diffMap, oldCount);
+
+// Files the line-based judge cannot certify at all → ambiguous, never a
+// retry on zero signal.
+for (const [path, d] of disc) {
+  if (d.unjudgeable) {
+    decide("ambiguous",
+      [`unverifiable-content ${path}: ${d.unjudgeable} — the diff carries no discriminating lines for this file`],
+      { file: path, unjudgeable: d.unjudgeable });
+  }
+}
+
+// (f) Supersession re-check: a retry against a moved HEAD would regress a
+// newer publish.
+let head;
+try {
+  head = execFileSync("git", ["-C", repoPath, "rev-parse", "HEAD"], { encoding: "utf8" }).trim();
+} catch (e) {
+  decide("ambiguous", [`git rev-parse HEAD failed: ${e.message.slice(0, 200)}`], {});
+}
+if (head !== commit) {
+  decide("superseded",
+    [`HEAD is ${head}, not ${commit} — a newer publish supersedes this one; no retry`],
+    { head, commit });
+}
+
+// The findings must cover every discriminating line, or the read is not a
+// read of this diff.
+const { findings, malformed } = parseFindings(findingsText);
+if (malformed) {
+  decide("ambiguous", [`unreadable findings: ${malformed}`], {});
+}
+let totalDisc = 0;
+let addedPresent = 0, addedAbsent = 0, removedPresent = 0, removedAbsent = 0;
+for (const [path, d] of disc) {
+  const found = findings.get(path);
+  if (!found) {
+    decide("ambiguous", [`no findings for changed file ${path}`], { file: path });
+  }
+  for (const line of d.addedDisc) {
+    totalDisc++;
+    const v = found.added.get(line);
+    if (v === undefined) decide("ambiguous", [`no ADDED finding for line in ${path}`], { file: path });
+    if (v === "PRESENT") addedPresent++; else addedAbsent++;
+  }
+  for (const line of d.removedDisc) {
+    totalDisc++;
+    const v = found.removed.get(line);
+    if (v === undefined) decide("ambiguous", [`no REMOVED finding for line in ${path}`], { file: path });
+    if (v === "PRESENT") removedPresent++; else removedAbsent++;
+  }
+}
+if (totalDisc === 0) {
+  decide("ambiguous",
+    ["zero discriminating lines across the diff — no signal to judge; refusing to decide on vacuous truth"],
+    {});
+}
+
+const details = {
+  manifest_built_at: manifest ? manifest.built_at : null,
+  manifest_advanced: manifestAdvanced,
+  head,
+  discriminating_added: addedPresent + addedAbsent,
+  discriminating_removed: removedPresent + removedAbsent,
+  added_present: addedPresent,
+  added_absent: addedAbsent,
+  removed_present: removedPresent,
+  removed_absent: removedAbsent,
+};
+
+// Manifest advanced past the trigger: a build ran for this attempt.
+if (manifestAdvanced) {
+  // Verified ⟺ the source shows the full post-edit state. A side with no
+  // discriminating lines is vacuously satisfied; totalDisc > 0 (checked
+  // above) guarantees at least one side carries signal.
+  const addedOk = addedPresent + addedAbsent === 0 || (addedPresent > 0 && addedAbsent === 0);
+  const removedOk = removedPresent + removedAbsent === 0 || (removedAbsent > 0 && removedPresent === 0);
+  if (addedOk && removedOk) {
+    // Design §1.9: the manifest must be a NEW build identity, not a
+    // replayed manifest with a bumped built_at. When the pre-trigger
+    // baseline is available, require the content_sha256 to differ; when
+    // unavailable, fall back to the time-based advance (noted) — the Step
+    // 4.5 verifier is the strict gate and fails closed without a baseline
+    // before stamping.
+    const beforeHash = manifestBefore ? manifestBefore.content_sha256 : null;
+    const currentHash = manifest ? manifest.content_sha256 : null;
+    if (manifestBefore && beforeHash && currentHash) {
+      if (beforeHash === currentHash) {
+        decide("ambiguous",
+          [`manifest built_at advanced past trigger but content_sha256 is unchanged from the pre-trigger baseline — a replayed manifest, not a new build; refusing to verify`],
+          { ...details, manifest_before: manifestBefore });
+      }
+      decide("verified",
+        [`manifest built_at ${manifest.built_at} advanced past trigger ${triggerTs} with a new content_sha256 (differs from pre-trigger baseline); content matches the diff`],
+        { ...details, manifest_before: manifestBefore });
+    }
+    decide("verified",
+      [`manifest built_at ${manifest.built_at} advanced past trigger ${triggerTs}; content matches the diff (no pre-trigger baseline — freshness by time only; the Step 4.5 verifier fails closed without a baseline)`],
+      { ...details, manifest_before: null, baseline_absent: true });
+  }
+  // A build ran but the content does not match: not ours to claim.
+  decide("ambiguous",
+    [`manifest advanced past trigger but content mismatched (added PRESENT ${addedPresent}/${addedPresent + addedAbsent}, removed ABSENT ${removedAbsent}/${removedPresent + removedAbsent}) — a build ran that is not this diff`],
+    details);
+}
+
+// Manifest stale: no build for this attempt. Judge the source state.
+const addedDropped = addedPresent + addedAbsent === 0 || (addedAbsent > 0 && addedPresent === 0);
+const removedDropped = removedPresent + removedAbsent === 0 || (removedPresent > 0 && removedAbsent === 0);
+const addedApplied = addedPresent + addedAbsent === 0 || (addedPresent > 0 && addedAbsent === 0);
+const removedApplied = removedPresent + removedAbsent === 0 || (removedAbsent > 0 && removedPresent === 0);
+if (addedDropped && removedDropped) {
+  decide("provably-dropped",
+    [
+      "(a) every discriminating added line ABSENT",
+      "(b) every discriminating removed line PRESENT",
+      `(c) manifest built_at ${manifest ? manifest.built_at : "missing"} NOT advanced past trigger ${triggerTs}`,
+      "(d) no build in flight (checked twice, bracketing the read)",
+      `(e) decision time past park+${quiesceMins}min quiesce`,
+      "(f) HEAD == commit",
+    ],
+    details);
+}
+if (addedApplied && removedApplied) {
+  // J1's shape: the platform started something (the phantom) but no build
+  // completed — "platform build-emission failure." No retry: re-applying a
+  // possibly mid-apply diff is the 2026-09-12 hazard in a new coat.
+  decide("applied-not-built",
+    [
+      `source shows the full post-edit state but manifest stale (built_at ${manifest ? manifest.built_at : "missing"}) — platform build-emission failure; no retry`,
+    ],
+    details);
+}
+decide("ambiguous",
+  [`partial-apply or indeterminate (added PRESENT ${addedPresent}/${addedPresent + addedAbsent}, removed PRESENT ${removedPresent}/${removedPresent + removedAbsent}) with a stale manifest`],
+  details);