muse-crew 0.14.3 → 0.14.5

package/lib/retry-publish.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
-// retry-publish.js — Deterministic unknown-recovery retry protocol (2026-09-18, should-fix 5).
+// retry-publish.js — Deterministic unknown-recovery retry protocol (2026-09-18, should-fix 5;
+// ported 2026-09-20: node:sqlite + crew-state.db (blocker 23) and direct
+// tick-worker issuance (blocker 22 — children cannot reach artifact_edit).
 //
 // The cron Step 4.4 retry protocol was prose-owned: the cron agent performed
 // lock handling, journaling, diff generation, ledger writes, mirroring, and
@@ -8,19 +10,20 @@
 //
 // This command owns all deterministic transitions with try/finally lock
 // release. Only the unavoidable `artifact_edit` tool call remains
-// agent-mediated (it requires the artifact namespace, which this process
-// cannot load).
+// tick-mediated (it requires the artifact namespace, which this process
+// cannot load): the session-carrying tick worker issues the edit directly
+// in its own turn — NEVER a child (blocker 22, room #24).
 //
 // Two phases:
 //   Phase 1 (prepare): acquire merge lock, re-check HEAD, re-classify,
 //     journal intent, generate diff. Outputs JSON with the diff path/sha
-//     for the agent to feed to artifact_edit. The lock is HELD on success
-//     (the agent must call phase 2 to release it).
+//     for the tick worker's direct artifact_edit call. The lock is HELD on
+//     success (the tick must call phase 2 to release it).
 //   Phase 2 (complete): given the artifact_edit outcome (accepted/refused),
 //     write the outcome notes, append the ledger entry, mirror verification,
 //     and RELEASE the lock in a finally block.
 //
-// Crash safety: if the agent dies between phases, the lock expires after
+// Crash safety: if the tick dies between phases, the lock expires after
 // 600s and the note journal (`publish: retry-intended` without
 // `publish: retry-issued`) lets the next scan mirror verification-requested
 // without re-triggering — exactly one retry, enforced from notes.
@@ -31,7 +34,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 +53,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 +75,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(); }
@@ -70,25 +98,24 @@ function writePublishNote(db, taskId, message) {
   ).run(uuid(), taskId, message, nowISO());
 }
 
-// Load the crew DB. We use better-sqlite3 via the crew-api's own dependency
-// resolution — fall back to a clear error if unavailable.
-let Database;
-try {
-  Database = (await import("better-sqlite3")).default;
-} catch {
-  fail("db-unavailable", "better-sqlite3 is not available to retry-publish.js");
-}
-const dbPath = join(crewHome, "crew.db");
+// Load the crew DB via node:sqlite (the runtime's built-in — 2026-09-20,
+// blocker 23: better-sqlite3 is not available and the old code pointed at
+// the wrong database name). crew-api.js opens the same path the same way.
+import { DatabaseSync } from "node:sqlite";
+const dbPath = join(crewHome, "crew-state.db");
 if (!existsSync(dbPath)) fail("no-db", `crew database not found at ${dbPath}`);
-const db = new Database(dbPath);
+const db = new DatabaseSync(dbPath);
 
 const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 
