muse-crew 0.14.3 → 0.14.4

package/lib/retry-publish.js

@@ -31,7 +31,7 @@
 //
 // Exit codes: 0 = success, 1 = terminal stop (no retry), 2 = usage error.
 
-import { readFileSync, writeFileSync, appendFileSync, existsSync } from "fs";
+import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync, unlinkSync } from "fs";
 import { join } from "path";
 import { execFileSync } from "child_process";
 import { randomUUID as uuid } from "crypto";
@@ -50,6 +50,19 @@ function fail(code, msg, exitCode = 1) {
   process.exit(exitCode);
 }
 
+// --help: handled before any required-arg parsing so
+// `node retry-publish.js --help` always exits 0 (entry-gate contract).
+if (args.includes("--help")) {
+  console.log(
+    "usage: node retry-publish.js --crew-home <path> --task-id <uuid> --phase <prepare|complete>\n" +
+    "  prepare:  acquire the merge lock, re-check HEAD, re-classify, journal intent, emit the diff\n" +
+    "  complete: --edit-outcome <accepted|refused> [--refusal-text <text>] — write the outcome,\n" +
+    "            append the ledger entry, mirror verification, and release the lock\n" +
+    "exit 0 = success, 1 = terminal stop, 2 = usage error"
+  );
+  process.exit(0);
+}
+
 const crewHome = arg("--crew-home");
 const taskId = arg("--task-id");
 const phase = arg("--phase");
@@ -59,6 +72,18 @@ if (!["prepare", "complete"].includes(phase)) {
   process.exit(2);
 }
 
