session-orchestrator 5.1.0 → 5.2.0

package/scripts/lib/validate/check-unwired-features.mjs

@@ -265,9 +265,9 @@
 
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 
 import { sizingSubject } from '../learnings/sizing-subject.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
 /** Documented config surface — every `yaml` fence in this file is a declaration. */
 const TEMPLATE_REL = 'docs/session-config-template.md';
@@ -652,19 +652,57 @@ export function collectExportedSymbols(body) {
   return [...names];
 }
 
+/**
+ * Re-export targets of a barrel: the specifiers of its `export * from '…'`
+ * (and `export * as ns from '…'`) lines.
+ *
+ * `collectExportedSymbols` cannot see these — a star re-export names no symbol —
+ * so a PURE barrel reads as `exports: []`. That does not merely hide the barrel:
+ * the S4 population predicate below requires at least one export, so the barrel
+ * never enters `unreachable` at all, and is therefore unavailable as the CLUSTER
+ * ROOT of the module it re-exports. The target is then reported as its own root.
+ *
+ * Measured 2026-09-16 on the live tree: `scripts/lib/worktree.mjs` is exactly
+ * `export * from './worktree/index.mjs';`, its only importers (`workspace.mjs`,
+ * `worktree-freshness.mjs`) are themselves unreachable — yet S4 reported
+ * `scripts/lib/worktree/index.mjs`, an interior file, instead of the cluster.
+ *
+ * Only the POPULATION is affected. Edge propagation already works: the BFS walks
+ * `mentions`, and a star re-export line is not a comment, so a barrel that IS
+ * reachable already marks its target reachable (measured the same day:
+ * `worktree.mjs` carries `index.mjs` in `mentions`).
+ *
+ * Anchored at column 0 like the export-symbol grammar above, so a docblock line
+ * (`* export * from …`) and an indented string never count.
+ *
+ * @param {string} body module source
+ * @returns {string[]} re-exported module specifiers, as written
+ */
+export function collectReExportTargets(body) {
+  return [
+    ...body.matchAll(/^export\s+\*(?:\s+as\s+[A-Za-z0-9_$]+)?\s+from\s+['"]([^'"]+)['"]/gm),
+  ].map((match) => match[1]);
+}
+
 /**
  * Whether a module is a CLI entrypoint rather than a library.
  *
  * An entrypoint is invoked by path (npm script, hook wiring, CI job), so having
  * no importer is its normal state and says nothing about being wired.
  *
+ * `isMainModule(` is part of the grammar because the #1371 sweep replaced ~50
+ * hand-written `process.argv[1] === import.meta.url` guards with the shared
+ * `scripts/lib/is-main-module.mjs` predicate. Without this alternative a swept
+ * CLI matches none of the other branches and silently reclassifies as a library
+ * candidate, so S4 reports it as an `unreachable-library-module` root.
+ *
  * @param {string} body module source
  * @returns {boolean}
  */
 export function isCliEntrypoint(body) {
   return (
     body.startsWith('#!') ||
-    /import\.meta\.url\s*===|require\.main\s*===\s*module|process\.argv\[1\]/.test(body)
+    /import\.meta\.url\s*===|require\.main\s*===\s*module|process\.argv\[1\]|isMainModule\(/.test(body)
   );
 }
 
@@ -890,6 +928,10 @@ export function collectUnreachableLibraryModules(pluginRoot) {
       edgeOnly,
       entrypoint: isCliEntrypoint(body),
       exports: collectExportedSymbols(body),
+      // Star re-exports name no symbol, so `exports` is empty for a pure
+      // barrel — see collectReExportTargets for why that silently promoted an
+      // interior module to a root.
+      reExports: collectReExportTargets(body),
       // This file contributes NO edges — the S4 counterpart of the SELF_REL
       // exclusion the S1/S2 corpus already applies, and for the identical
       // reason. Every S4 `ALLOWLIST` key is a module path written here as a
@@ -947,8 +989,15 @@ export function collectUnreachableLibraryModules(pluginRoot) {
     }
   }
 
+  // A module with NO public surface at all is not a finding — nothing can be
+  // wired to it. A pure `export * from` barrel HAS a surface (everything its
+  // target exports), so it belongs in the population: otherwise it cannot be
+  // the cluster root of the module it re-exports (collectReExportTargets).
   const unreachable = modules.filter(
-    (module) => !reachable.has(module.relative) && !module.entrypoint && module.exports.length > 0,
+    (module) =>
+      !reachable.has(module.relative) &&
+      !module.entrypoint &&
+      (module.exports.length > 0 || module.reExports.length > 0),
   );
   const unreachableSet = new Set(unreachable.map((module) => module.relative));
   // Basename census, shared by the root filter below and the downgrade half
@@ -984,6 +1033,35 @@ export function collectUnreachableLibraryModules(pluginRoot) {
     );
   });
 
