session-orchestrator 5.1.0 → 5.3.0

package/hooks/post-tool-batch-wave-signal.mjs

@@ -66,18 +66,21 @@
  * hooks.json wiring is managed separately (W3-C4 scope).
  */
 
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { fileURLToPath } from 'node:url';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
-// Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
-if (!shouldRunHook('post-tool-batch-wave-signal')) process.exit(0);
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 
 import { getProjectDir } from '../scripts/lib/platform.mjs';
 import { emitEvent } from '../scripts/lib/events.mjs';
 import { findScopeFile } from '../scripts/lib/scope-gate.mjs';
 import { atomicMutateJson } from './_lib/atomic-json.mjs';
+import { _parseReaper } from '../scripts/lib/config/reaper.mjs';
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -205,7 +208,7 @@ async function ownsSessionFile(input, sessionFile) {
  * previous hard-coded `.claude/` path made this hook's whole wave-lifecycle
  * fallback structurally dead on Codex CLI, Cursor and pi: the manifest exists,
  * it just is not under `.claude/`, so every batch read 0 and no
- * `orchestrator.wave.started`/`completed` event was ever emitted there.
+ * wave-lifecycle event was ever emitted there.
  *
  * @param {string} projectDir
  * @returns {Promise<number>}
@@ -305,6 +308,145 @@ function countFilesChangedSince(projectDir, sha) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// orphan-reaper trigger (#1432 B4)
+// ---------------------------------------------------------------------------
+//
+// DUPLICATED VERBATIM between the two trigger hooks —
+// hooks/post-tool-batch-wave-signal.mjs <-> hooks/on-stop.mjs. Deliberate, with
+// a named revisit trigger (BV-004): they are the only two trigger points the
+// PRD declares, and a shared `hooks/_lib/reaper-trigger.mjs` would be a third
+// file in the hook import graph. SIZE, measured 2026-09-22 by diffing the two
+// blocks: 138 identical lines — this note said "~40 lines of glue" until then,
+// which is what made the duplicate look cheaper than it is. Extract it the
+// moment a THIRD hook needs the trigger, or the moment the copies must differ.
+
+/**
+ * Filesystem path of the scan CLI, spawned as a PLAIN argv call.
+ *
+ * It used to be a `file://` URL handed to `node --input-type=module -e
+ * <program>`, because `scripts/lib/orphan-reaper.mjs` had no entry guard. It
+ * has one now (`parseReaperCliArgs` + the `isMainModule` tail), so the child's
+ * contract lives in that module instead of as source text duplicated here —
+ * and nothing this hook builds is a program any more: every variable part is
+ * an argv value, which cannot become code whatever the checkout path contains.
+ *
+ * `fileURLToPath`, not `new URL(...).pathname`: the latter leaves a
+ * percent-encoded path for any checkout directory containing a space.
+ */
+const ORPHAN_REAPER_SCRIPT = fileURLToPath(
+  new URL('../scripts/lib/orphan-reaper.mjs', import.meta.url),
+);
+
+/**
+ * Read the `reaper:` block from the project's Session Config host file.
+ * Sync + inline, mirroring `hooks/loop-guard.mjs` `loadConfig()` — a hot hook
+ * path must not import the full config orchestrator. A missing or unreadable
+ * file yields the parser defaults, i.e. DISABLED.
+ *
+ * @param {string} projectDir
+ * @returns {ReturnType<typeof _parseReaper>}
+ */
+function loadReaperConfig(projectDir) {
+  for (const name of ['CLAUDE.md', 'AGENTS.md']) {
+    try {
+      return _parseReaper(readFileSync(path.join(projectDir, name), 'utf8'));
+    } catch {
+      // missing or unreadable — try the next candidate
+    }
+  }
+  return _parseReaper('');
+}
+
+/**
+ * Trigger the orphan scan, throttled and NON-BLOCKING (PRD FA4).
+ *
+ * The hook itself does exactly two pieces of I/O — one config read and one
+ * `stat` of the throttle marker — and then hands the work to a DETACHED,
+ * unref'd child. The scan is never run inline: one `ps` round-trip out of Node
+ * was measured at ~47 ms over 287 KB of output, which alone would blow the
+ * 50 ms `reaper.max-hook-latency-ms` budget this hook has to stay inside.
+ *
+ * The marker is stamped BEFORE the spawn, so a spawn that fails still consumes
+ * the throttle window — otherwise a broken spawn would be retried on every
+ * single tool batch.
+ *
+ * `reaper.max-hook-latency-ms` is the ceiling on the work above — measured here
+ * with `performance.now()` and reported as ONE stderr WARN line when exceeded.
+ * A WARN and not an event: this fires from a `PostToolBatch`-class hook, and a
+ * per-fire telemetry record is exactly the always-on signal
+ * `.claude/rules/host-resources.md` HR-101 calls a broken instrument. The
+ * measurement covers preparation only — the scan itself runs detached, which is
+ * the whole reason the budget can be held.
+ *
+ * Never throws: any failure degrades silently (PRD FA4 "lautlos degradieren").
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.projectDir]  Repo root; defaults to `getProjectDir()`.
+ * @param {number} [opts.now]         Injected clock (ms).
+ * @param {Function} [opts.spawnFn]   Injected `spawn` (tests).
+ * @param {Function} [opts.statFn]    Injected `statSync` (tests).
+ * @param {Function} [opts.writeFn]   Injected marker writer (tests).
+ * @param {() => number} [opts.clockFn]  Injected monotonic clock for the latency
+ *   budget (tests); defaults to `performance.now`.
+ * @returns {Promise<{spawned: boolean, reason: string}>}
+ */
+export async function maybeTriggerOrphanScan({
+  projectDir,
+  now,
+  spawnFn = spawn,
+  statFn,
+  writeFn,
+  clockFn = () => performance.now(),
+} = {}) {
+  const startedAt = clockFn();
+  /** One WARN line when the preparation overran `reaper.max-hook-latency-ms`. */
+  const checkLatency = (budgetMs) => {
+    const elapsed = clockFn() - startedAt;
+    if (Number.isFinite(budgetMs) && budgetMs > 0 && elapsed > budgetMs) {
+      process.stderr.write(
+        `orphan-reaper trigger: hook latency ${elapsed.toFixed(1)} ms exceeded `
+        + `reaper.max-hook-latency-ms (${budgetMs} ms)\n`,
+      );
+    }
+  };
+  try {
+    const root = typeof projectDir === 'string' && projectDir ? projectDir : getProjectDir();
+    const cfg = loadReaperConfig(root);
+    // Cheapest gate first: disabled means no stat, no spawn, no module load.
+    if (cfg.enabled !== true) return { spawned: false, reason: 'disabled' };
+
+    const reaper = await import('../scripts/lib/orphan-reaper.mjs');
+    const markerPath = reaper.scanMarkerPath(root);
+    const nowMs = typeof now === 'number' ? now : Date.now();
+
+    if (!reaper.shouldScanNow(markerPath, nowMs, cfg['min-scan-interval-seconds'], { statFn })) {
+      checkLatency(cfg['max-hook-latency-ms']);
+      return { spawned: false, reason: 'throttled' };
+    }
+    reaper.touchScanMarker(markerPath, { writeFn });
+
+    const child = spawnFn(
+      process.execPath,
+      [
+        ORPHAN_REAPER_SCRIPT,
+        '--repo-root', root,
+        '--mode', cfg.mode,
+        '--min-age-seconds', String(cfg['min-age-seconds']),
+        '--kill-grace-ms', String(cfg['kill-grace-ms']),
+        '--verify-wait-ms', String(cfg['verify-wait-ms']),
+        '--false-alarm-window', String(cfg['false-alarm-window']),
+      ],
+      { detached: true, stdio: 'ignore' },
+    );
+    if (child && typeof child.unref === 'function') child.unref();
+    checkLatency(cfg['max-hook-latency-ms']);
+    return { spawned: true, reason: 'spawned' };
+  } catch {
+    return { spawned: false, reason: 'error' };
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -378,9 +520,13 @@ async function main() {
     }
   } catch { /* best effort — hook must remain non-blocking */ }
 
-  // Emit wave-lifecycle events via the canonical stream when the orchestrator
-  // populates wave_signal ('wave-start' | 'wave-complete'). Mechanical seam —
-  // see docs/events-schema.md. Best-effort; never blocks the hook.
+  // Emit the wave-completion event via the canonical stream when the
+  // orchestrator populates wave_signal 'wave-complete'. Mechanical seam — see
+  // docs/events-schema.md. Best-effort; never blocks the hook. A 'wave-start'
+  // signal is still ACCEPTED — it keeps suppressing the fallback below, as
+  // before — but emits nothing: the `started` sibling event was removed
+  // 2026-09-19, having no reader once the convergence monitor stopped
+  // admitting it.
   //
   // Live path today: the `wave_signal === null` branch below provides the
   // mechanical wave-lifecycle fallback (#612). It fires live by diffing
@@ -388,19 +534,14 @@ async function main() {
   // payload injection required. This explicit-signal branch remains as the
   // preferred path for whenever the harness DOES inject `wave_signal` into the
   // batch payload (it takes precedence over the fallback when present).
-  if (waveSignal === 'wave-start' || waveSignal === 'wave-complete') {
+  if (waveSignal === 'wave-complete') {
     try {
-      await emitEvent(
-        waveSignal === 'wave-start'
-          ? 'orchestrator.wave.started'
-          : 'orchestrator.wave.completed',
-        {
-          ...(waveNumber !== null ? { wave_number: waveNumber } : {}),
-          ...(nextWaveRole !== null ? { next_wave_role: nextWaveRole } : {}),
-          ...(batchId !== null ? { batch_id: batchId } : {}),
-          ...(batchSize !== null ? { batch_size: batchSize } : {}),
-        },
-      );
+      await emitEvent('orchestrator.wave.completed', {
+        ...(waveNumber !== null ? { wave_number: waveNumber } : {}),
+        ...(nextWaveRole !== null ? { next_wave_role: nextWaveRole } : {}),
+        ...(batchId !== null ? { batch_id: batchId } : {}),
+        ...(batchSize !== null ? { batch_size: batchSize } : {}),
+      });
       // #1193 review F2 — this branch is a SECOND emitter of
       // `wave.completed`, so it must feed the same high-water mark the other
       // two read; otherwise SessionEnd (and the fallback below) would close the
@@ -413,8 +554,7 @@ async function main() {
       // and walked the marker BACKWARDS to 4. Both keys go through maxWave().
       // W4c Q1-MED — and neither is written into a PEER's record.
       if (
-        waveSignal === 'wave-complete'
-        && typeof waveNumber === 'number'
+        typeof waveNumber === 'number'
         && waveNumber > 0
         && await ownsSessionFile(input, sessionFile)
       ) {
@@ -498,24 +638,31 @@ async function main() {
               ...(batchSize !== null ? { batch_size: batchSize } : {}),
             });
           }
-          // Open the new wave.
-          await emitEvent('orchestrator.wave.started', {
-            wave_number: wave,
-            ...(nextWaveRole !== null ? { next_wave_role: nextWaveRole } : {}),
-            ...(batchId !== null ? { batch_id: batchId } : {}),
-            ...(batchSize !== null ? { batch_size: batchSize } : {}),
-          });
-          // Persist the high-water marks so the next batch does not re-emit,
-          // and so SessionEnd can tell whether the prior wave was already
-          // closed here (#1193). `last_wave_completed` is only advanced when a
-          // `completed` was actually emitted above (lastWave > 0).
+          // Open the new wave. There is no event for this (the `started`
+          // sibling was removed 2026-09-19); opening IS the high-water marks
+          // persisted below, so the next batch does not re-close the prior
+          // wave, and SessionEnd can tell whether it was already closed here
+          // (#1193). `last_wave_completed` is only advanced when a `completed`
+          // was actually emitted above (lastWave > 0).
           // W4c Q1-MED — never stamp these into a PEER session's record. The
-          // events above are still emitted (they carry THIS session's
+          // event above is still emitted (it carries THIS session's
           // attribution via emitEvent); only the shared-file claim is withheld.
           // NAMED CEILING: for a non-owning session the marks therefore never
-          // advance, so this branch re-emits started{wave} once per batch until
-          // that session's own SessionStart takes over the file. Revisit if the
-          // ledger shows repeated started{N} for one wave in a shared checkout.
+          // advance, so each of its batches re-emits completed{lastWave} while
+          // the file's `last_wave` is ahead of its `last_wave_completed`, until
+          // that session's own SessionStart takes over the file. The revisit
+          // trigger (repeated emissions for one wave) HAS FIRED — measured
+          // 2026-09-19 @ 8f6ac022 over this repo's
+          // `.orchestrator/metrics/events.jsonl{.1,}`, timestamps >= 2026-09-12,
+          // grouped by (session_id, wave_number) with jq:
+          //   started   — 1936 emissions / 48 groups, 19 duplicated, max 274
+          //   completed —  650 emissions / 28 groups,  2 duplicated, max 579
+          // The `started` half is GONE (#1202 §11): its only reader,
+          // `scripts/lib/convergence-monitor.mjs`, no longer admits it — it
+          // carried no measurement and, sharing a tail tick with completed{N},
+          // masked the (N-1, N) shrinking_diff pair. The `completed` half is
+          // OPEN: that event has readers, so the fix is a mark a non-owning
+          // session can keep for itself, not a removal.
           if (await ownsSessionFile(input, sessionFile)) {
             // #980 — the OPEN half: stamp the sha this new wave starts from.
             // Written as null (not omitted) when git is unreadable, so the
@@ -559,7 +706,22 @@ async function main() {
       },
     }));
   }
+
+  // Orphan-reaper trigger (#1432 B4). LAST, after this hook's own contract is
+  // fulfilled — the stdout envelope above must never wait on the watchdog.
+  // Awaited (not fired and forgotten) because the entry guard calls
+  // `process.exit(0)` in a `finally`: an un-awaited spawn would race the exit.
+  // The await is bounded by design — one config read, one stat, one detached
+  // spawn, all measured under `reaper.max-hook-latency-ms` (50 ms).
+  await maybeTriggerOrphanScan();
 }
 
-// Exit 0 always — informational hook must never block Claude.
-main().catch(() => {}).finally(() => process.exit(0));
+// Entry guard (#1393): run only as the node script the harness execs — a bare
+// `import()` must run no handler and must not exit the importing process.
+if (isMainModule(import.meta.url)) {
+  // Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
+  if (!shouldRunHook('post-tool-batch-wave-signal')) process.exit(0);
+
+  // Exit 0 always — informational hook must never block Claude.
+  main().catch(() => {}).finally(() => process.exit(0));
+}

package/hooks/post-tool-failure-corrective-context.mjs

@@ -27,8 +27,7 @@
 import path from 'node:path';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
-// Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
-if (!shouldRunHook('post-tool-failure-corrective-context')) process.exit(0);
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 
 import { getProjectDir } from '../scripts/lib/platform.mjs';
 import { atomicMutateJson } from './_lib/atomic-json.mjs';
@@ -206,7 +205,7 @@ async function main() {
   // Strip control chars (newlines, ANSI escapes) before forwarding to additionalContext —
   // SEC-016 (Log Injection): tool errors may contain attacker-controlled bytes.
   const safeSummary = errorSummary
-    ? errorSummary.replace(/[\r\n]/g, ' ').split('').join(' ').slice(0, 120)
+    ? errorSummary.replace(/[\r\n]/g, ' ').split('\x1b').join(' ').slice(0, 120)
     : '';
   const summaryLabel = safeSummary ? ` Error: ${safeSummary}` : '';
   const additionalContext =
@@ -221,5 +220,12 @@ async function main() {
   }));
 }
 
