session-orchestrator 3.19.0 → 3.20.0

package/docs/session-config-template.md

@@ -938,29 +938,6 @@ config-protection:
   mode: warn               # warn | strict (strict blocks loosening, exit 2)
 allow-config-weakening: false   # per-session bypass (mirrors allow-destructive-ops)
 
-# Strategic compact-nudge (ecc-analysis / #620)
-compact-nudge:
-  enabled: false           # opt-in advisory /compact nudge at inter-wave checkpoints
-  after: [discovery, impl] # subset of {discovery, impl, failed-wave}
-  # NOTE: `discovery` / `impl` are wave ROLES — the §3c gate matches them against
-  # the wave's role string. `failed-wave` is NOT a role; it keys off the wave's
-  # failure OUTCOME (any wave that did not pass its quality gate), so it can fire
-  # after a wave of any role.
-  mode: warn               # warn | off
-
-# /goal continuation anchor at named seams (Lever 5 / #636)
-goal-integration:
-  enabled: false                          # opt-in advisory; default off — zero behaviour change when absent
-  seams: [session-end-backlog, inter-wave-fixloop]   # subset of {session-end-backlog, inter-wave-fixloop}
-  # ADVISORY ONLY. Surfaces ONE suggested /goal command at the named seam(s);
-  # never auto-invokes /goal, never blocks. /goal = Adapter (ADR-0010): the
-  # evaluator reads the transcript and runs NO tools — it anchors CONTINUATION,
-  # never JUDGMENT. Deterministic exit-code gates (npm test/typecheck/lint) stay
-  # the completion authority. ONE goal per session — the two seams cannot both
-  # hold an active goal; the operator picks one. See `.claude/rules/loop-and-monitor.md`
-  # § LM-008, `skills/session-end/SKILL.md § 1.3a`, and
-  # `skills/wave-executor/wave-loop.md § /goal Continuation Anchor`.
-
 # Webhooks (URLs are required when used — no defaults)
 # webhooks:
 #   slack:

package/hooks/_lib/guard-source-loader.mjs