+  // A pure `export *` barrel enters the population above so it can HEAD its own
+  // cluster, but reporting it needs one more condition. S3 already exempts this
+  // exact shape by name (`autopilot-telemetry.mjs`, condition 4): a star
+  // re-export has zero NAMED symbols, so every "does prose name one of its
+  // exports?" test is vacuously FALSE — including S4's own coordinator-invoked
+  // downgrade below, which iterates `module.exports`. A reported pure barrel
+  // could therefore never be downgraded, only allowlisted: a finding with no
+  // legitimate exit. The category split is the barrel's TARGET. A barrel over a
+  // module that is itself unreachable heads a genuinely dead cluster and is
+  // reported; a barrel over LIVE code is a backward-compat shim, which is a
+  // different (and much weaker) finding than "nothing can reach this feature".
+  // Measured 2026-09-16: without this split `scripts/lib/autopilot-telemetry.mjs`
+  // — `export * from './autopilot/telemetry.mjs'`, target reachable, sole
+  // importer a test — became a new permanent WARN.
+  // Ceiling: a dead shim over live code is now invisible to S4 as well as to S3.
+  // Revisit if a stale back-compat shim is ever confirmed to have outlived its
+  // last importer unnoticed — that wants its own check, not a looser S4.
+  const reportableRoots = roots.filter((module) => {
+    if (module.exports.length > 0) return true;
+    return module.reExports.some((spec) => {
+      if (!spec.startsWith('.')) {
+        // Aliased/bare specifier: fall back to the basename granularity this
+        // file already documents as its named residual.
+        return [...unreachableSet].some((rel) => path.basename(rel) === path.basename(spec));
+      }
+      return unreachableSet.has(path.normalize(path.join(path.dirname(module.relative), spec)));
+    });
+  });
+
   // Category split (see § Category split in the doc block above): an INSTRUCTION
   // document that names both the module AND one of its exported symbols is an
   // order addressed to a reader who will execute it — the same grammar