-// Exit 0 always — informational hook must never block Claude.
-main().catch(() => {}).finally(() => process.exit(0));
+// Entry guard (#1393): run only as the node script the harness execs — a bare
+// `import()` must run no handler and must not exit the importing process.
+if (isMainModule(import.meta.url)) {
+  // Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
+  if (!shouldRunHook('post-tool-failure-corrective-context')) process.exit(0);
+
+  // Exit 0 always — informational hook must never block Claude.
+  main().catch(() => {}).finally(() => process.exit(0));
+}

package/hooks/post-tooluse-frontend-slop.mjs

@@ -24,8 +24,7 @@
  */
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
-// Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
-if (!shouldRunHook('frontend-slop-hook')) process.exit(0);
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 
 import path from 'node:path';
 
@@ -180,5 +179,12 @@ async function main() {
   }));
 }
 
-// Exit 0 always — informational hook must never block Claude (#684).
-main().catch(() => {}).finally(() => process.exit(0));
+// Entry guard (#1393): run only as the node script the harness execs — a bare
+// `import()` must run no handler and must not exit the importing process.
+if (isMainModule(import.meta.url)) {
+  // Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
+  if (!shouldRunHook('frontend-slop-hook')) process.exit(0);
+
+  // Exit 0 always — informational hook must never block Claude (#684).
+  main().catch(() => {}).finally(() => process.exit(0));
+}

