session-orchestrator 5.2.0 → 5.3.0

package/hooks/on-session-start.mjs

@@ -36,8 +36,6 @@ import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
-// #211: exit 0 immediately (silent allow) when this hook is disabled via profile/env
-if (!shouldRunHook('on-session-start')) process.exit(0);
 
 import { emitEvent, eventsFilePath } from '../scripts/lib/events.mjs';
 import { maybeRotate } from '../scripts/lib/events-rotation.mjs';
@@ -54,6 +52,7 @@ import { detectColdStart, consumeMarker } from '../scripts/lib/cold-start-detect
 import { parseSessionId } from '../scripts/lib/session-id.mjs';
 import { readTelemetryState, resolveConsent, isCiEnv } from '../scripts/lib/telemetry/consent.mjs';
 import { loadOwnerConfig } from '../scripts/lib/owner-yaml.mjs';
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 // SSOT for the "is this a re-entry into the same logical session?" question
 // (#1091). Defined in the lock-bootstrap leaf module, which this hook already
 // loads, so the preservation branch below and the lock force-refresh gate can
@@ -453,8 +452,10 @@ async function resolveSessionId(input, projectRoot) {
     // observe. A naive full overwrite of current-session.json drops the
     // `last_wave` / `last_batch` markers written mid-session by
     // post-tool-batch-wave-signal.mjs, which makes the next PostToolBatch
-    // re-read last_wave as absent→0 and re-emit a duplicate
-    // orchestrator.wave.started{N} with no intervening wave.completed.
+    // re-read last_wave as absent→0 and RE-OPEN wave N mid-wave, re-stamping
+    // wave_start_sha and so moving the #980 files_changed start point. (Until
+    // 2026-09-19 it also re-emitted a duplicate wave.started{N}; that event
+    // has since been removed.)
     //
     // Three cases, exactly one of which preserves nothing:
     //   'raw-id'   — same-logical-session source AND the recorded raw
@@ -764,8 +765,12 @@ async function main() {
   // v3.1.0 env-aware banner (opt-out via enable-host-banner: false in Session Config).
   // The ask-via-tool nudge rides the same opt-out flag — both are coordinator
   // reminders shown at session start; users who silence one expect silence.
+  // Hoisted because the cold-start DISPLAY below rides the same opt-out (#1133)
+  // and `bannerData` is not a usable proxy for it: `emitHostBanner()` returns
+  // null on its own error paths, which would silently re-open the nudge.
+  const hostBannerEnabled = await isHostBannerEnabled(projectRoot);
   let bannerData = null;
-  if (await isHostBannerEnabled(projectRoot)) {
+  if (hostBannerEnabled) {
     bannerData = await emitHostBanner(projectRoot);
     // Always-on nudge: a user decision has three legitimate forms and AUQ-001
     // routes between them in order — operator verb first (nothing is blocked
@@ -795,7 +800,14 @@ async function main() {
         enabled: coldStartCfg.enabled !== false,
       });
       if (decision.shouldEmit) {
-        pushBanner(decision.bannerLines.join('\n'));
+        // #1133 — the DISPLAY rides the enable-host-banner opt-out like every
+        // other start-of-session emitter ("users who silence one expect
+        // silence"). The one-shot marker consumption below does NOT: the
+        // opt-out silences the display, never the measurement or the state
+        // transition. Consuming it unconditionally is what keeps the nudge
+        // one-shot for an operator who has banners off — otherwise it re-arms
+        // on every start forever.
+        if (hostBannerEnabled) pushBanner(decision.bannerLines.join('\n'));
         if (decision.markerPath) {
           await consumeMarker(decision.markerPath).catch(() => false);
         }
@@ -1219,6 +1231,14 @@ async function main() {
   // Size-based rotation of events.jsonl (#251). Session-start is the single
   // rotation trigger — per-append overhead is rejected design. Any failure
   // is swallowed: rotation must NEVER block the hook.
+  //
+  // #1401 — the DURABLE record of a rotation is no longer this block. Until
+  // 2026-09-19 the only evidence a rotation had happened was the `console.error`
+  // below, and this hook's stderr is discarded by the harness: a rotation and a
+  // DELETED archive were byte-identical from outside. `maybeRotate()` now writes
+  // an `orchestrator.events.rotated` record as the first line of the new active
+  // file, so the ledger carries its own break whatever happens to this stderr
+  // line. The line stays as an operator convenience only — never as the record.
   try {
     let rotCfg = { enabled: true, 'max-size-mb': 10, 'max-backups': 5 };
     try {
@@ -1234,7 +1254,13 @@ async function main() {
       enabled: rotCfg.enabled !== false,
     });
     if (result.rotated) {
-      console.error(`events-rotation: archived ${result.archivedAs} (${result.sizeBefore} bytes)`);
+      const pruned = result.pruned?.length ? `, pruned ${result.pruned.length}` : '';
+      const ledger = result.recordWritten ? '' : ' [WARN: rotation record NOT written]';
+      console.error(
+        `events-rotation: archived ${result.archivedAs} ` +
+          `(${result.sizeBefore} bytes, ${result.lines ?? '?'} lines, ` +
+          `${result.firstTs ?? 'unknown'} → ${result.lastTs ?? 'unknown'}${pruned})${ledger}`,
+      );
     }
   } catch (err) {
     console.error(`events-rotation: skipped (${err?.message ?? err})`);
@@ -1245,7 +1271,18 @@ async function main() {
 // flushBanner() runs here too so a throw partway through main() still surfaces
 // whatever was already collected; it is idempotent, so the normal path (which
 // flushes at the end of main) does not double-emit.
-main().catch(() => {}).finally(() => {
-  flushBanner();
-  process.exit(0);
-});
+//
+// Entry guard (#1298 P7): every harness execs this file as the node script
+// (`sh run-node.sh <this file>` → `exec node "$@"`), so argv[1] IS this module
+// on every real path. A bare `import()` — a probe, a test, a curious agent —
+// must not run main() against the live repo: incident W4-FX1 overwrote
+// `.orchestrator/current-session.json` exactly that way.
+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-session-start')) process.exit(0);
+  main().catch(() => {}).finally(() => {
+    flushBanner();
+    process.exit(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)
@@ -743,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();
@@ -774,10 +768,6 @@ function readStatusFromTranscriptTail(transcriptPath) {
     return null;
   } catch {
     return null;
-  } finally {
-    if (fd !== null) {
-      try { closeSync(fd); } catch { /* best-effort */ }
-    }
   }
 }
 
@@ -785,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.
@@ -860,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';
@@ -1136,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);
+  });
+}