session-orchestrator 5.4.0 → 5.6.0

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

@@ -66,21 +66,22 @@
  * hooks.json wiring is managed separately (W3-C4 scope).
  */
 
-import { execFileSync, spawn } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
 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';
 import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 
-import { getProjectDir } from '../scripts/lib/platform.mjs';
+import { getProjectDir, resolveSessionRoot } from '../scripts/lib/platform.mjs';
 import { emitEvent } from '../scripts/lib/events.mjs';
-import { findScopeFile } from '../scripts/lib/scope-gate.mjs';
+import { findOwnScopeFile } from '../scripts/lib/scope-gate.mjs';
+import {
+  classifyManifestSession,
+  readProcessLocalSessionIds,
+} from '../scripts/lib/session-identity/own-session.mjs';
 import { atomicMutateJson } from './_lib/atomic-json.mjs';
-import { _parseReaper } from '../scripts/lib/config/reaper.mjs';
+import { maybeTriggerOrphanScan } from '../scripts/lib/orphan-reaper/trigger.mjs';
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -203,18 +204,23 @@ async function ownsSessionFile(input, sessionFile) {
  * wave-scope.json absent"). The file is deleted mid-session at Quality phase
  * transitions and final cleanup, so absence is an expected, non-error state.
  *
- * The manifest is located via `findScopeFile()` (#1082), the same precedence
+ * The manifest is located via `findOwnScopeFile()` (#1504), the same precedence
  * every other consumer uses — `.pi` > `.cursor` > `.codex` > `.claude`. The
  * 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
  * wave-lifecycle event was ever emitted there.
  *
- * @param {string} projectDir
+ * Only THIS session's manifest counts (#1504): `findOwnScopeFile` skips a
+ * peer's manifest in the same working copy, and a peer-only result is "no own
+ * wave" → 0, never the peer's number recorded as ours.
+ *
+ * @param {string} projectDir  the session root (`resolveSessionRoot`)
+ * @param {Set<string>} ownIds  this process's own session ids
  * @returns {Promise<number>}
  */
-async function resolveWaveNumber(projectDir) {
-  const waveFile = findScopeFile(projectDir);
+async function resolveWaveNumber(projectDir, ownIds) {
+  const { path: waveFile } = findOwnScopeFile(projectDir, ownIds, classifyManifestSession);
   if (waveFile === null) return 0;
   try {
     const raw = await readFile(waveFile, 'utf8');
@@ -308,147 +314,6 @@ 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' };
-
-    // The throttle module only — the scan's ledger, `ps` and kill-ladder code
-    // load in the detached child, never on this hook path (#1437).
-    const reaper = await import('../scripts/lib/orphan-reaper/scan-throttle.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
 // ---------------------------------------------------------------------------
@@ -489,6 +354,13 @@ async function main() {
     ...(waveSignal !== null ? { wave_signal: waveSignal } : {}),
   };
 
+  // Two roots, by writer (#1511 point a). `current-session.json` and
+  // `session.lock` stay at the LAUNCH dir: on-session-start.mjs writes both at
+  // `resolveProjectDir()`, and a reader elsewhere finds no record. Everything
+  // about the WAVE — its manifest, its start sha, the files it changed — is read
+  // at the SESSION root: after EnterWorktree the launch dir is a different
+  // checkout, whose HEAD and working tree say nothing about this wave.
+  const sessionRoot = resolveSessionRoot(input?.cwd);
   const sessionFile = path.join(getProjectDir(), '.orchestrator', 'current-session.json');
 
   const lastBatchResult = await atomicMutateJson(sessionFile, {}, (current) => ({
@@ -596,7 +468,10 @@ async function main() {
     // when an N+1 transition already closed wave N, SessionEnd sees
     // last_wave_completed === last_wave and stays silent.
     try {
-      const wave = await resolveWaveNumber(getProjectDir());
+      const wave = await resolveWaveNumber(
+        sessionRoot,
+        new Set(readProcessLocalSessionIds({ hookInput: input })),
+      );
       if (wave > 0) {
         // Read last_wave from the just-written session file (after the
         // last_batch RMW above, so we observe the latest persisted value).
@@ -627,7 +502,7 @@ async function main() {
           if (lastWave > lastWaveCompleted) {
             // #980 — measure the closing wave's diff size BEFORE the new wave's
             // start sha is persisted below. Unmeasurable → both keys omitted.
-            const filesChanged = countFilesChangedSince(getProjectDir(), waveStartSha);
+            const filesChanged = countFilesChangedSince(sessionRoot, waveStartSha);
             await emitEvent('orchestrator.wave.completed', {
               wave_number: lastWave,
               ...(filesChanged !== null
@@ -669,7 +544,7 @@ async function main() {
             // #980 — the OPEN half: stamp the sha this new wave starts from.
             // Written as null (not omitted) when git is unreadable, so the
             // PREVIOUS wave's sha can never linger and inflate the next count.
-            const startSha = readHeadSha(getProjectDir());
+            const startSha = readHeadSha(sessionRoot);
             const markResult = await atomicMutateJson(sessionFile, {}, (current) => ({
               ...current,
               wave_start_sha: startSha,
@@ -715,7 +590,17 @@ async function main() {
   // `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();
+  //
+  // The returned reason is deliberately NOT recorded here (#1489): this hook
+  // emits no record per batch, and adding one is the per-fire telemetry HR-101
+  // rejects. The throttle marker is one file per repo, so a defeated marker
+  // (`spawned-unthrottled`) shows on the next Stop/SubagentStop record, whose
+  // `reaper_trigger` key hooks/on-stop.mjs fills from the same trigger.
+  //
+  // Rooted at the SESSION root (#1492 point 2, #1504 point 4): the quality gate
+  // registers its children in the ledger of the tree it runs in, which for an
+  // entered worktree is the worktree — the launch dir holds none of them.
+  await maybeTriggerOrphanScan({ projectDir: sessionRoot });
 }
 
 // Entry guard (#1393): run only as the node script the harness execs — a bare

package/hooks/pre-bash-memory-propose-audit.mjs

@@ -29,7 +29,12 @@ import { readFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { emitEvent } from '../scripts/lib/events.mjs';
-import { findScopeFile } from '../scripts/lib/hardening.mjs';
+import { getProjectDir, resolveSessionRoot } from '../scripts/lib/platform.mjs';
+import { findOwnScopeFile } from '../scripts/lib/scope-gate.mjs';
+import {
+  classifyManifestSession,
+  readProcessLocalSessionIds,
+} from '../scripts/lib/session-identity/own-session.mjs';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
 import { isMainModule } from '../scripts/lib/is-main-module.mjs';
@@ -201,14 +206,16 @@ async function resolveSessionId(input, projectDir) {
 }
 
 /**
- * Resolve the current wave number from the active wave-scope.json.
- * Returns 0 when the file is absent or unparseable.
+ * Resolve the current wave number from THIS session's wave-scope.json.
+ * Returns 0 when the file is absent or unparseable — and when the only
+ * manifest is a peer's (#1504): its number is not this session's wave.
  *
- * @param {string} projectDir
+ * @param {string} projectDir  the session root (`resolveSessionRoot`)
+ * @param {Set<string>} ownIds  this process's own session ids
  * @returns {Promise<number>}
  */
-async function resolveWave(projectDir) {
-  const waveFile = findScopeFile(projectDir);
+async function resolveWave(projectDir, ownIds) {
+  const { path: waveFile } = findOwnScopeFile(projectDir, ownIds, classifyManifestSession);
   if (!waveFile || !existsSync(waveFile)) return 0;
   try {
     const raw = await readFile(waveFile, 'utf8');
@@ -239,15 +246,25 @@ async function main() {
   if (!MEMORY_PROPOSE_REGEX.test(command)) return emitAllow();
 
   // Matched — proceed with audit logging (G4-G7)
-  const projectDir = process.env.CLAUDE_PROJECT_DIR
-    ?? process.env.CODEX_PROJECT_DIR
-    ?? process.cwd();
+  // Two roots, by writer (#1511 point c). The session-id fallback reads
+  // `current-session.json` where on-session-start.mjs WRITES it — the launch dir,
+  // through the same resolver (`resolveProjectDir`; the hand-rolled
+  // `CLAUDE_PROJECT_DIR ?? CODEX_PROJECT_DIR ?? process.cwd()` kept a set-but-
+  // empty var, skipped the Cursor/Pi vars and never walked up). The wave and the
+  // recorded `cwd` describe the tree the session WORKS in: the SESSION root the
+  // scope guards use (#1504 point 4), which after EnterWorktree is not the
+  // launch dir.
+  const projectDir = getProjectDir();
+  const sessionRoot = resolveSessionRoot(input.cwd);
 
   // G4 — resolve session_id
   const sessionId = await resolveSessionId(input, projectDir);
 
   // G5 — resolve wave
-  const wave = await resolveWave(projectDir);
+  const wave = await resolveWave(
+    sessionRoot,
+    new Set(readProcessLocalSessionIds({ hookInput: input })),
+  );
 
   // G6 — derive the non-reversible argv summary (#1415). Nothing downstream
   // ever sees the command text: hash for grouping, known flag NAMES for
@@ -268,7 +285,7 @@ async function main() {
       command_hash: commandHash,
       flags_present: flags,
       argv_length: command.length,
-      cwd: relativeCwd(process.cwd(), projectDir),
+      cwd: relativeCwd(process.cwd(), sessionRoot),
       exit_code: null,
     });
   } catch { /* telemetry never blocks the hook (#1183) */ }

package/hooks/pre-bash-staging-fence.mjs

@@ -75,6 +75,7 @@ import crypto from 'node:crypto';
 import { shouldRunHook } from './_lib/profile-gate.mjs';
 import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 import { stableHostname } from '../scripts/lib/host-identity.mjs';
+import { dotGitAncestor, launchDirFromEnv } from '../scripts/lib/platform.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -400,16 +401,36 @@ function deriveAgentId() {
 }
 
 /**
- * Resolve the project directory the hook should operate against. Mirrors
- * pre-bash-memory-propose-audit.mjs resolution: prefer CLAUDE_PROJECT_DIR /
- * CODEX_PROJECT_DIR env-vars, fall back to cwd.
+ * The repo whose fence directory this `git add` is recorded in — the SAME root
+ * the reader uses (#1504 point 4). The only reader, `hooks/wave-scope-commit-guard.mjs`,
+ * runs as git's pre-commit hook and walks `<git rev-parse --show-toplevel>/.orchestrator/staging-fence/`,
+ * i.e. the work-tree root the commit is made in. `dotGitAncestor(cwd)` is that
+ * root without a spawn: the nearest `.git` entry at or above the payload `cwd` —
+ * the worktree root for a session that entered a worktree (measured 2026-10-03:
+ * launch dir `<main>`, cwd `<worktree>/sub` → `<worktree>`, git toplevel
+ * `<worktree>`), the repo root for a launch in a repo SUBDIRECTORY. The launch
+ * dir (`$CLAUDE_PROJECT_DIR`) was wrong in both: the fence landed where no
+ * commit guard looked, and every cross-agent overlap passed.
  *
+ * Deliberately NOT `resolveSessionRoot()`: its clamp answers the launch
+ * SUBDIRECTORY of a monorepo package, while git's toplevel is the repo root.
+ *
+ * Fallback when the payload carries no `cwd`, or `cwd` is in no repo (where no
+ * commit can read a fence anyway): the launch dir from env, then `process.cwd()`.
+ *
+ * NAMED CEILING (BV-004): the root follows the payload `cwd`, not the command —
+ * `git -C <other-tree> add` or `cd <other-tree> && git add` records the intent
+ * in the CURRENT tree's fence dir while the commit in `<other-tree>` reads its
+ * own, so that overlap stays unseen (as before). Revisit if a fence miss is
+ * ever traced to a redirected `git add`; the fix then is to resolve the root
+ * from the tokenized command's `-C` / leading `cd`.
+ *
+ * @param {object|null} input  the hook payload
  * @returns {string}
  */
-function resolveProjectDir() {
-  return process.env.CLAUDE_PROJECT_DIR
-    ?? process.env.CODEX_PROJECT_DIR
-    ?? process.cwd();
+function resolveFenceRoot(input) {
+  const cwd = typeof input?.cwd === 'string' ? input.cwd.trim() : '';
+  return (cwd !== '' && dotGitAncestor(cwd)) || launchDirFromEnv() || process.cwd();
 }
 
 /**
@@ -494,7 +515,7 @@ async function main() {
   if (!recognised) return emitAllow();
 
   // G5 — derive paths.
-  const projectDir = resolveProjectDir();
+  const projectDir = resolveFenceRoot(input);
   const agentId = deriveAgentId();
   const fenceFile = path.join(
     projectDir,