package/hooks/pre-auq-clarity.mjs

@@ -659,6 +659,20 @@ export function decide(input, lib) {
   }
   const tail = omitted > 0 ? `\n(+${omitted} weitere Befund(e) nicht gezeigt)` : '';
 
+  // Die Optionsgrenze wird aus der Schwelle GERENDERT, nie danebengeschrieben.
+  // Ausgeschriebene Zahlwörter ("zwei bis vier") standen hier bis 2026-09-18
+  // und waren für jeden Zahlen-grep unsichtbar: verschiebt sich
+  // `THRESHOLDS.K6.optionsMax`, blockt der Hook nach der neuen Zahl und nennt
+  // dem Operator die alte. Fehlt die Schwelle (defektes Schema-Modul), entfällt
+  // der Satz — eine Lücke ist besser als eine erfundene Zahl.
+  const k6Limits = lib?.schema?.THRESHOLDS?.K6;
+  const limitSentence =
+    Number.isInteger(k6Limits?.optionsMin) && Number.isInteger(k6Limits?.optionsMax)
+      ? `Das ist keine Stilfrage: das Tool selbst nimmt nur ${k6Limits.optionsMin} bis ` +
+        `${k6Limits.optionsMax} Optionen je Frage an, und mehr als ${k6Limits.optionsMax} kann ` +
+        'niemand gegeneinander abwägen.\n\n'
+      : '';
+
   // The FIRST LINE names the concrete break, because `emitDeny` derives the
   // operator-visible headline from it. A general preamble first would put a
   // sentence that is identical for every deny in front of the human, and the