-function runMergeLock(action) {
+// The merge lock is per-repo (merge-lock.sh fails closed without
+// CREW_REPO — 2026-09-20: the old code never set it, so the lock could
+// never be acquired). The retry protocol locks the task's own repo.
+function runMergeLock(action, repoPath) {
   const lockScript = join(crewHome, "lib", "merge-lock.sh");
   try {
     execFileSync(lockScript, [action, taskId], {
-      env: { ...process.env, CREW_HOME: crewHome },
+      env: { ...process.env, CREW_HOME: crewHome, CREW_REPO: repoPath },
       encoding: "utf8",
       timeout: 30000,
     });
@@ -101,7 +128,7 @@ function runMergeLock(action) {
 // --- Phase 1: prepare --------------------------------------------------------
 // Acquires the lock, re-checks HEAD, re-classifies, journals intent,
 // generates the diff. On success the lock is HELD and the output carries
-// the diff path/sha for the agent's artifact_edit child.
+// the diff path/sha for the tick worker's direct artifact_edit call.
 
 if (phase === "prepare") {
   // Derive the unknown attempt (same derivation as scan-publish-unknown).
@@ -113,6 +140,7 @@ if (phase === "prepare") {
   const slug = project && project.deploy_slug;
   if (!slug) fail("no-slug", "project has no deploy_slug");
   const repoPath = (project && project.repo_path) || null;
+  if (!repoPath) fail("no-repo", "project has no repo_path — the retry protocol locks the task's repo");
 
   const ledgerPath = join(crewHome, ".publish-ledger", slug + ".jsonl");
   let entries = [];
@@ -149,7 +177,7 @@ if (phase === "prepare") {
   }
 
   // 2. Acquire the merge lock.
-  const lock = runMergeLock("acquire");
+  const lock = runMergeLock("acquire", repoPath);
   if (!lock.ok) {
     process.stdout.write(JSON.stringify({
       ok: true, phase: "prepare", outcome: "lock-held",
@@ -163,7 +191,7 @@ if (phase === "prepare") {
   let lockHeld = true;
   const releaseLock = () => {
     if (lockHeld) {
-      runMergeLock("release");
+      runMergeLock("release", repoPath);
       lockHeld = false;
     }
   };
@@ -180,12 +208,21 @@ 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
+    // tick-worker "submitted" entry by ts (D1, 2026-09-19; entry_kind cut
+    // 2026-09-20; issuer anchor 2026-09-20, one-party worker-owned publish —
+    // only the session-carrying tick worker performs issuance, so only its
+    // stamped writes bind; a workflow-written "submitted" without issuer is
+    // a phantom claim, never a baseline source) — 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) =>
-      e.outcome === "submitted" && e.commit === commit && (attempt == null || e.attempt === attempt));
+    const submitted = entries.filter((e) =>
+      e.outcome === "submitted" && e.issuer === "tick-worker" &&
+      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 +241,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,
     ];
@@ -265,11 +302,11 @@ if (phase === "prepare") {
       fail("diff-not-ok", `compute-publish-diff.js returned ok:false — intent note stands; next tick mirrors verification-requested`);
     }
 
-    // Success: lock remains HELD. The agent spawns the artifact_edit child
-    // with the diff, then calls phase 2 (complete) to finish.
+    // Success: lock remains HELD. The tick worker issues the edit directly
+    // in its own turn 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,
@@ -283,7 +320,7 @@ if (phase === "prepare") {
       task_id: taskId, commit, attempt,
       diff_path: diffPath, diff_sha256: diffMeta.sha256,
       slug,
-      message: "lock held; spawn the artifact_edit child with the diff, then call phase 2 (complete)",
+      message: "lock held; issue the artifact_edit directly in this tick (the session-carrying tick worker owns issuance), then call phase 2 (complete)",
     }) + "\n");
     process.exit(0);
   } catch (e) {
@@ -304,17 +341,21 @@ 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`);
   }
   const state = JSON.parse(readFileSync(statePath, "utf8"));
-  const { commit, attempt, slug, ledger_path: ledgerPath, retry_baseline: retryBaseline } = state;
+  const { commit, attempt, slug, repoPath, ledger_path: ledgerPath, retry_baseline: retryBaseline } = state;
+  // (2026-09-20, one-party publish) The phase-1 pin carries repoPath; the
+  // merge lock is repo-scoped, so a missing value is a hard failure — the
+  // finally's release must never run against an undefined repo.
+  if (!repoPath) fail("no-repo-in-state", "phase-1 state has no repoPath — cannot release the merge lock safely; the lock lease expires on its own");
 
   let lockHeld = true;
   const releaseLock = () => {
     if (lockHeld) {
-      runMergeLock("release");
+      runMergeLock("release", repoPath);
       lockHeld = false;
     }
   };
@@ -325,49 +366,52 @@ 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 tick worker's direct call ended 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",
+        issuer: "tick-worker",
+        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();