session-orchestrator 5.1.0 → 5.2.0

package/scripts/lib/is-main-module.mjs

@@ -0,0 +1,82 @@
+/**
+ * is-main-module.mjs — the one entry-guard predicate, symlink-safe.
+ *
+ * ## The incident class
+ *
+ * An ESM module that wants to run `main()` only when invoked as a CLI has to
+ * compare "the module I am" against "the script Node was told to run". The two
+ * sides are NOT the same kind of path:
+ *
+ *   - `import.meta.url` is resolved by Node to the module's **realpath**.
+ *   - `process.argv[1]` is the path **as typed on the command line**.
+ *
+ * With a symlink anywhere in the invocation path — a `node_modules/.bin/` shim,
+ * a `~/bin/foo -> /repo/scripts/foo.mjs` convenience link, a plugin directory
+ * symlinked into `~/.claude/plugins/`, or `/tmp` itself (on macOS `/tmp` is a
+ * symlink to `/private/tmp`) — the two strings differ and the guard is FALSE.
+ *
+ * The failure is silent and total: `main()` never runs, nothing is printed, and
+ * the process exits 0. Every caller — a hook, a CI job, an npm script, an
+ * operator — reads that as success. This is the single worst shape a defect can
+ * have in this repo, which is why the predicate is centralised here instead of
+ * being re-typed per file.
+ *
+ * ## The textual variants this replaces
+ *
+ * Measured 2026-09-16 @ ca214376 over the 50 files swept for #1371, the guard
+ * had been hand-written in 15 distinct textual forms (measured by extracting the
+ * guard expression from every file at HEAD), collapsing into four
+ * semantic variants — all four wrong in the same way:
+ *
+ *   V1  import.meta.url === `file://${process.argv[1]}`
+ *       (also breaks on any space or non-ASCII char in the path — no escaping)
+ *   V2  import.meta.url === pathToFileURL(process.argv[1] ?? '').href
+ *   V3  resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))
+ *       / resolve(process.argv[1]) === resolve(__filename)
+ *   V4  fileURLToPath(import.meta.url) === process.argv[1]
+ *
+ * V2/V3 fix the `undefined`-argv and relative-path cases; none of them resolve
+ * symlinks, because only `realpath` does.
+ *
+ * ## Non-goal: Windows drive-letter / case folding
+ *
+ * `realpathSync.native` delegates to the OS, so on NTFS it canonicalises the
+ * stored casing of every path component and the two sides agree. Where the
+ * realpath call FAILS (deleted path, permission error) the fallback is a raw
+ * string compare, which on Windows can be case-sensitive against a
+ * case-insensitive filesystem. That residual case is deliberately out of scope:
+ * this repo runs on macOS and Linux CI, and a case-only mismatch degrades to
+ * today's behaviour rather than to something worse.
+ *
+ * @module scripts/lib/is-main-module
+ */
+
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Whether the module identified by `importMetaUrl` is the script Node was
+ * invoked with.
+ *
+ * Symlink-safe: both sides are canonicalised via `realpathSync.native` before
+ * comparison, so an invocation through a symlink (shim, `~/bin` link, `/tmp` on
+ * macOS) still matches. When either path cannot be realpath'd — it was deleted
+ * between spawn and this call, or is unreadable — the comparison degrades to a
+ * raw string compare rather than throwing, because an entry guard must never be
+ * the thing that crashes an import.
+ *
+ * @param {string} importMetaUrl the calling module's `import.meta.url`
+ * @param {string | undefined} [argv1] the invoked script path; defaults to
+ *   `process.argv[1]`, which is `undefined` under `node -e`, the REPL and some
+ *   dynamic-import contexts — those return `false`
+ * @returns {boolean} true when this module IS the entrypoint
+ */
+export function isMainModule(importMetaUrl, argv1 = process.argv[1]) {
+  if (!argv1) return false;
+  const self = fileURLToPath(importMetaUrl);
+  try {
+    return realpathSync.native(argv1) === realpathSync.native(self);
+  } catch {
+    return argv1 === self;
+  }
+}