@@ -30,12 +30,25 @@
  *    began routing around. The banner therefore names the CONSEQUENCE ("guard
  *    INACTIVE" / "running against HEAD, not your working tree"), not just a
  *    file path.
- * 2. **`git show HEAD:<path>` fallback — for `command-blocker.mjs` ONLY.** That
- *    module is dependency-free (its single import is `node:path`) and hence
- *    `data:`-URL loadable. Deliberately NOT generalised to the guard's other 6
- *    repo imports: those were never audited for RELATIVE imports, which a
- *    `data:` URL cannot resolve — that would need its own recursive resolver.
- *    For those modules part 1 (banner) stands alone.
+ * 2. **`git show HEAD:<path>` fallback — for dependency-free modules ONLY.** A
+ *    module whose every import is a `node:*` builtin is `data:`-URL loadable, so
+ *    its committed source can be re-imported from HEAD. Deliberately NOT
+ *    generalised to modules with RELATIVE imports, which a `data:` URL cannot
+ *    resolve — that would need its own recursive resolver. Opt-in per module via
+ *    `headFallback: true`, gated by {@link HEAD_FALLBACK_ALLOWLIST}; for every
+ *    other module part 1 (banner) stands alone.
+ *
+ * ## Generalised across all four deny-capable hooks (#993)
+ *
+ * This started life hard-wired to `pre-bash-destructive-guard` +
+ * `command-blocker.mjs` (the banner text, the required-export list, and the
+ * repo-relative path were all module constants). {@link armGuard} lifts every
+ * one of those into a PARAMETER — `hookName`, per-spec `requires`, per-spec
+ * `headFallback`, and the `consequence` prose — so `enforce-scope`,
+ * `enforce-commands` and `sessions-ledger-guard` bind their own repo
+ * dependencies through the same loader without re-freezing this hook's name into
+ * a banner literal. `hookName` is MANDATORY on both public exports: a default
+ * would silently reintroduce exactly the drift #993 removes.
  *
  * **The coupling is mandatory: the fallback must never fire silently.** A
  * successful HEAD fallback banners too ("running against HEAD, not the working
@@ -98,6 +111,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 
 /** TTL for the session-id-less marker fallback, mirroring `run-node.sh` (6h). */
@@ -110,33 +124,61 @@ const MARKER_VERSION = 1;
 /** Bucket width for the boot-epoch field (seconds), and its accepted drift. */
 const BOOT_BUCKET_S = 10;
 
-/** Repo-relative path of the one module that gets the HEAD fallback. */
-const COMMAND_BLOCKER_REL = 'scripts/lib/command-blocker.mjs';
+/**
+ * The ONLY module basenames a `git show HEAD:` fallback is sound for.
+ *
+ * The fallback re-imports committed source through a `data:` URL (see
+ * {@link importFromSource}), and a `data:` URL has NO base against which a
+ * RELATIVE import specifier could resolve. So the fallback is correct only for a
+ * module whose every import is a `node:*` builtin (or which imports nothing at
+ * all). This set is that dependency-free allowlist; a `headFallback: true` on a
+ * module NOT in it (e.g. `hardening.mjs` / `platform.mjs`, which carry relative
+ * imports) would silently produce an unloadable `data:` module — so
+ * {@link armGuard} rejects it as a hard CONFIG error rather than arming a guard
+ * whose fallback can never fire.
+ *
+ * Keyed on BASENAME deliberately: it is the `git show HEAD:<relPath>` leaf, and
+ * a dependency-free file keeps that property wherever in the tree it sits. To
+ * add a module, verify its import list is `node:*`-only first.
+ */
+const HEAD_FALLBACK_ALLOWLIST = new Set([
+  'command-blocker.mjs',
+  'io.mjs',
+  'path-utils.mjs',
+  'common.mjs',
+  'plugin-root.mjs',
+]);
 
 /**
- * The FULL export set `pre-bash-destructive-guard.mjs` needs from
- * `command-blocker.mjs` — the single source of truth for the shape check.
- *
- * It lives here, and ONLY here, on purpose. The hook no longer destructures the
- * module (it holds the namespace object and calls through it), so there is no
- * second list to drift out of sync: a seventh export is added once, right here,
- * and both the working-tree and the HEAD copy are validated against it.
- *
- * Why the check must cover all of them: it used to assert 2 of the 6, so a HEAD
- * copy OLDER than the working tree — the normal case when a newly added export
- * is the very thing that broke, i.e. the #982/#983/#988 history — passed as
- * "DEGRADED, enforcement IS still armed" and then allowed every command with an
- * `⚠ internal error — <fn> is not a function` line. A fallback that cannot
- * enforce must banner as a TOTAL failure, never as "still armed".
+ * The ONLY environment keys `git show HEAD:<path>` may inherit (see
+ * {@link readFromHead}).
+ *
+ * An ALLOWLIST, deliberately — the predecessor was a denylist that named the
+ * git repository-/object-/config-discovery vars one by one, and a denylist is
+ * unsound by construction: it silently re-opens on every git release that adds a
+ * new config channel, and it had already MISSED three independent ones —
+ * `GIT_CONFIG_PARAMETERS` (a command-line config channel with NO
+ * `GIT_CONFIG_COUNT` gate: `GIT_CONFIG_PARAMETERS="'user.name=X'" git config
+ * user.name` prints `X`), `GIT_CEILING_DIRECTORIES` (can force the shell-out to
+ * fail), and the whole `GIT_TRACE*` family (writes to an attacker-named path as
+ * the invoking user). An allowlist omits every unlisted key — present and
+ * future — so no future git config channel can ride in.
+ *
+ * Kept, and only these: `PATH` (execFileSync resolves the `git` binary through
+ * it), `HOME` (git's own config-discovery root — the USER's `~/.gitconfig`, not
+ * an attacker-set channel), and the locale/tmp/tz vars git honours for messages
+ * and temp files. `git show HEAD:<blob>` on a pipe needs nothing else: no pager
+ * (not a tty), no default smudge/textconv filter, and aliases cannot shadow the
+ * `show` builtin.
  */
-const COMMAND_BLOCKER_EXPORTS = [
-  'tokenizeCommand',
-  'commandMatchesBlocked',
-  'extractRedirectTargets',
-  'redirectRuleMatches',
-  'resolveSegmentVerb',
-  'splitChainSegments',
-];
+const GIT_ENV_ALLOWLIST = Object.freeze([
+  'PATH',
+  'HOME',
+  'LANG',
+  'LC_ALL',
+  'TMPDIR',
+  'TZ',
+]);
 
 /**
  * Resolve the once-per-session banner key.
@@ -147,21 +189,42 @@ const COMMAND_BLOCKER_EXPORTS = [
  * `.orchestrator/session.lock`; when that fails we fall back to a time-TTL
  * marker exactly like `run-node.sh` does.
  *
+ * ## Why the id alone is not the key (#998.3)
+ *
+ * There is exactly ONE `session.lock` per working copy, so two parallel sessions
+ * in the SAME working copy resolve the same `session_id` — and the second one
+ * never sees its own degradation banner, because the first already wrote the
+ * marker. The key is therefore composed with a per-session PROCESS identity.
+ *
+ * **`ppid`, deliberately not `pid`.** Every hook invocation is its own short-lived
+ * node process, so a `pid`-keyed marker would be unique per tool call and the
+ * banner would fire on every call — the noisy-flood class the throttle exists to
+ * prevent, not the shared-marker class it is fixing. `ppid` is the harness
+ * process that spawns the hooks and is stable for the session's life:
+ * `hooks/run-node.sh` uses `exec node` on every branch, so no intermediate shell
+ * survives to become the parent and the ppid IS the harness. This is load-bearing
+ * — an added non-exec branch in `run-node.sh` would silently re-break the key.
+ *
+ * Total key length stays ≤ 64 (48-char id slice + `-pNNNNN`). Markers written in
+ * the old (id-only) format live at different paths and are simply never consulted
+ * — no migration, the worst case is one extra banner.
+ *
  * @param {string} projectDir
  * @returns {{key: string, ttl: boolean}} `ttl: true` means "key is not
  *   session-scoped — apply the 6h time TTL instead of pure existence".
  */
 function resolveBannerKey(projectDir) {
+  const proc = `p${typeof process.ppid === 'number' ? process.ppid : 0}`;
   try {
     const raw = fs.readFileSync(path.join(projectDir, '.orchestrator', 'session.lock'), 'utf8');
     const id = JSON.parse(raw)?.session_id;
     if (typeof id === 'string' && id.length > 0) {
-      return { key: id.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 64), ttl: false };
+      return { key: `${id.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 48)}-${proc}`, ttl: false };
     }
   } catch {
     /* no lock, unreadable, or malformed — fall through to the time TTL */
   }
-  return { key: 'ttl', ttl: true };
+  return { key: `ttl-${proc}`, ttl: true };
 }
 
 /** Per-project marker scope — the digest half of the marker file name. */
@@ -329,16 +392,51 @@ function emitGuardBannerOnce({ projectDir, kind, message }) {
 /**
  * Read a repo file's committed content via `git show HEAD:<relPath>`.
  *
+ * ## Why the git env is scrubbed here (#998.1 — defense in depth)
+ *
+ * The bytes this returns are handed straight to {@link importFromSource}, i.e.
+ * IMPORTED as code inside a deny-capable hook. `-C <repoRoot>` only sets the
+ * child's cwd; it does NOT win against `GIT_DIR`, which overrides repository
+ * discovery outright. With `GIT_DIR=<foreign repo>/.git` in the environment the
+ * call returns a FOREIGN repository's blob at the same relative path, and that
+ * blob is then executed — one env var plus one broken module away from code
+ * execution in the guard itself. Measured on this loader: without `GIT_DIR`
+ * 57,446 bytes of real source, with a foreign `GIT_DIR` 128 bytes of
+ * attacker-controlled content. **No vector is currently known by which a Bash
+ * command sets the LATER hook process's environment — this is defense in depth,
+ * not a fix for a reachable exploit.** It is applied at this single
+ * trust-sensitive shell-out rather than at {@link armGuard} entry, because this
+ * is the only place whose output becomes code.
+ *
+ * ## Allowlist, not denylist (LOW-4)
+ *
+ * The child env is BUILT from {@link GIT_ENV_ALLOWLIST} rather than
+ * `process.env` with a hand-maintained set of deletions. `execFileSync`'s `env`
+ * REPLACES the child environment wholesale (it does not merge into
+ * `process.env`), so every key not on the allowlist is omitted — including
+ * every git config/discovery channel the old denylist did not enumerate. The
+ * denylist had already MISSED `GIT_CONFIG_PARAMETERS` (an independent
+ * command-line config channel with no `GIT_CONFIG_COUNT` gate),
+ * `GIT_CEILING_DIRECTORIES`, and the `GIT_TRACE*` family; an allowlist closes
+ * those and any channel a future git release adds, which is the only form that
+ * survives such a release. See {@link GIT_ENV_ALLOWLIST} for the kept keys and
+ * why each is safe.
+ *
  * @param {string} repoRoot
  * @param {string} relPath - POSIX, repo-relative.
  * @returns {string} file content at HEAD.
  * @throws when git is absent, the dir is not a repo, or the path is not at HEAD.
  */
 function readFromHead(repoRoot, relPath) {
+  const env = {};
+  for (const key of GIT_ENV_ALLOWLIST) {
+    if (process.env[key] !== undefined) env[key] = process.env[key];
+  }
   return execFileSync('git', ['-C', repoRoot, 'show', `HEAD:${relPath}`], {
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'ignore'],
     maxBuffer: 8 * 1024 * 1024,
+    env,
   });
 }
 
@@ -358,73 +456,182 @@ function importFromSource(source) {
 }
 
 /**
- * Assert a loaded `command-blocker.mjs` namespace carries the COMPLETE API the
- * guard calls through. A partial namespace is not a degraded guard — it is a
- * guard that throws on the first command and fails open with an `internal
- * error` line, so it must be treated as a load failure here, at the one place
- * that can still fall back or banner.
+ * Derive a module's repo-relative POSIX path from its import `specifier`,
+ * relative to `repoRoot`. This is what `git show HEAD:<relPath>` consumes and
+ * what the banners name — it REPLACES the former hard-wired `COMMAND_BLOCKER_REL`
+ * constant, so a second `headFallback` module needs no new constant.
+ *
+ * Accepts a `file:` URL (the shape `pathToFileURL(...).href` produces) or an
+ * absolute path; a bare relative specifier is returned verbatim (it cannot be
+ * resolved against `repoRoot` without guessing the importing module's dir, and
+ * `headFallback` callers always pass an absolute `file:` URL).
+ *
+ * @param {string} specifier
+ * @param {string} repoRoot
+ * @returns {string} repo-relative POSIX path
+ */
+function deriveRelPath(specifier, repoRoot) {
+  let absPath;
+  if (typeof specifier === 'string' && specifier.startsWith('file:')) {
+    absPath = fileURLToPath(specifier);
+  } else if (typeof specifier === 'string' && path.isAbsolute(specifier)) {
+    absPath = specifier;
+  } else {
+    return specifier;
+  }
+  return path.relative(repoRoot, absPath).split(path.sep).join('/');
+}
+
+/**
+ * Assert a loaded module namespace exports every name in `requires` as a
+ * function. A partial namespace is not a degraded guard — it is a guard that
+ * throws on the first call and fails open with an `internal error` line, so it
+ * must surface here, at the one place that can still fall back or banner.
+ *
+ * `requires` is passed PER MODULE by the call site — it replaces the former
+ * module-wide `COMMAND_BLOCKER_EXPORTS`, which was both hard-wired to one module
+ * and already INCOMPLETE (it listed 6 of the 8 exports command-blocker.mjs
+ * actually ships). When a spec entry omits `requires`, the shape check is
+ * skipped by construction: correct for a module (io.mjs, events.mjs, …) whose
+ * missing export surfaces as a plain TypeError at its single call site, with no
+ * half-armed fallback to guard against.
+ *
+ * Why the check must cover ALL required names: it used to assert 2 of 6, so a
+ * HEAD copy OLDER than the working tree — the normal case when a newly added
+ * export is the very thing that broke (#982/#983/#988 history) — passed as
+ * "DEGRADED, enforcement IS still armed" and then allowed every command with an
+ * `⚠ internal error — <fn> is not a function` line.
  *
  * @param {object} mod
  * @param {string} origin - human label for the banner ("working-tree copy" | "HEAD copy")
+ * @param {string[]} requires - export names that must be functions
+ * @param {string} relPath - repo-relative path, for the error message
  * @throws {Error} naming every missing export.
  */
-function assertBlockerShape(mod, origin) {
-  const missing = COMMAND_BLOCKER_EXPORTS.filter((name) => typeof mod?.[name] !== 'function');
+function assertShape(mod, origin, requires, relPath) {
+  const missing = requires.filter((name) => typeof mod?.[name] !== 'function');
   if (missing.length > 0) {
     throw new Error(
-      `${origin} of ${COMMAND_BLOCKER_REL} is missing required export(s): ${missing.join(', ')}`
+      `${origin} of ${relPath} is missing required export(s): ${missing.join(', ')}`
     );
   }
 }
 
 /**
- * Load `command-blocker.mjs`, falling back to its HEAD version, never silently.
- *
- * @param {{specifier: string, repoRoot: string, projectDir: string}} opts
- *   `specifier` is the import URL/path used in normal operation; `repoRoot` is
- *   where `git show` runs; `projectDir` keys the banner marker.
- * @returns {Promise<{module: object, degraded: 'head'|null}>}
- * @throws the ORIGINAL working-tree error when the HEAD fallback also fails, so
- *   the caller's catch can banner "guard INACTIVE" with the real cause.
+ * Arm a deny-capable hook's repo dependencies, making every load failure VISIBLE
+ * and — for the dependency-free modules that opt in — recoverable from HEAD.
+ *
+ * The generalised successor to the former `loadCommandBlocker` (#993): the hook
+ * name, the required-export set, and which modules get a HEAD fallback are ALL
+ * parameters now, so `enforce-scope`, `enforce-commands` and
+ * `sessions-ledger-guard` share this one loader without each re-hard-wiring
+ * `pre-bash-destructive-guard` into a banner literal.
+ *
+ * ## The frozen contract (A2/A3 build on this — #993)
+ *
+ * @param {Record<string, {specifier: string, headFallback?: boolean, requires?: string[]}>} specMap
+ *   One entry per module the hook binds, keyed by a stable LABEL the caller reads
+ *   back from the returned `modules`. `specifier` is the normal-operation import
+ *   URL (an absolute `file:` URL for `headFallback` entries — a relative one
+ *   cannot be resolved from this module). `headFallback: true` opts a
+ *   DEPENDENCY-FREE module into the `git show HEAD:` recovery (legal only for a
+ *   {@link HEAD_FALLBACK_ALLOWLIST} basename — a hard error otherwise).
+ *   `requires` lists the export names that must be functions; omit it to skip the
+ *   shape check for that module.
+ * @param {{hookName: string, repoRoot: string, projectDir: string, consequence?: {degraded?: string[], inactive?: string[]}}} opts
+ *   `hookName` is MANDATORY — no default, because a default would re-freeze the
+ *   #993 drift. `repoRoot` is where `git show` runs; `projectDir` keys the
+ *   once-per-session degradation banner; `consequence.degraded` is spliced,
+ *   verbatim, into the DEGRADED banner.
+ * @returns {Promise<{modules: Record<string, object>, degraded: string[]}>}
+ *   `modules` maps each label to its namespace; `degraded` lists the labels that
+ *   loaded from HEAD (empty in the healthy path).
+ * @throws the ORIGINAL working-tree error (with `.headFallbackError` attached
+ *   when a HEAD fallback also failed) so the caller's catch can banner GUARD
+ *   INACTIVE with the real cause.
  */
-export async function loadCommandBlocker({ specifier, repoRoot, projectDir }) {
-  try {
-    const module = await import(specifier);
-    // The shape check runs on BOTH paths. A working-tree copy that parses but
-    // lost an export is the same defect class as a stale HEAD copy: without
-    // this it would arm "successfully" and then fail open per command.
-    assertBlockerShape(module, 'working-tree copy');
-    return { module, degraded: null };
-  } catch (workingTreeError) {
-    let mod;
-    try {
-      mod = await importFromSource(readFromHead(repoRoot, COMMAND_BLOCKER_REL));
-      // A HEAD copy that parses but lost part of the API is NOT a usable
-      // fallback — treat it as a total failure rather than half-arming.
-      assertBlockerShape(mod, 'HEAD copy');
-    } catch (headError) {
-      workingTreeError.headFallbackError = headError;
-      throw workingTreeError;
+export async function armGuard(specMap, { hookName, repoRoot, projectDir, consequence } = {}) {
+  if (typeof hookName !== 'string' || hookName.length === 0) {
+    throw new Error(
+      'armGuard: hookName is required and has no default — a default would reintroduce the exact #993 drift this refactor removes.'
+    );
+  }
+
+  // Insertion order, EXCEPT headFallback entries move LAST: the cheap plain
+  // imports fail first, so a broken dep-free module never pays for a pointless
+  // `git show` on a headFallback module that would have loaded fine.
+  const entries = Object.entries(specMap);
+  entries.sort(([, a], [, b]) => (a.headFallback ? 1 : 0) - (b.headFallback ? 1 : 0));
+
+  const modules = {};
+  const degraded = [];
+
+  for (const [label, spec] of entries) {
+    const { specifier, headFallback = false, requires } = spec;
+    const relPath = deriveRelPath(specifier, repoRoot);
+
+    if (!headFallback) {
+      // No fallback: a missing export or parse error is a plain throw the caller
+      // banners as GUARD INACTIVE. No `git show`, no half-arming to guard.
+      const module = await import(specifier);
+      if (Array.isArray(requires)) assertShape(module, 'working-tree copy', requires, relPath);
+      modules[label] = module;
+      continue;
     }
 
-    emitGuardBannerOnce({
-      projectDir,
-      kind: 'head-fallback',
-      message: [
-        '',
-        '⚠️  pre-bash-destructive-guard: DEGRADED — running against HEAD, not your working tree.',
-        `    ${COMMAND_BLOCKER_REL} failed to load from the working tree:`,
-        `      ${String(workingTreeError?.message || workingTreeError).split('\n')[0]}`,
-        '    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.',
-        `    Fix: repair ${COMMAND_BLOCKER_REL} (conflict markers? partial edit?) and re-run.`,
-        '    See: issue #992.',
-        '',
-      ].join('\n'),
-    });
-
-    return { module: mod, degraded: 'head' };
+    // headFallback is sound ONLY for a dependency-free (node:*-only) module — a
+    // data: URL cannot resolve the relative imports of e.g. hardening.mjs, so a
+    // headFallback:true there would produce a silently-unloadable fallback. Fail
+    // LOUD on the misconfiguration instead of arming a guard that can never
+    // recover.
+    if (!HEAD_FALLBACK_ALLOWLIST.has(path.posix.basename(relPath))) {
+      throw new Error(
+        `armGuard: headFallback:true is only sound for a dependency-free module ` +
+          `(a data: URL cannot resolve relative imports); '${relPath}' is not on the allowlist ` +
+          `[${[...HEAD_FALLBACK_ALLOWLIST].join(', ')}].`
+      );
+    }
+
+    try {
+      const module = await import(specifier);
+      // The shape check runs on BOTH paths. A working-tree copy that parses but
+      // lost an export is the same defect class as a stale HEAD copy: without
+      // this it would arm "successfully" and then fail open per command.
+      if (Array.isArray(requires)) assertShape(module, 'working-tree copy', requires, relPath);
+      modules[label] = module;
+    } catch (workingTreeError) {
+      let headMod;
+      try {
+        headMod = await importFromSource(readFromHead(repoRoot, relPath));
+        // A HEAD copy that parses but lost part of the API is NOT a usable
+        // fallback — treat it as a total failure rather than half-arming.
+        if (Array.isArray(requires)) assertShape(headMod, 'HEAD copy', requires, relPath);
+      } catch (headError) {
+        workingTreeError.headFallbackError = headError;
+        throw workingTreeError;
+      }
+
+      emitGuardBannerOnce({
+        projectDir,
+        kind: 'head-fallback',
+        message: [
+          '',
+          `⚠️  ${hookName}: DEGRADED — running against HEAD, not your working tree.`,
+          `    ${relPath} failed to load from the working tree:`,
+          `      ${String(workingTreeError?.message || workingTreeError).split('\n')[0]}`,
+          ...(consequence?.degraded ?? []),
+          `    Fix: repair ${relPath} (conflict markers? partial edit?) and re-run.`,
+          '    See: issue #992.',
+          '',
+        ].join('\n'),
+      });
+
+      modules[label] = headMod;
+      degraded.push(label);
+    }
   }
+
+  return { modules, degraded };
 }
 
 /**
@@ -439,12 +646,20 @@ export async function loadCommandBlocker({ specifier, repoRoot, projectDir }) {
  * anyway — every call after the first is equally unprotected, so every call
  * has equal right to say so. Repetition is the point.
  *
- * `projectDir` is retained for signature symmetry with the degraded banner and
- * for future scoping; it deliberately does not gate anything.
+ * `hookName` is MANDATORY and has no default (see {@link armGuard}) — a default
+ * would silently reintroduce the #993 drift, naming one hook in every hook's
+ * banner. `consequence.inactive` is spliced verbatim, so each hook states the
+ * concrete commands its outage stops blocking. `projectDir` is accepted for
+ * signature symmetry with the degraded banner; it deliberately gates nothing.
  *
- * @param {{projectDir?: string, error: unknown}} opts
+ * @param {{hookName: string, projectDir?: string, error: unknown, consequence?: {inactive?: string[]}}} opts
  */
-export function emitGuardInactiveBanner({ error }) {
+export function emitGuardInactiveBanner({ hookName, error, consequence } = {}) {
+  if (typeof hookName !== 'string' || hookName.length === 0) {
+    throw new Error(
+      'emitGuardInactiveBanner: hookName is required and has no default (see armGuard — a default would reintroduce the #993 drift).'
+    );
+  }
   const primary = String(error?.message || error).split('\n')[0];
   const secondary = error?.headFallbackError
     ? String(error.headFallbackError.message || error.headFallbackError).split('\n')[0]
@@ -453,12 +668,10 @@ export function emitGuardInactiveBanner({ error }) {
   writeBanner(
     [
       '',
-      '🚨 pre-bash-destructive-guard: GUARD INACTIVE — this session is NOT protected.',
+      `🚨 ${hookName}: GUARD INACTIVE — this session is NOT protected.`,
       `    Module load failed: ${primary}`,
       ...(secondary ? [`    HEAD fallback also failed: ${secondary}`] : []),
-      '    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.',
+      ...(consequence?.inactive ?? []),
       '    Fix: repair the failing module under scripts/lib/, then re-run.',
       '    See: issue #992, .claude/rules/parallel-sessions.md (PSA-003).',
       '',