session-orchestrator 5.1.0 → 5.3.0

package/scripts/lib/reconcile/sanitize.mjs

@@ -198,8 +198,27 @@ export const LEARNING_KEY_RE = /^[a-z0-9/-]+$/;
 /** `expires-at:` — YYYY-MM-DD. A garbage value makes the loader's expiry gate FAIL OPEN. */
 export const EXPIRES_AT_RE = /^\d{4}-\d{2}-\d{2}$/;
 
-/** `learning-id` / `source-session` — rendered inside backticks, which an interior backtick would close. */
-export const PROVENANCE_TOKEN_RE = /^[A-Za-z0-9._:-]+$/;
+/**
+ * `learning-id` / `source-session` — rendered inside backticks, which an
+ * interior backtick would close.
+ *
+ * `/` is admitted since GH#71. A semantic session id is DERIVED FROM A BRANCH
+ * NAME, and branch names carry slashes — so the narrower class did not reject
+ * hostile text, it rejected a whole legitimate id family. The damage is silent
+ * and unbounded: `engine.mjs` degrades the throw to an audited rejection, so
+ * every learning from such a session is proposed on every run and rejected on
+ * every run, forever. Measured in THIS repo 2026-09-20 @ `9b118cf6`:
+ * `jq -r 'select(.session_id != null) | .session_id'
+ * .orchestrator/metrics/sessions.jsonl | grep -c '/'` → **3**, all of the
+ * `feat/operator-surface-2026-08-08-…` family; `git branch -a --format=…
+ * | grep -c '/'` → **6**. It hit two usable learnings in the reporting
+ * consumer's run (source: peer session eventdrop-at, 2026-09-20).
+ *
+ * Widening a SANITISER is only safe against a census of what the new character
+ * makes expressible at the call sites — see {@link assertNoPathEscape} for the
+ * one hazard `/` adds and for the four it does not.
+ */
+export const PROVENANCE_TOKEN_RE = /^[A-Za-z0-9._:/-]+$/;
 
 // The Unicode Control category (C0 + DEL + C1). Deliberately expressed as
 // `\p{Cc}` rather than a hand-written character class: an escape-written class
@@ -275,6 +294,51 @@ function rejection(field, why, value) {
   return new Error(`reconcile-sanitize: rejecting record — ${field} ${why} (got ${shown})`);
 }
 
