session-orchestrator 3.19.0 → 3.21.0

package/hooks/enforce-commands.mjs

@@ -35,17 +35,159 @@ import { shouldRunHook } from './_lib/profile-gate.mjs';
 if (!shouldRunHook('enforce-commands')) process.exit(0);
 
 import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 
-import { readStdin, emitAllow, emitDeny, emitWarn } from '../scripts/lib/io.mjs';
-import { resolveProjectDir } from '../scripts/lib/platform.mjs';
-import {
-  findScopeFile,
-  commandMatchesBlocked,
-  suggestForCommandBlock,
-  extractBashWriteTargets,
-  pathMatchesPattern,
-} from '../scripts/lib/hardening.mjs';
-import { readJson } from '../scripts/lib/common.mjs';
+// ---------------------------------------------------------------------------
+// #993 — late-bound repo dependencies
+//
+// These used to be STATIC imports. A SyntaxError in any of them failed at ESM
+// LINK time, before the first statement here ran: node exited 1 with 0 bytes on
+// stdout, and the `main().catch(...)` handler at the bottom of this file was
+// structurally unreachable (it only covers runtime errors inside `main()`).
+// Under the exit-0 PreToolUse protocol (#906) that crash is, on the only
+// decision-bearing channel, INDISTINGUISHABLE from an explicit `emitAllow()` —
+// the guard failed open and SILENTLY. This is the sibling defect #992 fixed for
+// pre-bash-destructive-guard; #993 generalises the same repair here.
+//
+// Binding them late (dynamic `import()` inside `bootstrap()`, below) turns that
+// link-time crash into a catchable runtime error, which is what makes the
+// GUARD INACTIVE banner in `_lib/guard-source-loader.mjs` reachable at all.
+//
+// `profile-gate.mjs` stays static on purpose — it has ZERO imports of its own
+// and gates whether this hook runs at all.
+// ---------------------------------------------------------------------------
+/** @type {typeof import('../scripts/lib/io.mjs').readStdin} */ let readStdin;
+/** @type {typeof import('../scripts/lib/io.mjs').emitAllow} */ let emitAllow;
+/** @type {typeof import('../scripts/lib/io.mjs').emitDeny} */ let emitDeny;
+/** @type {typeof import('../scripts/lib/io.mjs').emitWarn} */ let emitWarn;
+let resolveProjectDir;
+let readJson;
+let findScopeFile;
+let extractBashWriteTargets;
+let pathMatchesPattern;
+/**
+ * The `command-blocker.mjs` namespace, imported DIRECTLY (not via the
+ * hardening.mjs barrel — which does not carry the `headFallback` recovery, and
+ * which transitively imports command-blocker via scope-gate.mjs, so it fails
+ * anyway when command-blocker breaks). Mirrors the direct binding in
+ * pre-bash-destructive-guard / sessions-ledger-guard. Held as ONE object so the
+ * required-export list lives in exactly one place: the `requires` array on the
+ * `blocker` spec passed to `armGuard`.
+ *
+ * @type {Record<string, Function>|null}
+ */
+let blocker = null;
+
+/**
+ * Module labels `armGuard` recovered from HEAD because the working-tree copy
+ * failed (parse error OR shape check). Non-empty ⇒ this hook is armed against
+ * COMMITTED source. Surfaced on the visible stdout channel by {@link flushNotices}
+ * (#1001) — the stderr DEGRADED banner alone is discarded under the exit-0
+ * protocol, which made a degraded ALLOW indistinguishable from a healthy one.
+ *
+ * @type {string[]}
+ */
+let degradedLabels = [];
+
+const PLUGIN_ROOT = path.resolve(import.meta.dirname, '..');
+
+/** This hook's name — threaded into the guard banner (#993: no hard-wired literal). */
+const HOOK_NAME = 'enforce-commands';
+
+/**
+ * The consequence block spliced VERBATIM into the DEGRADED and GUARD INACTIVE
+ * banners (#993), naming the enforcement this hook's outage stops applying.
+ */
+const GUARD_CONSEQUENCE = {
+  degraded: [
+    '    Consequence: command enforcement IS still armed, but it is evaluating the',
+    '    COMMITTED (HEAD) command-blocker — any uncommitted change to it is NOT in effect.',
+  ],
+  inactive: [
+    '    Consequence: blocked Bash commands (rm -rf, git push --force, git reset',
+    '    --hard, and the wave blockedCommands list) are NOT being screened. This is',
+    '    a BROKEN GUARD, not a policy decision — do not route around it, repair it.',
+  ],
+};
+
+/**
+ * Project dir for banner keying, resolved WITHOUT `platform.mjs` — that module
+ * is one of the ones that may have failed to load.
+ *
+ * @returns {string}
+ */
+function bannerProjectDir() {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+/**
+ * Bind every repo dependency late, making a load failure VISIBLE (GUARD INACTIVE
+ * banner) instead of a silent exit-1 / 0-byte disarm. Throws on any load failure;
+ * the entry-point catch banners.
+ *
+ * `hardening.mjs` is bound (no headFallback — it carries relative imports) for
+ * `findScopeFile` / `extractBashWriteTargets` / `pathMatchesPattern`; the two
+ * command-matching primitives come from the direct `blocker` namespace, which is
+ * the only entry that opts into the `git show HEAD:` recovery. Because hardening
+ * transitively imports command-blocker (via scope-gate.mjs), a broken command-blocker
+ * fails hardening FIRST (it arms before the headFallback entry) — so that case
+ * degrades straight to GUARD INACTIVE, git or no git.
+ *
+ * @returns {Promise<void>}
+ */
+async function bootstrap() {
+  const lib = (...seg) => pathToFileURL(path.join(PLUGIN_ROOT, 'scripts', 'lib', ...seg)).href;
+
+  const { armGuard } = await import('./_lib/guard-source-loader.mjs');
+  const { modules, degraded } = await armGuard(
+    {
+      io: { specifier: lib('io.mjs') },
+      platform: { specifier: lib('platform.mjs') },
+      common: { specifier: lib('common.mjs') },
+      hardening: { specifier: lib('hardening.mjs') },
+      blocker: {
+        specifier: lib('command-blocker.mjs'),
+        headFallback: true,
+        requires: ['commandMatchesBlocked', 'suggestForCommandBlock'],
+      },
+    },
+    {
+      hookName: HOOK_NAME,
+      repoRoot: PLUGIN_ROOT,
+      projectDir: bannerProjectDir(),
+      consequence: GUARD_CONSEQUENCE,
+    }
+  );
+
+  ({ readStdin, emitAllow, emitDeny, emitWarn } = modules.io);
+  ({ resolveProjectDir } = modules.platform);
+  ({ readJson } = modules.common);
+  ({ findScopeFile, extractBashWriteTargets, pathMatchesPattern } = modules.hardening);
+  blocker = modules.blocker;
+  degradedLabels = degraded;
+}
+
+/**
+ * Flush the aggregated allow-with-notice channel (#1001).
+ *
+ * Notices raised during gate evaluation accumulate in `notices` and are emitted
+ * ONCE, here, on the VISIBLE stdout channel via `emitWarn` (allow-with-notice) —
+ * else a plain `emitAllow`. Both exit 0 and never return, so this is always the
+ * LAST statement on an allow path.
+ *
+ * Why aggregate instead of `emitWarn`-ing inline at the degraded site: `emitWarn`
+ * is `@returns never` (scripts/lib/io.mjs), so an inline call before the G6
+ * blocked-pattern loop would exit BEFORE any pattern was matched — turning every
+ * would-be DENY into an ALLOW-with-notice for the whole degraded session. A deny,
+ * when it fires, exits via `emitDeny` and these notices are simply dropped: DENY
+ * wins, and armGuard's stderr banner remains for CI/debug.
+ *
+ * @param {string[]} notices
+ * @returns {never}
+ */
+function flushNotices(notices) {
+  return notices.length > 0 ? emitWarn(notices.join('\n')) : emitAllow();
+}
 
 // Fallback safety list — applied when scope.blockedCommands is empty.
 // Keep in sync with hooks/enforce-commands.sh; v3 additions (#138, SECURITY-REQ-07)
@@ -71,11 +213,29 @@ async function main() {
   const command = input?.tool_input?.command;
   if (typeof command !== 'string' || command.length === 0) return emitAllow();
 
+  // #1001 — aggregated allow-with-notice channel, opened only AFTER G1/G2 (a
+  // non-Bash tool call or an empty command is not this hook's business, and must
+  // stay a bare allow so the notice does not ride every unrelated tool call).
+  // Flushed ONCE at the end of whichever allow path is taken; see flushNotices
+  // for why an inline emitWarn here would disarm the G6 deny below.
+  const notices = [];
+  // A guard armed from HEAD (working-tree module unparseable or shape-invalid) is
+  // a visible-channel concern: the DEGRADED banner rides stderr only, which exit 0
+  // discards. armGuard already fired that banner once per session; surface it on
+  // stdout too so a degraded ALLOW is not silently indistinguishable from a
+  // healthy one.
+  if (degradedLabels.length > 0) {
+    notices.push(
+      `${HOOK_NAME}: DEGRADED — guard module(s) loaded from HEAD, not your working tree ` +
+        `(${degradedLabels.join(', ')}); uncommitted changes to them are NOT in effect. See #992.`
+    );
+  }
+
   const projectRoot = resolveProjectDir();
 
   // G3 — no scope file → allow
   const scopePath = findScopeFile(projectRoot);
-  if (!scopePath) return emitAllow();
+  if (!scopePath) return flushNotices(notices);
 
   // SECURITY-REQ-08: read scope file exactly once; use the parsed object
   // for all subsequent gate checks.
@@ -106,30 +266,35 @@ async function main() {
   }
 
   // G4 — gate disabled → allow
-  if (!gateOn) return emitAllow();
+  if (!gateOn) return flushNotices(notices);
   // G5 — enforcement "off" → allow
-  if (enforcement === 'off') return emitAllow();
+  if (enforcement === 'off') return flushNotices(notices);
 
   // G6 — determine which list to check
   const useFallback = blockedCommands.length === 0;
   const patternsToCheck = useFallback ? FALLBACK_BLOCKED : blockedCommands;
 
   for (const pattern of patternsToCheck) {
-    if (commandMatchesBlocked(command, pattern)) {
+    if (blocker.commandMatchesBlocked(command, pattern)) {
       const prefix = useFallback
         ? 'Blocked by fallback safety list'
         : 'Blocked command';
       const reason = `${prefix}: '${pattern}' found in command`;
-      const suggestion = suggestForCommandBlock(pattern);
+      const suggestion = blocker.suggestForCommandBlock(pattern);
       if (enforcement === 'strict') {
         return emitDeny(reason, suggestion);
       }
-      return emitWarn(`${reason} — ${suggestion}`);
+      // Aggregated, not inline: when the guard is DEGRADED the notice list is
+      // non-empty and both lines ride ONE envelope (a second emitWarn would be
+      // unreachable — emitWarn never returns). Undegraded, notices is empty and
+      // this stays the single-line warn it has always been.
+      notices.push(`${reason} — ${suggestion}`);
+      return flushNotices(notices);
     }
   }
 
   // G7 — no match → allow
-  return emitAllow();
+  return flushNotices(notices);
 }
 
 /**
@@ -181,6 +346,40 @@ function targetInWaveScope(target, allowedPaths, projectRoot) {
   );
 }
 
+// ---------------------------------------------------------------------------
+// Entry point (#993)
+//
+// TWO distinct failure classes, two distinct handlers — do NOT merge them:
+//
+//   1. LOAD failure (`bootstrap()` throws): the guard never armed. Under the
+//      exit-0 protocol a bare exit-1 crash with 0 bytes of stdout is, on the
+//      only decision-bearing channel, indistinguishable from an allow. Now it
+//      exits 0 (still fail-OPEN — a broken module must not brick the session,
+//      and emitDeny itself may be the module that failed to load) but SAYS SO,
+//      loudly: GUARD INACTIVE.
+//   2. RUNTIME failure inside `main()`: pre-existing behaviour, unchanged. The
+//      guard armed and then tripped over a specific command; that fails CLOSED
+//      via emitDeny (SECURITY-REQ-01). The two paths MUST stay separate.
+// ---------------------------------------------------------------------------
+try {
+  await bootstrap();
+} catch (loadError) {
+  try {
+    const { emitGuardInactiveBanner } = await import('./_lib/guard-source-loader.mjs');
+    // hookName is threaded explicitly (#993 — no hard-wired literal in the loader).
+    emitGuardInactiveBanner({ hookName: HOOK_NAME, error: loadError, consequence: GUARD_CONSEQUENCE });
+  } catch {
+    // Last resort: even the banner helper failed to load. Emit unconditionally —
+    // repeated noise beats a silent disarm.
+    process.stderr.write(
+      '🚨 enforce-commands: GUARD INACTIVE — module load failed ' +
+        `(${String(loadError?.message || loadError).split('\n')[0]}). ` +
+        'Blocked Bash commands are NOT being screened. See issue #993.\n'
+    );
+  }
+  process.exit(0); // fail-open, but no longer fail-silent
+}
+
 // SECURITY-REQ-01 (F-03): top-level try/catch — never let exit 1 leak.
 main().catch((e) => {
   emitDeny('Internal hook error — request blocked for safety', `${e?.message || e}`);

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):
@@ -48,20 +54,122 @@
 
 import path from 'node:path';
 import { promises as fs } from 'node:fs';
+import { pathToFileURL } from 'node:url';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
 // #211: exit 0 immediately (silent allow) when this hook is disabled via profile/env
 if (!shouldRunHook('enforce-scope')) process.exit(0);
 
-import { readStdin, emitAllow, emitDeny, emitWarn } from '../scripts/lib/io.mjs';
-import { isPathInside, relativeFromRoot } from '../scripts/lib/path-utils.mjs';
-import { resolveProjectDir } from '../scripts/lib/platform.mjs';
-import {
-  findScopeFile,
-  pathMatchesPattern,
-  suggestForScopeViolation,
-} from '../scripts/lib/hardening.mjs';
-import { readJson } from '../scripts/lib/common.mjs';
+// ---------------------------------------------------------------------------
+// #993 — late-bound repo dependencies
+//
+// These used to be STATIC imports. A SyntaxError in any of them failed at ESM
+// LINK time, before the first statement here ran: node exited 1 with 0 bytes on
+// stdout, and the `main().catch(...)` handler at the bottom of this file was
+// structurally unreachable. Under the exit-0 PreToolUse protocol (#906) that
+// crash is, on the only decision-bearing channel, INDISTINGUISHABLE from an
+// explicit `emitAllow()` — the guard failed open and SILENTLY. This is the
+// sibling defect #992 fixed for pre-bash-destructive-guard; #993 generalises the
+// same repair here.
+//
+// Binding them late (dynamic `import()` inside `bootstrap()`, below) turns that
+// link-time crash into a catchable runtime error, which is what makes the
+// GUARD INACTIVE banner in `_lib/guard-source-loader.mjs` reachable at all.
+//
+// BANNER-ONLY (#993 D1): this hook consumes ZERO command-blocker symbols, so no
+// module here opts into the `git show HEAD:` fallback — every load failure
+// degrades straight to GUARD INACTIVE, never DEGRADED.
+//
+// `profile-gate.mjs` and `node:*` builtins stay static — they cannot be the
+// broken repo module.
+// ---------------------------------------------------------------------------
+/** @type {typeof import('../scripts/lib/io.mjs').readStdin} */ let readStdin;
+/** @type {typeof import('../scripts/lib/io.mjs').emitAllow} */ let emitAllow;
+/** @type {typeof import('../scripts/lib/io.mjs').emitDeny} */ let emitDeny;
+/** @type {typeof import('../scripts/lib/io.mjs').emitWarn} */ let emitWarn;
+let isPathInside;
+let relativeFromRoot;
+let resolveProjectDir;
+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, '..');
+
+/** This hook's name — threaded into the guard banner (#993: no hard-wired literal). */
+const HOOK_NAME = 'enforce-scope';
+
+/**
+ * The consequence block spliced VERBATIM into the GUARD INACTIVE banner (#993),
+ * naming the enforcement this hook's outage stops applying. No `degraded` block:
+ * this hook has no headFallback module, so it can never DEGRADE — only go INACTIVE.
+ */
+const GUARD_CONSEQUENCE = {
+  inactive: [
+    '    Consequence: Edit/Write/MultiEdit scope enforcement is OFF — writes',
+    '    outside the wave allowedPaths (and outside the project root) are NOT',
+    '    being blocked. This is a BROKEN GUARD, not a policy decision — do not',
+    '    route around it, repair it.',
+  ],
+};
+
+/**
+ * Project dir for banner keying, resolved WITHOUT `platform.mjs` — that module
+ * is one of the ones that may have failed to load.
+ *
+ * @returns {string}
+ */
+function bannerProjectDir() {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+/**
+ * Bind every repo dependency late, making a load failure VISIBLE (GUARD INACTIVE
+ * banner) instead of a silent exit-1 / 0-byte disarm. Throws on any load failure;
+ * the entry-point catch banners. No entry opts into headFallback — this hook is
+ * banner-only (#993 D1).
+ *
+ * @returns {Promise<void>}
+ */
+async function bootstrap() {
+  const lib = (...seg) => pathToFileURL(path.join(PLUGIN_ROOT, 'scripts', 'lib', ...seg)).href;
+
+  const { armGuard } = await import('./_lib/guard-source-loader.mjs');
+  const { modules } = await armGuard(
+    {
+      io: { specifier: lib('io.mjs') },
+      pathUtils: { specifier: lib('path-utils.mjs') },
+      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,
+      repoRoot: PLUGIN_ROOT,
+      projectDir: bannerProjectDir(),
+      consequence: GUARD_CONSEQUENCE,
+    }
+  );
+
+  ({ readStdin, emitAllow, emitDeny, emitWarn } = modules.io);
+  ({ isPathInside, relativeFromRoot } = modules.pathUtils);
+  ({ resolveProjectDir } = modules.platform);
+  ({ findScopeFile, pathMatchesPattern, suggestForScopeViolation } = modules.hardening);
+  ({ readJson } = modules.common);
+  ({ classifyEmptyScope, suggestForEmptyScope, sessionStartedAtMs } = modules.scopeGate);
+}
 
 async function main() {
   // SECURITY-REQ-01: null-guard empty stdin — treat as allow (no input = not a real hook call)
@@ -93,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
@@ -110,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
@@ -174,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}`);
@@ -186,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}`);
@@ -207,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}`);
@@ -217,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',
@@ -264,6 +454,40 @@ function matchesAbsoluteAllowlist(resolvedPath, allowedPaths) {
   return abs.some((pat) => pathMatchesPattern(normalizedAbs, pat.split(path.sep).join('/')));
 }
 
+// ---------------------------------------------------------------------------
+// Entry point (#993)
+//
+// TWO distinct failure classes, two distinct handlers — do NOT merge them:
+//
+//   1. LOAD failure (`bootstrap()` throws): the guard never armed. Under the
+//      exit-0 protocol a bare exit-1 crash with 0 bytes of stdout is, on the
+//      only decision-bearing channel, indistinguishable from an allow. Now it
+//      exits 0 (still fail-OPEN — a broken module must not brick the session,
+//      and emitDeny itself may be the module that failed to load) but SAYS SO:
+//      GUARD INACTIVE. Banner-only — no headFallback module here (#993 D1).
+//   2. RUNTIME failure inside `main()`: pre-existing behaviour, unchanged. The
+//      guard armed and then tripped over a specific path; that fails CLOSED via
+//      emitDeny (SECURITY-REQ-01). The two paths MUST stay separate.
+// ---------------------------------------------------------------------------
+try {
+  await bootstrap();
+} catch (loadError) {
+  try {
+    const { emitGuardInactiveBanner } = await import('./_lib/guard-source-loader.mjs');
+    // hookName is threaded explicitly (#993 — no hard-wired literal in the loader).
+    emitGuardInactiveBanner({ hookName: HOOK_NAME, error: loadError, consequence: GUARD_CONSEQUENCE });
+  } catch {
+    // Last resort: even the banner helper failed to load. Emit unconditionally —
+    // repeated noise beats a silent disarm.
+    process.stderr.write(
+      '🚨 enforce-scope: GUARD INACTIVE — module load failed ' +
+        `(${String(loadError?.message || loadError).split('\n')[0]}). ` +
+        'Edit/Write/MultiEdit scope enforcement is OFF. See issue #993.\n'
+    );
+  }
+  process.exit(0); // fail-open, but no longer fail-silent
+}
+
 // SECURITY-REQ-01 (fail-closed): any unhandled rejection → structured deny, never bare exit 1
 main().catch((e) => {
   emitDeny(

package/hooks/hooks-codex.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v3.19.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.19.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": [