session-orchestrator 3.20.0 → 3.21.0

package/hooks/enforce-scope.mjs

@@ -20,6 +20,12 @@
  *   G7  relative path matches an allowedPaths pattern
  *   G8  (all passed) → allow
  *
+ * Empty-allowedPaths reasoning (#1057): the VERDICT for an empty allowlist is
+ * unchanged (deny-all, the #256 contract), but the deny REASON is now classified
+ * — Discovery's read-only contract, an unreadable manifest, a crashed session's
+ * leftover, an incomplete `--union`, or undecidable. See
+ * `scripts/lib/scope-gate.mjs` § Empty-`allowedPaths` classification.
+ *
  * Exit codes:  0 = allow   2 = deny
  *
  * SECURITY notes (inline refs):
@@ -88,6 +94,10 @@ let findScopeFile;
 let pathMatchesPattern;
 let suggestForScopeViolation;
 let readJson;
+// #1057 — empty-`allowedPaths` classification + the session clock it needs.
+let classifyEmptyScope;
+let suggestForEmptyScope;
+let sessionStartedAtMs;
 
 const PLUGIN_ROOT = path.resolve(import.meta.dirname, '..');
 
@@ -137,6 +147,13 @@ async function bootstrap() {
       platform: { specifier: lib('platform.mjs') },
       hardening: { specifier: lib('hardening.mjs') },
       common: { specifier: lib('common.mjs') },
+      // #1057. Bound DIRECTLY rather than through the `hardening.mjs` barrel:
+      // that barrel re-exports an explicit, frozen symbol list shared by six
+      // hooks, and widening it for one hook's need would drag three symbols
+      // into five unrelated import surfaces. `hardening` already imports
+      // `scope-gate` transitively, so this adds no new failure mode — a broken
+      // scope-gate already banners GUARD INACTIVE through that edge.
+      scopeGate: { specifier: lib('scope-gate.mjs') },
     },
     {
       hookName: HOOK_NAME,
@@ -151,6 +168,7 @@ async function bootstrap() {
   ({ resolveProjectDir } = modules.platform);
   ({ findScopeFile, pathMatchesPattern, suggestForScopeViolation } = modules.hardening);
   ({ readJson } = modules.common);
+  ({ classifyEmptyScope, suggestForEmptyScope, sessionStartedAtMs } = modules.scopeGate);
 }
 
 async function main() {
@@ -183,15 +201,31 @@ async function main() {
   if (!scopePath) return emitAllow();
 
   // SECURITY-REQ-08: read scope file once; pass parsed object to all subsequent checks
+  //
+  // #1057: `parseOk` records WHETHER that read produced a usable scope RECORD.
+  // Both fold-to-`{}` / fold-to-`[]` paths (corrupt JSON #794 GAP-5, malformed
+  // shapes #558) already deny and CONTINUE to deny — the flag exists so the deny
+  // REASON can say "the manifest is broken" instead of "update the session plan
+  // and restart the wave", which is the one instruction that cannot help here.
   let scope;
+  let parseOk = true;
   try {
     scope = await readJson(scopePath);
+    if (scope === null || typeof scope !== 'object' || Array.isArray(scope)) {
+      parseOk = false;
+      scope = {};
+    }
   } catch {
+    parseOk = false;
     scope = {};
   }
 
   const enforcement = scope.enforcement ?? 'strict';
   const allowedPaths = Array.isArray(scope.allowedPaths) ? scope.allowedPaths : [];
+  // A PRESENT-but-non-array `allowedPaths` (#558: null / string / object) is a
+  // MALFORMED record, not an empty grant — same class as unparseable JSON, so it
+  // earns the same reason. Absent is different and stays `parseOk`.
+  if (scope.allowedPaths !== undefined && !Array.isArray(scope.allowedPaths)) parseOk = false;
   const gatesEnabled = scope.gates?.['path-guard'] !== false;
 
   // Gate 4: path-guard gate explicitly disabled
@@ -200,6 +234,48 @@ async function main() {
   // Gate 5: enforcement is turned off
   if (enforcement === 'off') return emitAllow();
 
+  // -------------------------------------------------------------------------
+  // #1057 — WHY is the allowlist empty?
+  //
+  // FIVE repo states produce `allowedPaths.length === 0` and the DENY IS RIGHT
+  // IN ALL FIVE; only the instruction differs (Discovery's read-only contract,
+  // a corrupt manifest, a crashed session's leftover, an incomplete `--union`,
+  // or genuinely undecidable). This block is therefore VERDICT-NEUTRAL: it
+  // selects a sentence, never a decision — `suggest()` below is the only
+  // consumer, and its `'unknown'` branch is byte-identical to the pre-#1057 text.
+  //
+  // Computed AFTER the early-exit gates (a disabled or `off` wave pays no
+  // fs.stat) and BEFORE the first deny site, so all three deny sites share one
+  // explanation instead of drifting apart.
+  // -------------------------------------------------------------------------
+  const emptyScopeReason =
+    allowedPaths.length === 0
+      ? classifyEmptyScope({
+          role: scope.role,
+          parseOk,
+          scopeMtimeMs: await mtimeMsOf(scopePath),
+          sessionStartMs: sessionStartedAtMs(projectRoot),
+        })
+      : null;
+  const scopeRelRaw = relativeFromRoot(projectRoot, scopePath);
+  const scopeHint = (scopeRelRaw ?? scopePath).split(path.sep).join('/');
+
+  /**
+   * The suggestion half of every deny below.
+   *
+   * With a NON-empty allowlist this is byte-identical to the pre-#1057 call.
+   * With an empty one it routes through the classifier — whose `'unknown'`
+   * branch delegates back to `suggestForScopeViolation(target, '')`, i.e. the
+   * same sentence as before. Strictly an addition.
+   *
+   * @param {string} target
+   * @returns {string}
+   */
+  const suggest = (target) =>
+    emptyScopeReason === null
+      ? suggestForScopeViolation(target, allowedPaths.join(', '))
+      : suggestForEmptyScope(target, emptyScopeReason, { role: scope.role, scopePath: scopeHint });
+
   // SECURITY-REQ-06: resolve relative file_path against projectRoot, not process.cwd()
   const absPathInput = path.isAbsolute(filePath)
     ? filePath
@@ -264,7 +340,7 @@ async function main() {
   // Gate 6: path must be inside the project root
   if (!isPathInside(resolvedPath, projectRoot)) {
     const reason = `Scope violation: path outside project root`;
-    const suggestion = suggestForScopeViolation(filePath, allowedPaths.join(', '));
+    const suggestion = suggest(filePath);
     return enforcement === 'strict'
       ? emitDeny(reason, suggestion)
       : emitWarn(`${reason} — ${suggestion}`);
@@ -276,7 +352,7 @@ async function main() {
   // SECURITY-REQ-04: null return means outside root — deny rather than pass null to pathMatchesPattern
   if (relPath === null) {
     const reason = `Scope violation: '${filePath}' outside project root`;
-    const suggestion = suggestForScopeViolation(filePath, allowedPaths.join(', '));
+    const suggestion = suggest(filePath);
     return enforcement === 'strict'
       ? emitDeny(reason, suggestion)
       : emitWarn(`${reason} — ${suggestion}`);
@@ -297,7 +373,7 @@ async function main() {
 
   if (!matched) {
     const reason = `Scope violation: '${normalizedRel}' not in allowed paths [${allowedPaths.join(', ')}]`;
-    const suggestion = suggestForScopeViolation(normalizedRel, allowedPaths.join(', '));
+    const suggestion = suggest(normalizedRel);
     return enforcement === 'strict'
       ? emitDeny(reason, suggestion)
       : emitWarn(`${reason} — ${suggestion}`);
@@ -307,6 +383,30 @@ async function main() {
   return emitAllow();
 }
 
+/**
+ * `mtimeMs` of a file, or `null` when it cannot be stat'ed.
+ *
+ * The PROVENANCE half of the #1057 staleness comparison. It is fed into a
+ * SUBTRACTION against this session's start time — deliberately NOT compared to a
+ * TTL: an absolute age cap blinds the check in exactly the regime it exists for
+ * (a legitimate long deep session ages into the blind spot with nothing having
+ * gone wrong). Same argument `hooks/post-bash-write-verify.mjs` makes for
+ * `sessionAgeMs` under "Why the minimum, and why NOT a staleness cap".
+ *
+ * Never throws — an unstat-able manifest simply yields an undecidable clock, and
+ * {@link classifyEmptyScope} degrades to `'unknown'`, never to an allow.
+ *
+ * @param {string} file
+ * @returns {Promise<number|null>}
+ */
+async function mtimeMsOf(file) {
+  try {
+    return (await fs.stat(file)).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
 const COORDINATOR_CARVEOUT_PATHS = Object.freeze([
   '.claude/STATE.md',
   '.codex/STATE.md',

package/hooks/hooks-codex.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v3.20.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v3.21.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

package/hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v3.20.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v3.21.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {
@@ -95,6 +95,16 @@
             "timeout": 5
           }
         ]
+      },
+      {
+        "matcher": "Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CLAUDE_PLUGIN_ROOT/hooks/run-node.sh\" \"$CLAUDE_PLUGIN_ROOT/hooks/pre-task-scope-disjoint.mjs\"",
+            "timeout": 5
+          }
+        ]
       }
     ],
     "PostToolUse": [

package/hooks/on-session-end.mjs

@@ -39,6 +39,7 @@ import {
   isLockOwnedByProof,
   OWNER_PROOF_RELPATH,
 } from '../scripts/lib/session-lock.mjs';
+import { deregisterSelf, logSweepEvent } from '../scripts/lib/session-registry.mjs';
 import { attemptLockReconciliation } from './_lib/lock-reconcile.mjs';
 
 // ---------------------------------------------------------------------------
@@ -275,16 +276,17 @@ async function main() {
       if (releaseEligible) {
         // Defense-in-depth (#987): when a persisted proof exists, hand it to
         // release() so the delete is double-gated (session_id match AND
-        // proof match) at the fs layer too. TRAP — release()'s proof gate
-        // triggers on `proof !== undefined`, so a null proof MUST be
-        // spread-guarded out: passing `proof: null` would fail
-        // isLockOwnedByProof() unconditionally and refuse EVERY release.
+        // proof match) at the fs layer too. `proof` is `null` whenever
+        // loadOwnerProof() could not prove ownership (pre-#987 sessions,
+        // failed proof write) — release() gates on `proof != null` (#989) and
+        // degrades to the session_id-only path for that case, so passing it
+        // through unguarded is correct.
         // A 'proof-mismatch' result flows into the existing release_failed
         // breadcrumb below (releaseResult.reason surfaces verbatim).
         const releaseResult = release({
           sessionId: lock.session_id,
           repoRoot: projectRoot,
-          ...(proof ? { proof } : {}),
+          proof,
         });
         // release() has a no-throw contract (always returns a structured
         // result). A matched ownership that still fails to delete — an
@@ -369,6 +371,51 @@ async function main() {
     // 'absent' — no lock file at all; nothing to release or reconcile
     // (mirrors the pre-existing `if (lock)` guard's false branch).
   } catch { /* best-effort — never block teardown */ }
+
+  // (c) #1047 — host-registry deregistration, the symmetric partner of
+  //     on-session-start.mjs's registerSelf(). This used to live in
+  //     hooks/on-stop.mjs, which fires at TURN end, so every assistant turn
+  //     deleted the entry of a still-live session; on-stop.mjs now refreshes
+  //     the entry (heartbeat) and teardown happens here, at the real end.
+  //
+  //     Keyed by `sessionId` ONLY, never by `semanticSessionId`: the registry
+  //     file is named after the id registerSelf() was called with, and in the
+  //     `generated-uuid-fallback-collision` path (on-session-start.mjs) the
+  //     semantic candidate names ANOTHER session's entry — deregistering by it
+  //     would delete a foreign live session. Ownership is therefore structural
+  //     here, not a check.
+  //
+  //     CONSEQUENCE, accepted deliberately — and the affected platform is
+  //     CODEX ALONE. Measured 2026-08-17 across the three bridge manifests:
+  //       hooks.json         SessionStart + SessionEnd        -> registers, deregisters
+  //       hooks-pi.json      session_start + session_shutdown -> registers, deregisters
+  //                          (session_shutdown maps to THIS file)
+  //       hooks-codex.json   SessionStart + Stop, no SessionEnd
+  //                          -> registers, never deregisters      <- the gap
+  //       hooks-cursor.json  afterFileEdit + beforeShellExecution only
+  //                          -> never registers, so nothing to leak
+  //     On Codex an entry therefore persists until sweepZombies() removes it at
+  //     the next SessionStart — up to the sweep threshold (`thresholdMin`,
+  //     default 60 min) after the session ended. That is the same path crash
+  //     and Ctrl-C already rely on for EVERY platform; no platform-detecting
+  //     second teardown branch exists by design.
+  //
+  //     Note where this is written: THIS file does not run on Codex, so the
+  //     consequence is also pointed at from hooks/on-stop.mjs, which does.
+  //
+  //     The `sessionId` guard is not decoration: deregisterSelf() throws
+  //     TypeError on a null/empty id, and "no id resolvable" is a normal
+  //     degraded state (no stdin id, no current-session.json), not a failure
+  //     worth a sweep.log breadcrumb.
+  if (sessionId) {
+    try {
+      await deregisterSelf(sessionId);
+    } catch (err) {
+      // Deregistration failed — observability breadcrumb to sweep.log, never a
+      // throw and never stderr: the hook must not block teardown.
+      logSweepEvent({ event: 'deregister-failed', session_id: sessionId, error: err?.message ?? String(err) });
+    }
+  }
 }
 
 // Exit 0 always — informational hook must never block session teardown.

package/hooks/on-stop.mjs

@@ -8,7 +8,10 @@
  *
  * Part of v3.0.0 Windows-native migration. Issue #141.
  *
- * Exit codes: 0 always (informational hooks must never block).
+ * Exit codes: 0 always (informational hooks must never block) — including when
+ * node_modules is absent: zx is imported lazily and a missing package degrades
+ * to one rate-limited stderr line instead of an ERR_MODULE_NOT_FOUND stack on
+ * every turn end (GH Kanevry/session-orchestrator#63).
  *
  * JSONL format (`.orchestrator/metrics/events.jsonl`) — emitted via the canonical
  * `emitEvent()` so the JSONL record and the optional Clank webhook always carry the
@@ -18,8 +21,7 @@
  */
 
 import path from 'node:path';
-import { promises as fs } from 'node:fs';
-import { $ } from 'zx';
+import { promises as fs, statSync, writeFileSync } from 'node:fs';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
 // #211: exit 0 immediately (silent allow) when this hook is disabled via profile/env
@@ -27,7 +29,7 @@ if (!shouldRunHook('on-stop')) process.exit(0);
 
 import { emitEvent } from '../scripts/lib/events.mjs';
 import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
-import { deregisterSelf, logSweepEvent } from '../scripts/lib/session-registry.mjs';
+import { heartbeat, logSweepEvent } from '../scripts/lib/session-registry.mjs';
 import { updateHeartbeat } from '../scripts/lib/session-lock.mjs';
 
 // ---------------------------------------------------------------------------
@@ -87,17 +89,87 @@ function discriminate(input) {
   return 'stop';
 }
 
+// ---------------------------------------------------------------------------
+// dependency degradation (GH Kanevry/session-orchestrator#63)
+// ---------------------------------------------------------------------------
+//
+// zx is loaded LAZILY. A static `import { $ } from 'zx'` fails at MODULE LOAD
+// time when node_modules is absent (interrupted install, EPERM sandbox, half-
+// synced plugin cache), so the harness prints a 10-frame ERR_MODULE_NOT_FOUND
+// stack on EVERY turn end with no hint that `npm install` is the fix. This
+// mirrors the missing-`node` degradation in hooks/run-node.sh (§5): one
+// actionable stderr line per 6h window, then carry on with reduced features.
+
+/** Rate-limit window for the dependencies-missing warning — mirrors run-node.sh's 6h TTL. */
+const DEP_WARN_TTL_MS = 6 * 60 * 60 * 1000;
+
+/** Plugin root (the directory that owns package.json / node_modules). */
+const PLUGIN_ROOT = path.resolve(import.meta.dirname, '..');
+
+/**
+ * Marker path for the dependencies-missing warning. Deliberately a DIFFERENT
+ * name from run-node.sh's `session-orchestrator-node-missing-*`: sharing one
+ * marker would let a missing-node warning mask a missing-deps warning (and
+ * vice versa), leaving the operator with half a diagnostic.
+ * @returns {string}
+ */
+function depWarnMarkerPath() {
+  // `||` alone falls back only on falsy values — a whitespace-only TMPDIR is
+  // truthy and would yield a garbage path (see .claude/rules/development.md).
+  const tmpDir = (process.env.TMPDIR || '').trim() || '/tmp';
+  const user = (process.env.USER || '').trim() || 'uid';
+  return path.join(tmpDir, `session-orchestrator-deps-missing-${user}`);
+}
+
+/**
+ * Print ONE actionable stderr line telling the operator to run `npm install`,
+ * at most once per DEP_WARN_TTL_MS. Marker mtime is the clock, exactly like
+ * run-node.sh's `find -mmin +360` check. Best-effort throughout: a marker we
+ * cannot stat is treated as expired (warn), a marker we cannot write means the
+ * next invocation warns again — noisier, never silent-broken.
+ */
+function warnDependenciesMissingOnce() {
+  const marker = depWarnMarkerPath();
+  try {
+    if (Date.now() - statSync(marker).mtimeMs < DEP_WARN_TTL_MS) return;
+  } catch { /* missing / unreadable marker → treat as expired */ }
+  try { writeFileSync(marker, ''); } catch { /* best-effort */ }
+  process.stderr.write(
+    `session-orchestrator: dependencies missing — run 'npm install' in ${PLUGIN_ROOT}. `
+    + 'Hook features degraded (this warning is rate-limited to once per 6h).\n',
+  );
+}
+
+/**
+ * Load zx's `$` lazily. Returns null when the package is not installed (after
+ * emitting the rate-limited advisory). Any OTHER import failure is re-thrown —
+ * a corrupt zx install is not a missing-dependency problem and must not be
+ * mislabelled as one.
+ * @returns {Promise<Function|null>}
+ */
+async function loadZx() {
+  try {
+    return (await import('zx')).$;
+  } catch (err) {
+    if (err?.code !== 'ERR_MODULE_NOT_FOUND') throw err;
+    warnDependenciesMissingOnce();
+    return null;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // git helpers
 // ---------------------------------------------------------------------------
 
 /**
  * Returns { commit, branch } from the git repo at projectRoot, or null values
- * if git is unavailable or the directory is not a git repo.
+ * if git is unavailable, zx is not installed, or the directory is not a git repo.
  * @param {string} projectRoot — working directory for git commands
  * @returns {Promise<{commit:string|null, branch:string|null}>}
  */
 async function gitInfo(projectRoot) {
+  const $ = await loadZx();
+  if ($ === null) return { commit: null, branch: null };
   $.verbose = false;
   $.quiet = true;
   const opts = projectRoot ? { cwd: projectRoot } : {};
@@ -180,16 +252,59 @@ async function handleStop(input) {
 
   const sessionId = await resolveSessionId(input, projectRoot);
 
-  // v3.1.0 multi-session registry (#169) — best-effort deregister. Missing
-  // entry is fine (zombie sweep handles crashed sessions). Failures are logged
-  // to sweep.log for observability but never re-thrown (hook must remain silent).
+  // v3.1.0 multi-session registry (#169), corrected in #1047 — REFRESH the
+  // registry entry here; never remove it.
+  //
+  // Stop fires at TURN end, not session end (see the file docblock). The
+  // original #169 wiring called deregisterSelf() here, so every assistant turn
+  // deleted this session's registry entry while the session was still live:
+  // measured on this host as 1 surviving entry (dead PID) against 12 live
+  // sockets, with sweep.log recording deletions of sessions aged 72/335/351/369
+  // minutes. Epic #583 fixed exactly this class for `.orchestrator/session.lock`
+  // (release → updateHeartbeat, below); the host registry never got the same
+  // correction. Deregistration now lives in hooks/on-session-end.mjs, which
+  // fires at the real end of the session.
+  //
+  // CODEX CAVEAT — stated here because THIS file runs on Codex and the file
+  // that owns deregistration does not. `hooks-codex.json` wires SessionStart +
+  // Stop but no SessionEnd (the Codex contract rejects the event), so on that
+  // bridge a session registers and never deregisters: its entry persists until
+  // sweepZombies() reaps it at the next SessionStart, up to `thresholdMin`
+  // (default 60 min). Accepted deliberately — it is the same path crash and
+  // Ctrl-C already take on every platform, and it is safe precisely BECAUSE
+  // the heartbeat below now advances, so a live session never ages into the
+  // sweep. Do NOT add a platform-detecting deregister branch here; that is the
+  // two-teardown-paths shape Epic #583 removed from the lock.
+  // (pi is unaffected: hooks-pi.json maps session_shutdown to on-session-end.mjs.
+  //  Cursor is unaffected: it wires no SessionStart, so it never registers.)
+  //
+  // Failures are logged to sweep.log for observability but never re-thrown
+  // (hook must remain silent and non-blocking).
   if (sessionId) {
     try {
-      await deregisterSelf(sessionId);
+      // heartbeat() returns null when no entry exists — a SILENT no-op that
+      // would otherwise make the loss permanent for the rest of the session
+      // (e.g. after a zombie sweep, or a harness UUID rotation with no fresh
+      // SessionStart). We do NOT re-register here: this hook has no access to
+      // the entry's platform / mode / host_class, and a re-registration would
+      // reset started_at to now — fabricating a session age instead of
+      // reporting one. Emit an observability breadcrumb instead, so the miss
+      // is visible in sweep.log rather than invisible. One line per turn while
+      // the entry is absent; that volume IS the signal, and the next
+      // SessionStart's registerSelf() ends it.
+      const refreshed = await heartbeat(sessionId);
+      if (refreshed === null) {
+        logSweepEvent({
+          event: 'heartbeat-missing',
+          session_id: sessionId,
+          error: 'no registry entry to refresh at turn end',
+        });
+      }
     } catch (err) {
-      // Deregistration failed — emit an observability breadcrumb to sweep.log.
-      // Do NOT throw, do NOT write to stderr: the hook is informational-only.
-      logSweepEvent({ event: 'deregister-failed', session_id: sessionId, error: err?.message ?? String(err) });
+      // Refresh failed at the fs layer — emit an observability breadcrumb to
+      // sweep.log. Do NOT throw, do NOT write to stderr: the hook is
+      // informational-only.
+      logSweepEvent({ event: 'heartbeat-failed', session_id: sessionId, error: err?.message ?? String(err) });
     }
 
     // Epic #583 W5-F1c — refresh session.lock heartbeat on every turn-end.

package/hooks/post-bash-write-verify.mjs

@@ -154,6 +154,13 @@ import { readFileSync, mkdirSync, writeFileSync, renameSync, realpathSync, statS
 import { readStdin, writeStdoutLineSync } from '../scripts/lib/io.mjs';
 import { resolveProjectDir } from '../scripts/lib/platform.mjs';
 import { findScopeFile, pathMatchesPattern } from '../scripts/lib/hardening.mjs';
+// #1057 — `sessionAgeMs` and its private `clockAgeMs` helper MOVED to the lib so
+// hooks/enforce-scope.mjs can read the same session clock without a hook->hook
+// import. Re-exported below, so this hook's public surface — and
+// tests/hooks/post-bash-write-verify.test.mjs, which imports the named export —
+// is unchanged. Two byte-identical copies of a clock is exactly the one-fact-two-
+// copies class this repo keeps paying for.
+import { sessionAgeMs } from '../scripts/lib/scope-gate.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -538,30 +545,6 @@ function readDirtyPaths(repoRoot) {
   }
 }
 
-/**
- * Age in ms of one session clock: a JSON file carrying an ISO start timestamp.
- *
- * Never throws. Absent / unparseable / non-string / non-ISO ⇒ null. A NEGATIVE
- * age (timestamp in the future) is also null rather than a negative number —
- * see `sessionAgeMs` for why that matters once two clocks are combined.
- *
- * @param {string} file  absolute path to the JSON file
- * @param {string} field name of the ISO-timestamp property
- * @param {number} now
- * @returns {number|null}
- */
-function clockAgeMs(file, field, now) {
-  try {
-    const parsed = JSON.parse(readFileSync(file, 'utf8'));
-    const startedAt = Date.parse(parsed?.[field]);
-    if (!Number.isFinite(startedAt)) return null;
-    const age = now - startedAt;
-    return age >= 0 ? age : null;
-  } catch {
-    return null;
-  }
-}
-
 /**
  * Milliseconds since the current session started, or null when unknown — the
  * MINIMUM of two independently-written session clocks (#957 finding 2):
@@ -634,14 +617,7 @@ function clockAgeMs(file, field, now) {
  * @param {number} [now]
  * @returns {number|null}
  */
-export function sessionAgeMs(repoRoot, now = Date.now()) {
-  const dir = path.join(repoRoot, '.orchestrator');
-  const ages = [
-    clockAgeMs(path.join(dir, 'current-session.json'), 'timestamp', now),
-    clockAgeMs(path.join(dir, 'session.lock'), 'started_at', now),
-  ].filter((age) => age !== null);
-  return ages.length > 0 ? Math.min(...ages) : null;
-}
+export { sessionAgeMs };
 
 /** @returns {object|null} */
 function readSnapshot(file) {