@@ -997,7 +1075,7 @@ export function collectUnreachableLibraryModules(pluginRoot) {
     .map((file) => ({ relative: path.relative(pluginRoot, file), body: readFileSync(file, 'utf8') }));
 
   let coordinatorInvoked = 0;
-  const findings = roots.map((module) => {
+  const findings = reportableRoots.map((module) => {
     // Docs write POSIX separators regardless of host; `path.relative` does not.
     const relativePosix = module.relative.split(path.sep).join('/');
     const qualified = relativePosix.split('/').slice(-2).join('/');
@@ -1032,11 +1110,17 @@ export function collectUnreachableLibraryModules(pluginRoot) {
       (token) => token !== module.base && [...unreachableSet].some((rel) => path.basename(rel) === token),
     );
     const tail = dragged.length > 0 ? `, and drags ${dragged.length} further unreachable module(s)` : '';
+    // A pure barrel reports its re-export surface; naming "0 symbol(s)" there
+    // would read as a checker bug rather than as the barrel it is.
+    const surface =
+      module.exports.length > 0
+        ? `exports ${module.exports.length} symbol(s) (${module.exports.slice(0, 3).join(', ')})`
+        : `re-exports ${module.reExports.length} module(s) (${module.reExports.slice(0, 3).join(', ')})`;
     return /** @type {Finding} */ ({
       kind: 'unreachable-library-module',
       key: module.relative,
       message:
-        `exports ${module.exports.length} symbol(s) (${module.exports.slice(0, 3).join(', ')}) but no hook, ` +
+        `${surface} but no hook, ` +
         `npm script, CI job or husky stage reaches it — transitively${tail}. No instruction surface names ` +
         'one of its exports either: wire it, delete it, or allowlist it with a reason',
     });
@@ -1046,7 +1130,7 @@ export function collectUnreachableLibraryModules(pluginRoot) {
     findings,
     scanned: {
       modules: modules.length,
-      roots: roots.length,
+      roots: reportableRoots.length,
       unreachable: unreachable.length,
       coordinatorInvoked,
     },
@@ -1393,7 +1477,7 @@ export function runCheckUnwiredFeatures(pluginRoot, { list = false } = {}) {
   return 0;
 }
 
-const isMain = import.meta.url === pathToFileURL(process.argv[1] || '').href;
+const isMain = isMainModule(import.meta.url);
 if (isMain) {
   const args = process.argv.slice(2);
   const pluginRoot = args.find((arg) => !arg.startsWith('-'));

package/scripts/lib/validate/check-validator-registration.mjs

@@ -72,8 +72,8 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { enumerateRepoFiles } from './enumerate-repo-files.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
 /** Marker line inside a checker's own header — declares deliberate CLI-only status. */
 export const STANDALONE_MARKER = /^\s*\/\/\s*registration:\s*standalone\b(?:\s+(.*))?$/m;
@@ -243,7 +243,7 @@ export function runCheckValidatorRegistration(repoRoot) {
   return fail > 0 ? 1 : 0;
 }
 
-const isMain = import.meta.url === pathToFileURL(process.argv[1] || '').href;
+const isMain =isMainModule(import.meta.url);
 if (isMain) {
   const root = process.argv[2];
   if (!root) {

package/scripts/lib/validate/check-vcs-repo-flag.mjs

@@ -193,8 +193,8 @@
 
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { SHELL_LANGS, forEachLine } from './markdown-fences.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
 /** Directories whose content is scanned. Root-level `*.md` is added separately. */
 const SCAN_DIRS = Object.freeze([
@@ -906,7 +906,7 @@ export function runCheckVcsRepoFlag(pluginRoot) {
   return 0;
 }
 
-const isMain = import.meta.url === pathToFileURL(process.argv[1] || '').href;
+const isMain =isMainModule(import.meta.url);
 if (isMain) {
   const argv = process.argv.slice(2);
   const flags = new Set(argv.filter((a) => a.startsWith('--')));

package/scripts/lib/validate-vendored-rules.mjs

@@ -6,9 +6,12 @@
  * Catches vendoring bugs that are invisible at the source-of-truth layer but
  * become live footguns once synced into a target repo:
  *
- *   - `paths:` frontmatter — `rule-loader.mjs` only understands `globs:`; a
- *     `paths:` key is silently ignored, so the rule loads as always-on
- *     instead of the intended glob-scoped subset.
+ *   - `paths:` frontmatter in a `rules/` LIBRARY SOURCE — a vendoring-
+ *     CONVENTION gate, not a loader-compatibility one. Since #795
+ *     `rule-loader.mjs` accepts `paths:` as an alias for `globs:`, so such a
+ *     rule IS glob-scoped; `globs:` stays the canonical form for a rule
+ *     vendored out through the library (#742). See § Scope below — this probe
+ *     never judges a repo's own consolidated `.claude/rules/` files.
  *   - Missing provenance header — `rules-sync.mjs` detects "plugin-owned vs.
  *     local override" purely by checking whether the first line starts with
  *     `PLUGIN_HEADER_PREFIX`. A source file missing that header gets
@@ -31,6 +34,25 @@
  * module imports the already-exported `parseGlobsFrontmatter` from
  * `rule-loader.mjs` directly.
  *
+ * ## Scope: the `rules/` fleet library, never a repo's own `.claude/rules/`
+ *
+ * Every production caller feeds this module SOURCE files from the plugin's
+ * fleet library: `syncRules()` (`rules-sync.mjs`) validates
+ * `<pluginRoot>/rules/<relPath>` for each entry listed in `rules/_index.md`
+ * BEFORE writing the vendored copy into a consumer's `.claude/rules/` — the
+ * written target is never read back through the gate. The CLI's `--dir` is
+ * operator-supplied and means that same library.
+ *
+ * This is load-bearing for `paths-frontmatter`: a repo's own CONSOLIDATED rules
+ * under `.claude/rules/` are `paths:`-canonical by design, because Claude
+ * Code's native loader reads ONLY `paths:` and treats a rule without it as
+ * always-on (`validate/check-rules.mjs` #1108; `docs/rule-authoring.md`
+ * § Consolidated rules point 3). Measured 2026-09-16 in this repo: 10
+ * path-scoped rule files there, 9 of them `paths:`-only. Pointing `--dir` at
+ * such a tree would emit findings that, if obeyed, UNDO that consolidation —
+ * which is also why `check-rules.mjs` deliberately does not duplicate this
+ * probe for `.claude/rules/`.
+ *
  * @module validate-vendored-rules
  */
 
@@ -40,6 +62,7 @@ import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { parseGlobsFrontmatter } from './rule-loader.mjs';
+import { isMainModule } from './is-main-module.mjs';
 
 // Mirrors rules-sync.mjs's exported PLUGIN_HEADER_PREFIX (rules-sync.mjs
 // line ~13). NOT imported from there on purpose: rules-sync.mjs imports
@@ -478,10 +501,17 @@ export function validateRuleContent({ content, relPath, targetRoot = null, requi
         // `paths:`-only rule IS glob-scoped. The probe itself stays: it enforces the canonical
         // vendoring form, which is a convention gate, not a loader-compatibility gate. That
         // intent survives #795 and is the subject of the #742 fleet canonicalisation sweep.
+        // SCOPE (2026-09-16): this fires only over `rules/` library sources — the module doc's
+        // § Scope section names every caller. Do NOT re-point it at a repo's own
+        // `.claude/rules/`: those consolidated files are `paths:`-canonical and obeying this
+        // remedy there would undo the consolidation (docs/rule-authoring.md point 3).
         message:
           `${relPath}: frontmatter declares a top-level 'paths:' key. It is a recognized alias ` +
           `for 'globs:' (issue #795), so the rule does load glob-scoped — but 'globs:' is the ` +
-          `canonical form for vendored rules. Migrate to 'globs:' (see issue #742).`,
+          `canonical form for a rule VENDORED OUT through the plugin's rules/ library, which is ` +
+          `this probe's only population. Migrate to 'globs:' (see issue #742). This does NOT ` +
+          `apply to a repo's own consolidated .claude/rules/ files — those are paths:-canonical ` +
+          `(Claude Code's native loader reads only 'paths:') and this gate never scans them.`,
         line: lineWithinFrontmatter(fm.startLine, fm.body, pathsMatch.index),
       });
     }
@@ -652,11 +682,7 @@ export function validateRulesDir({ dir, targetRoot = null, requireProvenance = f
 
 const __filename = fileURLToPath(import.meta.url);
 
-const isMain =
-  typeof process !== 'undefined' &&
-  process.argv[1] !== null &&
-  process.argv[1] !== undefined &&
-  resolve(process.argv[1]) === resolve(__filename);
+const isMain =isMainModule(import.meta.url);
 
 /**
  * @param {{ ok: boolean, files: Array<{ file: string, violations: RuleViolation[] }>, errorCount: number, warnCount: number }} result

package/scripts/lib/wave-transcript-tail.mjs

@@ -55,12 +55,12 @@ import {
 } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, relative, isAbsolute } from 'node:path';
-import { pathToFileURL } from 'node:url';
 
 import { emitEvent, sessionAttribution } from './events.mjs';
 import { tryAcquireFileLock, releaseFileLock } from './file-lock.mjs';
 import { readLock, isLockLive } from './session-lock.mjs';
 import { resolveSubagentSidecar } from '../../hooks/_lib/subagent-paths.mjs';
+import { isMainModule } from './is-main-module.mjs';
 
 const DEFAULT_INTERVAL_S = 2;
 const EVENTS_FILE_REL = '.orchestrator/metrics/events.jsonl';
@@ -998,6 +998,6 @@ function main() {
 
 // Run only when executed as a script — importing for unit tests must not parse
 // vitest's argv and exit 1.
-if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isMainModule(import.meta.url)) {
   main();
 }

package/scripts/lock-reaper.mjs

@@ -22,6 +22,7 @@
  */
 
 import { reapStaleLocks } from './lib/lock-reaper.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 // ---------------------------------------------------------------------------
 // Human-readable output
@@ -175,7 +176,7 @@ EXIT CODES
 // CLI guard — prevents execution during test-time imports.
 // ---------------------------------------------------------------------------
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   main()
     .then((code) => process.exit(code))
     .catch((err) => {

package/scripts/materialize-wave-scope.mjs

@@ -23,10 +23,11 @@
  */
 
 import { existsSync, readdirSync, readFileSync, unlinkSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
 import { writeJsonAtomicSync } from './lib/io.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 import { isPeerRecordId } from './lib/scope-gate.mjs';
+import { SCOPE_MATERIALIZED_EVENT, scopeDigest } from './lib/scope-echo.mjs';
 import {
   MANIFEST_SESSION_KEYS,
   manifestSessionBinding,
@@ -479,6 +480,83 @@ export function materializeWaveScope(records, {
   return { aggregatePath, perAgentPaths, removedOrphans: removed, retainedOrphans: retained };
 }
 
+/**
+ * Is the SEND-side half of the #1092 chain installed on this platform at all?
+ *
+ * The send-side record only exists because a `PreToolUse` hook with matcher
+ * `Agent` observes the dispatch. `hooks-codex.json` / `hooks-cursor.json` /
+ * `hooks-pi.json` deliberately carry no such entry (those platforms have no
+ * `Agent` dispatch tool — `DOCUMENTED_ASYMMETRIES`), so on them a MISSING
+ * dispatch record is not evidence of a missing injection. Recording the answer
+ * beside the wave is what lets `--verify` tell those two apart later instead of
+ * re-deriving a platform fact from an absence.
+ *
+ * Fail-CLOSED on any read error: an unreadable hooks file means the guard cannot
+ * be shown to be installed, and claiming observability we cannot prove is the
+ * direction that produces false `injection-missing` accusations.
+ *
+ * @param {string} [pluginRoot]
+ * @param {typeof readFileSync} [readFile]
+ * @returns {boolean}
+ */
+export function transportObservable(pluginRoot = resolve(import.meta.dirname, '..'), readFile = readFileSync) {
+  try {
+    const parsed = JSON.parse(readFile(resolve(pluginRoot, 'hooks', 'hooks.json'), 'utf8'));
+    const entries = parsed?.hooks?.PreToolUse;
+    if (!Array.isArray(entries)) return false;
+    return entries.some((entry) => typeof entry?.matcher === 'string'
+      && entry.matcher.split('|').map((m) => m.trim()).includes('Agent'));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * One `orchestrator.wave_dispatch.scope_materialized` record per wave (#1092) —
+ * the DEGRADATION half of the chain.
+ *
+ * It runs here, and not in the hook, precisely because this command runs on
+ * EVERY platform while the hook runs on one. Without it a wave with zero
+ * `scope_checked` records is ambiguous between "the coordinator skipped the
+ * manifest step" (the #1020 failure this whole chain exists for) and "this
+ * platform has no dispatch hook".
+ *
+ * `repoRoot` is the state directory's PARENT, never `process.cwd()`: the state
+ * dir is the artefact this command owns, and a caller invoking it from a
+ * subdirectory (or a test from the repo root against a `$TMPDIR` state dir)
+ * must not write its record into a different repo's ledger.
+ *
+ * Best-effort in both directions and SILENT on failure: the corpus pins
+ * byte-empty stderr on this command's success path
+ * (`tests/integration/wave-scope-producer.test.mjs`), and a telemetry write must
+ * never be the thing that fails a materialization.
+ *
+ * @param {{stateDir: string, wave: number, records: Array<{id: string, files: string[]}>}} params
+ * @returns {Promise<void>}
+ */
+async function emitScopeMaterialized({ stateDir, wave, records }) {
+  try {
+    const repoRoot = dirname(resolve(stateDir));
+    const agentRecords = records.filter((r) => !isPeerRecordId(r.id));
+    const digests = new Set();
+    for (const record of agentRecords) {
+      if (Array.isArray(record.files) && record.files.length > 0) digests.add(scopeDigest(record.files));
+    }
+    const { emitEvent, sessionAttribution } = await import('./lib/events.mjs');
+    await emitEvent(
+      SCOPE_MATERIALIZED_EVENT,
+      {
+        wave,
+        agent_count: agentRecords.length,
+        digest_count: digests.size,
+        transport_observable: transportObservable(),
+        ...sessionAttribution(repoRoot),
+      },
+      { repoRoot },
+    );
+  } catch { /* observability is best-effort — it never fails a materialization */ }
+}
+
 /**
  * @param {string} message
  * @param {number} code
@@ -536,6 +614,12 @@ export function main() {
         ? `${JSON.stringify({ ok: true, aggregatePath, perAgentPaths, removedOrphans, retainedOrphans })}\n`
         : `${aggregatePath}\n`,
     );
+
+    // Fire-and-forget AFTER stdout, so the telemetry append can never reorder or
+    // delay this command's own contract. Node drains the pending append before
+    // exiting because nothing here calls `process.exit()`; the `.catch` keeps an
+    // unhandled rejection from turning observability into an exit code.
+    emitScopeMaterialized({ stateDir: args.stateDir, wave: args.wave, records }).catch(() => {});
   } catch (error) {
     if (error instanceof InputError) {
       fail(error.message, 1);
@@ -549,7 +633,6 @@ export function main() {
   }
 }
 
-const invokedPath = process.argv[1] ? resolve(process.argv[1]) : null;
-if (invokedPath === fileURLToPath(import.meta.url)) {
+if (isMainModule(import.meta.url)) {
   main();
 }

package/scripts/migrate-sessions-jsonl.mjs

@@ -41,6 +41,7 @@
 import { readFileSync, writeFileSync, renameSync, copyFileSync, existsSync } from 'node:fs';
 import { join, dirname, basename } from 'node:path';
 import { validateSession, normalizeSession, ValidationError } from './lib/session-schema.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 const DEFAULT_FILE = '.orchestrator/metrics/sessions.jsonl';
 
@@ -440,7 +441,7 @@ async function main() {
 
 // Run main() only when this file is invoked directly as a CLI, not when imported.
 // Prevents process.exit during test-time imports (#368).
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   main().catch((err) => {
     process.stderr.write(`migrate-sessions-jsonl: unexpected error: ${err?.stack ?? err}\n`);
     process.exit(2);

package/scripts/migrate-vault-paths.mjs

@@ -50,7 +50,6 @@
 
 import { promises as fs, existsSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
-import { pathToFileURL } from 'node:url';
 import path from 'node:path';
 import os from 'node:os';
 import {
@@ -58,6 +57,7 @@ import {
   VAULT_MIGRATION_RULES_PATH,
 } from './lib/vault-migration-rules.mjs';
 import { parseColumnFlags, CliFlagError } from './lib/cli-flags.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -773,8 +773,7 @@ function emit(opts, rec) {
 // importing the module is never a hard error regardless of how the importer runs.
 // ---------------------------------------------------------------------------
 
-const invokedDirectly =
-  process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+const invokedDirectly =isMainModule(import.meta.url);
 
 if (invokedDirectly) {
   main().catch((err) => {

package/scripts/release.mjs

@@ -356,7 +356,7 @@ const INTENTIONAL_TEST_ASSET_PATHS = new Set([
   'templates/python-uv/tests/test_sanity.py',
 ]);
 
-// `commands/release.md` quotes the `npm view` OUTPUT that proves the 3.18.0 gap,
+// `skills/release/SKILL.md` quotes the `npm view` OUTPUT that proves the 3.18.0 gap,
 // dated at the line. Bumping it would destroy the evidence it exists to carry —
 // the registry state on that date is the whole point of the paragraph.
 //
@@ -384,7 +384,7 @@ const INTENTIONAL_TEST_ASSET_PATHS = new Set([
 // September 10 campaign snapshot: inputs and receipt reproduce the dated 4.3-planned
 // render made while 4.2.0 was current. Exact files only; neighboring marketing
 // remains checked. Do not bump receipt props without a newly reviewed render.
-export const HISTORY_ALLOWLIST = /^(CHANGELOG\.md|README\.md|CLAUDE\.md|AGENTS\.md|CONTRIBUTING\.md|NOTICE|\.husky\/pre-push|docs\/|tests\/|skills\/npm-publish\/|skills\/architecture\/references\/domain-model\.md|skills\/autopilot\/SKILL\.md|scripts\/release\.mjs|\.orchestrator\/|site\/leaderboard\.json|site\/guide\/index\.html|site\/llms-full\.txt|commands\/release\.md|marketing\/remotion\/(?:README\.md|campaign\.json|render-receipt\.json|src\/ReleaseFilm\.tsx)$)/;
+export const HISTORY_ALLOWLIST = /^(CHANGELOG\.md|README\.md|CLAUDE\.md|AGENTS\.md|CONTRIBUTING\.md|NOTICE|\.husky\/pre-push|docs\/|tests\/|skills\/npm-publish\/|skills\/architecture\/references\/domain-model\.md|skills\/autopilot\/SKILL\.md|scripts\/release\.mjs|\.orchestrator\/|site\/leaderboard\.json|site\/guide\/index\.html|site\/llms-full\.txt|skills\/release\/SKILL\.md|marketing\/remotion\/(?:README\.md|campaign\.json|render-receipt\.json|src\/ReleaseFilm\.tsx)$)/;
 
 /** Pure check over packed-entry lines. Returns violations: {name, line}[]. */
 export function checkLeakage(lines) {
@@ -908,6 +908,11 @@ export function evaluateCiRow(ci) {
  * "we could not read the mirror" is not "the mirror is green" (the fail-closed
  * house rule at the top of this file).
  *
+ * This function only judges the `ci` reading it is handed — it is
+ * `evaluateCiPreflightRows` (the caller, see its own docblock) that fetches
+ * `ci` for the commit actually being released, rather than whichever HEAD the
+ * GitHub mirror itself reports.
+ *
  * @param {string|undefined} repoSpec — `resolveRepoSpec({vcs:'github'})`, undefined when no github remote resolves
  * @param {null | {status?: string, failingJobName?: string, degraded?: string}} ci
  * @returns {{ok: boolean, detail: string}}
@@ -969,6 +974,62 @@ function readPackageVersion(repoRoot) {
   return JSON.parse(readFileSync(join(repoRoot, 'package.json'), 'utf8')).version;
 }
 
+/**
+ * Both CI preflight rows (`ci-green-on-head` + `ci-green-on-head-github`) for
+ * ONE commit — the commit actually about to be released — never whichever
+ * HEAD the queried platform happens to report.
+ *
+ * Before this function existed, neither `checkCiStatus` call below passed
+ * `sha`, so the GitHub branch fell back to `commits/HEAD` — the MIRROR's own
+ * default-branch head, which is the release commit only once `head-pushed-github`
+ * has ALREADY proven `github/main == local HEAD`. A release cut before that
+ * push landed asked GitHub about a commit that was never pushed and could read
+ * green for work GitHub has not seen at all (measured 2026-09-16 for
+ * `3ebf0e9d`). The GitLab branch was already correct by default (`deps.sha ??
+ * getHeadSha(repoRoot)`), so only the two call sites below needed the fix —
+ * see `checkCiStatus`'s own docblock in `ci-status-banner.mjs` for the `sha`
+ * contract (#1332).
+ *
+ * Factored out of `preflight()` as its own async, DI-testable unit:
+ * `checkCiStatus` reaches the network by default, and `preflight()`'s
+ * surrounding checks (git, npm) are not test-doubled, so this is the seam
+ * through which the `sha` wiring can be unit-tested without spinning up a
+ * full fixture release.
+ *
+ * @param {string} repoRoot
+ * @param {string} head - full hex commit id of the commit being released (the
+ *   local HEAD `preflight()` already computed for the remote-parity rows).
+ * @param {{
+ *   skipCi?: boolean,
+ *   checkCiStatus?: Function,
+ *   resolveRepoSpec?: (opts: { repoRoot: string, vcs: 'github' }) => string|undefined,
+ * }} [deps]
+ * @returns {Promise<{ gitlab: {ok: boolean, detail: string}, github: {ok: boolean, detail: string} }>}
+ */
+export async function evaluateCiPreflightRows(repoRoot, head, {
+  skipCi = false,
+  checkCiStatus: checkCiStatusDep,
+  resolveRepoSpec: resolveRepoSpecDep = resolveRepoSpec,
+} = {}) {
+  if (skipCi) {
+    const skipped = { ok: true, detail: 'SKIPPED via --skip-ci' };
+    return { gitlab: skipped, github: skipped };
+  }
+  const checkCiStatusImpl = checkCiStatusDep ?? (await import('./lib/ci-status-banner.mjs')).checkCiStatus;
+
+  const ci = await checkCiStatusImpl({ repoRoot, timeoutMs: 15000, sha: head });
+  const gitlab = evaluateCiRow(ci);
+
+  const githubSpec = resolveRepoSpecDep({ repoRoot, vcs: 'github' });
+  let githubCi = null;
+  if (githubSpec) {
+    githubCi = await checkCiStatusImpl({ repoRoot, vcs: 'github', timeoutMs: 15000, sha: head });
+  }
+  const github = evaluateGithubCiRow(githubSpec, githubCi);
+
+  return { gitlab, github };
+}
+
 async function preflight(repoRoot, target, { skipCi = false } = {}) {
   const checks = [];
   const add = (name, ok, detail = '') => checks.push({ name, ok, detail });
@@ -1098,39 +1159,23 @@ async function preflight(repoRoot, target, { skipCi = false } = {}) {
     add('npm-token-live', false, err.message);
   }
 
-  // 6. CI green on HEAD (the repo's iron session-start rule applies to
-  // releases doubly: local green is not evidence — see .claude/rules).
-  // --skip-ci is refused under --publish upstream in validateFlags(); it can
-  // only reach this branch from --check.
-  if (skipCi) {
-    add('ci-green-on-head', true, 'SKIPPED via --skip-ci');
-  } else {
-    const { checkCiStatus } = await import('./lib/ci-status-banner.mjs');
-    const ci = await checkCiStatus({ repoRoot, timeoutMs: 15000 });
-    const row = evaluateCiRow(ci);
-    add('ci-green-on-head', row.ok, row.detail);
-  }
-
-  // 6b. CI green on the GitHub mirror too. The row above asks the platform
-  // `detectVcsFamily` picks for `origin` (GitLab), whose pipeline is Linux-only;
-  // the macOS matrix leg lives exclusively in `.github/workflows/test.yml`.
-  // `vcs: 'github'` forces the probe onto the mirror without touching the
-  // detection order. The GitHub check-runs path reads `commits/HEAD`, i.e. the
-  // mirror's default-branch head — which is HEAD only because `head-pushed-github`
-  // above proves github/main == local HEAD; that row is this one's precondition,
-  // not a duplicate of it.
-  if (skipCi) {
-    add('ci-green-on-head-github', true, 'SKIPPED via --skip-ci');
-  } else {
-    const githubSpec = resolveRepoSpec({ repoRoot, vcs: 'github' });
-    let githubCi = null;
-    if (githubSpec) {
-      const { checkCiStatus } = await import('./lib/ci-status-banner.mjs');
-      githubCi = await checkCiStatus({ repoRoot, vcs: 'github', timeoutMs: 15000 });
-    }
-    const row = evaluateGithubCiRow(githubSpec, githubCi);
-    add('ci-green-on-head-github', row.ok, row.detail);
-  }
+  // 6/6b. CI green on HEAD, both platforms — judged for the commit actually
+  // being released, never whichever HEAD the queried platform reports (see
+  // evaluateCiPreflightRows's docblock for the `sha`-wiring history, #1332).
+  //
+  // GitLab: the repo's iron session-start rule applies to releases doubly —
+  // local green is not evidence — see .claude/rules. GitHub: this second row
+  // exists because `detectVcsFamily` picks `origin` (GitLab) for the row
+  // above, whose pipeline is Linux-only; the macOS matrix leg lives
+  // exclusively in `.github/workflows/test.yml`. `vcs: 'github'` forces the
+  // probe onto the mirror without touching the detection order.
+  // SELF-DISABLING: a checkout with no `github` remote has no mirror to be
+  // red, so `evaluateGithubCiRow` reports `skipped` rather than red — see its
+  // own docblock. --skip-ci is refused under --publish upstream in
+  // validateFlags(); it can only reach this branch from --check.
+  const ciRows = await evaluateCiPreflightRows(repoRoot, head, { skipCi });
+  add('ci-green-on-head', ciRows.gitlab.ok, ciRows.gitlab.detail);
+  add('ci-green-on-head-github', ciRows.github.ok, ciRows.github.detail);
 
   // 7. Leakage gate over the actual pack file list.
   // `npm_config_loglevel` is INHERITED, and `npm pack --dry-run` writes its whole