session-orchestrator 3.19.0 → 3.20.0

package/hooks/pre-bash-sessions-ledger-guard.mjs

@@ -123,7 +123,12 @@
  * "If file exists and the -a flag is not specified, the file will be
  * overwritten"), while the verb is whatever `time` goes on to run. The target
  * is therefore invisible in both `verb` and `args`, which is why
- * `/usr/bin/time -o <ledger> npm test` was allowed and now denies. The bash
+ * `/usr/bin/time -o <ledger> npm test` was allowed and now denies.
+ * `resolveSegmentVerb` itself supplies the file-vs-option semantics: each
+ * write-destination operand is flagged `writesFile: true` from its per-wrapper
+ * `fileArgFlags` table (#996.1), so this guard keys on that flag directly and no
+ * longer keeps a local `<wrapper>:<flag>` pair list that had to track the lexer's
+ * grammar by hand. The bash
  * KEYWORD `time` is unaffected: it rejects the flag outright
  * (`bash -c 'time -o x echo hi'` → "-o: command not found"), so only
  * `/usr/bin/time`, `command time` and `env time` can carry it at all.
@@ -181,6 +186,15 @@
  * through. Under the #906 exit-0 protocol, "fail-open" is literally exit 0 with
  * no stdout envelope — the harness reads no decision and proceeds.
  *
+ * A LOAD failure is a distinct class since #993: the repo dependencies (`io.mjs`,
+ * `command-blocker.mjs`) are bound LATE (dynamic `import()` in `bootstrap()`), so
+ * a link-time SyntaxError in either becomes a catchable runtime error that
+ * banners GUARD INACTIVE on stderr instead of the pre-#993 exit-1 / 0-byte crash
+ * that disarmed the guard invisibly under the exit-0 protocol. The
+ * `command-blocker` half additionally recovers its COMMITTED source via
+ * `git show HEAD:` (banner: DEGRADED, guard still armed against HEAD) — the whole
+ * mechanism lives in `_lib/guard-source-loader.mjs` (`armGuard`).
+ *
  * ## Override
  *
  *   SO_DISABLED_HOOKS=pre-bash-sessions-ledger-guard   (session-level)
@@ -191,24 +205,141 @@
  * failure this hook exists to replace.
  */
 
-import { readStdin, emitAllow, emitDeny } from '../scripts/lib/io.mjs';
-// Single direct import from the source module (#991), matching the precedent in
-// hooks/pre-bash-destructive-guard.mjs: the hardening.mjs barrel re-exports
-// tokenizeCommand from this very module (same instance either way) but
-// deliberately does NOT re-export the #982/#983 primitives, so importing the
-// lexer from the barrel and the wrapper resolver from the source would give
-// this hook two dependency edges to one module. The barrel is unchanged.
-import {
-  tokenizeCommand,
-  resolveSegmentVerb,
-  splitChainSegments,
-} from '../scripts/lib/command-blocker.mjs';
+import { spawnSync } from 'node:child_process';
 import path from 'node:path';
+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-sessions-ledger-guard')) process.exit(0);
 