@@ -666,8 +680,7 @@ export function decide(input, lib) {
   const reason =
     `AskUserQuestion blockiert: harte Grenze ${groups.map(([id]) => id).join(' + ')} gerissen — ` +
     'so erreicht die Frage den Operator nicht.\n\n' +
-    'Das ist keine Stilfrage: das Tool selbst nimmt nur zwei bis vier Optionen je Frage an, ' +
-    'und mehr als vier kann niemand gegeneinander abwägen.\n\n' +
+    limitSentence +
     `${sections.join('\n\n')}${tail}`;
 
   const suggestion =
@@ -778,6 +791,9 @@ async function main() {
 // under a symlinked plugin install) while `import.meta.url` is realpath-resolved
 // by node's default loader, so BOTH sides are realpath'd.
 // ---------------------------------------------------------------------------
+// BV-004 ceiling: kept inline — hooks avoid importing scripts/lib on the hot
+// path; the canonical predicate is scripts/lib/is-main-module.mjs. Revisit if the
+// hook-import-set (hooks/_lib/hook-import-set.json) ever admits scripts/lib here.
 function invokedAsScript() {
   const entry = process.argv[1];
   if (!entry) return false;

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

@@ -29,6 +29,12 @@
  *          generic pattern path — its `pattern: ">"` would FP-match nearly
  *          every redirect. Unresolved targets (variable/substitution) warn
  *          on stderr (fail-visible) and never block.
+ *        rule.type === 'path-delete' (#1401): decided by the DELETE/RENAME
+ *          operand via firstDeniedDeleteTarget (same target-denylist globs,
+ *          same compiler), likewise shadowing the generic pattern path. The
+ *          redirect class answers "what does this command WRITE"; nothing
+ *          answered "what does it REMOVE", so `rm -f <ledger>` was allowed
+ *          while `> <ledger>` was denied — 53,896 lines of telemetry lost.
  *   G6 no match → exit 0
  *
  * Telemetry (Epic #803 process-safety dimension): best-effort
@@ -46,8 +52,7 @@ 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);
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 
 // ---------------------------------------------------------------------------
 // #992 — late-bound repo dependencies
@@ -179,6 +184,8 @@ async function bootstrap() {
           'redirectSpanEnd',
           'resolveSegmentVerb',
           'splitChainSegments',
+          'extractDeleteTargets',
+          'firstDeniedDeleteTarget',
         ],
       },
     },
@@ -877,6 +884,61 @@ async function main() {
       continue; // unreachable (blockCommand never returns) — kept for clarity
     }
 
+    // #1401 — path-delete rules are decided by the DELETE/RENAME operand via
+    // firstDeniedDeleteTarget, never by the generic pattern path below (same
+    // full-shadow contract as redirect-truncate above: this rule's `pattern` is
+    // a human-readable label, and routing it through commandMatchesBlocked
+    // would match either nothing or every `rm`).
+    //
+    // Why a second surface at all: the redirect rule answers "what does this
+    // command WRITE". Nothing answered "what does it REMOVE" — so `rm -f
+    // .orchestrator/metrics/events.jsonl.1` was ALLOWED while `> ` on the same
+    // file was DENIED (measured 2026-09-19, #1401: 53,896 ledger lines lost).
+    if (rule.type === 'path-delete') {
+      const collected = blocker.extractDeleteTargets(command);
+      const cutOff = collected.filter(
+        (e) => e.unresolved && (e.reason === 'budget-exhausted' || e.reason === 'depth-exceeded')
+      );
+      if (cutOff.length > 0) {
+        // A recursion cap that drops payloads silently is a bypass, not a cap
+        // (#988 T2) — surface it on the VISIBLE channel (#995).
+        //
+        // Deliberately NARROWER than the redirect branch above, which also
+        // surfaces `variable/substitution` operands: `rm -rf "$WORK"` is the
+        // ORDINARY spelling of a temp cleanup, so notifying on it would fire on
+        // a large share of benign commands and train the operator to ignore the
+        // channel (host-resources.md § HR-101 — a signal may only warn if it is
+        // rare). A cut-off marker, by contrast, needs 32+ payload segments or
+        // 3 levels of nesting: pathological by construction. Unresolved
+        // operands stay fail-visible on stderr below; neither class ever blocks.
+        const reasons = [...new Set(cutOff.map((e) => e.reason))].join(', ');
+        const msg = `pre-bash-destructive-guard: delete-target traversal cut off (${reasons}) — not matched (fail-visible)`;
+        process.stderr.write(`⚠ ${msg}\n`);
+        notices.push(msg);
+      }
+      const unresolvedOperands = collected.filter(
+        (e) => e.unresolved && e.reason === 'variable/substitution'
+      );
+      if (unresolvedOperands.length > 0) {
+        process.stderr.write(
+          `ℹ pre-bash-destructive-guard: ${unresolvedOperands.length} delete target(s) carry a variable/substitution — not matched (rule: ${id})\n`
+        );
+      }
+      const hit = blocker.firstDeniedDeleteTarget(rule, collected, { repoRoot: projectDir });
+      if (!hit) continue;
+      if (severity !== 'block') {
+        const msg = `pre-bash-destructive-guard: protected delete target matched (rule: ${id}) — ${rationale}`;
+        process.stderr.write(`⚠ ${msg}\n`);
+        notices.push(msg);
+        continue;
+      }
+      // Reason stays short (stdout-budget): verb + target, never the command.
+      // The policy `rationale` is long by design (it carries the measurement
+      // trail); blockCommand puts only its first line in the systemMessage.
+      await blockCommand(`${hit.verb} ${hit.target}`, 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'
@@ -984,10 +1046,19 @@ try {
   process.exit(0); // fail-open, but no longer fail-silent
 }
 
-// Top-level error handler — never let exit 1 leak
-main().catch((e) => {
-  process.stderr.write(
-    `⚠ pre-bash-destructive-guard: internal error — ${e?.message || e}\n`
-  );
-  process.exit(0); // fail-open on internal errors to avoid blocking legitimate work
-});
+// Entry guard (#1393): run only as the node script the harness execs — a bare
+// `import()` must run no handler and must not exit the importing process.
+// Placed strictly AFTER all decision logic: it gates whether main() is invoked,
+// never what main() decides, so no deny path can be short-circuited by it.
+if (isMainModule(import.meta.url)) {
+  // #211: exit 0 immediately (silent allow) when this hook is disabled via profile/env
+  if (!shouldRunHook('pre-bash-destructive-guard')) process.exit(0);
+
+  // Top-level error handler — never let exit 1 leak
+  main().catch((e) => {
+    process.stderr.write(
+      `⚠ pre-bash-destructive-guard: internal error — ${e?.message || e}\n`
+    );
+    process.exit(0); // fail-open on internal errors to avoid blocking legitimate work
+  });
+}