+// Retry protocol: phase-1 state is a persistent-disk pin
+// ($CREW_HOME/.pins/ — never /tmp: tmpfs is wiped on cell reboot, and the
+// lock release depends on phase 2 reading this state).
+function pinsDir() {
+  const dir = join(crewHome, ".pins");
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+function retryStatePath() {
+  return join(pinsDir(), `retry-publish-${taskId}.json`);
+}
+
 // --- Shared helpers ---------------------------------------------------------
 
 function nowISO() { return new Date().toISOString(); }
@@ -180,12 +205,17 @@ if (phase === "prepare") {
     }
 
     const classifierPath = join(crewHome, "lib", "classify-publish-absence.js");
-    // Find the trigger entry for the manifest baseline: the OLDEST matching
-    // "submitted" (the trigger issuance), matching verify-publish.js's anchor.
+    // Find the trigger entry for the manifest baseline: the OLDEST submitted
+    // entry by ts (D1, 2026-09-19; entry_kind cut 2026-09-20 — the retired
+    // kind-preference could never change the bound anchor) — it binds
+    // issued_at (falling back to its ts when the capture was unobserved),
+    // the same anchor verify-publish.js and findTriggerEntry use.
     // agent_id is null on the issuance entry (no receipt observed at trigger
     // time) — the baseline comes from manifest_before, never agent_id.
-    const trigger = entries.find((e) =>
+    const submitted = entries.filter((e) =>
       e.outcome === "submitted" && e.commit === commit && (attempt == null || e.attempt === attempt));
+    submitted.sort((a, b) => (a.ts || "").localeCompare(b.ts || ""));
+    const trigger = submitted[0] || null;
     const manifestBefore = trigger && trigger.manifest_before ? JSON.stringify(trigger.manifest_before) : null;
 
     // Find the park note timestamp for quiesce calculation.
@@ -204,7 +234,7 @@ if (phase === "prepare") {
       "--slug", slug,
       "--commit", commit,
       "--base", base,
-      "--trigger-ts", trigger ? trigger.ts : parkNote.timestamp,
+      "--trigger-ts", trigger ? (trigger.issued_at || trigger.ts) : parkNote.timestamp,
       "--park-ts", parkNote.timestamp,
       "--repo-path", repoPath,
     ];
@@ -269,7 +299,7 @@ if (phase === "prepare") {
     // with the diff, then calls phase 2 (complete) to finish.
     // Persist the phase-1 state for phase 2 (crash recovery reads the notes,
     // but phase 2 needs the exact commit/attempt/baseline/ledger path).
-    const statePath = `/tmp/retry-publish-${taskId}.json`;
+    const statePath = retryStatePath();
     writeFileSync(statePath, JSON.stringify({
       task_id: taskId, commit, attempt, slug, repoPath,
       project_id: project.id, ledger_path: ledgerPath,
@@ -304,7 +334,7 @@ if (phase === "complete") {
   }
   const refusalText = arg("--refusal-text", false, "");
 
-  const statePath = `/tmp/retry-publish-${taskId}.json`;
+  const statePath = retryStatePath();
   if (!existsSync(statePath)) {
     fail("no-prepare-state", `no phase-1 state at ${statePath} — the prepare phase did not complete or the state was cleaned`);
   }
@@ -325,49 +355,51 @@ if (phase === "complete") {
       writePublishNote(db, taskId,
         `publish: retry-refused ${commit} — the platform refused the re-issued edit (${refusalText.split("\n")[0].slice(0, 200)}); not retrying again.`);
       process.stdout.write(JSON.stringify({ ok: true, phase: "complete", outcome: "refused", commit }) + "\n");
-      return;
-    }
-
-    // The child ended after the edit call with no explicit refusal —
-    // fire-and-forget, same shape as the first attempt.
-    writePublishNote(db, taskId,
-      `publish: retry-issued ${commit} — the dropped edit was re-issued once; no explicit refusal was observed.`);
-
-    // Mirror verification with a settle window.
-    const notBefore = new Date(Date.now() + 20 * 60 * 1000).toISOString();
-    const retryAttempt = attempt ? `${attempt}-retry1` : "retry1";
-    writePublishNote(db, taskId,
-      `publish: verification-requested ${commit} attempt=${retryAttempt} not-before=${notBefore} — unknown-recovery retried the dropped edit once; content verification is the arbiter. Waiting on the manual read-back in docs/publish-verification.md.`);
+    } else {
+      // The child ended after the edit call with no explicit refusal —
+      // fire-and-forget, same shape as the first attempt.
+      writePublishNote(db, taskId,
+        `publish: retry-issued ${commit} — the dropped edit was re-issued once; no explicit refusal was observed.`);
+
+      // Mirror verification with a settle window.
+      const settleMs = Number(process.env.CREW_RETRY_SETTLE_MS) > 0
+        ? Number(process.env.CREW_RETRY_SETTLE_MS)
+        : 20 * 60 * 1000;
+      const notBefore = new Date(Date.now() + settleMs).toISOString();
+      const retryAttempt = attempt ? `${attempt}-retry1` : "retry1";
+      writePublishNote(db, taskId,
+        `publish: verification-requested ${commit} attempt=${retryAttempt} not-before=${notBefore} — unknown-recovery retried the dropped edit once; content verification is the arbiter. Waiting on the manual read-back in docs/publish-verification.md.`);
+
+      // Append the -retry1 ledger entry with the pre-retry baseline (required).
+      const ledgerEntry = {
+        ts: nowISO(),
+        task_id: taskId,
+        workflow: "unknown-recovery",
+        slug,
+        commit,
+        attempt: retryAttempt,
+        agent_id: null,
+        applied_report: null,
+        outcome: "submitted",
+        manifest_before: retryBaseline,
+        detail: "retry trigger re-issued after provably-dropped classification",
+      };
+      try {
+        appendFileSync(ledgerPath, JSON.stringify(ledgerEntry) + "\n");
+      } catch (e) {
+        // Best-effort: the note journal is the source of truth, not the ledger.
+        console.error(`ledger append failed (non-fatal): ${e.message}`);
+      }
 
-    // Append the -retry1 ledger entry with the pre-retry baseline (required).
-    const ledgerEntry = {
-      ts: nowISO(),
-      task_id: taskId,
-      workflow: "unknown-recovery",
-      slug,
-      commit,
-      attempt: retryAttempt,
-      agent_id: null,
-      applied_report: null,
-      outcome: "submitted",
-      manifest_before: retryBaseline,
-      detail: "retry trigger re-issued after provably-dropped classification",
-    };
-    try {
-      appendFileSync(ledgerPath, JSON.stringify(ledgerEntry) + "\n");
-    } catch (e) {
-      // Best-effort: the note journal is the source of truth, not the ledger.
-      console.error(`ledger append failed (non-fatal): ${e.message}`);
+      process.stdout.write(JSON.stringify({
+        ok: true, phase: "complete", outcome: "issued",
+        commit, attempt: retryAttempt, not_before: notBefore,
+      }) + "\n");
     }
-
-    process.stdout.write(JSON.stringify({
-      ok: true, phase: "complete", outcome: "issued",
-      commit, attempt: retryAttempt, not_before: notBefore,
-    }) + "\n");
   } finally {
     releaseLock();
     // Clean up the phase-1 state file (best-effort).
-    try { (await import("fs")).unlinkSync(statePath); } catch {}
+    try { unlinkSync(statePath); } catch {}
   }
   process.exit(0);
 }

package/lib/sample-project.js

@@ -15,9 +15,11 @@
 //   --name:    directory/project name (e.g. "flashcards")
 // Prints JSON: { path, committed, commitSha }
 
-const fs = require("fs");
-const path = require("path");
-const { execFileSync } = require("child_process");
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 
 function run(cmd, args, cwd) {
   return execFileSync(cmd, args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
@@ -60,10 +62,24 @@ function setupSampleProject(tarballPath, destParent, name) {
   return { path: destDir, committed: true, commitSha: sha };
 }
 
-module.exports = { setupSampleProject };
+export { setupSampleProject };
 
-if (require.main === module) {
+const USAGE = "Usage: node lib/sample-project.js --tarball <path> --dest <dir> --name <project-name>";
+
+const isMainModule = (() => {
+  try {
+    return !!process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+})();
+
+if (isMainModule) {
   const argv = process.argv.slice(2);
+  if (argv.includes("--help")) {
+    console.log(USAGE);
+    process.exit(0);
+  }
   const get = (flag) => {
     const i = argv.indexOf(flag);
     return i >= 0 ? argv[i + 1] : null;
@@ -72,7 +88,7 @@ if (require.main === module) {
   const dest = get("--dest");
   const name = get("--name");
   if (!tarball || !dest || !name) {
-    console.error("Usage: node lib/sample-project.js --tarball <path> --dest <dir> --name <project-name>");
+    console.error(USAGE);
     process.exit(2);
   }
   try {

package/lib/scaffold-crew.js

@@ -18,8 +18,8 @@
 // source (fail-closed: never stamp an empty 0/0 receipt). Exit 2 on usage
 // errors. No wall-clock reads, no randomness.
 
-const fs = require("node:fs");
-const path = require("node:path");
+import fs from "node:fs";
+import path from "node:path";
 
 function usageError(msg) {
   process.stderr.write("scaffold-crew.js usage: --repo <crewRepoPath> --orch-dir <orchDir>\n" + msg + "\n");
@@ -27,6 +27,15 @@ function usageError(msg) {
 }
 
 const args = process.argv.slice(2);
+// --help: before required-arg parsing (shebang⇔CLI contract).
+if (args.includes("--help")) {
+  console.log(
+    "usage: node scaffold-crew.js --repo <crewRepoPath> --orch-dir <orchDir>\n" +
+    "copies the fixed scaffold file sets (no-clobber), verifies every file on disk,\n" +
+    "writes <orchDir>/.scaffold-receipt.json and prints {created, skipped}"
+  );
+  process.exit(0);
+}
 let repo = null;
 let orchDir = null;
 for (let i = 0; i < args.length; i++) {

package/lib/see-act.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 // see-act.js — single-step browser driver for experiential QA.
 //
 // The agent closes the OODA loop: run one step, READ the screenshot or aria
@@ -30,12 +31,14 @@
 // Determinism: no wall-clock reads, no randomness. Archive names are sequential.
 //
 // Dependencies: playwright-core (resolved below), a Chromium binary.
-"use strict";
 
-const { createServer, request: httpRequest } = require("node:http");
-const { request: httpsRequest } = require("node:https");
-const { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } = require("node:fs");
-const { join, dirname, resolve } = require("node:path");
+import { createServer, request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { createRequire } from "node:module";
+
+const cjsRequire = createRequire(import.meta.url);
 
 const VIEWPORTS = {
   desktop: { width: 1440, height: 900 },
@@ -73,15 +76,15 @@ function loadPlaywright() {
   // playwright-core is a declared dependency (package.json), so a normal
   // npm install resolves it from the package's own node_modules.
   try {
-    return require("playwright-core");
+    return cjsRequire("playwright-core");
   } catch (e) { /* fall through */ }
   const envDir = (process.env.PLAYWRIGHT_CORE_DIR || "").trim();
   if (envDir) {
     try {
-      return require(join(envDir, "playwright-core"));
+      return cjsRequire(join(envDir, "playwright-core"));
     } catch (e) { /* fall through */ }
     try {
-      return require(envDir);
+      return cjsRequire(envDir);
     } catch (e) { /* fall through */ }
   }
   fail(3, {
@@ -188,6 +191,12 @@ function startProxy() {
 }
 
 async function main() {
+  // --help: before required-arg parsing (shebang⇔CLI contract).
+  if (process.argv.slice(2).includes("--help")) {
+    console.log("usage: node see-act.js --url <url> [--viewport desktop|mobile] [--timeout-ms <n>] <action> [args]\n" +
+      "actions: aria | shot --out <png> [--full] | click --out <png> --selector <css> | scroll --out <png> --y <px|bottom> | type --out <png> --selector <css> --text <text>");
+    process.exit(0);
+  }
   const args = parseArgs(process.argv.slice(2));
   if (!args.url) {
     fail(2, { ok: false, error: "usage: node see-act.js --url <url> [--viewport desktop|mobile] <aria|shot|click|scroll|type> [args]" });

package/lib/serve-artifact.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 // serve-artifact.js — serve a built TS space locally for experiential QA.
 //
 // Serves <space-dir>/client/dist statically and dispatches POST */actions
@@ -20,13 +21,12 @@
 //   what the artifact's server needs before starting this.
 //
 // Determinism: no wall-clock reads, no randomness.
-"use strict";
 
-const { createServer } = require("node:http");
-const { join, normalize, dirname, sep } = require("node:path");
-const { existsSync } = require("node:fs");
-const { readFile, writeFile, mkdir, mkdtemp } = require("node:fs/promises");
-const { tmpdir } = require("node:os");
+import { createServer } from "node:http";
+import { join, normalize, dirname, sep } from "node:path";
+import { existsSync } from "node:fs";
+import { readFile, writeFile, mkdir, mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
 
 function parseArgs(argv) {
   const out = { spaceDir: null, port: 0, tag: null };
@@ -57,6 +57,12 @@ const CONTENT_TYPES = {
 };
 
 async function main() {
+  // --help: before required-arg parsing (shebang⇔CLI contract).
+  if (process.argv.slice(2).includes("--help")) {
+    console.log("usage: node serve-artifact.js --space-dir <path> [--port <n>]\n" +
+      "serves <space-dir>/client/dist statically, dispatches POST */actions to the built server actions");
+    process.exit(0);
+  }
   const args = parseArgs(process.argv.slice(2));
   if (!args.spaceDir) {
     process.stderr.write("serve-artifact.js: --space-dir <path> is required\n");

package/lib/setup-project-repo.js

@@ -30,14 +30,25 @@
 // Prints JSON: { orchestration: {...}, gitignore: {...} | { declined: true }, commit: {...} }
 // Exits non-zero on any failure (fail closed, loud).
 
-const fs = require("fs");
-const path = require("path");
-const { scaffoldRepoOrchestration } = require("./repo-orchestration");
-const { ensureGitignoreEntries, describeGitignoreChange } = require("./gitignore");
-const { commitScaffold, isPathDirty } = require("./commit-scaffold");
+import fs from "node:fs";
+import path from "node:path";
+import { scaffoldRepoOrchestration } from "./repo-orchestration.js";
+import { ensureGitignoreEntries, describeGitignoreChange } from "./gitignore.js";
+import { commitScaffold, isPathDirty } from "./commit-scaffold.js";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 
 function main() {
   const argv = process.argv.slice(2);
+  // --help: before required-arg parsing (shebang⇔CLI contract).
+  if (argv.includes("--help")) {
+    console.log(
+      "usage: node setup-project-repo.js --repo <path> --crew-repo <path> [--consent]\n" +
+      "--consent: user approved the .gitignore change (from the setup conversation)\n" +
+      "prints JSON: { orchestration, gitignore, commit }"
+    );
+    process.exit(0);
+  }
   const get = (flag) => {
     const i = argv.indexOf(flag);
     return i >= 0 ? argv[i + 1] : null;
@@ -91,6 +102,14 @@ function main() {
   }
 }
 
-if (require.main === module) main();
+const isMainModule = (() => {
+  try {
+    return !!process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+})();
+
+if (isMainModule) main();
 
-module.exports = { main };
+export { main };

package/lib/update-watch.js

@@ -22,9 +22,11 @@
 //     every path except a missing --crew-home (exit 2).
 "use strict";
 
-const fs = require("fs");
-const path = require("path");
-const { execFileSync } = require("child_process");
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 
 const STATE_FILE = ".update-watch.json";
 const LOG_FILE = "update-watch.log";
@@ -653,6 +655,11 @@ function buildRealDeps(crewHome) {
 
 function main() {
   const args = process.argv.slice(2);
+  // --help: before required-arg parsing (entry-gate contract).
+  if (args.includes("--help")) {
+    console.log(USAGE);
+    process.exit(0);
+  }
   let crewHome = null;
   let enrollSha = null;
   let enrollForce = false;
@@ -693,19 +700,29 @@ function main() {
   );
 }
 
-module.exports = {
-  parseSemver: parseSemver,
-  compareSemver: compareSemver,
-  channelAllows: channelAllows,
-  crewDecision: crewDecision,
-  dashboardDecision: dashboardDecision,
-  crewVersionOrdering: crewVersionOrdering,
-  fileCrewUpgrade: fileCrewUpgrade,
-  enrollDashboardBase: enrollDashboardBase,
-  readState: readState,
-  writeState: writeState,
-  appendLog: appendLog,
-  run: run
+export {
+  parseSemver,
+  compareSemver,
+  channelAllows,
+  crewDecision,
+  dashboardDecision,
+  crewVersionOrdering,
+  fileCrewUpgrade,
+  enrollDashboardBase,
+  readState,
+  writeState,
+  appendLog,
+  run
 };
 
-if (require.main === module) main();
+const USAGE = "usage: node update-watch.js --crew-home <path> [--record-dashboard-sha <sha> [--force]]";
+
+const isMainModule = (() => {
+  try {
+    return !!process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+})();
+
+if (isMainModule) main();

package/lib/ux-doctrine.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 // ux-doctrine.js — UX-surface doctrine page resolution.
 //
 // One canonical doctrine page per environment_type value: the crew reads
@@ -11,10 +12,16 @@
 // against this file, so the two can never silently diverge.
 //
 // Pure and deterministic: no clock, no randomness, no I/O.
-"use strict";
+//
+// Module shape (blocker 21): this file is an import-safe shared module —
+// it has NO shebang, so the entry gate bare-loads it (`node ux-doctrine.js`
+// exits 0). The CLI below runs only when the file itself is the process
+// entrypoint.
 
-const { existsSync } = require("node:fs");
-const { join } = require("node:path");
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 
 // THE MAP. environment_type value -> doctrine page filename, relative to
 // the release docs dir ($CREW_HOME/current/docs/). null is unclassified —
@@ -44,12 +51,30 @@ function doctrinePageExists(crewHome, environmentType) {
   return p ? existsSync(p) : false;
 }
 
-module.exports = { DOCTRINE_PAGES, doctrinePage, doctrinePath, doctrinePageExists };
+export { DOCTRINE_PAGES, doctrinePage, doctrinePath, doctrinePageExists };
+
+// realpath: production spawns through $CREW_HOME/current/lib (a symlink),
+// so argv[1] must be resolved before comparison with import.meta.url.
+const isMainModule = (() => {
+  try {
+    return !!process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+})();
 
-if (require.main === module) {
+const USAGE = "usage: node ux-doctrine.js --page <environment_type|null> | --path <crewHome> <environment_type|null>";
+
+if (isMainModule) {
   // CLI: node ux-doctrine.js --page <environment_type>
   //      node ux-doctrine.js --path <crewHome> <environment_type>
   const args = process.argv.slice(2);
+  // Import-safe module contract: a bare invocation (no args) is a load
+  // check, not a usage error — it exits 0. --help always exits 0.
+  if (args.length === 0 || args.includes("--help")) {
+    console.log(USAGE);
+    process.exit(0);
+  }
   if (args[0] === "--page" && args.length === 2) {
     const page = doctrinePage(args[1] === "null" ? null : args[1]);
     console.log(page === null ? "null" : page);
@@ -57,7 +82,7 @@ if (require.main === module) {
     const p = doctrinePath(args[1], args[2] === "null" ? null : args[2]);
     console.log(p === null ? "null" : p);
   } else {
-    console.error("usage: node ux-doctrine.js --page <environment_type|null> | --path <crewHome> <environment_type|null>");
+    console.error(USAGE);
     process.exit(2);
   }
 }

package/lib/verify-publish.js

@@ -51,6 +51,19 @@ import {
   makeOldCounter,
   discriminatingLines,
 } from "./publish-content.js";
+// Terminal-note vocabulary (D7, 2026-09-19): the writer-side guard.
+// terminal() asserts its emitted verb is a registry member before writing,
+// so no future terminal verb ships unrecognized by the scans.
+import { matchTerminalPublishNote } from "./publish-note-vocabulary.js";
+
+// --help: before required-arg parsing (shebang⇔CLI contract).
+if (process.argv.slice(2).includes("--help")) {
+  console.log(
+    "usage: node verify-publish.js --repo-path <path> --commit <sha> --base <sha> --task-id <uuid> --slug <artifact-slug> --project-id <id> [--spaces-root <dir>]\n" +
+    "the mechanical publish verification JUDGE: certifies read-back findings against git diff, checks manifest freshness, stamps provenance"
+  );
+  process.exit(0);
+}
 
 function arg(name, required = true) {
   const i = process.argv.indexOf(name);
@@ -89,10 +102,25 @@ function api(command, json) {
   });
   return JSON.parse(out);
 }
+// The terminal verdict this writer emits. A single const (not an inline
+// literal) so the emitted verb and the asserted verb can never drift apart.
+const TERMINAL_VERB = "publish: verification-failed";
 function terminal(reason, detail) {
   // Always lands a terminal parent verdict, then exits 1 (failed) — the
   // task stays parked for human attention. Only the verified path exits 0.
-  const msg = `publish: verification-failed ${commit} ${reason}${detail ? ` — ${detail}` : ""} (read-back ${inspectionId})`;
+  // Writer-side registry guard (D7): the verb is in the terminal-note
+  // registry before the note is written — a writer can never introduce a
+  // terminal verb the scans don't recognize.
+  if (!matchTerminalPublishNote(TERMINAL_VERB)) {
+    // Registry and writer disagree — fail loud, never emit an unrecognized
+    // terminal note.
+    process.stderr.write(JSON.stringify({
+      ok: false, verdict: "vocabulary-mismatch",
+      message: `terminal verb '${TERMINAL_VERB}' is not in the terminal-note registry`,
+    }) + "\n");
+    process.exit(2);
+  }
+  const msg = `${TERMINAL_VERB} ${commit} ${reason}${detail ? ` — ${detail}` : ""} (read-back ${inspectionId})`;
   api("log-event", { task_id: taskId, type: "note", message: msg.slice(0, 1000) });
   process.stderr.write(JSON.stringify({ ok: false, verdict: reason, message: msg }) + "\n");
   process.exit(1);
@@ -301,6 +329,14 @@ if (head !== commit) {
 // submitted entry (the trigger issuance; a receipt-bearing second "submitted"
 // may follow it — the oldest binds the trigger instant, the latest carries
 // the observed agent_id).
+// D1 (2026-09-19; entry_kind cut 2026-09-20): the trigger instant is the
+// ISSUANCE instant, not the ledger-write instant — a slow ledger write must
+// not make a fresh build look stale (room #23 J1). The anchor is the OLDEST
+// submitted entry by ts and the bound instant is its issued_at (falling back
+// to its ts when the capture was unobserved). One anchor, one field — the
+// retired entry_kind preference filter could never change the bound anchor
+// (issuance and receipt entries carried the same captured issued_at), so the
+// oldest-by-ts selection is the whole mechanism.
 let triggerTs = null;
 let manifestBefore = null;
 try {
@@ -316,7 +352,7 @@ try {
   if (candidates.length > 0) {
     candidates.sort((a, b) => (a.ts || "").localeCompare(b.ts || ""));
     const e = candidates[0];
-    triggerTs = e.ts || null;
+    triggerTs = e.issued_at || e.ts || null;
     if (e.manifest_before && typeof e.manifest_before === "object") manifestBefore = e.manifest_before;
   }
 } catch (e) {

package/lib/write-ooda-verdict.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 // write-ooda-verdict.js — deterministic writer for the OODA report's terminal state.
 //
 // After the see-act loop, the QA/repro agent records its verdict as
@@ -34,10 +35,9 @@
 //
 // Exit 0 on success, 2 on bad input. Determinism: no wall-clock reads, no
 // randomness; ts comes only from --ts and is omitted when not passed.
-"use strict";
 
-const { writeFileSync, appendFileSync, mkdirSync, readFileSync, existsSync } = require("node:fs");
-const { join, resolve } = require("node:path");
+import { writeFileSync, appendFileSync, mkdirSync, readFileSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
 
 const VERDICTS = { PASS: 1, FAIL: 1, NOT_POSSIBLE: 1 };
 
@@ -85,6 +85,15 @@ function ledgerSeq(ledgerPath) {
 }
 
 function main() {
+  // --help: before required-arg parsing (shebang⇔CLI contract).
+  if (process.argv.slice(2).includes("--help")) {
+    console.log(
+      "usage: node write-ooda-verdict.js --dir <phase-dir> --attempt <id> --verdict <PASS|FAIL|NOT_POSSIBLE>\n" +
+      "       [--summary <text>] [--expected <text>] [--actual <text>] [--missing <json-array>] [--reason <text>] [--ts <iso>]\n" +
+      "--reason is REQUIRED and must be non-empty for FAIL and NOT_POSSIBLE"
+    );
+    process.exit(0);
+  }
   const args = parseArgs(process.argv.slice(2));
   if (!args.dir) fail("missing --dir <phase-dir>");
   if (args.attempt === undefined || String(args.attempt).trim() === "") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "muse-crew",
-  "version": "0.14.3",
+  "version": "0.14.4",
   "description": "Opinionated orchestration for Muse — workflows, identities, and tooling for autonomous software development.",
   "license": "UNLICENSED",
   "private": false,