+// ---------------------------------------------------------------------------
+// #993 — late-bound repo dependencies
+//
+// `io.mjs` (readStdin/emitAllow/emitDeny) and `command-blocker.mjs`
+// (tokenizeCommand/resolveSegmentVerb/splitChainSegments) used to be STATIC
+// imports. A SyntaxError in either failed at ESM LINK time, before the first
+// statement here ran: node exited 1 with 0 bytes on stdout, and the
+// `main().catch(...)` handler at the bottom of this file was structurally
+// unreachable. Under the exit-0 PreToolUse protocol (#906) that crash is, on the
+// only decision-bearing channel, INDISTINGUISHABLE from an explicit
+// `emitAllow()` — the guard failed open and silently.
+//
+// This hook is fail-open BY DESIGN (a nudge, not a boundary — see the module
+// docblock), so a silent disarm is a smaller loss here than in the
+// destructive-guard. It is still a loss: the #958 corruption class stops being
+// caught with no sign it stopped. Binding these late (dynamic `import()` inside
+// `bootstrap()`) turns the link-time crash into a catchable runtime error, which
+// is what makes the GUARD INACTIVE banner in `_lib/guard-source-loader.mjs`
+// reachable at all.
+//
+// `command-blocker.mjs` is held as a NAMESPACE object (`blocker.*`) rather than
+// three destructured bindings on purpose: the required-export list then exists in
+// exactly one place — the `requires` array on the `blocker` spec passed to
+// `armGuard` — which validates BOTH the working-tree copy and the HEAD copy
+// against it, so a partial namespace banners GUARD INACTIVE instead of arming a
+// guard that fails open per command.
+//
+// `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;
+/**
+ * The whole `command-blocker.mjs` namespace (#991: one direct import path, not
+ * via the hardening.mjs barrel, which deliberately does NOT re-export the
+ * #982/#983 primitives). Held as ONE object rather than destructured so the
+ * required-export set lives only on the `blocker` spec's `requires` array (#993).
+ *
+ * @type {Record<string, Function>|null}
+ */
+let blocker = null;
+
+/**
+ * Module labels `armGuard` recovered from HEAD because the working-tree copy
+ * failed (parse error OR shape check). Non-empty ⇒ this hook is analysing
+ * commands with the COMMITTED lexer. Surfaced on the visible stdout channel by
+ * {@link flushNotices} (#1001) — the stderr DEGRADED banner alone is discarded
+ * under the exit-0 protocol, which made a degraded ALLOW indistinguishable from
+ * a healthy one.
+ *
+ * @type {string[]}
+ */
+let degradedLabels = [];
+
+const PLUGIN_ROOT = path.resolve(import.meta.dirname, '..');
+
+/** This hook's name — threaded into the guard banners (#993: no hard-wired literal). */
+const HOOK_NAME = 'pre-bash-sessions-ledger-guard';
+
+/**
+ * Consequence prose spliced VERBATIM into the DEGRADED and GUARD INACTIVE banners
+ * (#993). This hook is fail-open by design, so the `inactive` text says so plainly
+ * rather than borrowing the destructive-guard's "do not route around it" framing.
+ */
+const GUARD_CONSEQUENCE = {
+  degraded: [
+    '    Consequence: ledger-write 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: a direct shell write into .orchestrator/metrics/sessions.jsonl',
+    '    (>, >>, tee, dd of=, cp/mv destination) is NOT being blocked. This hook is a',
+    '    fail-open nudge, not a security boundary — but repair it so the #958 corruption',
+    '    class stays caught.',
+  ],
+};
+
+/**
+ * Project dir for banner keying, resolved WITHOUT any repo module — those are 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.
+ *
+ * `io` gets NO HEAD fallback (a missing export surfaces as a plain TypeError at
+ * its single call site — no half-armed guard to protect against). `blocker` opts
+ * into the `git show HEAD:` recovery (it is dependency-free — its only import is
+ * `node:path`) and carries the COMPLETE required-export set, so a partial
+ * namespace banners GUARD INACTIVE rather than arming a guard that fails open per
+ * command.
+ *
+ * @returns {Promise<void>}
+ */
+async function bootstrap() {
+  const lib = (...seg) => pathToFileURL(path.join(PLUGIN_ROOT, 'scripts', 'lib', ...seg)).href;
+
+  const { armGuard } = await import('./_lib/guard-source-loader.mjs');
+  const { modules, degraded } = await armGuard(
+    {
+      io: { specifier: lib('io.mjs') },
+      blocker: {
+        specifier: lib('command-blocker.mjs'),
+        headFallback: true,
+        requires: ['tokenizeCommand', 'resolveSegmentVerb', 'splitChainSegments'],
+      },
+    },
+    {
+      hookName: HOOK_NAME,
+      repoRoot: PLUGIN_ROOT,
+      projectDir: bannerProjectDir(),
+      consequence: GUARD_CONSEQUENCE,
+    }
+  );
+
+  ({ readStdin, emitAllow, emitDeny, emitWarn } = modules.io);
+  blocker = modules.blocker;
+  degradedLabels = degraded;
+}
+
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -216,6 +347,10 @@ if (!shouldRunHook('pre-bash-sessions-ledger-guard')) process.exit(0);
 /** The ledger's filename. A write target matches on basename equality. */
 const LEDGER_BASENAME = 'sessions.jsonl';
 
+/** The repair CLI whose effective apply mode mutates the sessions ledger internally. */
+const REPAIR_SCRIPT_BASENAME = 'repair-invalid-sessions.mjs';
+const REPAIR_APPLY_MARKER = `${REPAIR_SCRIPT_BASENAME} --apply`;
+
 /**
  * How much of the offending target may appear in the deny reason.
  *
@@ -230,19 +365,6 @@ const TARGET_ECHO_MAX = 200;
 /** Verbs whose LAST non-flag argument is a write destination. */
 const DEST_LAST_VERBS = new Set(['cp', 'mv']);
 