package/scripts/lib/locks/index.mjs

@@ -1,31 +1,38 @@
 /**
- * locks/index.mjs — convenience barrel for the short-lived lock protocols split
- * out of session-lock.mjs in #630 (A1 barrel-preserving split).
+ * locks/index.mjs — DEPRECATED convenience barrel for the lock protocols
+ * split out of session-lock.mjs in #630 (A1 barrel-preserving split).
  *
- * Re-exports both protocol modules so a consumer can `import { withStateMdLock,
- * withStagingFenceLock } from '@lib/locks/index.mjs'` in one statement. This is
- * a nice-to-have: session-lock.mjs remains the canonical barrel that preserves
- * the original 22-symbol import surface, and the two protocol modules are also
- * importable directly.
+ * @deprecated since 5.2.0, removed in 6.0.0. Import directly from
+ * `./state-md-lock.mjs` / `./staging-fence-lock.mjs`, or from
+ * `scripts/lib/session-lock.mjs` for the canonical 22-symbol barrel that
+ * preserves the original import surface for all its importers.
  *
- * Pure re-export leaf — imports only the two sibling modules, never
- * session-lock.mjs, so there is no import cycle.
+ * This file shipped in 5.1.0 with zero in-repo importers and was deleted in
+ * dd05e0f8 (`check-unwired-features` S4: no hook, npm script, CI job or husky
+ * stage reached it, and it named symbols — not modules — so it did not qualify
+ * for the pure `export *` exemption that shape gets). Restored here as a
+ * one-cycle deprecation shim (`.claude/rules/development.md` § Package Lifecycle
+ * & Versioning) because `package.json` carries no `exports` map: every packed
+ * file under `scripts/lib/` is public, so a consumer that deep-imported this
+ * path before the deletion has no compile error to warn it, only a runtime
+ * "module not found" — a shim buys that consumer one minor cycle to migrate
+ * before 6.0.0 removes the path outright.
+ *
+ * Deliberately the `export *` form with ZERO named exports (matches the
+ * `scripts/lib/autopilot-telemetry.mjs` precedent): a named-export re-export
+ * barrel is exactly the shape `check-unwired-features.mjs` S4 flags as an
+ * unreachable library module (condition 4 in `collectUnreachableLibraryModules`
+ * requires named exports before a re-export shim over live code enters that
+ * census) — that flag is what got this file deleted the first time. A star
+ * re-export names no symbol, so the shim reads as `exports: []` and stays
+ * invisible to that census while its target modules stay reachable through it.
  */
 
-export {
-  STATE_LOCK_PATH,
-  DEFAULT_STATE_LOCK_TIMEOUT_MS,
-  STATE_LOCK_POLL_MS,
-  acquireStateLock,
-  releaseStateLock,
-  withStateMdLock,
-} from './state-md-lock.mjs';
+console.warn(
+  '[deprecated] scripts/lib/locks/index.mjs is deprecated since 5.2.0 and will be removed in 6.0.0 — ' +
+    "import from './state-md-lock.mjs' / './staging-fence-lock.mjs' directly, or from " +
+    'scripts/lib/session-lock.mjs for the canonical surface.',
+);
 
-export {
-  STAGING_FENCE_LOCK_PATH,
-  DEFAULT_STAGING_FENCE_LOCK_TIMEOUT_MS,
-  STAGING_FENCE_LOCK_POLL_MS,
-  acquireStagingFenceLock,
-  releaseStagingFenceLock,
-  withStagingFenceLock,
-} from './staging-fence-lock.mjs';
+export * from './state-md-lock.mjs';
+export * from './staging-fence-lock.mjs';

package/scripts/lib/maintenance-due-banner.mjs

@@ -20,7 +20,7 @@
  * ## Design constraints it is written against
  *
  * - **HR-101 (a signal may only warn if it is rare).** Nothing is due ⇒ the