+/**
+ * Reject the ONE hazard a `/` adds to a machine token: a path shape.
+ *
+ * Derived from the call sites, not from caution. Both slash-bearing patterns —
+ * {@link PROVENANCE_TOKEN_RE} and {@link LEARNING_KEY_RE} — route through
+ * {@link assertMachineToken}, so the guard lives in that ONE shared function
+ * rather than at each caller: one guard beats one-guard-per-call-site, and it
+ * covers the next caller of an EXPORTED assert by construction
+ * (`.claude/rules/build-value.md` BV-003).
+ *
+ * **What `/` does NOT make expressible**, so this guard deliberately does not
+ * re-check it (each is already structurally impossible in every pattern that
+ * admits a slash):
+ *
+ *   1. *Inline-code break-out.* Both provenance values render inside a backtick
+ *      span (`renderer.mjs:469-470`); a backtick is in no slash-bearing class.
+ *   2. *Frontmatter escape.* A newline would open a sibling top-level key — but
+ *      JS `$` without the `m` flag does not match before a trailing newline
+ *      (measured 2026-09-20: `/^[A-Za-z0-9._:-]+$/.test("abc\n")` → `false`),
+ *      so a trailing newline was and stays rejected.
+ *   3. *Wrapper forgery.* Every literal in {@link WRAPPER_FORGERY_LITERALS}
+ *      needs `<`, `>`, `#`, a space or `(` — none of them in these classes.
+ *   4. *Dangerous invisibles.* Cf code points are outside these classes too.
+ *
+ * Gated on a literal `/` being present, which makes the guard a provable no-op
+ * for every token shape accepted BEFORE the widening: without a separator there
+ * is no traversal to express, and `..` alone in a backtick span is inert text.
+ * Census over the live store 2026-09-20 @ `9b118cf6`: 0 of 263 learning-keys and
+ * 0 learning ids carry `..` or a leading `/`, so nothing legitimate is caught.
+ *
+ * @param {string} value  a value that already matched its pattern
+ * @param {string} field
+ * @returns {void}
+ * @throws {Error} on a leading `/` (absolute path) or any `..` (traversal)
+ */
+function assertNoPathEscape(value, field) {
+  if (!value.includes('/')) return;
+  if (value.startsWith('/')) {
+    throw rejection(field, 'must not start with "/" (absolute path)', value);
+  }
+  if (value.includes('..')) {
+    throw rejection(field, 'must not contain ".." (path traversal)', value);
+  }
+}
+
 /**
  * Assert that a machine value is a non-empty string matching `pattern`.
  * REJECTS (throws) rather than repairing — see the module doc's dividing line.
@@ -282,7 +346,8 @@ function rejection(field, why, value) {
  * @param {unknown} value
  * @param {{ field: string, pattern: RegExp }} opts
  * @returns {string} the value, unchanged, when it passes
- * @throws {Error} when the value is not a string or does not match `pattern`
+ * @throws {Error} when the value is not a string, does not match `pattern`, or
+ *   carries a path escape (see {@link assertNoPathEscape})
  */
 export function assertMachineToken(value, { field, pattern }) {
   if (typeof value !== 'string' || value === '') {
@@ -291,6 +356,7 @@ export function assertMachineToken(value, { field, pattern }) {
   if (!pattern.test(value)) {
     throw rejection(field, `must match ${pattern.source}`, value);
   }
+  assertNoPathEscape(value, field);
   return value;
 }
 

package/scripts/lib/reconcile-nudge-banner.mjs

@@ -45,6 +45,14 @@
  *   - `surfaceTopN` (`./learnings/surface.mjs`) — the canonical active-learning
  *     filter (confidence > floor, not expired); called with a large cap to get
  *     the full active set rather than a top-N slice.
+ *   - `countReconcileBacklog` (`./reconcile/backlog.mjs`) — the SAME eligibility +
+ *     materialization partition `/reconcile` applies, imported from the LEAF module
+ *     rather than from `./reconcile/engine.mjs`. The engine is WRITE-capable (it
+ *     merges the candidate store) and drags the emitter, renderer and unicode
+ *     validator behind it: importing the count from there took this probe's static
+ *     closure from 11 modules / 151,946 B to 19 / 322,897 B (+112 %, measured
+ *     2026-09-18), inherited unasked by `maintenance-due-banner.mjs`. A banner must
+ *     not be able to reach a writer.
  *   - `filterEligible` (`./reconcile/eligibility.mjs`) — the SAME type/file_paths
  *     allow-list gate the reconcile engine itself uses (deliberately NOT
  *     confidence-gated — mirrors `runReconcile`'s own posture, see
@@ -68,7 +76,7 @@ import { join } from 'node:path';
 
 import { readLearnings } from './learnings/io.mjs';
 import { surfaceTopN } from './learnings/surface.mjs';
-import { filterEligible } from './reconcile/eligibility.mjs';
+import { countReconcileBacklog } from './reconcile/backlog.mjs';
 import { loadCandidates } from './reconcile/idempotency.mjs';
 import { readConfigFile } from './config/io.mjs';
 import { _parseReconcile } from './config/reconcile.mjs';
@@ -82,9 +90,67 @@ export const NUDGE_MIN_LEARNINGS = 20;
 /** Nudge threshold (b): new learnings accrued since the last determinable reconcile run. */
 export const NUDGE_MIN_DELTA = 15;
 
-/** Nudge threshold (c): rule-eligible learnings (type + file_paths allow-list), regardless of confidence. */
+/**
+ * Nudge threshold (c): reconcile BACKLOG — rule-eligible learnings (type + file_paths
+ * allow-list, not expired, regardless of confidence) MINUS those already materialized
+ * in the idempotency sidecar or a `.claude/rules/` provenance marker. Counting the
+ * materialized ones too made the probe un-greenable (#1380: 98 eligible, 35 already
+ * materialized, and no `/reconcile` run could ever clear it).
+ */
 export const NUDGE_MIN_ELIGIBLE = 3;
 
+/**
+ * Resolve the `reconcile` Session Config settings this module needs, in ONE read.
+ *
+ * Both consumers go through here, so the nudge can never judge on a different
+ * population than `/reconcile` does: the skill reads `reconcile.min-insight-chars`
+ * (default 24) and forwards it to the engine, and so must this probe. Before #1380
+ * follow-up the value was only read AFTER the backlog had already been counted, which
+ * left the placeholder-insight gate practically OFF for the banner.
+ *
+ * Precedence: an injected already-parsed Session Config wins per KEY (DI seam, avoids a
+ * second CLAUDE.md read); any key it does not carry falls back to parsing
+ * CLAUDE.md/AGENTS.md; an unreadable config falls back to `_parseReconcile('')`, i.e.
+ * the parser's OWN documented defaults — never a literal repeated here.
+ *
+ * Never throws.
+ *
+ * @param {string} repoRoot
+ * @param {unknown} [config] already-parsed Session Config
+ * @returns {Promise<{enabled: boolean, minInsightChars: number}>}
+ */
+async function _resolveReconcileSettings(repoRoot, config) {
+  const injected =
+    config && typeof config === 'object' && /** @type {any} */ (config).reconcile &&
+    typeof (/** @type {any} */ (config).reconcile) === 'object'
+      ? /** @type {Record<string, unknown>} */ (/** @type {any} */ (config).reconcile)
+      : null;
+
+  const hasEnabled = injected !== null && typeof injected.enabled === 'boolean';
+  const hasChars = injected !== null && Number.isFinite(injected['min-insight-chars']);
+  if (hasEnabled && hasChars) {
+    return {
+      enabled: /** @type {boolean} */ (injected.enabled),
+      minInsightChars: Number(injected['min-insight-chars']),
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = _parseReconcile(await readConfigFile(repoRoot));
+  } catch {
+    // Config unreadable — take the parser's own defaults (single source of truth).
+    parsed = _parseReconcile('');
+  }
+
+  return {
+    enabled: hasEnabled ? /** @type {boolean} */ (injected.enabled) : parsed.enabled,
+    minInsightChars: hasChars
+      ? Number(injected['min-insight-chars'])
+      : parsed['min-insight-chars'],
+  };
+}
+
 /**
  * Resolve the max `created_at` across reconcile-candidate sidecar records —
  * the most recent reconcile run's timestamp, or `null` when no run is on
@@ -110,11 +176,19 @@ function _lastRunAt(candidates) {
  *
  * @param {object} [opts]
  * @param {string} [opts.repoRoot] — project root (defaults to process.cwd()).
- * @param {Date|number} [opts.now] — injectable clock, forwarded to the active-learning filter.
+ * @param {Date|number} [opts.now] — injectable clock, forwarded to the active-learning
+ *   filter AND the eligibility expiry gate.
+ * @param {number} [opts.minInsightChars] — forwarded to the eligibility filter. When
+ *   OMITTED the value is read from Session Config (`reconcile.min-insight-chars`,
+ *   default 24) rather than left inert, so the nudge and `/reconcile` count the SAME
+ *   population — see `_resolveReconcileSettings`.
+ * @param {object} [opts.config] — optional already-parsed Session Config (DI seam).
  * @returns {Promise<{
  *   totalLearnings: number,
  *   activeLearnings: number,
  *   eligibleCount: number,
+ *   alreadyMaterialized: number,
+ *   backlogCount: number,
  *   lastRunAt: string|null,
  *   lastRunCandidateCount: number,
  *   delta: number,
@@ -131,6 +205,8 @@ export async function computeReconcileNudge(opts = {}) {
     totalLearnings: 0,
     activeLearnings: 0,
     eligibleCount: 0,
+    alreadyMaterialized: 0,
+    backlogCount: 0,
     lastRunAt: null,
     lastRunCandidateCount: 0,
     delta: 0,
@@ -166,20 +242,29 @@ export async function computeReconcileNudge(opts = {}) {
 
   if (active.length === 0) return empty;
 
-  let eligibleCount;
-  try {
-    eligibleCount = filterEligible(entries).eligible.length;
-  } catch {
-    eligibleCount = 0;
-  }
+  // Same partition a real /reconcile run applies (engine.mjs step 3/3a) — one
+  // truth, so the nudge can only fire on work /reconcile is able to clear.
+  // That includes the placeholder-insight gate: when the caller did not supply
+  // `minInsightChars`, read it from Session Config BEFORE counting, or the
+  // banner counts learnings `/reconcile` would reject.
+  const minInsightChars = Number.isFinite(opts.minInsightChars)
+    ? Number(opts.minInsightChars)
+    : (await _resolveReconcileSettings(repoRoot, opts.config)).minInsightChars;
 
+  // The candidate store is read ONCE, BEFORE the backlog count — the count needs
+  // the same records for its sidecar-dedupe half, and reading them here lets it
+  // be handed down instead of read a second time (`candidatesRead` says whether
+  // the hand-down is trustworthy; on a failed read we hand nothing down and let
+  // `countReconcileBacklog` decide for itself rather than pass a fake empty set).
   /** @type {Array<Record<string, unknown>>} */
   let candidates;
   /** @type {number|undefined} */
   let skippedCandidates;
+  let candidatesRead = false;
   try {
     const diag = loadCandidates({ repoRoot });
     candidates = Array.isArray(diag?.records) ? diag.records : [];
+    candidatesRead = Array.isArray(diag?.records);
     // Absence-preserving, mirroring `engine.mjs` `summary.skipped`: only a
     // finite count means "the store was inspected". Absent ⇒ never checked,
     // 0 ⇒ checked and clean.
@@ -190,6 +275,25 @@ export async function computeReconcileNudge(opts = {}) {
     // fabricating a clean 0.
   }
 
+  // ONE corpus, ONE population. `entries` (read above via `readLearnings`) is
+  // handed down instead of letting the count re-read and re-normalize the same
+  // file: the banner line names `activeLearnings` and `backlogCount` side by
+  // side, and two independent reads of one file are two populations wearing one
+  // sentence (HR-106). `repoRoot` stays required — the sidecar and the
+  // `.claude/rules/` provenance scan are resolved from it.
+  // Never throws (all-zero on failure).
+  const {
+    eligible: eligibleCount,
+    alreadyMaterialized,
+    backlog: backlogCount,
+  } = countReconcileBacklog({
+    repoRoot,
+    learnings: entries,
+    ...(candidatesRead ? { existingCandidates: candidates } : {}),
+    now: opts.now,
+    minInsightChars,
+  });
+
   const lastRunAt = _lastRunAt(candidates);
   const lastRunCandidateCount = Array.isArray(candidates) ? candidates.length : 0;
   const delta = entries.length - lastRunCandidateCount;
@@ -213,15 +317,18 @@ export async function computeReconcileNudge(opts = {}) {
   if (lastRunAt !== null && delta > NUDGE_MIN_DELTA) {
     reasons.push(`${delta} new learnings since the last reconcile run`);
   }
-  // (c) — enough rule-eligible learnings to be worth a batch, independent of confidence.
-  if (eligibleCount >= NUDGE_MIN_ELIGIBLE) {
-    reasons.push(`${eligibleCount} rule-eligible learnings`);
+  // (c) — enough NOT-YET-MATERIALIZED rule-eligible learnings to be worth a
+  // batch, independent of confidence. HR-106: the reason names the number judged.
+  if (backlogCount >= NUDGE_MIN_ELIGIBLE) {
+    reasons.push(`${backlogCount} rule-eligible learnings awaiting a rule`);
   }
 
   const computed = {
     totalLearnings: entries.length,
     activeLearnings: active.length,
     eligibleCount,
+    alreadyMaterialized,
+    backlogCount,
     lastRunAt,
     lastRunCandidateCount,
     delta,
@@ -236,25 +343,6 @@ export async function computeReconcileNudge(opts = {}) {
   return computed;
 }
 
-/**
- * Best-effort extraction of `reconcile.enabled` from an already-parsed Session
- * Config object (DI/test seam — avoids re-reading CLAUDE.md when the caller
- * already has it). Returns `null` when unresolvable from `config` alone, in
- * which case `checkReconcileNudge` falls back to reading CLAUDE.md/AGENTS.md.
- *
- * @param {unknown} config
- * @returns {boolean|null}
- */
-function _reconcileEnabledFromConfig(config) {
-  if (config && typeof config === 'object') {
-    const rc = /** @type {Record<string, unknown>} */ (config).reconcile;
-    if (rc && typeof rc === 'object' && typeof (/** @type {any} */ (rc).enabled) === 'boolean') {
-      return /** @type {any} */ (rc).enabled;
-    }
-  }
-  return null;
-}
-
 /**
  * Check reconcile-nudge readiness and produce a session-start banner.
  *
@@ -274,26 +362,30 @@ export async function checkReconcileNudge(opts = {}) {
     const { repoRoot, config, now } = opts;
     if (!repoRoot || typeof repoRoot !== 'string') return null;
 
+    // ONE config read for both settings, BEFORE the backlog is counted — the
+    // `min-insight-chars` gate must reach `countReconcileBacklog`, and reading the
+    // config afterwards (as this did before) left it inert.
+    let reconcileEnabled = false;
+    let minInsightChars;
+    try {
+      ({ enabled: reconcileEnabled, minInsightChars } = await _resolveReconcileSettings(
+        repoRoot,
+        config,
+      ));
+    } catch {
+      // Unreachable in practice (_resolveReconcileSettings never throws) — keep the
+      // conservative default and let computeReconcileNudge resolve the gate itself.
+      reconcileEnabled = false;
+    }
+
     let computed;
     try {
-      computed = await computeReconcileNudge({ repoRoot, now });
+      computed = await computeReconcileNudge({ repoRoot, now, minInsightChars });
     } catch {
       return null;
     }
     if (!computed || computed.nudge !== true) return null;
 
-    let reconcileEnabled = _reconcileEnabledFromConfig(config);
-    if (reconcileEnabled === null) {
-      try {
-        const content = await readConfigFile(repoRoot);
-        reconcileEnabled = _parseReconcile(content).enabled;
-      } catch {
-        // Config unreadable — fall back to the documented config default (false)
-        // so the informational parenthetical still renders conservatively.
-        reconcileEnabled = false;
-      }
-    }
-
     // Three-state last-run label. `never` is a claim about history and must only
     // be made when the store was inspected and held nothing: a store whose lines
     // were quarantined by the shape guard is EVIDENCE OF A RUN that can no longer
@@ -323,7 +415,8 @@ export async function checkReconcileNudge(opts = {}) {
     }
 
     const lines = [
-      `⚠ reconcile-nudge: ${computed.activeLearnings} active learnings, ${computed.eligibleCount} rule-eligible, ` +
+      `⚠ reconcile-nudge: ${computed.activeLearnings} active learnings, ${computed.backlogCount} rule-eligible awaiting a rule ` +
+        `(${computed.alreadyMaterialized} already materialized), ` +
         `last reconcile run: ${lastRunLabel} — run /reconcile to convert learnings into rules.`,
     ];
     if (reconcileEnabled === false) {

package/scripts/lib/resource-probe/parsers.mjs

@@ -30,6 +30,37 @@ export function parseEtimeToMinutes(etime) {
   return days * 24 * 60 + hours * 60 + mins;
 }
 
+/**
+ * Parse a `ps` etime field (`[[DD-]HH:]MM:SS`) into whole SECONDS.
+ *
+ * Twin of {@link parseEtimeToMinutes}, which drops the seconds field because
+ * minute resolution is all the zombie counter needs. The orphan reaper
+ * (`scripts/lib/orphan-reaper.mjs`) cannot use that: its minimum age is 300
+ * seconds and its identity check reconstructs a start time as
+ * `now - etimeSeconds * 1000`, where a discarded seconds field would be a
+ * systematic error of up to 59 s against a 2 s tolerance.
+ *
+ * Deliberately a sibling rather than a refactor of the twin: `parseEtimeToMinutes`
+ * has live callers (`countZombieProcesses`) whose behaviour must not shift.
+ *
+ * Returns null when the format is unrecognised. Pure function.
+ * @param {string} etime
+ * @returns {number|null}
+ */
+export function parseEtimeToSeconds(etime) {
+  if (typeof etime !== 'string') return null;
+  const s = etime.trim();
+  // Same shape as parseEtimeToMinutes: optional "DD-", optional "HH:", then "MM:SS".
+  const m = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/.exec(s);
+  if (!m) return null;
+  const days = parseInt(m[1] ?? '0', 10);
+  const hours = parseInt(m[2] ?? '0', 10);
+  const mins = parseInt(m[3], 10);
+  const secs = parseInt(m[4], 10);
+  if ([days, hours, mins, secs].some(Number.isNaN)) return null;
+  return days * 86400 + hours * 3600 + mins * 60 + secs;
+}
+
 /**
  * Parse the detailed ps output and count Claude/Node zombie candidates.
  * A zombie candidate is a process matching "claude" or "node" that:

package/scripts/lib/rule-loader.mjs

@@ -11,8 +11,9 @@
  * when at least one `scopePath` matches at least one glob pattern.
  *
  * `paths:` is a same-shape alias for `globs:` (issue #795) — some repos use a
- * `paths:` frontmatter convention instead of `globs:` (e.g. projects-baseline:
- * 26 rule files, all `paths:`, 0 `globs:`). Before #795 these repos'
+ * `paths:` frontmatter convention instead of `globs:` (projects-baseline did
+ * when #795 landed; it now carries both keys — measured count:
+ * docs/baseline.md). Before #795 these repos'
  * path-scoped rules were silently misclassified as always-on, inflating the
  * `instruction-budget-guard.mjs` (#687) always-on count with a false positive.
  * `paths:` supports the identical inline-array and block-list forms as
@@ -365,6 +366,35 @@ function metaToEntryFields(meta) {
   return out;
 }
 
+/**
+ * The expiry predicate, shared by the injection gate below and the `/reconcile`
+ * provenance reader (`scripts/lib/reconcile/backlog.mjs`) — one `Date.parse`
+ * for both, so "expired" can never mean two different things to the two
+ * consumers (#1387).
+ *
+ * FAIL-OPEN by design: an absent, empty or unparseable `expires-at` is NOT
+ * expired. Fail-closed here would un-inject (and, in the reconcile reader,
+ * un-materialize) the whole corpus on a single typo.
+ *
+ * Pure apart from the optional `onUnparseable` callback, which exists so the
+ * injection path can keep its stderr WARN while the reconcile reader stays
+ * silent.
+ *
+ * @param {unknown} rawExpiry - the raw `expires-at` frontmatter value (or undefined)
+ * @param {number} [now] - epoch ms; defaults to `Date.now()`
+ * @param {(raw: unknown) => void} [onUnparseable] - called when `expires-at` is present but unparseable
+ * @returns {boolean} true only when a PARSEABLE `expires-at` lies before `now`
+ */
+export function isRuleExpired(rawExpiry, now = Date.now(), onUnparseable) {
+  if (rawExpiry === undefined || rawExpiry === null) return false;
+  const ts = Date.parse(String(rawExpiry));
+  if (Number.isNaN(ts)) {
+    if (typeof onUnparseable === 'function') onUnparseable(rawExpiry);
+    return false;
+  }
+  return ts < now;
+}
+
 /**
  * Deterministic gating check (issue #694 + #692). Returns `{ excluded: boolean,
  * reason?: string }`. Applied to BOTH always-on and glob-matched rules.
@@ -378,18 +408,17 @@ function metaToEntryFields(meta) {
  * @returns {{ excluded: boolean }}
  */
 function applyGates(meta, filePath, mode, hostClass, now, context = null) {
-  // Expiry gate — fail-open on a malformed `expires-at`.
+  // Expiry gate — fail-open on a malformed `expires-at` ({@link isRuleExpired}).
   if (Object.prototype.hasOwnProperty.call(meta, 'expires-at')) {
     const rawExpiry = meta['expires-at'];
-    const ts = Date.parse(String(rawExpiry));
-    if (Number.isNaN(ts)) {
-      process.stderr.write(
-        `[rule-loader] Rule ${filePath} has unparseable expires-at ${JSON.stringify(rawExpiry)} — ignoring expiry\n`,
-      );
-    } else if (ts < now) {
-      process.stderr.write(
-        `[rule-loader] Rule ${filePath} expired at ${rawExpiry} — excluded\n`,
-      );
+    if (
+      isRuleExpired(rawExpiry, now, (raw) =>
+        process.stderr.write(
+          `[rule-loader] Rule ${filePath} has unparseable expires-at ${JSON.stringify(raw)} — ignoring expiry\n`,
+        ),
+      )
+    ) {
+      process.stderr.write(`[rule-loader] Rule ${filePath} expired at ${rawExpiry} — excluded\n`);
       return { excluded: true };
     }
   }

package/scripts/lib/rules-sync.mjs

@@ -10,6 +10,7 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join, basename, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { validateRuleContent, scanVendoringLeaks } from './validate-vendored-rules.mjs';
+import { isMainModule } from './is-main-module.mjs';
 
 // The vendoring sanitizer (issue #1098) lives in validate-vendored-rules.mjs —
 // it has that module's shape ("judge one rule file → findings") and its
@@ -451,11 +452,7 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 // Detect direct execution: node scripts/lib/rules-sync.mjs
-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);
 
 if (isMain) {
   const args = process.argv.slice(2);