-/**
- * Wrapper flags from {@link resolveSegmentVerb}'s `wrapperArgs` whose operand is
- * a FILE the wrapper itself writes, keyed `<wrapper>:<flag>`.
- *
- * Deliberately an explicit pair list rather than "any argFlag operand": most
- * value-taking wrapper flags name something that is NOT a path — `sudo -u` a
- * user, `nice -n` a niceness, `timeout -k` a duration, `env -u` a variable, and
- * `stdbuf -o` a BUFFERING MODE (`0`, `L`, `4096`), which shares its spelling
- * with `time -o` and would be the obvious false positive of a blanket rule.
- * Only `time -o`/`--output` opens a file for writing.
- */
-const WRAPPER_FILE_FLAGS = new Set(['time:-o', 'time:--output']);
-
 /**
  * How deep to follow a wrapper's command-string payload (`env -S '…'`).
  *
@@ -282,6 +404,147 @@ function refersToLedger(target) {
   return path.posix.basename(normalized) === LEDGER_BASENAME;
 }
 
+/**
+ * Does this token name the repair CLI by its immediate script operand basename?
+ *
+ * @param {string} target
+ * @returns {boolean}
+ */
+function refersToRepairScript(target) {
+  if (typeof target !== 'string' || target.length === 0) return false;
+  const normalized = target.replace(/\\/g, '/');
+  return path.posix.basename(normalized) === REPAIR_SCRIPT_BASENAME;
+}
+
+/**
+ * Node's own `--help` output is the source of truth for the runtime-option
+ * grammar. A hand-maintained option set is necessarily stale as Node adds
+ * runtime flags (for example, Node 24's `--experimental-worker-inspection`).
+ *
+ * The parser only records option names and whether the help specification says
+ * the option takes a value. Optional inline values such as `--inspect[=...]`
+ * deliberately do not consume the next token: Node treats a separated token as
+ * the script in that form. Aliases inherit the value-taking shape of the whole
+ * help row (`--loader, --experimental-loader=...`).
+ *
+ * @returns {{ available: true, grammar: Map<string, { takesNextValue: boolean }> } |
+ *   { available: false, reason: string }}
+ */
+function loadNodeOptionGrammar() {
+  const result = spawnSync(process.execPath, ['--help'], {
+    encoding: 'utf8',
+    maxBuffer: 2 * 1024 * 1024,
+  });
+  if (result.error || result.status !== 0 || typeof result.stdout !== 'string') {
+    return { available: false, reason: 'spawn-failed' };
+  }
+  if (!/^Usage: node \[options\]/m.test(result.stdout)) {
+    return { available: false, reason: 'malformed-help' };
+  }
+
+  const grammar = new Map();
+  for (const line of result.stdout.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('-')) continue;
+
+    const specification = trimmed.split(/\s{2,}/, 1)[0];
+    const aliases = specification.split(',').map((alias) => alias.trim());
+    const names = aliases
+      .map((alias) => /^(-{1,2}[A-Za-z0-9][A-Za-z0-9-]*)/.exec(alias)?.[1])
+      .filter((name) => typeof name === 'string');
+    if (names.length === 0) continue;
+
+    const takesNextValue = aliases.some((alias) => {
+      const equals = alias.indexOf('=');
+      const optionalValue = alias.indexOf('[');
+      return equals >= 0 && (optionalValue < 0 || equals < optionalValue);
+    });
+    for (const name of names) grammar.set(name, { takesNextValue });
+  }
+
+  // These stable Node help entries make a truncated or otherwise incomplete
+  // output unavailable rather than an empty grammar that silently allows.
+  if (!grammar.has('--version') || !grammar.has('--eval')) {
+    return { available: false, reason: 'malformed-help' };
+  }
+  return { available: true, grammar };
+}
+
+/** Parsed lazily so ordinary non-Node Bash commands do not spawn a child process. */
+let nodeOptionGrammar;
+
+/**
+ * Return Node's runtime-option grammar, loading it only when a Node command
+ * actually presents an option token for resolution.
+ *
+ * @returns {{ available: true, grammar: Map<string, { takesNextValue: boolean }> } |
+ *   { available: false, reason: string }}
+ */
+function getNodeOptionGrammar() {
+  if (!nodeOptionGrammar) nodeOptionGrammar = loadNodeOptionGrammar();
+  return nodeOptionGrammar;
+}
+
+/** Node modes in which a later token is not an executing script operand. */
+const NODE_EVAL_OPTIONS = new Set(['-e', '--eval', '-p', '--print']);
+const NODE_CHECK_OPTIONS = new Set(['-c', '--check']);
+
+/**
+ * Return the option name without an inline `=value` suffix.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function nodeOptionName(text) {
+  const equals = text.indexOf('=');
+  return equals > 0 ? text.slice(0, equals) : text;
+}
+
+/**
+ * Resolve Node's actual script operand from tokens immediately following `node`.
+ *
+ * Values consumed by the runtime's own help-derived options are never candidates
+ * for the script. Eval/print/check modes have no executing script operand for
+ * this guard's contract, so their following tokens cannot activate the repair
+ * mutation rule. Unknown options stop resolution rather than causing a later
+ * argument to be searched.
+ *
+ * @param {Array<{ text: string, quoted: boolean }>} args
+ * @returns {{ scriptIndex: number }|{ unavailable: true, reason: string }|null}
+ */
+function resolveNodeScriptOperand(args) {
+  for (let i = 0; i < args.length;) {
+    const text = args[i].text;
+    const name = nodeOptionName(text);
+
+    if (text === '--') return i + 1 < args.length ? { scriptIndex: i + 1 } : null;
+
+    if (NODE_EVAL_OPTIONS.has(name)) return null;
+    if ((text.startsWith('-e') || text.startsWith('-p')) && !text.startsWith('--') && text.length > 2) {
+      return null;
+    }
+    if (NODE_CHECK_OPTIONS.has(name)) return null;
+
+    if (!text.startsWith('-')) return { scriptIndex: i };
+
+    const grammarState = getNodeOptionGrammar();
+    if (!grammarState.available) return { unavailable: true, reason: grammarState.reason };
+
+    const option = grammarState.grammar.get(name);
+    if (option?.takesNextValue) {
+      i += text.includes('=') ? 1 : 2;
+      continue;
+    }
+    if (option) {
+      i++;
+      continue;
+    }
+
+    return null;
+  }
+  return null;
+}
+
 /**
  * Skip a quoted run that OPENS at `open`.
  *
@@ -491,56 +754,134 @@ function scanCommand(command) {
  * OPTIONS are consumed with it and `sudo -u root tee -a <ledger>` reaches the
  * real verb instead of stopping at `-u`.
  *
+ * DUAL PARSE (#1000). `resolveSegmentVerb` returns an optional `alt` reading —
+ * the value-taking interpretation of an unknown dash-flag — whenever the two
+ * readings disagree about the verb. Both are judged here and the FIRST hit wins,
+ * which is the safe direction: guessing wrong in the boolean direction hid the
+ * write verb behind an unrecognised flag, and two commands were MEASURED to slip
+ * through that way (`nice --unknown 5 tee -a <ledger>` read the verb as `5`;
+ * `env -Q x tee -a <ledger>` read it as `x`). Judging both cannot lose a deny
+ * parse A already found — parse A is still evaluated first and unchanged.
+ *
  * @param {string} command - sanitized command
  * @param {number} [depth] - payload recursion level (see MAX_PAYLOAD_DEPTH)
+ * @param {string[]} [marks] - OUT-param accumulator for fail-visible markers
+ *   (#998): analysis this pass could not complete, e.g. a payload dropped at the
+ *   MAX_PAYLOAD_DEPTH cut. Threaded through the recursion so a mark raised in a
+ *   nested payload reaches `main()`. Never affects the return value — the
+ *   `string|null` contract is unchanged; marks add VISIBILITY, never a deny.
  * @returns {string|null} the offending target, or null
  */
