session-orchestrator 3.17.0 → 3.20.0

package/hooks/pre-bash-destructive-guard.mjs

@@ -14,13 +14,21 @@
  *   G2 command present + string
  *   G3 bypass: allow-destructive-ops: true in Session Config → exit 0
  *   G4 policy load: .orchestrator/policy/blocked-commands.json
- *      Missing → exit 0 (warn). Malformed → exit 0 (warn).
+ *      #972 floor/overlay merge (scripts/lib/blocked-commands-policy.mjs):
+ *      pluginRoot policy = floor, cwd/projectDir policy = overlay (add or
+ *      escalate only). Overlay failures fail-to-floor; only "no usable policy
+ *      anywhere" keeps the historical fail-open (exit 0 + warn).
  *   G5 rule evaluation per rule in policy.rules
- *      severity:"block" → exit 2 with deny message
+ *      severity:"block" → deny envelope on stdout via emitDeny, exit 0 (#906)
  *      severity:"warn"  → emit warning, exit 0 (allow)
  *      Special cases:
  *        git-stash-any: only warn when stash is non-empty
  *        rm-rf-destructive: path exception for .orchestrator/tmp and node_modules
+ *        rule.type === 'redirect-truncate' (#983): decided by redirect TARGET
+ *          via redirectRuleMatches (target-denylist globs), NEVER by the
+ *          generic pattern path — its `pattern: ">"` would FP-match nearly
+ *          every redirect. Unresolved targets (variable/substitution) warn
+ *          on stderr (fail-visible) and never block.
  *   G6 no match → exit 0
  *
  * Telemetry (Epic #803 process-safety dimension): best-effort
@@ -31,54 +39,194 @@
  * finalized; a telemetry failure never changes the guard's decision.
  */
 
-import { readStdin, emitAllow } from '../scripts/lib/io.mjs';
-import { resolveProjectDir, resolvePluginRoot } from '../scripts/lib/platform.mjs';
-import { commandMatchesBlocked, tokenizeCommand } from '../scripts/lib/hardening.mjs';
-import { readConfigFile } from '../scripts/lib/config.mjs';
-import { readJson } from '../scripts/lib/common.mjs';
-import { emitEvent } from '../scripts/lib/events.mjs';
-import fs, { existsSync } from 'node:fs';
+import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
+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('pre-bash-destructive-guard')) process.exit(0);
 
-// Module-level policy cache (issue #250). Safe because each hook invocation runs as
-// an isolated Node subprocess — state is fresh per process, never shared across calls.
-// Cache is invalidated on:
-//   (a) resolved policy path changes (different projectDir/CWD)
-//   (b) file mtime advances (user edited the policy)
-// Any stat/read error → skip cache + fall back to uncached read (fail-safe).
-let _cachedPolicy = null;
-let _cachedPolicyPath = null;
-let _cachedPolicyMtimeMs = null;
-
-async function loadPolicyCached(policyPath) {
-  try {
-    const stat = await fs.promises.stat(policyPath);
-    const mtimeMs = stat.mtimeMs;
-    if (
-      _cachedPolicy !== null &&
-      _cachedPolicyPath === policyPath &&
-      _cachedPolicyMtimeMs === mtimeMs
-    ) {
-      return _cachedPolicy;
+// ---------------------------------------------------------------------------
+// #992 — 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.
+//
+// Binding them late (dynamic `import()` inside `bootstrap()`, below) turns that
+// link-time crash into a catchable runtime error, which is what makes the
+// banner + HEAD-fallback in `_lib/guard-source-loader.mjs` reachable at all.
+// The command-blocker half is held as a NAMESPACE object (`blocker.*`) rather
+// than six destructured bindings — see the `blocker` docblock below for why
+// that single change removes the shape-check drift that made a 4-of-6-missing
+// HEAD copy read as "still armed".
+//
+// `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 resolvePluginRoot;
+/**
+ * The whole `command-blocker.mjs` namespace (W4 B6: one direct import path, not
+ * via the hardening.mjs barrel, which does not re-export the #982/#983
+ * primitives).
+ *
+ * Held as ONE object rather than destructured into six bindings on purpose: the
+ * required-export list then exists in exactly one place — the `requires` array
+ * on the `blocker` spec passed to `armGuard` (#993), which validates both the
+ * working-tree and the HEAD copy against it. The previous split (six names
+ * destructured here, two of them checked in the loader) is what let a HEAD copy
+ * missing four exports banner "DEGRADED — still armed" and then fail open on
+ * every command.
+ *
+ * @type {Record<string, Function>|null}
+ */
+let blocker = null;
+let readConfigFile;
+let loadEffectivePolicy;
+let isSessionConfigHeading;
+let emitEvent;
+
+/**
+ * Labels of guard modules that loaded from HEAD rather than the working tree
+ * (#993/#995). Populated by `bootstrap()` from `armGuard`'s return; read by
+ * `main()`, which pushes a visible-channel DEGRADED notice when it is non-empty —
+ * the stderr degradation banner alone is invisible under the exit-0 protocol.
+ *
+ * @type {string[]}
+ */
+let degradedLabels = [];
+
+const PLUGIN_ROOT = path.resolve(import.meta.dirname, '..');
+
+/** This hook's name — threaded into both guard banners (#993: no hard-wired literal). */
+const HOOK_NAME = 'pre-bash-destructive-guard';
+
+/**
+ * The two consequence blocks, spliced VERBATIM into the DEGRADED and GUARD
+ * INACTIVE banners (#993). Byte-identical to the pre-#993 inline banner text so
+ * the #992 banner-visibility tests stay green.
+ */
+const GUARD_CONSEQUENCE = {
+  degraded: [
+    '    Consequence: destructive-command enforcement IS still armed, but it is evaluating the',
+    '    COMMITTED (HEAD) command lexer — any uncommitted change to that file is NOT in effect.',
+  ],
+  inactive: [
+    '    Consequence: destructive Bash commands (git reset --hard, rm -rf, git push --force,',
+    '    git stash, redirect-truncate of protected artefacts) 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. Throws on any load failure; the caller banners.
+ *
+ * Order matters only for cost: the cheap plain imports run first, so a broken
+ * `io.mjs` never pays for a pointless `git show` on `command-blocker.mjs`.
+ *
+ * @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');
+  // #993: one generic loader for every repo dependency. Only `blocker` opts into
+  // the `git show HEAD:` fallback (dependency-free, so data:-URL loadable) and
+  // carries the COMPLETE required-export set — validated on the working-tree AND
+  // the HEAD copy, so a partial namespace banners GUARD INACTIVE rather than
+  // arming a guard that fails open per command. A load failure of any entry
+  // throws; the caller banners GUARD INACTIVE.
+  const { modules, degraded } = await armGuard(
+    {
+      io: { specifier: lib('io.mjs') },
+      platform: { specifier: lib('platform.mjs') },
+      config: { specifier: lib('config.mjs') },
+      blockedCommandsPolicy: { specifier: lib('blocked-commands-policy.mjs') },
+      sectionExtractor: { specifier: lib('config', 'section-extractor.mjs') },
+      events: { specifier: lib('events.mjs') },
+      blocker: {
+        specifier: lib('command-blocker.mjs'),
+        headFallback: true,
+        requires: [
+          'tokenizeCommand',
+          'commandMatchesBlocked',
+          'extractRedirectTargets',
+          'redirectRuleMatches',
+          'redirectSpanEnd',
+          'resolveSegmentVerb',
+          'splitChainSegments',
+        ],
+      },
+    },
+    {
+      hookName: HOOK_NAME,
+      repoRoot: PLUGIN_ROOT,
+      projectDir: bannerProjectDir(),
+      consequence: GUARD_CONSEQUENCE,
     }
-    const fresh = await readJson(policyPath);
-    _cachedPolicy = fresh;
-    _cachedPolicyPath = policyPath;
-    _cachedPolicyMtimeMs = mtimeMs;
-    return fresh;
-  } catch {
-    // On any error (stat failure, read failure), re-throw to let caller's existing
-    // try/catch handle the "malformed policy" branch. Do NOT poison the cache.
-    return readJson(policyPath);
-  }
+  );
+
+  ({ readStdin, emitAllow, emitDeny, emitWarn } = modules.io);
+  ({ resolveProjectDir, resolvePluginRoot } = modules.platform);
+  ({ readConfigFile } = modules.config);
+  ({ loadEffectivePolicy } = modules.blockedCommandsPolicy);
+  ({ isSessionConfigHeading } = modules.sectionExtractor);
+  ({ emitEvent } = modules.events);
+  blocker = modules.blocker;
+  degradedLabels = degraded;
+}
+
+/**
+ * Flush the aggregated allow-with-notice channel (#995).
+ *
+ * Warnings raised during rule 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 each warn site: `emitWarn`
+ * is `@returns never`, so an inline call mid-loop would exit BEFORE a later
+ * `block` rule was evaluated — flipping a would-be DENY into an ALLOW-with-notice
+ * (measured: `bash <33×-c>` overshoots the recursion cap, and a command that
+ * both trips the cap AND carries `rm -rf src/` would wave the delete through).
+ * A block, when it fires, exits via `emitDeny` and these notices are simply
+ * dropped: DENY wins, and the stderr copies of each notice remain for CI/debug.
+ *
+ * @param {string[]} notices
+ * @returns {never}
+ */
+function flushNotices(notices) {
+  return notices.length > 0 ? emitWarn(notices.join('\n')) : emitAllow();
 }
 
+// Module-level per-path policy cache (issue #250, extended for the #972
+// floor/overlay merge: one Map entry per policy path instead of a single-path
+// triple, so floor and overlay invalidate independently on mtime advance).
+// Safe because each hook invocation runs as an isolated Node subprocess —
+// state is fresh per process, never shared across calls.
+const _policyCache = new Map();
+
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -115,14 +263,28 @@ function resolveSessionId(input) {
 }
 
 /**
- * Block a command: write structured deny JSON to stdout + exit 2.
- * Uses raw process.exit(2) rather than emitDeny to emit the exact
- * multi-line message format required by the spec.
+ * Block a command: emit the PreToolUse deny envelope via emitDeny (exit 0).
+ *
+ * Until #906 this used a raw `process.exit(2)` plus its own stdout write,
+ * justified by a claim that the multi-line message "required by the spec"
+ * could not go through emitDeny. That claim was false in both halves:
+ *   - Claude Code DISCARDS stdout on exit 2 and reads stderr instead — and
+ *     this function wrote nothing to stderr, so the operator saw only
+ *     `hook error: … No stderr output`, i.e. what looks like a crash. This
+ *     was the single worst instance of that symptom in the repo.
+ *   - emitDeny preserves multi-line reasons verbatim: JSON.stringify escapes
+ *     the newlines, so the exact 4-line reason below round-trips unchanged
+ *     inside `permissionDecisionReason` on ONE stdout line (verified against
+ *     this very reason string). The operator additionally gets the first line
+ *     as the `systemMessage` headline.
  *
  * Emits a best-effort `orchestrator.destructive_guard.blocked` telemetry
- * event BEFORE exiting. Emission failure (e.g. unwritable events.jsonl path)
+ * event BEFORE denying. Emission failure (e.g. unwritable events.jsonl path)
  * must NEVER change the block outcome — the guard's block-decision is
- * strictly independent of telemetry success.
+ * strictly independent of telemetry success. emitDeny never returns, so it
+ * MUST stay the last statement here.
+ *
+ * @returns {Promise<never>}
  */
 async function blockCommand(pattern, ruleId, rationale, command, sessionId) {
   const reason = [
@@ -142,36 +304,8 @@ async function blockCommand(pattern, ruleId, rationale, command, sessionId) {
     // Best-effort — telemetry must never block or alter the guard decision.
   }
 
-  // Structured deny for Claude Code hook protocol
-  process.stdout.write(JSON.stringify({ permissionDecision: 'deny', reason }) + '\n');
-  process.exit(2);
-}
-
-/**
- * Resolve the policy file path, searching in priority order:
- *   1. <CWD>/.orchestrator/policy/blocked-commands.json
- *   2. <CLAUDE_PROJECT_DIR>/.orchestrator/policy/blocked-commands.json
- *   3. <CLAUDE_PLUGIN_ROOT>/.orchestrator/policy/blocked-commands.json
- * Returns the first existing path, or null if none found.
- */
-function resolvePolicyPath(projectDir) {
-  const candidates = [
-    path.join(process.cwd(), '.orchestrator', 'policy', 'blocked-commands.json'),
-  ];
-
-  if (projectDir && projectDir !== process.cwd()) {
-    candidates.push(path.join(projectDir, '.orchestrator', 'policy', 'blocked-commands.json'));
-  }
-
-  const pluginRoot = resolvePluginRoot();
-  if (pluginRoot) {
-    candidates.push(path.join(pluginRoot, '.orchestrator', 'policy', 'blocked-commands.json'));
-  }
-
-  for (const candidate of candidates) {
-    if (existsSync(candidate)) return candidate;
-  }
-  return null;
+  // Structured deny for the Claude Code PreToolUse hook protocol. Never returns.
+  emitDeny(reason);
 }
 
 /**
@@ -201,72 +335,123 @@ async function isGitStashNonEmpty(projectDir) {
  * chained commands (`rm -rf /tmp/x; rm -rf src/`). Quote-aware via
  * tokenizeCommand so a path with spaces inside quotes is one target.
  *
- * Returns an array of target path strings (possibly empty). The caller treats
- * the rm-rf rule as "allowed" only when EVERY returned target is allowlisted.
+ * Wrapper-aware (#982 T2): the segment verb resolves through the transparent
+ * wrappers in WRAPPER_UNWRAP via resolveSegmentVerb — `sudo rm -rf /tmp/ok`,
+ * `timeout 5 rm -rf /x`, `nohup rm -rf …` parse their REAL targets instead of
+ * falling back to the empty-target conservative block. Redirect tokens and
+ * their operands are skipped (#983): they are IO targets, not rm targets.
+ *
+ * Returns BOTH halves of the operand/redirect split (merge of the two
+ * 2026-08-03 guard sessions — the two protection layers are complementary):
+ *   - `targets` — the rm operands (what gets deleted). Judged against the
+ *     rule's `path-allowlist` by the caller.
+ *   - `writeTargets` — the files each WRITE redirect (`truncate` or `append`
+ *     mode) in the same invocation clobbers-or-creates. Read redirects,
+ *     here-docs/here-strings and fd duplications (`2>&1`) contribute nothing.
+ *     The caller holds these to the SAME allowlist (with `/dev/null` carved
+ *     out via isNullSink), because `rm -rf /tmp/ok > src/important.ts` empties
+ *     a project file on the strength of an allowlisted rm operand. This is the
+ *     rm-context layer; protected artefacts (`> CLAUDE.md` — `> AGENTS.md` on
+ *     Codex CLI, the same truncation class) are ADDITIONALLY
+ *     denied command-independently by the `redirect-truncate-protected`
+ *     policy rule (rule 14).
+ *
+ * The caller treats the rm-rf rule as "allowed" only when EVERY operand and
+ * EVERY write-redirect target passes its respective check — a segment whose
+ * pattern matched but whose verb does NOT resolve to `rm` (e.g. an interpreter
+ * payload) contributes no targets and stays fail-closed.
  *
  * @param {string} command
- * @returns {string[]}
+ * @returns {{targets: string[], writeTargets: string[]}}
  */
 function parseRmTargets(command) {
-  const tokens = tokenizeCommand(command);
   const targets = [];
-  let i = 0;
+  const writeTargets = [];
 
-  while (i < tokens.length) {
-    const verb = tokens[i].text.replace(/^.*\//, ''); // basename
-    const isOperator = !tokens[i].quoted && /^(;|&&|\|\||\||&)$/.test(tokens[i].text);
-    if (isOperator) { i++; continue; }
-    if (verb !== 'rm') { i++; continue; }
+  for (const segment of blocker.splitChainSegments(blocker.tokenizeCommand(command))) {
+    const { verb, index } = blocker.resolveSegmentVerb(segment);
+    if (verb !== 'rm') continue;
 
-    // Consume this `rm` invocation's args until the next chain operator.
-    i++; // skip `rm`
     let seenDashDash = false;
-    while (i < tokens.length) {
-      const tok = tokens[i];
-      // Stop at unquoted chain operators — they delimit the next command.
-      if (!tok.quoted && /^(;|&&|\|\||\||&)$/.test(tok.text)) break;
-      if (!seenDashDash && tok.text === '--') { seenDashDash = true; i++; continue; }
-      // A flag is unquoted and starts with '-' (and is not the bare '-' stdin marker).
-      if (!seenDashDash && !tok.quoted && tok.text.startsWith('-') && tok.text !== '-') {
-        i++;
+    for (let i = index + 1; i < segment.length; i++) {
+      const tok = segment[i];
+      if (tok.redirect) {
+        const end = blocker.redirectSpanEnd(segment, i);
+        const mode = tok.redirect.mode;
+        if ((mode === 'truncate' || mode === 'append') && end > i) {
+          const operand = segment[end];
+          if (operand && !(!operand.quoted && /^(;|&&|\|\||\||&)$/.test(operand.text))) {
+            writeTargets.push(operand.text);
+          }
+        }
+        i = end;
         continue;
       }
+      if (!seenDashDash && tok.text === '--') { seenDashDash = true; continue; }
+      // A flag is unquoted and starts with '-' (and is not the bare '-' stdin marker).
+      if (!seenDashDash && !tok.quoted && tok.text.startsWith('-') && tok.text !== '-') continue;
       targets.push(tok.text);
-      i++;
     }
   }
 
-  return targets;
+  return { targets, writeTargets };
+}
+
+/**
+ * `/dev/null` is the one write-redirect destination that destroys nothing: it is
+ * a character device, so `>` on it neither truncates nor creates a file. It is
+ * also the single most common rm-plumbing target (`rm -rf /tmp/x 2> /dev/null`).
+ *
+ * Deliberately NOT folded into isRmPathAllowed: `rm -rf /dev/null` must stay
+ * blocked — deleting the device node is destructive, writing to it is not.
+ *
+ * @param {string} targetPath
+ * @returns {boolean}
+ */
+function isNullSink(targetPath) {
+  return Boolean(targetPath)
+    && path.isAbsolute(targetPath)
+    && path.normalize(targetPath) === path.join(path.sep, 'dev', 'null');
 }
 
 /**
  * Detect whether the command contains an UNQUOTED `rm` invocation carrying BOTH
  * recursive (`-r`/`-R`/`--recursive`) AND force (`-f`/`--force`) semantics,
- * including combined/short forms (`-rf`, `-fr`, `-r -f`). This catches flag-form
- * variants the literal "rm -rf" pattern misses (#641 gap closure) while staying
- * consistent with the quoted-payload guard: an `rm` that appears only inside a
- * quoted token is NOT treated as an invocation here.
+ * including combined/short forms (`-rf`, `-fr`, `-r -f`) and the long-flag pair
+ * (`--recursive --force`). This catches flag-form variants the literal "rm -rf"
+ * pattern misses (#641 gap closure) while staying consistent with the
+ * quoted-payload guard: an `rm` that appears only inside a quoted token is NOT
+ * treated as an invocation here.
+ *
+ * Wrapper-aware (#982 T2) + redirect-skip (#983) — same segment mechanics as
+ * parseRmTargets above.
+ *
+ * Redirect operators and their targets are skipped for the same reason as in
+ * parseRmTargets: a redirect target is a filename the shell consumes, so
+ * `rm -r /tmp/x > -f` must not read `-f` as rm's force flag.
+ *
+ * This walker deliberately DISCARDS redirect spans entirely. Its question is
+ * only "does this command contain a recursive+force rm at all", i.e. whether
+ * the rm-rf rule MATCHES — it never decides allow-vs-deny. Write-redirect
+ * targets are judged once, by the `redirect-truncate-protected` policy rule
+ * (rule 14), never here — a second collector would give the guard a silently
+ * divergent opinion about the same fact.
  *
  * @param {string} command
  * @returns {boolean}
  */
 function commandHasRecursiveForceRm(command) {
-  const tokens = tokenizeCommand(command);
-  let i = 0;
-  while (i < tokens.length) {
-    const tok = tokens[i];
-    const verb = tok.text.replace(/^.*\//, ''); // basename
-    if (tok.quoted || verb !== 'rm') { i++; continue; }
-
-    // Scan this rm invocation's flags until the next unquoted chain operator.
-    i++; // skip `rm`
+  for (const segment of blocker.splitChainSegments(blocker.tokenizeCommand(command))) {
+    const { verb, index } = blocker.resolveSegmentVerb(segment);
+    if (verb !== 'rm' || segment[index].quoted) continue;
+
     let recursive = false;
     let force = false;
     let seenDashDash = false;
-    while (i < tokens.length) {
-      const t = tokens[i];
-      if (!t.quoted && /^(;|&&|\|\||\||&)$/.test(t.text)) break;
-      if (!seenDashDash && t.text === '--') { seenDashDash = true; i++; continue; }
+    for (let i = index + 1; i < segment.length; i++) {
+      const t = segment[i];
+      if (t.redirect) { i = blocker.redirectSpanEnd(segment, i); continue; }
+      if (!seenDashDash && t.text === '--') { seenDashDash = true; continue; }
       if (!seenDashDash && !t.quoted && t.text.startsWith('-') && t.text !== '-') {
         if (t.text === '--recursive') recursive = true;
         else if (t.text === '--force') force = true;
@@ -275,16 +460,138 @@ function commandHasRecursiveForceRm(command) {
           if (/[rR]/.test(t.text)) recursive = true;
           if (/f/.test(t.text)) force = true;
         }
-        i++;
-        continue;
       }
-      i++; // non-flag arg (a target) — skip
+      // non-flag arg (a target) — skip
     }
     if (recursive && force) return true;
   }
   return false;
 }
 
+/** Probe operator per redirect mode — see findMatchedRedirectEntry. */
+const REDIRECT_PROBE_OPS = { truncate: '>', append: '>>', read: '<' };
+
+/**
+ * Identify WHICH resolved redirect entry a matched redirect-truncate rule hit,
+ * so the deny reason can name the target (#983). redirectRuleMatches returns
+ * only a boolean and its glob matcher is internal to command-blocker.mjs —
+ * rather than duplicate the glob logic here (it would be the third copy), each
+ * candidate target is re-probed through redirectRuleMatches with a minimal
+ * single-redirect command. Resolved targets are guaranteed free of `$` and
+ * backticks (those are reported `unresolved`), so the quoted probe round-trips
+ * the target text exactly.
+ *
+ * `repoRoot` MUST be the same value the deciding redirectRuleMatches call used
+ * (#988 T1): an absolute/`~` target only matches when the root is supplied, so
+ * dropping it here would leave `hit === null` for exactly the targets the new
+ * resolution added and the deny reason would silently fall back to the pattern.
+ *
+ * @param {object} rule — the redirect-truncate policy rule
+ * @param {Array<{ target: string|null, mode: string, unresolved?: boolean }>} entries
+ * @param {string} repoRoot — absolute repo root, forwarded to redirectRuleMatches
+ * @returns {{ target: string, mode: string }|null}
+ */
+function findMatchedRedirectEntry(rule, entries, repoRoot) {
+  for (const entry of entries) {
+    if (entry.unresolved) continue;
+    const op = REDIRECT_PROBE_OPS[entry.mode] ?? '>';
+    const probe = `${op} "${entry.target.replace(/[\\"]/g, '\\$&')}"`;
+    if (blocker.redirectRuleMatches(rule, probe, { repoRoot })) return entry;
+  }
+  return null;
+}
+
+/**
+ * Expand a LEADING `$TMPDIR` / `${TMPDIR}` reference in an rm target token.
+ *
+ * The hook is a PreToolUse gate: it sees the raw, UNEXPANDED shell string.
+ * `rm -rf "${TMPDIR}"scratch` therefore arrives as the token `${TMPDIR}scratch`,
+ * which `path.isAbsolute()` reads as a RELATIVE path — so the #641 `wasAbsolute`
+ * gate (correctly, on its own terms) refuses to match it against any /tmp-class
+ * prefix, and the path is instead resolved against the PROJECT dir. A legitimate
+ * temp cleanup is blocked (#935 cause 1). Substituting the value the shell would
+ * have substituted, BEFORE absoluteness is judged, is the narrow fix.
+ *
+ * This does NOT by itself widen the safe set: the expansion result still has to
+ * land under a CONFINED allowlist prefix (see resolveAllowlistPrefixes), so an
+ * inherited `TMPDIR=/etc` expands to `/etc/...` and is still blocked (#642).
+ *
+ * Deliberately narrow: only TMPDIR, only in leading position, only when its
+ * value is absolute, and byte-for-byte as the shell would splice it (no invented
+ * separator — `TMPDIR=/tmp` + `${TMPDIR}x` really is `/tmpx`, not `/tmp/x`).
+ * A generic env-expander would be a far larger attack surface.
+ *
+ * @param {string} targetPath
+ * @returns {string}
+ */
+function expandTmpdirToken(targetPath) {
+  const m = /^\$(?:TMPDIR\b|\{TMPDIR\})/.exec(targetPath);
+  if (!m) return targetPath;
+  const value = process.env.TMPDIR || os.tmpdir();
+  if (!value || !path.isAbsolute(value)) return targetPath;
+  return value + targetPath.slice(m[0].length);
+}
+
+/**
+ * Canonicalise `absPath` by realpath-ing the deepest EXISTING ancestor and
+ * re-attaching the non-existent suffix.
+ *
+ * `fs.realpathSync.native` throws ENOENT on a path that does not exist — which
+ * is the NORMAL case here: `rm -rf` frequently targets something already gone,
+ * and a policy prefix (`$TMPDIR` of another boot session) need not exist either.
+ * The upward walk mirrors the identical pattern in hooks/enforce-scope.mjs
+ * (SECURITY-REQ-03) rather than inventing a second one.
+ *
+ * Any other fs error → return the lexical input unchanged. That is the fail-safe
+ * direction: the caller then compares lexically, i.e. exactly the pre-#935
+ * behaviour, never a broader one.
+ *
+ * @param {string} absPath
+ * @returns {string}
+ */
+function canonicalizeAncestors(absPath) {
+  let ancestor = absPath;
+  const segments = [];
+  for (;;) {
+    try {
+      const real = fs.realpathSync.native(ancestor);
+      return segments.length ? path.join(real, ...segments.reverse()) : real;
+    } catch (err) {
+      // ENOENT: nothing at this level yet. ENOTDIR: a FILE sits in the chain.
+      // Both mean "keep walking up"; anything else (ELOOP, EACCES) → lexical.
+      if (err?.code !== 'ENOENT' && err?.code !== 'ENOTDIR') return absPath;
+      const parent = path.dirname(ancestor);
+      if (parent === ancestor) return absPath; // reached the fs root, nothing existed
+      segments.push(path.basename(ancestor));
+      ancestor = parent;
+    }
+  }
+}
+
+/**
+ * Canonical LOCATION of an `rm` target.
+ *
+ * `rm -rf X` removes X ITSELF: when X is a symlink the link is unlinked and what
+ * it points at is untouched. So the final segment must NOT be symlink-resolved —
+ * only its parent chain. Resolving the leaf would be both wrong about what rm
+ * does and unsafe: `<project>/link-to-tmp` would canonicalise to /private/tmp and
+ * read as a safe temp target while the delete lands on project content.
+ *
+ * Canonicalising the parent chain keeps the judgement honest in both directions:
+ *   - `/tmp/link-to-etc/x` canonicalises OUT of the temp allowlist → blocked.
+ *     The pre-#935 literal prefix match allowed it (measured, real hole).
+ *   - `$TMPDIR/x` and its `/private/var/folders/...` canonical spelling collapse
+ *     onto the same string → both allowed, no literal-form guessing.
+ *
+ * @param {string} abs — already `path.normalize`d absolute path
+ * @returns {string}
+ */
+function canonicalizeRmTarget(abs) {
+  const parent = path.dirname(abs);
+  if (parent === abs) return abs; // filesystem root
+  return path.join(canonicalizeAncestors(parent), path.basename(abs));
+}
+
 /**
  * Return true when a single path is a safe `rm -rf` target.
  *
@@ -293,7 +600,7 @@ function commandHasRecursiveForceRm(command) {
  *   - <projectRoot>/node_modules (any depth)
  *   - /tmp/ (any depth)                    — agent-owned scratch
  *   - /private/tmp/ (any depth)            — macOS canonical /tmp
- *   - resolved os.tmpdir() / $TMPDIR (any depth)
+ *   - resolved os.tmpdir() / $TMPDIR (any depth), in either spelling
  *
  * The /tmp-class prefixes come from the rule's optional `path-allowlist` and are
  * resolved at runtime here.
@@ -307,12 +614,17 @@ function isRmPathAllowed(targetPath, projectDir, ruleAllowlist = []) {
   if (!targetPath) return false;
 
   const base = projectDir || process.cwd();
-  const wasAbsolute = path.isAbsolute(targetPath);
+  // Restore the shell's own substitution before judging absoluteness (#935).
+  const effective = expandTmpdirToken(targetPath);
+  const wasAbsolute = path.isAbsolute(effective);
 
   // Project-relative safe dirs (always allowed, independent of the rule allowlist).
+  // Deliberately LEXICAL: a project-relative candidate is never symlink-resolved,
+  // otherwise a link inside the project pointing at /tmp would read as safe and
+  // `rm -rf <that link>` — which destroys project content — would be allowed.
   const abs = wasAbsolute
-    ? path.normalize(targetPath)
-    : path.resolve(base, targetPath);
+    ? path.normalize(effective)
+    : path.resolve(base, effective);
 
   const safeProjectDirs = [
     path.join(base, '.orchestrator', 'tmp'),
@@ -328,9 +640,14 @@ function isRmPathAllowed(targetPath, projectDir, ruleAllowlist = []) {
   // /tmp prefix just because the project dir itself happens to live under /tmp
   // (the case on CI runners where os.tmpdir() === /tmp). #641.
   if (wasAbsolute) {
+    // Compare CANONICAL forms on both sides. Literal matching made the verdict
+    // depend on which spelling of the same directory was typed (`/var/folders/…`
+    // allowed, `/private/var/folders/…` blocked — #935 cause 2) and let a symlink
+    // under /tmp launder a non-temp destination into the allowlist.
+    const canonTarget = canonicalizeRmTarget(abs);
     for (const prefix of resolveAllowlistPrefixes(ruleAllowlist)) {
       // The target must be the prefix dir itself or a descendant of it.
-      if (abs === prefix || abs.startsWith(prefix + path.sep)) return true;
+      if (canonTarget === prefix || canonTarget.startsWith(prefix + path.sep)) return true;
     }
   }
 
@@ -342,23 +659,51 @@ function isRmPathAllowed(targetPath, projectDir, ruleAllowlist = []) {
  * prefixes. `$TMPDIR` expands to env.TMPDIR (if set) and os.tmpdir(); literal
  * paths are normalised. Trailing slashes are stripped for prefix comparison.
  *
+ * Every prefix is emitted in BOTH its lexical and its canonical (realpath)
+ * spelling, because the target it is compared against is canonicalised too
+ * (see canonicalizeRmTarget) — and when realpath is unavailable both sides fall
+ * back to lexical together, so the pair never drifts apart.
+ *
  * @param {string[]} ruleAllowlist
  * @returns {string[]} normalised absolute prefixes (no trailing slash)
  */
 function resolveAllowlistPrefixes(ruleAllowlist) {
   const out = new Set();
+  const strip = (p) => path.normalize(p).replace(/[/\\]+$/, '');
+
+  // Canonical macOS spellings are listed EXPLICITLY next to their symlink form:
+  // /tmp → /private/tmp and /var/folders → /private/var/folders. A TMPDIR handed
+  // to us already canonicalised (what fs.realpath returns on macOS) previously
+  // failed this confinement check and contributed NO prefix at all, so EVERY
+  // $TMPDIR target was blocked (#935 cause 2).
+  const tempRoots = ['/tmp', '/private/tmp', '/var/folders', '/private/var/folders']
+    .map((p) => path.normalize(p));
+  const underTempRoot = (p) =>
+    tempRoots.some((root) => p === root || p.startsWith(root + path.sep));
+
+  // Operator-authored, VCS-reviewed policy literals (`/tmp/`, `/private/tmp/`).
   const add = (p) => {
     if (!p) return;
-    const norm = path.normalize(p).replace(/[/\\]+$/, '');
-    if (norm) out.add(norm);
+    const lex = strip(p);
+    if (!lex) return;
+    out.add(lex);
+    const canon = strip(canonicalizeAncestors(lex));
+    if (canon) out.add(canon);
   };
-  const tempRoots = ['/tmp', '/private/tmp', '/var/folders'].map((p) => path.normalize(p));
+
+  // Environment-derived (`$TMPDIR`) — attacker-influencable, hence DOUBLE
+  // confinement: the value must sit under a temp root both as written AND after
+  // symlink resolution. Checking only the lexical form would let a `TMPDIR`
+  // pointing at a symlink under /tmp (e.g. /tmp/evil → <project>) promote the
+  // project itself to an allowlisted prefix (#642 confinement, extended).
   const addTemp = (p) => {
     if (!p || !path.isAbsolute(p)) return;
-    const norm = path.normalize(p).replace(/[/\\]+$/, '');
-    if (tempRoots.some((root) => norm === root || norm.startsWith(root + path.sep))) {
-      out.add(norm);
-    }
+    const lex = strip(p);
+    if (!lex || !underTempRoot(lex)) return;
+    const canon = strip(canonicalizeAncestors(lex));
+    if (!canon || !underTempRoot(canon)) return;
+    out.add(lex);
+    out.add(canon);
   };
 
   for (const entry of Array.isArray(ruleAllowlist) ? ruleAllowlist : []) {
@@ -392,6 +737,22 @@ async function main() {
   const projectDir = resolveProjectDir();
   const sessionId = resolveSessionId(input);
 
+  // #995 — aggregated allow-with-notice channel. Warn-severity matches and
+  // fail-visible markers accumulate here (stderr copies are kept for parity) and
+  // flush ONCE, on the visible stdout channel, only after EVERY rule has been
+  // evaluated. See flushNotices for why inline emitWarn would fail open.
+  const notices = [];
+  // A guard armed from HEAD (working-tree module unparseable) is a visible-channel
+  // concern too: the DEGRADED banner rides stderr only, which exit-0 discards. The
+  // stderr banner already fired once-per-session inside armGuard; surface it on
+  // stdout 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.`
+    );
+  }
+
   // G3 — bypass: allow-destructive-ops: true in Session Config
   // Note: parseSessionConfig only returns known fields; allow-destructive-ops is
   // a new field, so we parse the raw markdown for it directly.
@@ -402,7 +763,10 @@ async function main() {
     const lines = mdContent.split(/\r?\n/);
     let inConfig = false;
     for (const line of lines) {
-      if (line === '## Session Config') { inConfig = true; continue; }
+      // SSOT predicate (#968) — never re-derive this comparison. A local copy
+      // that drifts LOOSER than the extractor silently disagrees with the
+      // runtime about where the config block starts.
+      if (isSessionConfigHeading(line)) { inConfig = true; continue; }
       if (inConfig && /^## /.test(line)) break;
       if (inConfig) {
         const m = line.match(/^\s*(?:-\s+\*\*)?allow-destructive-ops(?::\*\*)?\s*:\s*(\S+)/);
@@ -416,42 +780,82 @@ async function main() {
     // No config file or parse error — proceed to policy check
   }
 
-  // G4 — policy load
-  const policyPath = resolvePolicyPath(projectDir);
-  if (!policyPath) {
-    process.stderr.write(
-      '⚠ pre-bash-destructive-guard: policy file not found ' +
-      '(.orchestrator/policy/blocked-commands.json) — skipping guard\n'
-    );
-    return emitAllow();
-  }
-
-  let policy;
-  try {
-    policy = await loadPolicyCached(policyPath);
-  } catch {
-    process.stderr.write(
-      '⚠ pre-bash-destructive-guard: policy file is malformed (invalid JSON) — skipping guard\n'
-    );
-    return emitAllow();
-  }
-
-  if (!policy || !Array.isArray(policy.rules)) {
-    process.stderr.write(
-      '⚠ pre-bash-destructive-guard: policy file missing .rules array — skipping guard\n'
-    );
-    return emitAllow();
+  // G4 — policy load (#972: floor/overlay merge, not first-hit-wins).
+  // The plugin-root policy is the FLOOR; a cwd/projectDir policy is an OVERLAY
+  // that can only add rules or escalate severity — an empty or malformed
+  // consumer policy fails TO THE FLOOR instead of silently disarming the guard.
+  // Only when NO usable policy exists at all does the guard keep its documented
+  // fail-open (rules === null → emitAllow with a stderr warning).
+  const { rules, warnings } = await loadEffectivePolicy({
+    cwd: process.cwd(),
+    projectDir,
+    pluginRoot: resolvePluginRoot(),
+    cache: _policyCache,
+  });
+  for (const warning of warnings) {
+    process.stderr.write(`⚠ pre-bash-destructive-guard: ${warning}\n`);
   }
+  // No usable policy anywhere → documented total fail-open. Flush any notice
+  // already queued (a DEGRADED head-fallback notice), else a plain allow: the
+  // policy-load warnings above stay stderr-only, as they always have.
+  if (!Array.isArray(rules)) return flushNotices(notices);
 
   // G5 — rule evaluation
-  for (const rule of policy.rules) {
+  for (const rule of rules) {
     const { id, pattern, severity, rationale = '' } = rule;
 
+    // #983 — redirect-truncate rules are decided by redirect TARGET via
+    // redirectRuleMatches, NEVER by the generic pattern path below: their
+    // `pattern: ">"` substring-matches virtually every redirect (measured
+    // interim FP: `bash -c 'echo a > b'` denied), so this branch must fully
+    // shadow the pattern match for this rule class.
+    if (rule.type === 'redirect-truncate') {
+      const modes = new Set(
+        Array.isArray(rule.modes) && rule.modes.length > 0 ? rule.modes : ['truncate']
+      );
+      const collected = blocker.extractRedirectTargets(command);
+      const entries = collected.filter((e) => modes.has(e.mode));
+      // Recursion-cap markers (#988 T2) carry `mode: null` by construction — a
+      // bare `modes.has(e.mode)` filter drops them, which would make the new
+      // marker unobservable here. Keep them alongside the mode-matching ones.
+      const unresolved = collected.filter(
+        (e) => e.unresolved && (e.mode === null || modes.has(e.mode))
+      );
+      if (unresolved.length > 0) {
+        // Variable/substitution operands are never match candidates (#641 FP
+        // class) — surface them instead of guessing; never block on a guess.
+        // Same for a payload subtree a recursion cap cut off: the cap stays,
+        // its effect stops being silent.
+        const reasons = [
+          ...new Set(unresolved.map((e) => e.reason ?? 'variable/substitution')),
+        ].join(', ');
+        // #995 — the #988-T2 recursion-cap marker used to reach stderr only, so
+        // under exit-0 a budget-exhausted command (`bash <33×-c>` hiding
+        // `> CLAUDE.md`) allowed with an INVISIBLE notice. Aggregate onto the
+        // visible channel; keep the stderr copy for parity.
+        const msg = `pre-bash-destructive-guard: unresolved redirect target (${reasons}) — not matched (fail-visible)`;
+        process.stderr.write(`⚠ ${msg}\n`);
+        notices.push(msg);
+      }
+      if (!blocker.redirectRuleMatches(rule, command, { repoRoot: projectDir })) continue;
+      if (severity !== 'block') {
+        const msg = `pre-bash-destructive-guard: redirect target matched (rule: ${id}) — ${rationale}`;
+        process.stderr.write(`⚠ ${msg}\n`);
+        notices.push(msg); // #995 — visible on the allow-with-notice channel
+        continue;
+      }
+      // Reason stays short (stdout-budget): operator + target, never the command.
+      const hit = findMatchedRedirectEntry(rule, entries, projectDir);
+      const label = hit ? `${REDIRECT_PROBE_OPS[hit.mode] ?? '>'} ${hit.target}` : pattern;
+      await blockCommand(label, id, rationale, command, sessionId);
+      continue; // unreachable (blockCommand never returns) — kept for clarity
+    }
+
     // The rm-rf-destructive rule also fires for recursive+force rm flag variants
     // the literal "rm -rf" pattern misses (`rm -r -f`, `rm -fr`) — #641 gap closure.
     const matched = id === 'rm-rf-destructive'
-      ? (commandMatchesBlocked(command, pattern) || commandHasRecursiveForceRm(command))
-      : commandMatchesBlocked(command, pattern);
+      ? (blocker.commandMatchesBlocked(command, pattern) || commandHasRecursiveForceRm(command))
+      : blocker.commandMatchesBlocked(command, pattern);
     if (!matched) continue;
 
     if (severity === 'warn') {
@@ -463,9 +867,9 @@ async function main() {
           continue;
         }
       }
-      process.stderr.write(
-        `⚠ pre-bash-destructive-guard: '${pattern}' (rule: ${id}) — ${rationale}\n`
-      );
+      const msg = `pre-bash-destructive-guard: '${pattern}' (rule: ${id}) — ${rationale}`;
+      process.stderr.write(`⚠ ${msg}\n`);
+      notices.push(msg); // #995 — visible on the allow-with-notice channel
       // Best-effort telemetry — must never affect the warn/allow outcome.
       try {
         await emitEvent('orchestrator.destructive_guard.warned', {
@@ -484,14 +888,25 @@ async function main() {
       // Special: rm-rf-destructive — path exception
       if (id === 'rm-rf-destructive') {
         const ruleAllowlist = Array.isArray(rule['path-allowlist']) ? rule['path-allowlist'] : [];
-        const targets = parseRmTargets(command);
+        const { targets, writeTargets } = parseRmTargets(command);
         // Allow ONLY when there is at least one target AND every target is
         // allowlisted. An unparseable command (no targets) or any non-allowlisted
         // target → block (conservative). This makes mixed chains like
         // `rm -rf /tmp/x; rm -rf src/` block on the src/ target.
+        //
+        // Every WRITE-redirect target of the same invocation must clear the SAME
+        // allowlist (with /dev/null carved out): `>` truncates its target before
+        // rm ever runs, so without this the allow path waved through
+        // `rm -rf /tmp/ok > src/important.ts` on the strength of an allowlisted
+        // rm operand. Protected artefacts (`> CLAUDE.md`) are ADDITIONALLY
+        // covered command-independently by rule 14 (redirect-truncate-protected)
+        // — two complementary layers from the two 2026-08-03 guard sessions.
         const allAllowed =
           targets.length > 0 &&
-          targets.every((t) => isRmPathAllowed(t, projectDir, ruleAllowlist));
+          targets.every((t) => isRmPathAllowed(t, projectDir, ruleAllowlist)) &&
+          writeTargets.every(
+            (t) => isNullSink(t) || isRmPathAllowed(t, projectDir, ruleAllowlist)
+          );
         if (allAllowed) {
           // Safe paths only (.orchestrator/tmp, node_modules, /tmp, $TMPDIR) — allow
           continue;
@@ -502,8 +917,45 @@ async function main() {
     // Unknown severity → skip (conservative allow for unknown future severities)
   }
 
-  // G6 — no blocking match
-  return emitAllow();
+  // G6 — no blocking match. Flush the aggregated allow-with-notice channel
+  // (#995): emitWarn if any notice queued (visible), else a silent allow.
+  return flushNotices(notices);
+}
+
+// ---------------------------------------------------------------------------
+// Entry point (#992)
+//
+// TWO distinct failure classes, two distinct banners — do not merge them:
+//
+//   1. LOAD failure (`bootstrap()` throws): the guard never armed. Nothing was
+//      evaluated, so the fail-open is total. This used to be a bare exit-1
+//      crash with 0 bytes of stdout — indistinguishable from an allow, and
+//      therefore invisible. Now it exits 0 (still fail-open, so a broken module
+//      cannot brick the session) but SAYS SO, loudly, once per session.
+//   2. RUNTIME failure inside `main()`: pre-existing behaviour, unchanged.
+//      The guard armed and then tripped over a specific command; that is a
+//      narrower blast radius and keeps its historical `internal error` line.
+// ---------------------------------------------------------------------------
+try {
+  await bootstrap();
+} catch (loadError) {
+  try {
+    const { emitGuardInactiveBanner } = await import('./_lib/guard-source-loader.mjs');
+    // Unthrottled by design: EVERY call in an unarmed session says so (#992
+    // hardening — the once-per-session marker it used to pass through was
+    // suppressible by a bare `touch` on a derivable tmp path). 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
+    // (no once-per-session keying) — repeated noise beats a silent disarm.
+    process.stderr.write(
+      '🚨 pre-bash-destructive-guard: GUARD INACTIVE — module load failed ' +
+        `(${String(loadError?.message || loadError).split('\n')[0]}). ` +
+        'Destructive Bash commands are NOT being blocked. See issue #992.\n'
+    );
+  }
+  process.exit(0); // fail-open, but no longer fail-silent
 }
 
 // Top-level error handler — never let exit 1 leak