session-orchestrator 5.1.0 → 5.3.0

package/hooks/on-stop.mjs

@@ -30,28 +30,28 @@
  */
 
 import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { performance } from 'node:perf_hooks';
 import {
   promises as fs,
-  closeSync,
   existsSync,
-  fstatSync,
-  openSync,
   readFileSync,
-  readSync,
   statSync,
   writeFileSync,
 } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
+import { readTailWindow } from '../scripts/lib/tail-window.mjs';
 import { AGENT_ID_RE, resolveSubagentSidecar } from './_lib/subagent-paths.mjs';
-// #211: exit 0 immediately (silent allow) when this hook is disabled via profile/env
-if (!shouldRunHook('on-stop')) process.exit(0);
 
 import { emitEvent } from '../scripts/lib/events.mjs';
 import { detectPlatform, getProjectDir } from '../scripts/lib/platform.mjs';
 import { parseSessionId } from '../scripts/lib/session-id.mjs';
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 import { heartbeat, logSweepEvent } from '../scripts/lib/session-registry.mjs';
 import { readLock, updateHeartbeat } from '../scripts/lib/session-lock.mjs';
+import { _parseReaper } from '../scripts/lib/config/reaper.mjs';
 
 // ---------------------------------------------------------------------------
 // stdin reading (inline — no io.mjs because Stop hooks exit 0 always, never deny)