- *   probe is SILENT. Six independent signals are ANDed with a cooldown, not
+ *   probe is SILENT. Seven independent signals are ANDed with a cooldown, not
  *   ORed into a permanent warning: a repo that ran `/session housekeeping`
  *   within the last {@link HOUSEKEEPING_COOLDOWN_DAYS} days says nothing at
  *   all, because the operator already did the thing the banner would ask for.
@@ -33,7 +33,7 @@
  *   an existing module constant. Same posture as `reconcile-nudge-banner.mjs`
  *   and `loop-readiness-banner.mjs`: an advisory banner needs no switch.
  *
- * ## The six signals
+ * ## The seven signals
  *
  * | id                | due when                                                              | source |
  * |-------------------|-----------------------------------------------------------------------|--------|
@@ -43,6 +43,20 @@
  * | `dialectic`       | `shouldDispatchAutoDialectic().trigger === true`                      | `auto-dialectic.mjs` |
  * | `memory-cleanup`  | `shouldDispatchAutoDream().trigger === true`                          | `auto-dream.mjs` |
  * | `pending-sidecar` | a pending dream/dialectic proposal younger than 14 days is unapplied   | `.orchestrator/*-pending*.md` |
+ * | `generated-rules-expiring` | a machine-generated rule is expired or expires within {@link GENERATED_RULE_EXPIRY_HORIZON_DAYS} days | `instruction-budget-guard.mjs` |
+ *
+ * ### Why the expiry alarm is HERE and not in the test suite (#1372 follow-up)
+ *
+ * The invariant "no generated rule file sits expired in `.claude/rules/`" was
+ * first written as a vitest case comparing `expires-at` against TODAY. That is
+ * a calendar time-bomb in a BLOCKING gate: with nothing committed and nothing
+ * broken, `npm test` — pre-push hook and CI alike — turns red on the morning
+ * after the earliest date and blocks every unrelated hotfix, while the repair
+ * (consolidate the file, move its provenance pairs, delete it) is a human
+ * decision no test run can take. HR-101/HR-105: a signal must fire when
+ * something CHANGED, at a moment the operator can act, and be repairable by the
+ * thing that fires it. Session start, recommending `/session housekeeping`, is
+ * that moment; the predicate itself is still tested, against an INJECTED clock.
  *
  * Only SIDE-EFFECT-FREE signal functions are called — never a variant that
  * advances `.orchestrator/dialectic-last-run`, because a probe that writes the
@@ -66,13 +80,32 @@ import { shouldDispatchAutoDream } from './auto-dream.mjs';
 import { resolveMemoryDir } from './memory-paths.mjs';
 import { readCanonicalSessions } from './sessions-canonical.mjs';
 import { filterRealSessions } from './session-schema.mjs';
+import {
+  daysUntilGeneratedRuleExpiry,
+  listMachineGeneratedRules,
+} from './instruction-budget-guard.mjs';
 
 /**
  * How many signals this probe knows about. The banner denominator is this
  * number MINUS the signals a kill-switch skipped on this host — see the
  * `skipped` array in {@link computeMaintenanceDue}'s result.
  */
