session-orchestrator 5.2.0 → 5.3.0

package/hooks/post-subagent-discovery-validator.mjs

@@ -22,7 +22,24 @@
  *      `findViolations()` — the whole matcher (claim patterns, negative-context
  *      guards, evidence proximity, normalisation, dedup) lives there so it can
  *      be measured against a claim corpus without spawning this hook. It
- *      returns DEDUPLICATED `{claim, normalized, occurrences}` records.
+ *      returns DEDUPLICATED `{claim, normalized, occurrences, kind, detail?}`
+ *      records in THREE classes: `distributional` (#567/#908 — "4 of 4
+ *      callers"), `gate-verdict` (w4-1 — "STATUS: done" / "alles grün" with
+ *      no run receipt anywhere in the report), and `claim-mismatch` (#1385 R1
+ *      — a claimed test count that NO observed vitest run carries). `kind`
+ *      reaches both the ledger record and the WARN; its ABSENCE on a record
+ *      means `distributional`, since no pre-w4-1 record could be anything
+ *      else.
+ *   5b. The `claim-mismatch` class needs the OTHER side of the transcript, so
+ *      `readTranscriptObservations()` reads the vitest summaries out of the
+ *      `tool_result` blocks in the same window and passes them in. It closes
+ *      an INVERSION: `RUN_RECEIPT_RE` is report-wide and matches
+ *      `\d+\s+passed`, so before R1 an INVENTED number was its own receipt
+ *      while an honest report with no number was flagged (measured
+ *      2026-09-19: `'STATUS: done\nTests pass: 5129 passed / 0 failed.'` → no
+ *      violation; `'STATUS: done\nAlles grün.'` → two). No observations in
+ *      the window ⇒ no `claim-mismatch` finding: evidence ABSENCE is
+ *      `gate-verdict`'s job.
  *   6. Attribute the claim: `agent` + `agent_source` (`payload`|`meta`|`none`)
  *      + `agent_description`, and — on `none` — the sorted stdin `payload_keys`
  *      the harness DID send, so a gap is diagnosable from the ledger.
@@ -62,8 +79,7 @@
  */
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
-// Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
-if (!shouldRunHook('post-subagent-discovery-validator')) process.exit(0);
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 
 import { createHash } from 'node:crypto';
 import { promises as fs } from 'node:fs';
@@ -71,7 +87,11 @@ import { tmpdir } from 'node:os';
 import path from 'node:path';
 
 import { resolveSubagentSidecar } from './_lib/subagent-paths.mjs';
-import { findViolations, readTranscriptTail } from './_lib/subagent-transcript.mjs';
+import {
+  findViolations,
+  readTranscriptObservations,
+  readTranscriptTail,
+} from './_lib/subagent-transcript.mjs';
 import { appendJsonl } from '../scripts/lib/common.mjs';
 import { eventsFilePath } from '../scripts/lib/events.mjs';
 import { getProjectDir } from '../scripts/lib/platform.mjs';
@@ -393,7 +413,11 @@ async function main() {
   if (sidecar === null) return;
 
   const text = await readTranscriptTail(sidecar.transcript);
-  const { violations, undatedVerified } = findViolations(text);
+  // The `tool_result` side of the SAME window (#1385 R1) — what the agent
+  // actually RAN, against which its claimed test counts are compared. An
+  // empty list disables the `claim-mismatch` class; it never creates one.
+  const observations = await readTranscriptObservations(sidecar.transcript);
+  const { violations, undatedVerified } = findViolations(text, { observations });
   if (violations.length === 0) return;
 
   const attribution = await resolveAgentAttribution(input, sidecar.meta);
@@ -443,7 +467,15 @@ async function main() {
       }
       if (seen) continue;
     }
