session-orchestrator 3.17.0 → 3.20.0

package/hooks/_lib/lock-bootstrap.mjs

@@ -187,6 +187,27 @@ export async function bootstrapLock({
     }
   }
 
+  // Step 2b (#987 Part 1): persist the durable ownership proof at lock
+  // genesis. `enriched` is byte-identical to the on-disk lock at this point
+  // (the v2 overlay never touches pid/host/started_at), so the proof written
+  // here will verify via isLockOwnedByProof() against any later re-read.
+  // This single call covers BOTH the plain-acquire and the forceAcquire
+  // branch — both flow through the enriched write above. Best-effort like
+  // the surrounding breadcrumb writes: writeOwnerProof() is no-throw by
+  // contract and a failure never bails the bootstrap — but it is no longer
+  // SILENT (#987 Part 2 review finding): a failed proof write means this
+  // session's /close will degrade to the weaker proof-less release path, so
+  // a one-line stderr WARN gives the operator the only signal there is.
+  try {
+    const { writeOwnerProof } = await import('../../scripts/lib/session-lock.mjs');
+    const proofResult = writeOwnerProof({ repoRoot, lock: enriched });
+    if (proofResult && !proofResult.ok) {
+      process.stderr.write(
+        `⚠ lock-bootstrap: owner-proof write failed (${proofResult.reason ?? 'unknown'}) — /close degrades to proof-less release behaviour\n`,
+      );
+    }
+  } catch { /* best-effort — a missing proof never breaks session-start */ }
+
   // Step 3: best-effort observability breadcrumb. Failures are swallowed
   // so a missing events module never breaks the hook.
   try {

package/hooks/_lib/vcs-create-matcher.mjs

@@ -0,0 +1,119 @@
+/**
+ * vcs-create-matcher.mjs — shared `gh` / `glab` create-command matcher for
+ * PreToolUse Bash hooks.
+ *
+ * Extracted from `hooks/pre-bash-templates-first.mjs` (#519) so the
+ * issue-budget hook (`hooks/pre-bash-issue-budget.mjs`) reuses the SAME
+ * regex + argument-boundary semantics instead of maintaining a second,
+ * silently-diverging copy. Both hooks share the PreToolUse Bash matcher and
+ * run sequentially, so a divergence here would mean one hook gates a command
+ * the other waves through.
+ *
+ * ZERO IMPORTS by design — a clean leaf so any hook can adopt it without
+ * pulling the scripts/lib layer in.
+ *
+ * LOAD-BEARING semantics (contract, mirrors the pre-#-extraction behaviour):
+ *   MATCH:    `gh|glab` + `pr|mr|issue` + `create|new`, anchored at start with
+ *             optional leading whitespace, word-boundary on the trailing edge
+ *             (so `created` / `news` do NOT match).
+ *   NO MATCH: edit operations (`gh pr edit`, `glab mr edit`) — deliberately
+ *             out of scope per the #519 PRD § 2 Out-of-Scope.
+ */
+
+/**
+ * Matches the canonical `gh` / `glab` issue/PR/MR creation invocations.
+ * Anchored at start (^) with optional leading whitespace to catch indented
+ * shell snippets. Word-boundary at the end avoids false positives on tokens
+ * like `created` or `news`.
+ */
+export const CREATE_REGEX = /^\s*(gh|glab)\s+(pr|mr|issue)\s+(create|new)\b/;
+
+/**
+ * Parse a shell command into its VCS-create shape.
+ *
+ * @param {string} command
+ * @returns {{ host: 'github'|'gitlab', kind: 'pr'|'mr'|'issue', verb: 'create'|'new' } | null}
+ *   `null` when the command is not a `gh`/`glab` create/new invocation.
+ */
+export function matchVcsCreate(command) {
+  if (typeof command !== 'string' || command.length === 0) return null;
+  const m = command.match(CREATE_REGEX);
+  if (!m) return null;
+  return {
+    host: m[1] === 'gh' ? 'github' : 'gitlab',
+    kind: /** @type {'pr'|'mr'|'issue'} */ (m[2]),
+    verb: /** @type {'create'|'new'} */ (m[3]),
+  };
+}
+
+/**
+ * Determine which host the command targets. `gh` → "github", `glab` → "gitlab".
+ * Thin wrapper kept for call-site readability in pre-bash-templates-first.mjs.
+ *
+ * @param {string} command
+ * @returns {"github"|"gitlab"|null}
+ */
+export function resolveHost(command) {
+  return matchVcsCreate(command)?.host ?? null;
+}
+
+/**
+ * True when the command creates an ISSUE specifically (not a PR/MR).
+ * The issue-budget cap counts issues only — PR/MR creation is not the
+ * runaway-volume problem the cap exists to bound.
+ *
+ * @param {string} command
+ * @returns {boolean}
+ */
+export function isIssueCreate(command) {
+  return matchVcsCreate(command)?.kind === 'issue';
+}
+
+/**
+ * True when the command starts with any of the bypass patterns. Bypass match
+ * is a prefix check with a word/EOL boundary on the trailing edge — this
+ * prevents trivial bypass via prefix-inclusion (e.g. a policy entry
+ * "gh issue create --label bot" must not match "gh issue create --label botanical").
+ *
+ * @param {string} command
+ * @param {string[]} bypassPatterns
+ * @returns {boolean}
+ */
+export function matchesBypass(command, bypassPatterns) {
+  if (typeof command !== 'string') return false;
+  if (!Array.isArray(bypassPatterns) || bypassPatterns.length === 0) {
+    return false;
+  }
+  const stripped = command.replace(/^\s+/, '');
+  for (const pat of bypassPatterns) {
+    if (typeof pat !== 'string' || pat.length === 0) continue;
+    const patStripped = pat.replace(/^\s+/, '');
+    if (!stripped.startsWith(patStripped)) continue;
+    // Boundary check: next character must be whitespace, EOL, or absent.
+    const nextChar = stripped.charAt(patStripped.length);
+    if (nextChar === '' || /\s/.test(nextChar)) return true;
+  }
+  return false;
+}
+
+/**
+ * Best-effort extraction of the `--title` value from a create command, for
+ * human-readable overflow bookkeeping. Handles `--title "x"`, `--title 'x'`,
+ * `--title=x` and the bare unquoted form. Returns `null` when no title flag
+ * is present.
+ *
+ * Deliberately NOT a shell parser: the value is only ever used as a display
+ * label in an overflow record, never re-executed.
+ *
+ * @param {string} command
+ * @returns {string|null}
+ */
+export function extractTitle(command) {
+  if (typeof command !== 'string' || command.length === 0) return null;
+  const m =
+    command.match(/--title[=\s]+"((?:[^"\\]|\\.)*)"/) ??
+    command.match(/--title[=\s]+'([^']*)'/) ??
+    command.match(/--title[=\s]+(\S+)/);
+  if (!m) return null;
+  return m[1].replace(/\\(["\\])/g, '$1').trim() || null;
+}

package/hooks/enforce-commands.mjs

@@ -13,10 +13,18 @@
  *   G5 enforcement != "off"
  *   G6 blocked pattern match against .blockedCommands[], or
  *      fallback safety list when .blockedCommands is empty
- *   G7 strict → deny (exit 2); warn → stderr + allow (exit 0); otherwise allow
+ *   G7 strict → deny; warn → stderr + allow; otherwise allow
+ *
+ * DECISION CHANNEL (post-#906): a deny is signalled by the single nested
+ *   PreToolUse JSON envelope emitDeny() writes to stdout, with exit **0** —
+ *   NOT by exit 2. The docs forbid the mixed form ("Exit 2 … Claude Code
+ *   ignores stdout and any JSON in it"), which silently discarded the reason
+ *   and surfaced to the operator as a crash. Do not reintroduce `exit 2` here.
+ *   Corollary: exit 0 alone no longer distinguishes allow from deny — the
+ *   envelope's presence does, and a malformed envelope fails OPEN.
  *
  * SECURITY-REQ-01: try/catch on main(). emitDeny on any unhandled error —
- *   exit 2, never exit 1. Null-guard readStdin() return.
+ *   fail-closed, never a bare exit 1. Null-guard readStdin() return.
  * SECURITY-REQ-07: FALLBACK_BLOCKED includes 'git push -f' and 'drop table'
  *   (short form + case variant gaps in the original Bash fallback list).
  * SECURITY-REQ-08: scope file read exactly once per invocation.
@@ -27,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';
+
+// ---------------------------------------------------------------------------
+// #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;
 
-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';
+  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)
@@ -63,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.
@@ -98,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);
 }
 
 /**
@@ -173,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

@@ -48,20 +48,110 @@
 
 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;
+
+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') },
+    },
+    {
+      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);
+}
 
 async function main() {
   // SECURITY-REQ-01: null-guard empty stdin — treat as allow (no input = not a real hook call)
@@ -264,6 +354,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.17.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v3.20.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

package/hooks/hooks-cursor.json

@@ -2,14 +2,23 @@
   "_comment": "Cursor IDE hook mapping reference. Configure hooks in Cursor Settings > Hooks.",
   "_note": "Cursor hooks fire at different lifecycle points than Claude Code. See docs/cursor-setup.md for details.",
   "_limitation": "SessionStart greeting (session-start skill) is NOT available on Cursor. Cursor has no conversation-start lifecycle event equivalent to Claude Code's UserPromptSubmit hook. Session initialisation must be triggered manually.",
+  "_enforcement": "reference-only",
+  "_enforcement_note": "MACHINE-READABLE STATUS (#919): every entry below is an intended mapping, NOT live enforcement. No Cursor payload adapter exists (Pi has scripts/lib/pi-hook-bridge.mjs; Cursor has nothing), so each handler short-circuits on a Cursor-shaped payload and writes 0 bytes with exit 0. Operator decision 2026-07-31: gap registered, not closed. The machine-readable counterpart of this key is DOCUMENTED_ASYMMETRIES.handlerAsymmetries.cursor in scripts/lib/validate/check-hooks-symmetry.mjs, which Check 6 counts per event; the projection that makes that comparison non-vacuous is DOCUMENTED_ASYMMETRIES.cursorEventMap.",
+  "_issues": ["#919", "#946"],
   "hooks": {
     "afterFileEdit": {
       "script": "hooks/enforce-scope.mjs",
-      "note": "Post-hoc scope warning — Cursor fires AFTER the edit (not before). Cannot prevent out-of-scope edits, only warn."
+      "enforcement": "none",
+      "issue": "#919",
+      "mapsToClaudeEvent": "PostToolUse",
+      "note": "Post-hoc scope warning — Cursor fires AFTER the edit (not before), so this maps onto PostToolUse, never PreToolUse. Cannot prevent out-of-scope edits, only warn — and today not even that: on a Cursor afterFileEdit payload enforce-scope.mjs writes 0 bytes to stdout AND stderr with exit 0 (measured 2026-07-31), because it reads Claude Code's PreToolUse field names."
     },
     "beforeShellExecution": {
       "script": "hooks/enforce-commands.mjs",
-      "note": "Blocks dangerous commands before shell execution. Direct equivalent of Claude Code's PreToolUse Bash hook."
+      "enforcement": "none",
+      "issue": "#919",
+      "mapsToClaudeEvent": "PreToolUse",
+      "note": "NOT WIRED (#919) — silent no-op on a Cursor payload, NOT a block. The handler reads Claude Code's PreToolUse field names (tool_name === 'Bash', tool_input.command) and emits a Claude Code PreToolUse envelope (hookSpecificOutput.permissionDecision). Fed a Cursor beforeShellExecution payload it short-circuits at gate G1 and writes 0 bytes to stdout AND stderr with exit 0 — the harness sees no decision, so the command runs. Cursor needs an input/output adapter like scripts/lib/pi-hook-bridge.mjs; none exists. Treat this entry as the intended mapping, not as live enforcement."
     }
   }
 }

package/hooks/hooks-pi.json

@@ -88,6 +88,16 @@
           }
         ]
       },
+      {
+        "matcher": "bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$PI_PLUGIN_ROOT/hooks/run-node.sh\" \"$PI_PLUGIN_ROOT/hooks/post-bash-write-verify.mjs\"",
+            "timeout": 5
+          }
+        ]
+      },
       {
         "matcher": "*",
         "hooks": [