-export const MAINTENANCE_TOTAL_SIGNALS = 6;
+export const MAINTENANCE_TOTAL_SIGNALS = 7;
+
+/**
+ * How far ahead the `generated-rules-expiring` signal looks.
+ *
+ * NAMED CEILING (BV-004): 7 days is one week of sessions — long enough that the
+ * operator meets the warning before the loader silently starts dropping the
+ * rule, short enough that it is not standing noise (HR-104: a signal that is
+ * essentially always present is no signal). On this repo's corpus at
+ * 2026-09-16 the earliest `expires-at` was 14 days out, so the row is silent.
+ *
+ * REVISIT TRIGGER: if the row is due on more than ~1 session start in 10, the
+ * horizon is measuring the reconcile engine's 30-day default TTL rather than an
+ * overdue consolidation — re-aim it (HR-101), never widen it.
+ */
+export const GENERATED_RULE_EXPIRY_HORIZON_DAYS = 7;
 
 /**
  * Active-learning floor for the `evolve` signal. Deliberately the SAME number
@@ -391,6 +424,39 @@ export async function computeMaintenanceDue(opts = {}) {
     undeterminable.push('pending-sidecar');
   }
 
+  // --- generated-rules-expiring (S7) ---------------------------------------
+  // The predicate and the population both come from `instruction-budget-guard`,
+  // which is where the generated corpus is DEFINED (its byte ceiling judges the
+  // same set). A local re-implementation would be a second definition of
+  // "machine-generated" that agrees only until one of the two is edited.
+  try {
+    const listed = listMachineGeneratedRules({ repoRoot });
+    if (!listed.ok) {
+      // The directory is there but unreadable — not knowing is not clean.
+      undeterminable.push('generated-rules-expiring');
+    } else {
+      const expiring = listed.rules
+        .map((r) => ({ ...r, days: daysUntilGeneratedRuleExpiry({ meta: r.meta, now }) }))
+        .filter((r) => r.days !== null && r.days <= GENERATED_RULE_EXPIRY_HORIZON_DAYS)
+        .sort((a, b) => a.days - b.days);
+      if (expiring.length > 0) {
+        // HR-106: name the files and the dates the verdict was computed from —
+        // the operator has to open exactly those files to repair this.
+        // HR-106 again, one step further: name the REPAIR, not only the
+        // finding. The sweep (#1377) is the mechanical half — prose out, the
+        // provenance pair kept as `markers only` — and an operator who is told
+        // only which files expired has to rediscover that the command exists.
+        markDue(
+          'generated-rules-expiring',
+          `${expiring.map((r) => `${r.file} ${r.expiresAt}`).join(', ')} → ` +
+            'node scripts/sweep-expired-rules.mjs (dry-run first)',
+        );
+      }
+    }
+  } catch {
+    undeterminable.push('generated-rules-expiring');
+  }
+
   return {
     due,
     // HR-106: the denominator counts the signals this host actually EVALUATED.

package/scripts/lib/peer-discovery.mjs

@@ -68,6 +68,7 @@ import { readLock, isLockLive, LOCK_PATH } from './session-lock.mjs';
 import { checkPeerStateMd } from './state-md-peer-guard.mjs';
 import { listWorktreesChecked } from './worktree/listing.mjs';
 import { parseSessionId } from './session-id.mjs';
+import { isMainModule } from './is-main-module.mjs';
 
 /** Closed enum of provenance sources. */
 const SOURCE_DISCOVERED = 'discovered'; // lock + registry unified (irreversibly merged upstream)
@@ -901,11 +902,7 @@ async function _cliMain(argv) {
 }
 
 const __filename = fileURLToPath(import.meta.url);
-const _isCliMain =
-  typeof process !== 'undefined'
-  && process.argv[1] !== null
-  && process.argv[1] !== undefined
-  && path.resolve(process.argv[1]) === path.resolve(__filename);
+const _isCliMain =isMainModule(import.meta.url);
 
 // Called WITHOUT `await` on purpose: a top-level await would make this module
 // async for every importer, and `_cliMain` cannot reject (all paths are caught

package/scripts/lib/playwright-driver/runner.mjs

@@ -32,6 +32,7 @@ import path from 'node:path';
 import { parseArgs } from 'node:util';
 import { getProfile, loadProfiles, validateProfile } from '../profiles/registry.mjs';
 import { validatePathInsideProject } from '../path-utils.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
 // ---------------------------------------------------------------------------
 // Path resolution helper
@@ -349,7 +350,7 @@ export default async function run(opts = {}) {
 // CLI entry-point
 // ---------------------------------------------------------------------------
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   run().catch((err) => {
     console.error(`runner: unhandled error — ${err.message}`);
     process.exit(2);