-    await appendJsonl(filePath, {
+    // AWAITED **and** CAUGHT. A telemetry write added to a guard silently
+    // disarms it unless both hold: without the await the process can exit
+    // before the append lands, and without the catch one failed write aborts
+    // the remaining violations AND the stderr WARN below — the coordinator's
+    // only copy of the finding. This hook never denies, so the failure is a
+    // lost finding rather than a lost block; it is still a loss, and a full
+    // disk must not be able to silence the scanner.
+    try {
+      await appendJsonl(filePath, {
       event: 'discovery_validator_violation',
       timestamp: new Date().toISOString(),
       agent,
@@ -457,8 +489,25 @@ async function main() {
       ...(sessionId !== null ? { session_id: sessionId } : {}),
       claim_text: violation.claim,
       occurrences: violation.occurrences,
-    });
-    written++;
+      // Claim CLASS (w4-1, #1385 R1): `distributional` (the #567/#908
+      // patterns), `gate-verdict` (a done/green assertion with no run
+      // receipt), or `claim-mismatch` (a test count no observed run carries).
+      // A new field rather than an overloaded old one — a ledger reader
+      // triaging 3,000 records must be able to separate them without
+      // re-parsing `claim_text`, and every pre-w4-1 record is
+      // `distributional` by construction (the field's absence means that).
+      kind: violation.kind ?? 'distributional',
+      // `claim-mismatch` only: `{mismatch, claimed, observed, observed_n}`.
+      // Numbers, never the command text that produced them (precedent
+      // `8f15f77b` — `command_hash` instead of the raw command); `observed`
+      // is capped at the last 3 runs by findViolations().
+      ...(violation.detail ?? {}),
+      });
+      written++;
+    } catch {
+      // Write failed — keep going. The WARN below still reaches the
+      // coordinator, which is the channel PSA-006 actually depends on.
+    }
   }
 
   // Advisory only (#908 item 4) — never promoted to a violation in v1.
@@ -473,10 +522,39 @@ async function main() {
     ? ` ${violations.length - written} already recorded earlier in this session.`
     : '';
 
+  // THREE claim CLASSES, counted separately in the WARN (w4-1, #1385 R1):
+  // they fail different rules and want different corrections — a
+  // distributional claim needs its grep transcript, a gate verdict needs a
+  // run receipt, and a count mismatch needs the run repeated or the number
+  // corrected. One aggregate count would leave the coordinator guessing which.
+  const gateCount = violations.filter((v) => v.kind === 'gate-verdict').length;
+  const mismatchCount = violations.filter((v) => v.kind === 'claim-mismatch').length;
+  const distCount = violations.length - gateCount - mismatchCount;
+  const classNote = gateCount === 0
+    ? ''
+    : ` ${gateCount} of them ${gateCount === 1 ? 'is a' : 'are'} DONE/GATE verdict(s) with no run ` +
+      `receipt (no test count, no exit code) anywhere in the report; ` +
+      `${distCount} repo-state/distributional.`;
+
+  // The correction this class asks for is named, because it is NOT the one
+  // the other two ask for: no amount of added grep evidence fixes a number
+  // that contradicts every run in the window.
+  const mismatchNote = mismatchCount === 0
+    ? ''
+    : ` ${mismatchCount} ${mismatchCount === 1 ? 'is a' : 'are'} COUNT MISMATCH: ` +
+      violations
+        .filter((v) => v.kind === 'claim-mismatch')
+        .map((v) => {
+          const observed = (v.detail?.observed ?? []).map((o) => `${o.passed} passed`).join(', ');
+          return `claimed ${v.detail?.claimed?.passed} passed, observed ${observed || 'none'}`;
+        })
+        .join('; ') +
+      ` — re-run the suite or correct the number.`;
+
   const warnText =
-    `⚠ PSA-006: ${violations.length} distinct repo-state/distributional claim(s) from agent ` +
-    `"${agent}" (source: ${attribution.source}) lack an adjacent measurement transcript ` +
-    `(grep/rg/find/git/wc/jq/ls/node/npm) (non-blocking).` +
+    `⚠ PSA-006: ${violations.length} distinct claim(s) from agent ` +
+    `"${agent}" (source: ${attribution.source}) lack measurement evidence ` +
+    `(grep/rg/find/git/wc/jq/ls/node/npm) (non-blocking).${classNote}${mismatchNote}` +
     `${suppressedNote}${undatedNote} ` +
     `See .claude/rules/parallel-sessions.md § PSA-006.`;
   process.stderr.write(warnText + '\n');
@@ -526,5 +604,12 @@ async function main() {
   }));
 }
 
-// Exit 0 always — informational hook must never block Claude (#567 v1).
-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-subagent-discovery-validator')) process.exit(0);
+
+  // Exit 0 always — informational hook must never block Claude (#567 v1).
+  main().catch(() => {}).finally(() => process.exit(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 =