muse-crew 0.14.3 → 0.14.4

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
@@ -1721,22 +1728,34 @@ 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 issuance-kind "submitted"
+// ledger entry for the same attempt (the trigger issuance), falling back to
+// the oldest by ts for pre-D1 ledgers. The issuance entry binds the trigger
+// instant — verify-publish.js and the decision doc prefer it the same way;
+// binding newest misclassifies builds that complete between issuance and
+// receipt — binding newest misclassifies builds that complete between
+// issuance and receipt (see docs/reviews/critic-0143.md findings 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.
 function findTriggerEntry(entries, commit, attempt) {
+  // D1 (2026-09-19; entry_kind cut 2026-09-20): the anchor is the OLDEST
+  // submitted entry by ts and the bound instant is its issued_at || ts —
+  // the same fallback verify-publish.js uses. The retired entry_kind
+  // preference filter could never change the bound anchor (issuance and
+  // receipt entries carried the same captured issued_at), so oldest-by-ts
+  // is the whole mechanism.
+  const matches = [];
   for (let i = 0; i < entries.length; i++) {
     const e = entries[i];
     if (e.outcome === "submitted" && 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 +1906,9 @@ 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"
+//   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
@@ -1925,7 +1943,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 +1979,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,
@@ -1989,11 +2009,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,7 +2087,7 @@ 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,
         });
@@ -2802,6 +2824,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) {

package/lib/crew-release.sh

@@ -81,7 +81,8 @@ _validate_workflows() {
   # --- Parse gate (restored 2026-09-18, finding B2) ---
   # The workflow runtime accepts top-level `export`, `return`, and `await`
   # (it wraps scripts in an async function), so neither `node --check` on the
-  # raw .js (vacuous for ESM — exits 0 even on blatant syntax errors) nor a
+  # raw .js (goal confusion: parsed as a module it masks breakage the
+  # async-wrapped loader rejects — a false negative, not a true check) nor a
   # .mjs check (rejects the runtime-legal top-level `return`) is correct.
   # Emulate the runtime instead: strip `export`, wrap the script in an async
   # function, then node --check the result. Tokenizer errors (e.g. an
@@ -210,6 +211,210 @@ _link_dep_node_modules() {
   echo "DEP-NODE-MODULES: $link -> $src"
 }
 
+# ── lib entry gate (blocker 21) ─────────────────────────────────────
+# Every shipped lib entry must actually EXECUTE (JS) — node --check is
+# banned from this gate. The true reason, not the folklore: node --check
+# can check a file under a different PARSE GOAL than the real loader uses
+# (blocker 21: checked as a script, loaded as a module), and V8's
+# preparser skips function bodies — a parse check proves nothing about the
+# loader's path. Real execution is the only check that uses the loader's
+# goal. Parse goal: whether Node reads a .js file as a module
+# (import/export, no top-level return) or as a script — set by the nearest
+# package.json's `type` field (shipped lib/package.json pins
+# {"type":"module"}).
+# What runs how:
+#   lib/*.js  with a first line carrying a node shebang token
+#             (#!/usr/bin/env node, #!/bin/node, env -S variants) →
+#             `node <file> --help` through the $tmp/liblink symlink, which
+#             mirrors production's $CREW_HOME/current path shape (the
+#             ff3fb53 realpath main-guard exists exactly for this shape; the
+#             gate runs through the link so it can tell the broken guard
+#             from the fixed one). shebang⇔CLI contract: exit 0, non-empty
+#             stdout.
+#   lib/*.js  without a shebang → bare `node <file>` through the link
+#             (import-safe module contract: exit 0, no side effects).
+#             Residual, documented: import-safety itself is unchecked — an
+#             import-dirty-but-exit-0 module passes. No cheap mechanism.
+#   lib/*.sh  (except test-*.sh) → `bash -n <file>` — parse-only by
+#             necessity: real .sh execution risks side effects. Test scripts
+#             are exercised by tests/run.sh, not shipped as library entries
+#             (they get a `skipped` evidence row, not silence).
+#   lib/*.py  → `python3 -m py_compile <file>` (bytecode goes to a temp
+#             PYTHONPYCACHEPREFIX, never into the staging dir) — parse-only
+#             by the same necessity.
+# So the headline is honest: the gate EXECUTES every JS entry and
+# PARSE-CHECKS sh/py.
+# Boundary: `--help` short-circuits before argument parsing — the gate
+# proves an entry LOADS, not that its main path behaves. The suite covers
+# behavior. workflows/*.js are not covered by this gate at all; their true
+# gate is the suite's loader emulation (publish-verdict-first.test.js —
+# see root AGENTS.md).
+# Every entry gets one ENTRY-GATE pass/FAIL line and one row in
+# $staging_dir/entry-gate.json {release, node, entries:[{file,kind,verdict,exit,reason}]}.
+# A FAIL reason folds the first 10 stderr lines in, so the row names the
+# actual error instead of a bare exit code.
+# On gate failure cmd_deploy copies entry-gate.json to $CREW_HOME before
+# removing the staging dir, and the rejection names the failing entries —
+# the evidence survives the burn.
+# All verdicts are aggregated (no early stop) so the evidence names every
+# failure. Returns 30 when any entry failed; any other exit is a gate
+# mechanism failure (fail closed — the release is rejected either way).
+_validate_lib_entries() {
+  local dir="$1" release="$2"
+  local tmp base f kind st reason verdict
+  tmp="$(mktemp -d)"
+  local rows="$tmp/rows.jsonl"
+  : > "$rows"
+  local failed=0
+  local node_version
+  node_version="$(node --version 2>/dev/null || echo "node-missing")"
+  # Invoke JS entries through a symlink mirroring production's
+  # $CREW_HOME/current path shape — the ff3fb53 realpath main-guard exists
+  # exactly for that shape, and the gate can only tell the broken guard
+  # from the fixed one when it exercises the symlinked path.
+  local link="$tmp/liblink"
+  if ! ln -s "$dir/lib" "$link" 2>/dev/null || [ ! -L "$link" ]; then
+    echo "ENTRY-GATE FAIL: cannot create lib invocation symlink ($link) — failing closed" >&2
+    return 31
+  fi
+
+  _gate_row() { # file kind verdict exit reason
+    node -e 'console.log(JSON.stringify({file:process.argv[1],kind:process.argv[2],verdict:process.argv[3],exit:+process.argv[4],reason:process.argv[5]}))' \
+      "$1" "$2" "$3" "$4" "$5" >> "$rows"
+  }
+
+  _gate_js() { # $1 = real file path; invoked through $link (the $CREW_HOME/current-shaped symlink)
+    local first
+    first="$(head -n 1 "$1")"
+    local cli=0
+    # Shebang match on a node token: #!/usr/bin/env node, #!/bin/node,
+    # env -S variants all classify as CLI.
+    case "$first" in
+      "#!"*"node"*) cli=1 ;;
+    esac
+    st=0
+    reason="ok"
+    local target="$link/$base"
+    if [ "$cli" = 1 ]; then
+      timeout 30 node "$target" --help >"$tmp/out" 2>"$tmp/err" || st=$?
+      kind="js-cli"
+      if [ "$st" -eq 0 ] && [ ! -s "$tmp/out" ]; then
+        reason="empty-stdout"
+        st=1
+      fi
+    else
+      timeout 30 node "$target" >"$tmp/out" 2>"$tmp/err" || st=$?
+      kind="js-module"
+    fi
+    if [ "$st" -eq 0 ]; then
+      reason="ok"
+    else
+      if grep -q "SyntaxError" "$tmp/err" 2>/dev/null; then
+        reason="syntax-error"
+      elif [ "$reason" != "empty-stdout" ]; then
+        reason="exit=$st"
+      fi
+      # Fold the first 10 stderr lines into the reason: a bare exit code
+      # names nothing, and the staging dir (with $tmp/err) is removed on
+      # failure — the row is the surviving evidence.
+      local errhead
+      errhead="$(head -n 10 "$tmp/err" 2>/dev/null | tr '\n' ';' | cut -c1-500)"
+      [ -n "$errhead" ] && reason="$reason | $errhead"
+    fi
+    verdict="pass"
+    [ "$st" -eq 0 ] || { verdict="FAIL"; failed=1; }
+    if [ "$verdict" = "pass" ]; then
+      echo "ENTRY-GATE pass $base ($kind)"
+    else
+      echo "ENTRY-GATE FAIL $base ($kind): $reason" >&2
+    fi
+    _gate_row "$base" "$kind" "$verdict" "$st" "$reason"
+  }
+
+  for f in "$dir"/lib/*.js; do
+    [ -f "$f" ] || continue
+    base="$(basename "$f")"
+    if ! command -v node >/dev/null 2>&1; then
+      echo "ENTRY-GATE FAIL $base (js): node missing" >&2
+      _gate_row "$base" "js" "FAIL" 127 "node-missing"
+      failed=1
+      continue
+    fi
+    _gate_js "$f"
+  done
+
+  for f in "$dir"/lib/*.sh; do
+    [ -f "$f" ] || continue
+    base="$(basename "$f")"
+    case "$base" in
+      test-*)
+        # Out of scope for the gate — but never silent: a skipped row, so
+        # "0 rows" is distinguishable from "all skipped".
+        _gate_row "$base" "sh" "skipped" 0 "test scripts are exercised by tests/run.sh, not shipped as library entries"
+        echo "ENTRY-GATE skipped $base (sh)"
+        continue ;;
+    esac
+    st=0
+    bash -n "$f" 2>"$tmp/err" || st=$?
+    reason="ok"; verdict="pass"
+    if [ "$st" -ne 0 ]; then
+      reason="bash-n exit=$st"
+      # Same evidence rule as the JS gate: the row names the actual error.
+      local errhead
+      errhead="$(head -n 10 "$tmp/err" 2>/dev/null | tr '\n' ';' | cut -c1-500)"
+      [ -n "$errhead" ] && reason="$reason | $errhead"
+      verdict="FAIL"; failed=1
+      echo "ENTRY-GATE FAIL $base (sh): $reason" >&2
+    else
+      echo "ENTRY-GATE pass $base (sh)"
+    fi
+    _gate_row "$base" "sh" "$verdict" "$st" "$reason"
+  done
+
+  for f in "$dir"/lib/*.py; do
+    [ -f "$f" ] || continue
+    base="$(basename "$f")"
+    st=0
+    if ! command -v python3 >/dev/null 2>&1; then
+      st=127; reason="python3-missing"
+    else
+      # Bytecode goes to a temp prefix — never into the staging dir, or it
+      # would be shipped inside the release.
+      PYTHONPYCACHEPREFIX="$tmp/pyc" python3 -m py_compile "$f" 2>"$tmp/err" || st=$?
+      reason="ok"
+      [ "$st" -eq 0 ] || reason="py-compile exit=$st"
+    fi
+    verdict="pass"
+    if [ "$st" -ne 0 ]; then
+      local errhead
+      errhead="$(head -n 10 "$tmp/err" 2>/dev/null | tr '\n' ';' | cut -c1-500)"
+      [ -n "$errhead" ] && reason="$reason | $errhead"
+      verdict="FAIL"; failed=1
+    fi
+    if [ "$verdict" = "pass" ]; then
+      echo "ENTRY-GATE pass $base (py)"
+    else
+      echo "ENTRY-GATE FAIL $base (py): $reason" >&2
+    fi
+    _gate_row "$base" "py" "$verdict" "$st" "$reason"
+  done
+
+  # Evidence: one row per enumerated entry.
+  node -e '
+    const fs = require("fs");
+    const rows = fs.readFileSync(process.argv[1], "utf8").split("\n").filter(Boolean).map(l => JSON.parse(l));
+    fs.writeFileSync(process.argv[4], JSON.stringify({ release: process.argv[2], node: process.argv[3], entries: rows }, null, 2) + "\n");
+  ' "$rows" "$release" "$node_version" "$dir/entry-gate.json"
+  rm -rf "$tmp"
+
+  if [ "$failed" -ne 0 ]; then
+    echo "ENTRY-GATE: $failed entr(y/ies) failed — release rejected" >&2
+    return 30
+  fi
+  echo "ENTRY-GATE: all lib entries executed cleanly"
+  return 0
+}
+
 # ── deploy ────────────────────────────────────────────────────────────
 # Build, validate, and atomically activate a release from repo HEAD.
 # Single command — no cross-step lock needed.
@@ -302,6 +507,29 @@ cmd_deploy() {
         *)  die "release $hash rejected: workflow validation failed (unexpected exit $_vw_status)" ;;
       esac
     fi
+    # Gate: every shipped lib entry must actually execute (blocker 21).
+    # _validate_lib_entries returns 30 when any entry failed, anything else
+    # on a gate mechanism failure; either way the release is rejected. The
+    # rejection names the failing entries (not just the gate) and points at
+    # the preserved evidence — the evidence is copied to $CREW_HOME before
+    # the staging dir is removed, so it survives the burn.
+    _le_status=0
+    _validate_lib_entries "$staging_dir" "$hash" || _le_status=$?
+    if [ "$_le_status" -ne 0 ]; then
+      # The staging dir (and its entry-gate.json) is about to be removed —
+      # preserve the evidence first, then name the failing entries in the
+      # rejection instead of a bare exit code.
+      local _le_evidence="$CREW_HOME/entry-gate-$hash.json"
+      [ -f "$staging_dir/entry-gate.json" ] && cp "$staging_dir/entry-gate.json" "$_le_evidence"
+      local _le_fails="(no entry rows — gate mechanism failure)"
+      if [ -f "$staging_dir/entry-gate.json" ]; then
+        _le_fails="$(node -e 'const j=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"));const f=j.entries.filter(e=>e.verdict==="FAIL").map(e=>e.file+" ("+e.kind+")");console.log(f.length?f.join(", "):"(no failing entries — gate mechanism failure)")' "$staging_dir/entry-gate.json" 2>/dev/null)"
+      fi
+      local _le_meaning="gate mechanism failure"
+      [ "$_le_status" = 30 ] && _le_meaning="at least one entry failed"
+      rm -rf "$staging_dir"
+      die "release $hash rejected: lib entry gate failed (exit $_le_status = $_le_meaning) — failing entries: $_le_fails; evidence: $_le_evidence"
+    fi
     # Atomic rename into place
     mv "$staging_dir" "$release_dir"
     echo "INSTALLED: $hash"
@@ -404,6 +632,9 @@ _prune_releases() {
 }
 
 # ── dispatch ──────────────────────────────────────────────────────────
+# Sourced (never executed) by tests/entry-gate.test.js to drive
+# _validate_lib_entries directly — dispatch only when run as the main script.
+if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
 case "${1:-}" in
   init)     shift; cmd_init "$@" ;;
   deploy)   shift; cmd_deploy "$@" ;;
@@ -412,3 +643,4 @@ case "${1:-}" in
   list)     shift; cmd_list "$@" ;;
   *)        die "usage: crew-release.sh {init|deploy|rollback|current|list} [args...]" ;;
 esac
+fi

package/lib/gitignore.js

@@ -16,8 +16,10 @@
 //   - Never removes, reorders, or reformats existing content.
 //   - Returns { created, appended[], skipped[] }.
 
-const fs = require("fs");
-const path = require("path");
+import fs from "node:fs";
+import path from "node:path";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 
 const CREW_GITIGNORE_ENTRIES = [".worktrees/", ".orchestration/user/"];
 
@@ -118,21 +120,37 @@ function describeGitignoreChange(repoPath, entries) {
   };
 }
 
-module.exports = {
+export {
   CREW_GITIGNORE_ENTRIES,
   ensureGitignoreEntries,
   describeGitignoreChange,
 };
 
+const USAGE = "Usage: node lib/gitignore.js --repo <path> [--dry-run]";
+
 // CLI: node lib/gitignore.js --repo <path> [--dry-run]
 // Used by crew-init and by tests. --dry-run prints the diff without writing.
-if (require.main === module) {
+// --help (and the shebang⇔CLI contract): prints usage, exits 0, before
+// required-arg parsing.
+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 repoIdx = argv.indexOf("--repo");
   const repoPath = repoIdx >= 0 ? argv[repoIdx + 1] : null;
   const dryRun = argv.includes("--dry-run");
   if (!repoPath) {
-    console.error("Usage: node lib/gitignore.js --repo <path> [--dry-run]");
+    console.error(USAGE);
     process.exit(2);
   }
   if (dryRun) {

package/lib/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/lib/publish-note-vocabulary.js

@@ -0,0 +1,44 @@
+// Terminal-note vocabulary registry (D7, 2026-09-19). Explicit state, not
+// prose: every `publish: …` note the state machine treats as terminally
+// parked. Readers (scan-publish-unknown in lib/crew-api.js) consult this;
+// writers assert against it (lib/verify-publish.js's terminal() fails loud
+// before emitting a verb that is not in the registry). Add a note here when
+// a new terminal verb is introduced — the scan recognizes it with no other
+// change.
+//
+// This module is the closed-enum pattern's first instance: the audit
+// (room23-design/blanket-call-audit.md §3) lists the other state-carrying
+// string families (the full `publish: <transition>` note shapes, the
+// publish-ledger `outcome` vocabulary, worker-report marker lines) that a
+// later unification pass extends the enum-guard pattern to. The contract
+// for any new family: one registry module, readers consult it, writers
+// assert membership before writing, closed by default and open by edit.
+//
+// ESM, no shebang, no side effects on import (import-safe module — bare
+// `node publish-note-vocabulary.js` exits 0).
+export const TERMINAL_PUBLISH_NOTES = [
+  "publish: ambiguous",
+  "publish: retry-superseded",
+  "publish: retry-refused",
+  "publish: verified",
+  "publish: superseded",
+  // Verification pipeline's terminal content verdict (verify-publish.js).
+  // The task stays parked for human attention; unknown-recovery never
+  // re-enters it. Added 2026-09-19 (Room #23 J1/J3: was mislogged as
+  // unrecognized-publish-note).
+  "publish: verification-failed",
+];
+export const TERMINAL_NOTE_MEANINGS = {
+  "publish: ambiguous": "unknown-recovery terminal: could not prove the drop; parked for human attention",
+  "publish: retry-superseded": "retry protocol terminal: superseded; parked for human attention",
+  "publish: retry-refused": "retry protocol terminal: platform refused the re-issued edit; parked for human attention",
+  "publish: verified": "publish verified and stamped; task re-queued (terminal for the scan)",
+  "publish: superseded": "HEAD moved past the attempt; recovery aborted; parked for human attention",
+  "publish: verification-failed": "verification pipeline's terminal content verdict — parked for human attention",
+};
+export function matchTerminalPublishNote(message) {
+  for (const note of TERMINAL_PUBLISH_NOTES) {
+    if (message.includes(note)) return note; // same substring semantics the scan already uses
+  }
+  return null;
+}

package/lib/read-ooda-verdict.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 // read-ooda-verdict.js — deterministic cross-checker for the OODA terminal
 // verdict (2026-09-15).
 //
@@ -50,10 +51,9 @@
 // Determinism: no wall-clock reads, no randomness. The script never judges
 // report content — the agent states the reason; the machine enforces its
 // presence and its agreement with the prose verdict.
-"use strict";
 
-const { readFileSync, existsSync } = require("node:fs");
-const { join, resolve } = require("node:path");
+import { readFileSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
 
 function fail(code, error) {
   process.stdout.write(JSON.stringify({ ok: false, code: code, error: error }) + "\n");
@@ -72,6 +72,14 @@ function parseArgs(argv) {
 }
 
 function main() {
+  // --help: before required-arg parsing (shebang⇔CLI contract).
+  if (process.argv.slice(2).includes("--help")) {
+    console.log(
+      "usage: node read-ooda-verdict.js --dir <phase-dir> --expect <PASS|FAIL>\n" +
+      "cross-checks the prose VERDICT: line against <phase-dir>/verdict.json"
+    );
+    process.exit(0);
+  }
   const args = parseArgs(process.argv.slice(2));
   if (!args.dir) fail("bad_input", "missing --dir <phase-dir>");
   if (!args.expect) fail("bad_input", "missing --expect <PASS|FAIL>");

package/lib/readback-disk.js

@@ -53,6 +53,15 @@ import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 
+// --help: before required-arg parsing (shebang⇔CLI contract).
+if (process.argv.slice(2).includes("--help")) {
+  console.log(
+    "usage: node readback-disk.js --repo-path <path> --commit <sha> --base <sha> --task-id <uuid> --slug <artifact-slug> [--spaces-root <dir>]\n" +
+    "the deterministic disk read-back SENSOR: emits the machine-readable findings block (FILE:/ADDED:/REMOVED:/END_FILE)"
+  );
+  process.exit(0);
+}
+
 const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 
 function arg(name) {

package/lib/render-html.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 // render-html.js — render an HTML evidence layout to PNG via headless Chromium.
 //
 // The reef-qa pattern (2026-09-14): the agent composes evidence as HTML —
@@ -26,11 +27,13 @@
 // The rendered composition is evidence: log it with append-ooda-step.js
 // (--action compose) and READ it — a composition you did not read is not
 // evidence.
-"use strict";
 
-const { existsSync, readFileSync } = require("node:fs");
-const { resolve, dirname } = require("node:path");
-const { pathToFileURL } = require("node:url");
+import { existsSync, readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createRequire } from "node:module";
+
+const cjsRequire = createRequire(import.meta.url);
 
 const DEFAULT_WIDTH = 1200;
 
@@ -54,16 +57,17 @@ function parseArgs(argv) {
 function loadPlaywright() {
   // playwright-core is a declared dependency (package.json), so a normal
   // npm install resolves it from the package's own node_modules.
+  // createRequire keeps the synchronous resolution the CLI relies on.
   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(envDir + "/playwright-core");
+      return cjsRequire(envDir + "/playwright-core");
     } catch (e) { /* fall through */ }
     try {
-      return require(envDir);
+      return cjsRequire(envDir);
     } catch (e) { /* fall through */ }
   }
   fail(3, {
@@ -86,6 +90,12 @@ function findChromium() {
 }
 
 async function main() {
+  // --help: before required-arg parsing (shebang⇔CLI contract).
+  if (process.argv.slice(2).includes("--help")) {
+    console.log("usage: node render-html.js --in <page.html> --out <shot.png> [--width <px>]\n" +
+      "renders a local HTML evidence layout to PNG via headless Chromium");
+    process.exit(0);
+  }
   const args = parseArgs(process.argv.slice(2));
   if (!args.in) fail(2, { ok: false, error: "missing --in <page.html>" });
   if (!args.out) fail(2, { ok: false, error: "missing --out <shot.png>" });

package/lib/repo-orchestration.js

@@ -14,8 +14,10 @@
 // Seeding uses no-clobber semantics: existing project customizations are
 // never overwritten. Idempotent: re-running is a no-op.
 
-const fs = require("fs");
-const path = require("path");
+import fs from "node:fs";
+import path from "node:path";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 
 function ensureDir(dirPath) {
   if (!fs.existsSync(dirPath)) {
@@ -106,19 +108,33 @@ function scaffoldRepoOrchestration(repoPath, crewRepoPath) {
   return result;
 }
 
-module.exports = {
+export {
   scaffoldRepoOrchestration,
 };
 
+const USAGE = "Usage: node lib/repo-orchestration.js --repo <path> --crew-repo <path>";
+
+const isMainModule = (() => {
+  try {
+    return !!process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+})();
+
 // CLI: node lib/repo-orchestration.js --repo <path> --crew-repo <path>
-if (require.main === module) {
+if (isMainModule) {
   const argv = process.argv.slice(2);
+  if (argv.includes("--help")) {
+    console.log(USAGE);
+    process.exit(0);
+  }
   const repoIdx = argv.indexOf("--repo");
   const crewRepoIdx = argv.indexOf("--crew-repo");
   const repoPath = repoIdx >= 0 ? argv[repoIdx + 1] : null;
   const crewRepoPath = crewRepoIdx >= 0 ? argv[crewRepoIdx + 1] : null;
   if (!repoPath || !crewRepoPath) {
-    console.error("Usage: node lib/repo-orchestration.js --repo <path> --crew-repo <path>");
+    console.error(USAGE);
     process.exit(2);
   }
   const r = scaffoldRepoOrchestration(repoPath, crewRepoPath);