session-orchestrator 3.19.0 → 3.21.0

package/hooks/on-session-end.mjs

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

package/hooks/on-session-start.mjs

@@ -458,12 +458,15 @@ async function main() {
   let bannerData = null;
   if (await isHostBannerEnabled(projectRoot)) {
     bannerData = await emitHostBanner(projectRoot);
-    // Always-on nudge: user decisions must go through AskUserQuestion, not inline
-    // markdown lists. The coordinator chat stream is dense and prose questions
-    // are reliably missed. Full rationale + exceptions in .claude/rules/ask-via-tool.md.
+    // Always-on nudge: a user decision has three legitimate forms and AUQ-001
+    // routes between them in order — operator verb first (nothing is blocked
+    // while the operator picks his moment), then derive-and-report from Session
+    // Config / STATE.md / git, and only then the tool. The banner carries the
+    // ORDER, not an absolute; full routing + exceptions in
+    // .claude/rules/ask-via-tool.md.
     try {
       console.log(JSON.stringify({
-        systemMessage: '🎯 User decisions → AskUserQuestion tool. Inline choice lists = bug (.claude/rules/ask-via-tool.md).',
+        systemMessage: '🎯 Decide: operator verb (/go) > derive+report > AUQ if blocking (.claude/rules/ask-via-tool.md).',
       }));
     } catch { /* best effort */ }
   }

package/hooks/on-stop.mjs

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

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

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

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

@@ -73,6 +73,7 @@ if (!shouldRunHook('pre-bash-destructive-guard')) process.exit(0);
 /** @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;
 /**
@@ -81,10 +82,10 @@ let resolvePluginRoot;
  * primitives).
  *
  * Held as ONE object rather than destructured into six bindings on purpose: the
- * required-export list then exists in exactly one place —
- * `COMMAND_BLOCKER_EXPORTS` in `_lib/guard-source-loader.mjs`, which validates
- * both the working-tree and the HEAD copy against it. The previous split (six
- * names destructured here, two of them checked there) is what let a HEAD copy
+ * 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.
  *
@@ -96,8 +97,38 @@ 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.
@@ -117,22 +148,76 @@ function bannerProjectDir() {
  * @returns {Promise<void>}
  */
 async function bootstrap() {
-  ({ readStdin, emitAllow, emitDeny } = await import('../scripts/lib/io.mjs'));
-  ({ resolveProjectDir, resolvePluginRoot } = await import('../scripts/lib/platform.mjs'));
-  ({ readConfigFile } = await import('../scripts/lib/config.mjs'));
-  ({ loadEffectivePolicy } = await import('../scripts/lib/blocked-commands-policy.mjs'));
-  ({ isSessionConfigHeading } = await import('../scripts/lib/config/section-extractor.mjs'));
-  ({ emitEvent } = await import('../scripts/lib/events.mjs'));
-
-  const { loadCommandBlocker } = await import('./_lib/guard-source-loader.mjs');
-  // Throws unless the loaded namespace carries the COMPLETE required export set
-  // (working-tree copy or HEAD fallback alike) — the caller then banners
-  // GUARD INACTIVE rather than arming a guard that cannot evaluate.
-  ({ module: blocker } = await loadCommandBlocker({
-    specifier: pathToFileURL(path.join(PLUGIN_ROOT, 'scripts', 'lib', 'command-blocker.mjs')).href,
-    repoRoot: PLUGIN_ROOT,
-    projectDir: bannerProjectDir(),
-  }));
+  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,
+    }
+  );
+
+  ({ 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
@@ -242,29 +327,6 @@ async function isGitStashNonEmpty(projectDir) {
   }
 }
 
-/**
- * Given a redirect token at `segment[i]`, return the index of the LAST token
- * belonging to that redirect (the operand word, when one exists). Redirect
- * operators and their operands name IO targets, not command arguments —
- * `rm -rf /tmp/ok > out.log` must not collect `>` or `out.log` as rm targets
- * (#983 FP fix). `dup` (`2>&1`) carries no operand word.
- *
- * @param {Array<{ text: string, quoted: boolean, redirect?: object }>} segment
- * @param {number} i — index of the redirect token
- * @returns {number}
- */
-function redirectSpanEnd(segment, i) {
-  const tok = segment[i];
-  // `dup` (2>&1) carries its target inline; `heredoc` consumes its delimiter in
-  // the lexer (the body arrives as a separate QUOTED token) — neither owns an
-  // operand word, and claiming one would swallow the next real token.
-  const hasOperandWord = tok.redirect.mode !== 'dup' && tok.redirect.mode !== 'heredoc';
-  if (hasOperandWord && i + 1 < segment.length && !segment[i + 1].redirect) {
-    return i + 1;
-  }
-  return i;
-}
-
 /**
  * Parse ALL non-flag path arguments from every `rm` invocation in a command.
  *
@@ -314,7 +376,7 @@ function parseRmTargets(command) {
     for (let i = index + 1; i < segment.length; i++) {
       const tok = segment[i];
       if (tok.redirect) {
-        const end = redirectSpanEnd(segment, i);
+        const end = blocker.redirectSpanEnd(segment, i);
         const mode = tok.redirect.mode;
         if ((mode === 'truncate' || mode === 'append') && end > i) {
           const operand = segment[end];
@@ -388,7 +450,7 @@ function commandHasRecursiveForceRm(command) {
     let seenDashDash = false;
     for (let i = index + 1; i < segment.length; i++) {
       const t = segment[i];
-      if (t.redirect) { i = redirectSpanEnd(segment, i); continue; }
+      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;
@@ -675,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.
@@ -717,7 +795,10 @@ async function main() {
   for (const warning of warnings) {
     process.stderr.write(`⚠ pre-bash-destructive-guard: ${warning}\n`);
   }
-  if (!Array.isArray(rules)) return emitAllow();
+  // 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 rules) {
@@ -748,15 +829,19 @@ async function main() {
         const reasons = [
           ...new Set(unresolved.map((e) => e.reason ?? 'variable/substitution')),
         ].join(', ');
-        process.stderr.write(
-          `⚠ pre-bash-destructive-guard: unresolved redirect target (${reasons}) — not matched (fail-visible)\n`
-        );
+        // #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') {
-        process.stderr.write(
-          `⚠ pre-bash-destructive-guard: redirect target matched (rule: ${id}) — ${rationale}\n`
-        );
+        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.
@@ -782,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', {
@@ -832,8 +917,9 @@ 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);
 }
 
 // ---------------------------------------------------------------------------
@@ -857,8 +943,9 @@ 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).
-    emitGuardInactiveBanner({ error: loadError });
+    // 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.