@@ -551,6 +551,39 @@ async function handleSubagentStop(input) {
     } catch { /* probe failed — omit rather than assert `false` */ }
 
     try {
+      // `sidecar_missing` — the DENOMINATOR for every meta-derived field below
+      // (#1289 Befund 2). `agent_type_meta` and `tool_use_id` come from the same
+      // read, so they co-occur perfectly (measured 2026-09-16 over
+      // `.orchestrator/metrics/events.jsonl`: 15.291 `orchestrator.agent.stopped`
+      // records, 542 with `agent_type_meta`, 542 with `tool_use_id`,
+      // both/only-meta/only-tool = 542/0/0). That made the low presence rate look
+      // like a producer defect in the KEY, when 1000/1000 sidecars on this host
+      // carry `agentType`. This flag makes "no sidecar found" visible in the
+      // record instead of indistinguishable from "sidecar found, field absent".
+      //
+      // WHAT THIS KEY IS NOT: a sidecar-LOOKUP failure rate. Re-measured
+      // 2026-09-16 over 15.457 `orchestrator.agent.stopped` records (5086
+      // `transcript_found:false` vs 553 `true`), the false mass is the #939/#949
+      // PHANTOM-STOP class — no subagent ever existed, so there is nothing for
+      // the lookup to find:
+      //   - 0 of 5077 distinct false `agent_id`s have a sidecar ANYWHERE on this
+      //     host (`find ~/.claude/projects -path '*/subagents/agent-*.jsonl'` →
+      //     8626 ids), and 0 have a `SubagentStart` record (2176 starts in
+      //     `.orchestrator/metrics/subagents.jsonl`);
+      //   - 0 records carrying a valid `agent_id` got a null resolver result;
+      //   - the two classes are perfectly bimodal on the type field:
+      //     `false` + no `agent` 5086, `true` + typed 553, off-diagonal 0.
+      // `agent` (the harness `agent_type`) is therefore the ready-made
+      // discriminator — no further key is needed. Do NOT "repair" the derivation
+      // in hooks/_lib/subagent-paths.mjs to chase this rate: it already resolves
+      // 553/553 of the real stops, and a widened one would only start resolving
+      // onto a FOREIGN agent's sidecar. This misreading has now cost three
+      // investigations (#939, the 2026-08-11 ledger re-run, #1289 Befund 2).
+      //
+      // Present ONLY when true, like every other optional key in this payload;
+      // its own probe is inside this try, so a failed `existsSync` omits it and
+      // nothing else (a telemetry fault must never change a decision).
+      if (!existsSync(metaPath)) payload.sidecar_missing = true;
       // One small read, one parse, two fields. `description` is operator prose
       // and is deliberately NOT carried: this payload also travels over the
       // optional Clank webhook unredacted.
@@ -565,7 +598,16 @@ async function handleSubagentStop(input) {
         payload.tool_use_id = meta.toolUseId.trim();
       }
       // A SECOND witness for the type — never merged into `agent`, so the
-      // empty-`agent_type` rate stays measurable.
+      // empty-`agent_type` rate stays measurable. NO FALLBACK MERGE, deliberately:
+      // `payload.agent` already carries the harness's `input.agent_type`, and
+      // filling one from the other would erase exactly the signal this pair
+      // exists to produce.
+      //
+      // REPORTING RULE: the presence rate of this key is only meaningful against
+      // the events whose SIDECAR WAS FOUND — "present on N of M events without
+      // `sidecar_missing`", never N of all `orchestrator.agent.stopped` records.
+      // Measured against all events the rate reads as a producer defect in this
+      // block; against its real denominator it is a lookup-failure rate.
       if (typeof meta?.agentType === 'string' && AGENT_TYPE_META_RE.test(meta.agentType.trim())) {
         payload.agent_type_meta = meta.agentType.trim();
       }
@@ -701,17 +743,11 @@ function firstNonEmptyString(input, keys) {
  * @returns {string|null}
  */
 function readStatusFromTranscriptTail(transcriptPath) {
-  let fd = null;
   try {
-    fd = openSync(transcriptPath, 'r');
-    const size = fstatSync(fd).size;
-    const length = Math.min(size, STATUS_TAIL_BYTES);
-    const start = size - length;
-    const buf = Buffer.alloc(length);
-    const read = readSync(fd, buf, 0, length, start);
-    let lines = buf.subarray(0, read).toString('utf8').split('\n');
+    const window = readTailWindow(transcriptPath, STATUS_TAIL_BYTES);
+    let lines = window.text.split('\n');
     // Drop the leading partial line when the window did not start at byte 0.
-    if (start > 0) lines = lines.slice(1);
+    if (window.cut) lines = lines.slice(1);
 
     for (let i = lines.length - 1; i >= 0; i -= 1) {
       const line = lines[i].trim();
@@ -732,10 +768,6 @@ function readStatusFromTranscriptTail(transcriptPath) {
     return null;
   } catch {
     return null;
-  } finally {
-    if (fd !== null) {
-      try { closeSync(fd); } catch { /* best-effort */ }
-    }
   }
 }
 
@@ -743,10 +775,158 @@ function readStatusFromTranscriptTail(transcriptPath) {
 // main
 // ---------------------------------------------------------------------------
 
+// ---------------------------------------------------------------------------
+// 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' };
+  }
+}
+
 async function main() {
   const input = await readStdinJson();
   const eventType = discriminate(input);
 
+  // Orphan-reaper trigger (#1432 B4) — SubagentStop is the PRD's second trigger
+  // point: it lands exactly when gate children have just finished and their PIDs
+  // are still known. Placed BEFORE the branch dispatch (unlike the PostToolBatch
+  // hook, which triggers last) because both branches below may throw — a
+  // `handleStop` failure must not silently disarm the watchdog. The cost is one
+  // config read plus one stat, bounded by `reaper.max-hook-latency-ms` (50 ms),
+  // and the scan itself runs in a detached child.
+  await maybeTriggerOrphanScan();
+
   if (eventType === 'subagent_stop') {
     const additionalContext = await handleSubagentStop(input);
     // v2.1.163+: emit hookSpecificOutput for SubagentStop path.
@@ -818,6 +998,14 @@ function buildTerminalSequenceJson(platform) {
 }
 
 // Exit 0 always — informational hook must never block Claude.
-main()
-  .catch(() => {})
-  .finally(() => process.exit(0));
+// Entry guard (#1298 P7): run only as the node script every harness execs
+// (`sh run-node.sh <this file>`); a bare `import()` must not run the Stop
+// handler against the live repo.
+if (isMainModule(import.meta.url)) {
+  // #1393: the profile gate sits INSIDE the entry guard — at module top level
+  // its `process.exit(0)` exited every process that merely imported this hook.
+  if (!shouldRunHook('on-stop')) process.exit(0);
+  main()
+    .catch(() => {})
+    .finally(() => process.exit(0));
+}

package/hooks/operator-steer.mjs

@@ -34,8 +34,7 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 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('operator-steer')) process.exit(0);
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 
 import { getProjectDir } from '../scripts/lib/platform.mjs';
 
@@ -61,4 +60,13 @@ async function main() {
 }
 
 // Exit 0 always — informational hook must never block Claude.
-main().catch(() => {}).finally(() => process.exit(0));
+// Entry guard (#1393): run only when this file IS the script node was invoked
+// with — every harness path execs it (`sh run-node.sh <this file>`). A bare
+// `import()` (a probe, a test, a curious agent) must neither run main() nor
+// tear the importing process down. The profile gate sits INSIDE the guard for
+// that second reason: at module top level its `process.exit(0)` exited every
+// process that merely imported this hook.
+if (isMainModule(import.meta.url)) {
+  if (!shouldRunHook('operator-steer')) process.exit(0);
+  main().catch(() => {}).finally(() => process.exit(0));
+}

package/hooks/post-bash-issue-budget-refund.mjs

@@ -68,12 +68,13 @@ import {
 } from '../scripts/lib/issue-budget.mjs';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 
 // Opt-out per session via SO_DISABLED_HOOKS=post-bash-issue-budget-refund; the
-// "minimal"/"off" profiles disable it like every other non-core hook.
-if (!shouldRunHook('post-bash-issue-budget-refund')) process.exit(0);
+// "minimal"/"off" profiles disable it like every other non-core hook — the gate
+// itself runs inside the entry guard at the bottom of this file (#1393).
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -367,9 +368,18 @@ async function main() {
 }
 
 // Top-level error handler — fail open, same posture as the sibling hooks.
-main().catch((e) => {
-  process.stderr.write(
-    `⚠ post-bash-issue-budget-refund: internal error — ${e?.message || e}\n`,
-  );
-  process.exit(0);
-});
+// Entry guard (#1393): run only when this file IS the script node was invoked
+// with — every harness path execs it (`sh run-node.sh <this file>`). A bare
+// `import()` (a probe, a test, a curious agent) must neither run main() nor
+// tear the importing process down. The profile gate sits INSIDE the guard for
+// that second reason: at module top level its `process.exit(0)` exited every
+// process that merely imported this hook.
+if (isMainModule(import.meta.url)) {
+  if (!shouldRunHook('post-bash-issue-budget-refund')) process.exit(0);
+  main().catch((e) => {
+    process.stderr.write(
+      `⚠ post-bash-issue-budget-refund: internal error — ${e?.message || e}\n`,
+    );
+    process.exit(0);
+  });
+}

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

@@ -143,8 +143,6 @@
  */
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
-// Exit 0 immediately (silent no-op) when disabled via profile/env (#211).
-if (!shouldRunHook('post-bash-write-verify')) process.exit(0);
 
 import path from 'node:path';
 import os from 'node:os';
@@ -1120,6 +1118,9 @@ async function main() {
 // string compare then reads false and silently no-ops the whole scope-detector
 // under a symlinked `$CLAUDE_PLUGIN_ROOT`. realpath'ing both sides also survives
 // `--preserve-symlinks` (where import.meta.url stays symlinked instead).
+// 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;
@@ -1133,6 +1134,9 @@ function invokedAsScript() {
 }
 const isMain = invokedAsScript();
 if (isMain) {
+  // #1393: the profile gate sits INSIDE the entry guard — at module top level
+  // its `process.exit(0)` exited every process that merely imported this hook.
+  if (!shouldRunHook('post-bash-write-verify')) process.exit(0);
   // Advisory hook: never block, never surface an error to the tool call.
   main().catch(() => {}).finally(() => process.exit(0));
 }

package/hooks/post-edit-import-probe.mjs

@@ -37,8 +37,7 @@
  */
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
-// Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
-if (!shouldRunHook('post-edit-import-probe')) process.exit(0);
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 
 import path from 'node:path';
 import { readFileSync, existsSync } from 'node:fs';
@@ -335,10 +334,19 @@ async function main() {
 // Exit 0 always — a hook that guards against hook breakage must never block.
 // The catch stays silent towards the TOOL CALL but not towards the operator:
 // a probe whose own breakage is invisible is a probe nobody can trust.
-main()
-  .catch((err) => {
-    try {
-      process.stderr.write(`post-edit-import-probe: ${err?.message ?? String(err)}\n`);
-    } catch { /* stderr gone — nothing left to report to */ }
-  })
-  .finally(() => process.exit(0));
+// Entry guard (#1393): run only when this file IS the script node was invoked
+// with — every harness path execs it (`sh run-node.sh <this file>`). A bare
+// `import()` (a probe, a test, a curious agent) must neither run main() nor
+// tear the importing process down. The profile gate sits INSIDE the guard for
+// that second reason: at module top level its `process.exit(0)` exited every
+// process that merely imported this hook.
+if (isMainModule(import.meta.url)) {
+  if (!shouldRunHook('post-edit-import-probe')) process.exit(0);
+  main()
+    .catch((err) => {
+      try {
+        process.stderr.write(`post-edit-import-probe: ${err?.message ?? String(err)}\n`);
+      } catch { /* stderr gone — nothing left to report to */ }
+    })
+    .finally(() => process.exit(0));
+}

package/hooks/post-edit-validate.mjs

@@ -32,8 +32,7 @@ import { spawnSync } from 'node:child_process';
 import { performance } from 'node:perf_hooks';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
-// #211: exit 0 immediately (silent allow) when this hook is disabled via profile/env
-if (!shouldRunHook('post-edit-validate')) process.exit(0);
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 
 import { readStdin } from '../scripts/lib/io.mjs';
 import { resolveProjectDir } from '../scripts/lib/platform.mjs';
@@ -220,6 +219,15 @@ async function main() {
 }
 
 // REQ-01: top-level catch — PostToolUse must never block; always exit 0
-main().catch(() => {
-  process.exit(0);
-});
+// Entry guard (#1393): run only when this file IS the script node was invoked
+// with — every harness path execs it (`sh run-node.sh <this file>`). A bare
+// `import()` (a probe, a test, a curious agent) must neither run main() nor
+// tear the importing process down. The profile gate sits INSIDE the guard for
+// that second reason: at module top level its `process.exit(0)` exited every
+// process that merely imported this hook.
+if (isMainModule(import.meta.url)) {
+  if (!shouldRunHook('post-edit-validate')) process.exit(0);
+  main().catch(() => {
+    process.exit(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));
+}