-function findWriteVerbTarget(command, depth = 0) {
-  for (const segment of splitChainSegments(tokenizeCommand(command))) {
-    const { verb, index, payloads, wrapperArgs } = resolveSegmentVerb(segment);
-
-    // A wrapper can write a file WITHOUT being the verb: `/usr/bin/time -o F`
-    // truncates F while the verb is whatever time runs. Checked before the verb
-    // dispatch because `time -o <ledger>` alone resolves to verb null.
-    for (const wa of wrapperArgs) {
-      if (!WRAPPER_FILE_FLAGS.has(`${wa.wrapper}:${wa.flag}`)) continue;
-      if (typeof wa.value === 'string' && refersToLedger(wa.value)) return wa.value;
+function findWriteVerbTarget(command, depth = 0, marks = []) {
+  for (const segment of blocker.splitChainSegments(blocker.tokenizeCommand(command))) {
+    const resolved = blocker.resolveSegmentVerb(segment);
+    const readings = [resolved, resolved.alt].filter(Boolean);
+    // Payloads are deduped ACROSS readings: both readings usually report the same
+    // `env -S '…'` operand, and recursing twice on one string only doubles work.
+    const payloadSet = new Set();
+
+    for (const { payloads, wrapperArgs } of readings) {
+      for (const p of payloads) payloadSet.add(p);
+
+      // A wrapper can write a file WITHOUT being the verb: `/usr/bin/time -o F`
+      // truncates F while the verb is whatever time runs. Checked before the verb
+      // dispatch because `time -o <ledger>` alone resolves to verb null. The
+      // file-vs-option distinction is the LEXER's now (#996.1): resolveSegmentVerb
+      // marks a write-destination operand `writesFile: true` from its per-wrapper
+      // `fileArgFlags` table (command-blocker.mjs — the writesFile contract, the
+      // `resolveSegmentVerb` return docblock), so a local `<wrapper>:<flag>` pair
+      // list here is gone. The rationale it encoded — `stdbuf -o` is a BUFFERING
+      // MODE, not a file, and `time -o` is the only wrapper flag that opens one —
+      // lives beside that table (command-blocker.mjs, the WRAPPER_UNWRAP docblock).
+      for (const wa of wrapperArgs) {
+        if (wa.writesFile !== true) continue;
+        if (typeof wa.value === 'string' && refersToLedger(wa.value)) return wa.value;
+      }
     }
 
     // `env -S 'tee -a <ledger>'` hides a whole command line in one operand.
     // Recurse on the payload with the SAME matcher rather than a second,
-    // weaker one — bounded by MAX_PAYLOAD_DEPTH.
-    if (depth < MAX_PAYLOAD_DEPTH) {
-      for (const payload of payloads) {
-        const hit = findLedgerWrite(payload, depth + 1);
-        if (hit) return hit;
+    // weaker one — bounded by MAX_PAYLOAD_DEPTH. Kept BEFORE the verb dispatch
+    // (pre-#1000 order), so which target a mixed command reports is unchanged.
+    if (payloadSet.size > 0) {
+      if (depth < MAX_PAYLOAD_DEPTH) {
+        for (const payload of payloadSet) {
+          const hit = findLedgerWrite(payload, depth + 1, marks);
+          if (hit) return hit;
+        }
+      } else if ([...payloadSet].some((p) => typeof p === 'string' && p.includes(LEDGER_BASENAME))) {
+        // The cut USED to be silent (#998 item 2): a payload nested past the cap
+        // was dropped with no trace, so an operator could not tell "analysed and
+        // clean" from "never looked at". Marked — but ONLY when the dropped
+        // payload actually mentions the ledger. An unfiltered mark would turn
+        // every ordinary deep-but-benign command into a warn envelope, which is
+        // noise this accident-guard must not generate. Still no deny: raising the
+        // cap into a deny is a policy change, not a visibility fix.
+        marks.push('depth-exceeded');
       }
     }
 
-    if (!verb) continue;
-    const args = segment.slice(index + 1);
+    for (const { verb, index } of readings) {
+      if (!verb) continue;
+      // `index` is the verb position OF THIS READING — never mix it with the
+      // other's (the lib docblock's positional-walk caveat).
+      const args = segment.slice(index + 1);
 
-    if (verb === 'tee') {
-      for (const arg of args) {
-        if (!arg.quoted && arg.text.startsWith('-')) continue;
-        if (refersToLedger(arg.text)) return arg.text;
+      // The repair CLI mutates the ledger from inside Node, so there is no
+      // redirect target for the structural matcher to see. Match only its
+      // effective apply contract at the resolved token seam: `node`, the
+      // actual script operand after Node runtime options, a later exact
+      // `--apply`, and no later exact `--dry-run`. The CLI remains the owner of
+      // target semantics.
+      if (verb === 'node') {
+        const script = resolveNodeScriptOperand(args);
+        const hasRepairMention = args.some((arg) => refersToRepairScript(arg.text));
+        const hasApply = args.some((arg) => arg.text === '--apply');
+        const hasDryRun = args.some((arg) => arg.text === '--dry-run');
+
+        if (script?.unavailable) {
+          // The runtime-derived grammar is an enforcement dependency. If it is
+          // unavailable, an ambiguous repair invocation must be visible and
+          // denied rather than falling through to the hook's normal allow path.
+          if (hasRepairMention && hasApply && !hasDryRun) {
+            return `${REPAIR_APPLY_MARKER} (Node option grammar unavailable: ${script.reason}; denied fail-closed)`;
+          }
+        } else {
+          const scriptToken = script && args[script.scriptIndex];
+          const laterArgs = script ? args.slice(script.scriptIndex + 1) : [];
+          if (
+            scriptToken &&
+            refersToRepairScript(scriptToken.text) &&
+            laterArgs.some((arg) => arg.text === '--apply') &&
+            !laterArgs.some((arg) => arg.text === '--dry-run')
+          ) {
+            return REPAIR_APPLY_MARKER;
+          }
+        }
       }
-      continue;
-    }
 
-    if (verb === 'dd') {
-      for (const arg of args) {
-        const m = /^of=(.*)$/.exec(arg.text);
-        if (m && refersToLedger(m[1])) return m[1];
+      if (verb === 'tee') {
+        for (const arg of args) {
+          if (!arg.quoted && arg.text.startsWith('-')) continue;
+          if (refersToLedger(arg.text)) return arg.text;
+        }
+        continue;
+      }
+
+      if (verb === 'dd') {
+        for (const arg of args) {
+          const m = /^of=(.*)$/.exec(arg.text);
+          if (m && refersToLedger(m[1])) return m[1];
+        }
+        continue;
       }
-      continue;
-    }
 
-    if (DEST_LAST_VERBS.has(verb)) {
-      const operands = args.filter((a) => a.quoted || !a.text.startsWith('-'));
-      // `cp a b` writes b; `cp ledger backup` READS the ledger and must pass.
-      const dest = operands.length >= 2 ? operands[operands.length - 1] : null;
-      if (dest && refersToLedger(dest.text)) return dest.text;
+      if (DEST_LAST_VERBS.has(verb)) {
+        const operands = args.filter((a) => a.quoted || !a.text.startsWith('-'));
+        // `cp a b` writes b; `cp ledger backup` READS the ledger and must pass.
+        const dest = operands.length >= 2 ? operands[operands.length - 1] : null;
+        if (dest && refersToLedger(dest.text)) return dest.text;
+      }
     }
   }
   return null;
@@ -556,12 +897,16 @@ function findWriteVerbTarget(command, depth = 0) {
  *
  * @param {string} command
  * @param {number} [depth] - payload recursion level (see MAX_PAYLOAD_DEPTH)
+ * @param {string[]} [marks] - OUT-param accumulator for fail-visible markers
+ *   (#998); see {@link findWriteVerbTarget}. Purely additive — the `string|null`
+ *   return contract is unchanged and a mark never becomes a deny.
  * @returns {string|null}
  */
-function findLedgerWrite(command, depth = 0) {
+function findLedgerWrite(command, depth = 0, marks = []) {
   if (typeof command !== 'string' || command.length === 0) return null;
-  // Cheap pre-filter: no mention of the filename at all → nothing to analyse.
-  if (!command.includes(LEDGER_BASENAME)) return null;
+  // Cheap pre-filter: commands naming neither the ledger nor the internal repair
+  // CLI cannot reach either deny path.
+  if (!command.includes(LEDGER_BASENAME) && !command.includes(REPAIR_SCRIPT_BASENAME)) return null;
 
   const scan = scanCommand(command);
   for (const target of scan.targets) {
@@ -574,7 +919,28 @@ function findLedgerWrite(command, depth = 0) {
   if (!scan.balanced) {
     return `${LEDGER_BASENAME} (unbalanced quote — command not parseable, denied fail-closed)`;
   }
-  return findWriteVerbTarget(scan.sanitized, depth);
+  return findWriteVerbTarget(scan.sanitized, depth, marks);
+}
+
+/**
+ * Flush the aggregated allow-with-notice channel (#1001).
+ *
+ * Notices accumulate during matching 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: `emitWarn` is `@returns never`
+ * (scripts/lib/io.mjs), so an inline call before `findLedgerWrite` would exit
+ * BEFORE the matcher ran — turning every would-be DENY into an ALLOW-with-notice.
+ * The deny path never reaches here and drops the notices by design: DENY wins,
+ * and the stderr copies remain for CI/debug.
+ *
+ * @param {string[]} notices
+ * @returns {never}
+ */
+function flushNotices(notices) {
+  return notices.length > 0 ? emitWarn(notices.join('\n')) : emitAllow();
 }
 
 // ---------------------------------------------------------------------------
@@ -592,9 +958,39 @@ async function main() {
   const command = input?.tool_input?.command;
   if (typeof command !== 'string' || command.length === 0) return emitAllow();
 
+  // #1001 — aggregated allow-with-notice channel, opened only AFTER G1/G2 (a
+  // non-Bash call or an empty command is not this hook's business and stays a
+  // bare allow). Flushed ONCE on the allow path; see flushNotices for why an
+  // inline emitWarn here would disarm the G4 deny below.
+  const notices = [];
+  // A guard armed from HEAD is a visible-channel concern: the DEGRADED banner
+  // rides stderr only, which exit 0 discards. armGuard already fired it once per
+  // session; 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 — matcher. No direct ledger write → allow.
-  const target = findLedgerWrite(command);
-  if (!target) return emitAllow();
+  const marks = [];
+  const target = findLedgerWrite(command, 0, marks);
+  if (!target) {
+    // Fail-VISIBLE (#998 item 2): the matcher completed without a hit, but part
+    // of the command was never analysed. Say so rather than reporting a clean
+    // allow. Still an ALLOW — this hook is an accident-guard, fail-open by
+    // design, and a depth cut is not evidence of a write.
+    if (marks.length > 0) {
+      const msg =
+        `${HOOK_NAME}: unresolved payload (${[...new Set(marks)].join(', ')}) — ` +
+        `not analysed (fail-visible)`;
+      process.stderr.write(`⚠ ${msg}\n`);
+      notices.push(msg);
+    }
+    return flushNotices(notices);
+  }
 
   // G4 — deny. emitDeny writes the envelope with fs.writeSync (#906/#914): a
   // console.log here would be dropped above the 64 KiB pipe buffer, and a
@@ -617,6 +1013,37 @@ async function main() {
   );
 }
 
+// ---------------------------------------------------------------------------
+// Entry point (#993)
+//
+// TWO distinct failure classes, two distinct handlers — do not merge them:
+//   1. LOAD failure (`bootstrap()` throws): the guard never armed, nothing was
+//      evaluated. 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
+//      via the GUARD INACTIVE banner, once loud on stderr.
+//   2. RUNTIME failure inside `main()`: pre-existing fail-open behaviour,
+//      unchanged (this hook is fail-open by design — see the module docblock).
+// ---------------------------------------------------------------------------
+try {
+  await bootstrap();
+} catch (loadError) {
+  try {
+    const { emitGuardInactiveBanner } = await import('./_lib/guard-source-loader.mjs');
+    // hookName is threaded explicitly (#993 — no hard-wired literal in the loader).
+    emitGuardInactiveBanner({ hookName: HOOK_NAME, error: loadError, consequence: GUARD_CONSEQUENCE });
+  } catch {
+    // Last resort: even the banner helper failed to load. Emit unconditionally —
+    // repeated noise beats a silent disarm.
+    process.stderr.write(
+      '🚨 pre-bash-sessions-ledger-guard: GUARD INACTIVE — module load failed ' +
+        `(${String(loadError?.message || loadError).split('\n')[0]}). ` +
+        'Direct shell writes to the sessions ledger are NOT being blocked. See issue #992.\n'
+    );
+  }
+  process.exit(0); // fail-open, but no longer fail-silent
+}
+
 // Top-level error handler — fail-OPEN (see the module docblock). Never let a
 // non-zero exit leak: on this protocol exit 0 + empty stdout is "no decision".
 main().catch((e) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "3.19.0",
+  "version": "3.20.0",
   "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
   "type": "module",
   "homepage": "https://session-orchestrator.com",
@@ -62,7 +62,7 @@
   "dependencies": {
     "@babel/parser": "^7.26.0",
     "ajv": "^8.17.1",
-    "js-yaml": "^4.2.0",
+    "js-yaml": "^4.3.1",
     "mdast-util-to-string": "^4.0.0",
     "remark": "^15.0.0",
     "remark-parse": "^11.0.0",