session-orchestrator 5.12.0 → 5.13.0

package/hooks/on-session-start.mjs

@@ -33,19 +33,22 @@ import { existsSync, writeSync } from 'node:fs';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
 import path from 'node:path';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
 import { ensureOrchestratorIgnore } from './_lib/orchestrator-ignore.mjs';
+import { resolveSessionStartRoot } from './_lib/hook-root.mjs';
 
 import { emitEvent, eventsFilePath } from '../scripts/lib/events.mjs';
 import { readNavigatorLease, fleetIntegrationEnabled } from '../scripts/lib/fleet-protocol.mjs';
 import { maybeRotate } from '../scripts/lib/events-rotation.mjs';
 import { readConfigFile, parseSessionConfig } from '../scripts/lib/config.mjs';
-import { getPlatform, resolveProjectDir } from '../scripts/lib/platform.mjs';
+import { getPlatform, resolveProjectDir, resolveSessionRoot } from '../scripts/lib/platform.mjs';
 import {
   registerSelf,
   detectPeers,
+  countRecentStarts,
   sweepZombies,
   logSweepEvent,
   repoPathHash,
@@ -58,8 +61,9 @@ 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
-// never drift apart.
-import { SAME_LOGICAL_SESSION_SOURCES } from './_lib/lock-bootstrap.mjs';
+// never drift apart. readClaudePid() is the process witness current-session.json
+// carries next to the raw id (#1746).
+import { SAME_LOGICAL_SESSION_SOURCES, readClaudePid } from './_lib/lock-bootstrap.mjs';
 
 const execFileAsync = promisify(execFile);
 
@@ -187,14 +191,20 @@ function supersessionMarker(peer) {
 }
 
 /**
- * Queue the ONE `additionalContext` string for the single end-of-hook flush.
- * Last writer wins; there is deliberately no accumulation, because every
- * character here costs context on every session start.
+ * Queue text for the ONE `additionalContext` string of the single end-of-hook
+ * flush. Two writers exist (the consent nudge, the #1635 lead notice) and both
+ * are needed by the model, so a second text is appended on its own line; an
+ * identical text is not repeated. Every character costs context on every
+ * session start, so writers stay terse and conditional.
  * @param {string|null|undefined} text
  */
 function setAdditionalContext(text) {
   if (typeof text !== 'string' || text.length === 0) return;
-  pendingAdditionalContext = text;
+  if (typeof pendingAdditionalContext !== 'string' || pendingAdditionalContext.length === 0) {
+    pendingAdditionalContext = text;
+  } else if (!pendingAdditionalContext.split('\n').includes(text)) {
+    pendingAdditionalContext = `${pendingAdditionalContext}\n${text}`;
+  }
 }
 
 /**
@@ -241,14 +251,16 @@ function flushBanner() {
 // ---------------------------------------------------------------------------
 
 /**
- * Run a git command in cwd; return trimmed stdout. Returns null on failure.
+ * Run a git command in cwd; return trimmed stdout. Returns null on failure
+ * (including a timeout, when `timeoutMs` is given).
  * @param {string[]} args
  * @param {string} cwd
+ * @param {number} [timeoutMs] — kill the git child after this many ms (0 = no limit)
  * @returns {Promise<string|null>}
  */
-async function gitOutput(args, cwd) {
+async function gitOutput(args, cwd, timeoutMs = 0) {
   try {
-    const { stdout } = await execFileAsync('git', args, { cwd });
+    const { stdout } = await execFileAsync('git', args, { cwd, timeout: timeoutMs });
     return stdout.trim();
   } catch {
     return null;
@@ -316,25 +328,27 @@ export async function readColdStartConfig(projectRoot) {
 }
 
 /**
- * Read `resource-thresholds.concurrent-sessions-warn` from Session Config.
- * Used to decide when the peer banner should show the WARN icon. Defaults to
- * 5 — matches the documented default in docs/session-config-reference.md.
+ * Start-wave rule (#1650): WARN when at least START_WAVE_MIN foreign registry
+ * entries started within the last START_WAVE_WINDOW_MIN minutes.
+ *
+ * Why not `peer_count >= concurrent-sessions-warn` (the previous WARN trigger):
+ * that is a permanent state, not an event. Measured 2026-10-17 08:08Z/08:09Z
+ * over `orchestrator.session.started` since 2026-08-24, dedup session_id +
+ * timestamp, per `host_class`: peer_count >= 5 fired on 880/1305 = 67.4% (M4)
+ * and 255/991 = 25.7% (M5) of starts — a broken instrument per HR-101.
+ * This rule, reconstructed from the start timestamps themselves, fires on
+ * 35/1305 = 2.7% (M4) and 52/991 = 5.2% (M5). Neighbouring candidates:
+ * >=3 in 2 min 4.0% / 7.1%, >=5 in 2 min 1.7% / 3.3%, >=3 in 5 min 6.3% / 10.7%.
+ * 5 min was chosen over 2 min so a wave spread over a few minutes still shows.
+ *
+ * Ceiling (BV-004): fixed constants, no config key; the reconstruction is an
+ * upper bound (sessions that ended inside the window leave the registry).
+ * Revisit when either host's firing rate on `recent_starts_count >= 5` in the
+ * event ledger exceeds 10%, or a start wave that hurt was not flagged.
+ * Report only — this single soft signal caps nothing (HR-104).
  */
-async function peerWarnThreshold(projectRoot) {
-  const DEFAULT = 5;
-  for (const name of ['CLAUDE.md', 'AGENTS.md']) {
-    try {
-      const raw = await readFile(path.join(projectRoot, name), 'utf8');
-      // Match `concurrent-sessions-warn: <int>` inside resource-thresholds or top-level.
-      const m = raw.match(/^\s*concurrent-sessions-warn:\s*(\d+)\b/im);
-      if (m) {
-        const n = parseInt(m[1], 10);
-        if (!Number.isNaN(n) && n > 0) return n;
-      }
-    } catch { /* file missing is fine */ }
-  }
-  return DEFAULT;
-}
+const START_WAVE_WINDOW_MIN = 5;
+const START_WAVE_MIN = 5;
 
 /**
  * Non-blocking stdin read for Claude Code hook payload. Returns parsed JSON or
@@ -372,8 +386,13 @@ async function readStdinJson(timeoutMs = 500) {
  * Codex/Cursor may not).
  *
  * Best-effort: any persistence failure is swallowed (hook must remain non-blocking).
+ *
+ * @param {object|null} input — the parsed SessionStart payload.
+ * @param {string} projectRoot
+ * @param {number|null} [claudePid=null] — readClaudePid(); recorded with the
+ *   host as the writer's process witness (#1746).
  */
-async function resolveSessionId(input, projectRoot) {
+async function resolveSessionId(input, projectRoot, claudePid = null) {
   const nativeSource = typeof input?.source === 'string' && input.source.length > 0
     ? input.source
     : null;
@@ -477,9 +496,12 @@ async function resolveSessionId(input, projectRoot) {
     // (`resume` was ABSENT from hooks.json until #1091, so on Claude Code this
     // hook never ran on a native resume), `startup|reload|new|resume|fork` on
     // pi, and every source on Cursor (empty matcher). Several of those sources
-    // are re-entries into the SAME logical session. On clear/compact the UUID
-    // `session_id` changes while the `semantic_session_id`
-    // (branch+date+mode+n) stays stable; whether Claude Code PRESERVES the raw
+    // are re-entries into the SAME logical session. The `semantic_session_id`
+    // (branch+date+mode+n) is meant to stay stable across them. The raw UUID
+    // `session_id` does not behave alike per source: on Claude Code `compact`
+    // KEEPS it (12/12 compact events in events.jsonl carry
+    // `resume_linkage: raw-id`, measured 2026-10-14), while `clear` showed
+    // 6/6 `resume_linkage: none`. Whether Claude Code PRESERVES the raw
     // `session_id` across a native resume is what #1091 measures via
     // `native_source` + `resume_linkage` on `orchestrator.session.started` —
     // nothing here ASSUMES either answer, it only reacts to the raw id it can
@@ -548,6 +570,11 @@ async function resolveSessionId(input, projectRoot) {
       pid: process.pid,
       source,
       timestamp: new Date().toISOString(),
+      // #1746 — `pid` above is this short-lived hook process, no witness of
+      // anything after it exits. The Claude Code process survives /clear, so
+      // the next run can tell its own predecessor from a peer that started
+      // later in this checkout. Absent without a readable CLAUDE_PID.
+      ...(typeof claudePid === 'number' ? { claude_pid: claudePid, host: hostname() } : {}),
       // Spread AFTER the base fields so the preserved high-water marks survive
       // (and never clobber the identity fields above).
       ...preserved,
@@ -565,12 +592,18 @@ async function resolveSessionId(input, projectRoot) {
     mode: normalizedMode,
     nativeSource,
     resumeLinkage,
-    // The raw session_id our OWN previous run of this hook recorded, or null.
-    // Surfaced (rather than kept local) because bootstrapLock() needs it as the
-    // third conjunct of the #1091 F2 force-refresh — see the call site in main().
+    // The raw session_id the LAST session start in this checkout recorded, or
+    // null. Every session start rewrites the file, so it is our own previous
+    // run only when no peer started here since (#1746). Surfaced (rather than
+    // kept local) because bootstrapLock() needs it as the third conjunct of
+    // the #1091 F2 force-refresh — see the call site in main().
     predecessorSessionId: typeof prev?.session_id === 'string' && prev.session_id.length > 0
       ? prev.session_id
       : null,
+    // #1746 — the process witness that writer recorded, unvalidated: the
+    // consumer compares it with isSameClaudeProcess(), which admits only an
+    // exact pid match on this host.
+    predecessorProcess: prev ? { claude_pid: prev.claude_pid, host: prev.host } : null,
   };
 }
 
@@ -780,7 +813,14 @@ function maybeQueueConsentNudge() {
 // ---------------------------------------------------------------------------
 
 async function main() {
-  const projectRoot = resolveProjectDir();
+  // #1605 — the root depends on the payload `source`/`cwd`/`session_id`, so the
+  // optional stdin payload is read BEFORE the first writer below. Best-effort:
+  // readStdinJson resolves null on a closed/empty/unparseable stdin and caps
+  // itself at 500 ms. The rule (entered worktree only for clear/compact/resume,
+  // only a verified linked worktree, never over another live session's state)
+  // lives in hooks/_lib/hook-root.mjs, beside the readers' own-lock lookup.
+  const input = await readStdinJson();
+  const projectRoot = await resolveSessionStartRoot(input, resolveProjectDir());
 
   // #1515 Pkt 5 — before this hook's own writers (host.json, session.lock,
   // events.jsonl) run: an un-bootstrapped repo gets `.orchestrator/.gitignore`
@@ -788,11 +828,6 @@ async function main() {
   // pay two existsSync and nothing else. Never throws.
   await ensureOrchestratorIgnore(projectRoot);
 
-  // Read optional stdin payload in parallel with git info so we don't stall
-  // the hook. Both are best-effort and the promise races against a 500 ms cap
-  // inside readStdinJson itself.
-  const stdinPromise = readStdinJson();
-
   // Resolve project name: basename of git toplevel, falling back to cwd basename.
   const topLevel = await gitOutput(['rev-parse', '--show-toplevel'], projectRoot);
   const projectName = topLevel
@@ -809,6 +844,24 @@ async function main() {
   const rawHeadSha = await gitOutput(['rev-parse', 'HEAD'], projectRoot);
   const headSha = rawHeadSha && /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(rawHeadSha) ? rawHeadSha : null;
 
+  // #1668 — the upstream state at start, so emit-session can tell a stale
+  // head_sha (checkout behind its upstream: a later pull drags foreign commits
+  // into `<head_sha>..HEAD`) from a current one. Local refs only — no fetch, no
+  // network — and bounded at 1 s per call. No upstream configured, a timeout or
+  // a non-numeric count → BOTH keys omitted (not measured), never 0.
+  let upstreamSha = null;
+  let behind = null;
+  if (headSha) {
+    const [rawUpstream, rawBehind] = await Promise.all([
+      gitOutput(['rev-parse', '--verify', '--quiet', '@{u}^{commit}'], projectRoot, 1000),
+      gitOutput(['rev-list', '--count', 'HEAD..@{u}'], projectRoot, 1000),
+    ]);
+    if (rawUpstream && /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(rawUpstream) && rawBehind && /^\d+$/.test(rawBehind)) {
+      upstreamSha = rawUpstream;
+      behind = Number(rawBehind);
+    }
+  }
+
   // 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.
@@ -872,13 +925,18 @@ async function main() {
 
   // v3.1.0 multi-session registry (#168). All steps best-effort — failures
   // must never break the hook, which is informational-only.
-  const input = await stdinPromise;
   // #1091 — the native SessionStart `source` (Claude Code: startup|resume|
   // clear|compact), plus the linkage decision resolveSessionId() derived from
   // it (see SAME_LOGICAL_SESSION_SOURCES). Both are surfaced on the event so
   // #1091 gets its measurement instead of an inference.
-  const { sessionId, semanticSessionId, mode, nativeSource, resumeLinkage, predecessorSessionId } =
-    await resolveSessionId(input, projectRoot);
+  // #1641: the Claude Code process survives /clear while the raw id and the
+  // semantic label are minted anew — its pid is the witness that a live lock,
+  // or the current-session.json entry (#1746), is our own predecessor's.
+  // Admitted only as this hook's direct parent: a Codex child of a Claude
+  // session inherits the variable.
+  const claudePid = readClaudePid();
+  const { sessionId, semanticSessionId, mode, nativeSource, resumeLinkage, predecessorSessionId, predecessorProcess } =
+    await resolveSessionId(input, projectRoot, claudePid);
   // getPlatform() ALREADY implements the SO_PLATFORM override as step 1 of its
   // precedence — and, unlike a bare `??`, it validates the value against the
   // four-platform allowlist and trims it. The former `process.env.SO_PLATFORM ??
@@ -905,12 +963,23 @@ async function main() {
       mode,
       ttlHours: 4,
       nativeSource,
-      // The raw session_id our OWN previous run of this hook recorded. It is the
+      // The raw session_id the last session start in this checkout recorded —
+      // our own previous run unless a peer started here since. It is the
       // third conjunct of the same-logical-session force-refresh (#1091 F2): a
       // semantic-label match alone is collidable on one host (#1066), so the
       // live lock must ALSO carry our predecessor's raw id before we take it
       // over. `prev` is read above, before the semantic id is minted.
       predecessorSessionId,
+      // #1746: who wrote that raw id — the lead yield trusts it as "our own
+      // predecessor" only when this same Claude process did.
+      predecessorProcess,
+      claudePid,
+      // #1635: a fleet lead holds this main checkout — no lock was taken; the
+      // model and the operator are told to work in a worktree instead.
+      onNotice: (context, banner) => {
+        setAdditionalContext(context);
+        pushBanner(banner);
+      },
     });
   } catch { /* hook must remain non-blocking */ }
 
@@ -973,6 +1042,12 @@ async function main() {
         platform,
         mode,
         hostClass: bannerData?.host?.host_class ?? null,
+        // #1605 — the pointer the readers (Stop, PostToolBatch, SessionEnd, the
+        // current-session.json side writers) follow to THIS session's lock,
+        // whatever their cwd; and the working copy, so a later relocation
+        // into it by another session sees this one (B4). Stop refreshes it.
+        sessionRoot: path.resolve(projectRoot),
+        workRoot: path.resolve(resolveSessionRoot(input?.cwd)),
       });
     } catch (err) {
       // Registration failed — emit an observability breadcrumb to sweep.log.
@@ -981,6 +1056,9 @@ async function main() {
     }
     peers = await detectPeers({ sessionId }).catch(() => []);
   } catch { /* swallow — hook must remain non-blocking */ }
+  // #1650 — foreign starts inside the window. detectPeers() already excludes
+  // self, and its 15-min freshness covers the 5-min window (see helper JSDoc).
+  const recentStarts = countRecentStarts(peers, { windowMin: START_WAVE_WINDOW_MIN });
 
   // Append a peer line to the host banner when a banner was already emitted
   // and at least one peer is live on this host.
@@ -1004,10 +1082,11 @@ async function main() {
       selfRepoHash && p.repo_path_hash ? p.repo_path_hash === selfRepoHash : false);
     const elsewhere = peers.filter((p) => !sameCopy.includes(p));
 
-    const threshold = await peerWarnThreshold(projectRoot);
     // WARN on any peer in THIS working copy — one is already enough to collide
-    // — or on host-wide count crossing the configured threshold.
-    const icon = sameCopy.length > 0 || peers.length >= threshold ? '⚠️ ' : '';
+    // — or on a start wave (#1650). The host-wide peer count stays on the line
+    // as information only: as a WARN trigger it fired on 67.4% of starts.
+    const startWave = recentStarts >= START_WAVE_MIN;
+    const icon = sameCopy.length > 0 || startWave ? '⚠️ ' : '';
 
     // Semantic ids are NOT unique — several live sessions routinely share e.g.
     // `main-2026-08-21-session-2`, which makes a bare semantic label unusable
@@ -1019,6 +1098,9 @@ async function main() {
       return `${label}${disc}:${p.branch ?? 'unknown'}:wave-${p.current_wave ?? 0}`;
     };
     pushBanner(`${icon}👥 Peers: ${peers.length} live on this host`);
+    if (startWave) {
+      pushBanner(`   ⚠️  Start wave: ${recentStarts} sessions started or resumed in the last ${START_WAVE_WINDOW_MIN} min — stagger further starts`);
+    }
     if (sameCopy.length > 0) {
       const list = sameCopy.slice(0, 3).map(fmt).join(', ');
       const more = sameCopy.length > 3 ? ` +${sameCopy.length - 3} more` : '';
@@ -1174,7 +1256,7 @@ async function main() {
     pluginUpdate = await checkPluginUpdate({
       cacheDir: path.join(projectRoot, '.orchestrator', 'runtime'),
       // The probe's own fallback is env-only (SO_PLATFORM, then each harness's
-      // compat var) and cannot run detectPlatform()'s third step, the marker-
+      // compat var) and cannot run detectPlatform()'s step 4, the marker-
       // directory walk from cwd. This hook already resolved the platform at the
       // top of run() through exactly that full precedence, so handing it over
       // makes the remedy instruction MEASURED rather than guessed — a Codex or
@@ -1195,8 +1277,16 @@ async function main() {
     // this root supersedes. `peer_count` is deliberately unchanged; this field
     // makes the supersession rate measurable instead of inferred (HR-105).
     peers_superseded: mechanicalPeersSuperseded,
+    // #1650 — start-wave signal (HR-105): foreign registry entries whose
+    // started_at lies within the last `recent_starts_window_min` minutes.
+    recent_starts_count: recentStarts,
+    recent_starts_window_min: START_WAVE_WINDOW_MIN,
   };
   if (headSha) payload.head_sha = headSha;
+  if (upstreamSha !== null) {
+    payload.upstream_sha = upstreamSha;
+    payload.behind = behind;
+  }
 
   // #1091 — record the native SessionStart source so "does the same raw
   // session_id repeat under source=resume?" becomes answerable from

package/hooks/on-stop.mjs

@@ -47,6 +47,7 @@ import { AGENT_ID_RE, resolveSubagentSidecar } from './_lib/subagent-paths.mjs';
 
 import { emitEvent } from '../scripts/lib/events.mjs';
 import { detectPlatform, getProjectDir, resolveSessionRoot } from '../scripts/lib/platform.mjs';
+import { resolveOwnLockRoot } from './_lib/hook-root.mjs';
 import { findOwnScopeFile } from '../scripts/lib/scope-gate.mjs';
 import {
   classifyManifestSession,
@@ -119,7 +120,7 @@ function discriminate(input) {
 // dependency degradation (GH Kanevry/session-orchestrator#63)
 // ---------------------------------------------------------------------------
 //
-// zx is loaded LAZILY. A static `import { $ } from 'zx'` fails at MODULE LOAD
+// zx is loaded LAZILY. A static `import { $ } from '../scripts/lib/zx.mjs'` fails at MODULE LOAD
 // time when node_modules is absent (interrupted install, EPERM sandbox, half-
 // synced plugin cache), so the harness prints a 10-frame ERR_MODULE_NOT_FOUND
 // stack on EVERY turn end with no hint that `npm install` is the fix. This
@@ -175,7 +176,7 @@ function warnDependenciesMissingOnce() {
  */
 async function loadZx() {
   try {
-    return (await import('zx')).$;
+    return (await import('../scripts/lib/zx.mjs')).$;
   } catch (err) {
     if (err?.code !== 'ERR_MODULE_NOT_FOUND') throw err;
     warnDependenciesMissingOnce();
@@ -401,11 +402,13 @@ function reaperTriggerField(trigger) {
  */
 async function handleStop(input, reaperTrigger = null) {
   // Two roots, by writer (#1511 point b). `current-session.json` and
-  // `session.lock` (session id, lock heartbeat, duration) stay at the LAUNCH
-  // dir: on-session-start.mjs writes both at `resolveProjectDir()`. The wave
+  // `session.lock` (session id, lock heartbeat, duration) are read where
+  // on-session-start.mjs wrote them: the launch dir, or — after EnterWorktree
+  // and a /clear, compact or resume there (#1605) — the entered worktree, found
+  // by the lock carrying this session's raw id (`resolveOwnLockRoot`). The wave
   // and the commit/branch describe the tree the session WORKS in — after
   // EnterWorktree that is the session root, not the launch checkout.
-  const projectRoot = getProjectDir();
+  const projectRoot = resolveOwnLockRoot(input, getProjectDir());
   const sessionRoot = resolveSessionRoot(input?.cwd);
 
   const wave = await readWaveNumber(sessionRoot, input);
@@ -453,7 +456,9 @@ async function handleStop(input, reaperTrigger = null) {
       // is visible in sweep.log rather than invisible. One line per turn while
       // the entry is absent; that volume IS the signal, and the next
       // SessionStart's registerSelf() ends it.
-      const refreshed = await heartbeat(sessionId);
+      // #1605 B4 — `work_root` follows the session into an entered worktree,
+      // so a relocating SessionStart of another session sees it working there.
+      const refreshed = await heartbeat(sessionId, { workRoot: path.resolve(sessionRoot) });
       if (refreshed === null) {
         logSweepEvent({
           event: 'heartbeat-missing',

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

@@ -100,7 +100,12 @@ async function resolveSessionId(input, projectDir) {
 
   let currentSession = null;
   if (projectDir) {
-    const persisted = path.join(projectDir, '.orchestrator', 'current-session.json');
+    // #1605 — read THIS session's record where on-session-start.mjs wrote it
+    // (the entered worktree after a /clear there), found by the lock carrying
+    // the raw id. Lazy: only a matched issue command pays for the lookup.
+    const { resolveOwnLockRoot } = await import('./_lib/hook-root.mjs');
+    const ownRoot = resolveOwnLockRoot({ session_id: nativeRawId, cwd: input?.cwd }, projectDir);
+    const persisted = path.join(ownRoot, '.orchestrator', 'current-session.json');
     if (existsSync(persisted)) {
       try {
         currentSession = await readJson(persisted);

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

@@ -1093,9 +1093,10 @@ async function main() {
   // manifest a Bash call just corrupted. `'own'` and `'unknown'` (legacy,
   // unbound, or no resolvable own identity) fall through unchanged.
   //
-  // CEILING (BV-004): on a harness that supplies no session id at all (Codex
-  // CLI, Cursor today) the own-id set is empty, so this gate is permanently
-  // `'unknown'` = full pre-#1153 behaviour there.
+  // CEILING (BV-004): on a harness that supplies no session id at all (Cursor
+  // today) the own-id set is empty, so this gate is permanently `'unknown'` =
+  // full pre-#1153 behaviour there. Codex CLI sends `session_id` in the hook
+  // payload (measured 2026-10-20, codex-cli 0.160.1, #1691).
   {
     const { verdict, manifestIds } = classifyManifestSession(scope ?? {}, ownIds);
     if (verdict === 'foreign') {
@@ -1172,7 +1173,10 @@ async function main() {
   // `toContain('out-of-scope.mjs')` test to say otherwise.
   const missingSnapshotNotice = prevScopeState === null
     ? formatSnapshotMissingNotice({
-      sessionAge: sessionAgeMs(context.manifestRoot),
+      // #1634: the clock lives beside this session's own lock, which after
+      // ExitWorktree is its `session_root`, not the manifest root. Loaded lazily:
+      // this branch is rare and the module graph costs ~7 ms per Bash call.
+      sessionAge: sessionAgeMs((await import('./_lib/hook-root.mjs')).resolveOwnLockRoot(input, context.manifestRoot)),
       scopeAge: typeof scopeMtimeMs === 'number' ? Date.now() - scopeMtimeMs : null,
       reason: snapshot === null ? 'absent' : 'untrusted',
     })

package/hooks/post-edit-validate.mjs

@@ -14,22 +14,23 @@
  *   G3  file_path present
  *   G4  file extension filter — only .ts|.tsx|.js|.jsx|.mjs|.cjs
  *   G5  gate check — wave-scope.json.gates['post-edit-validate'] === false → exit 0
- *   G6  resolve typecheck command: Session Config → tsgo → tsc → npx tsc → skip
- *   G7  run typecheck with 2s AbortController timeout
+ *   G6  resolve typecheck command: Session Config → tsgo → tsc → local tsc → skip
+ *   G7  run typecheck with 2s process-group timeout
  *   G8  emit JSONL result to stderr
  *
- * Output (stderr): {"check":"typecheck","status":"pass|fail|skip","file":"<rel>","duration_ms":<int>}
+ * Output (stderr): {"check":"typecheck","status":"pass|fail|timeout|skip","file":"<rel>","duration_ms":<int>}
  * Exit codes: 0 — always (PostToolUse hooks are informational)
  *
  * SECURITY notes:
  *   REQ-01  top-level try/catch → silent exit 0 on unexpected error (never blocks)
- *   REQ-02  typecheck process uses AbortController (not shell `timeout` — cross-platform)
+ *   REQ-02  typecheck runs the intact shell command; timeout kills its process tree
  *   REQ-03  relative path computed via path.relative(projectRoot, absFilePath)
  */
 
 import path from 'node:path';
+import { existsSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
-import { performance } from 'node:perf_hooks';
+import { spawnInGroup } from '../scripts/lib/process-group.mjs';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
 import { isMainModule } from '../scripts/lib/is-main-module.mjs';
@@ -54,9 +55,9 @@ const TS_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
 /**
  * Emit the JSONL result line to stderr.
  * @param {string} file            - relative file path
- * @param {'pass'|'fail'|'skip'} status
+ * @param {'pass'|'fail'|'timeout'|'skip'} status
  * @param {number} [duration_ms]   - omit for skip
- * @param {string} [reason]        - human-readable reason for skip or fail
+ * @param {string} [reason]        - human-readable reason for skip, timeout or fail
  * @param {string} [remediation]   - actionable fix hint for fail status only
  */
 function emitResult(file, status, duration_ms, reason, remediation) {
@@ -69,10 +70,10 @@ function emitResult(file, status, duration_ms, reason, remediation) {
 
 /**
  * Try to resolve the typecheck command.
- * Order: Session Config typecheck-command → tsgo → tsc → npx tsc → null
+ * Order: Session Config typecheck-command → tsgo → tsc → local tsc → null
  *
  * @param {string} projectRoot
- * @returns {Promise<{cmd: string, args: string[]}|null>}
+ * @returns {Promise<string|string[]|null>}
  */
 async function resolveTypecheckCommand(projectRoot) {
   // 1. Session Config typecheck-command
@@ -81,8 +82,8 @@ async function resolveTypecheckCommand(projectRoot) {
     const config = parseSessionConfig(md);
     const cmd = config['typecheck-command'];
     if (cmd && typeof cmd === 'string') {
-      const parts = cmd.trim().split(/\s+/);
-      return { cmd: parts[0], args: parts.slice(1) };
+      const command = cmd.trim();
+      return command === 'skip' ? null : command || null;
     }
   } catch {
     // config unavailable — fall through
@@ -90,15 +91,16 @@ async function resolveTypecheckCommand(projectRoot) {
 
   // 2. tsgo
   const tsgoParts = _tryWhich('tsgo');
-  if (tsgoParts) return { cmd: tsgoParts, args: ['--noEmit'] };
+  if (tsgoParts) return 'tsgo --noEmit';
 
   // 3. tsc
   const tscParts = _tryWhich('tsc');
-  if (tscParts) return { cmd: tscParts, args: ['--noEmit'] };
+  if (tscParts) return 'tsc --noEmit';
 
-  // 4. npx tsc
-  const npxParts = _tryWhich('npx');
-  if (npxParts) return { cmd: npxParts, args: ['tsc', '--noEmit'] };
+  // 4. Only an installed project compiler; npx may install the unrelated
+  // npm package `tsc` in projects without TypeScript (#1612).
+  const localTsc = path.join(projectRoot, 'node_modules', 'typescript', 'bin', 'tsc');
+  if (existsSync(localTsc)) return [process.execPath, localTsc, '--noEmit'];
 
   return null;
 }
@@ -111,9 +113,11 @@ async function resolveTypecheckCommand(projectRoot) {
  * @returns {string|null}
  */
 function _tryWhich(name) {
-  const whichCmd = process.platform === 'win32' ? 'where' : 'which';
+  const whichCmd = process.platform === 'win32' ? 'where.exe' : 'which';
+  // Two lookups get at most 1s total; revisit together with the outer
+  // 5s hook budget if a host needs slower executable discovery.
   try {
-    const result = spawnSync(whichCmd, [name], { encoding: 'utf8', timeout: 2000 });
+    const result = spawnSync(whichCmd, [name], { encoding: 'utf8', timeout: 500 });
     if (result.status === 0 && result.stdout.trim()) return name;
   } catch {
     // ignore
@@ -122,43 +126,32 @@ function _tryWhich(name) {
 }
 
 /**
- * Run the typecheck command with a 2s AbortController timeout.
- *
- * @param {string} cmd
- * @param {string[]} args
- * @returns {{status: 'pass'|'fail', duration_ms: number, reason?: string}}
+ * Configured commands retain shell semantics; the local compiler uses Node argv.
+ * Keep cleanup short for hooks.json's 5s budget; Windows skips CIM verification.
+ * @param {string|string[]} cmd
+ * @param {string} projectRoot
+ * @returns {Promise<{status: 'pass'|'fail'|'timeout', duration_ms: number, reason?: string}>}
  */
-function runTypecheck(cmd, args) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), 2000);
-
-  const start = performance.now();
-  let spawnResult;
-  try {
-    spawnResult = spawnSync(cmd, args, {
-      signal: controller.signal,
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'pipe'],
-      timeout: 2000,
-    });
-  } finally {
-    clearTimeout(timer);
-  }
-
-  const duration_ms = Math.max(0, Math.round(performance.now() - start));
-
-  // AbortError or SIGTERM from timeout
-  if (spawnResult.error?.name === 'AbortError' || spawnResult.signal === 'SIGTERM') {
-    return { status: 'fail', duration_ms, reason: 'typecheck timed out after 2s' };
+async function runTypecheck(cmd, projectRoot) {
+  const result = await spawnInGroup(cmd, {
+    cwd: projectRoot,
+    timeoutMs: 2000,
+    // Hook-specific ceiling: escalate quickly so an uncooperative compiler
+    // cannot consume the outer 5s hook budget. Revisit if compiler cleanup
+    // needs more than 100ms; the hook's outer budget must change with it.
+    killGraceMs: 100,
+    verifyWaitMs: 100,
+    // Two PowerShell startups would exceed the remaining hook budget (R1-04).
+    verifyTree: false,
+  });
+  const duration_ms = Math.max(0, Math.round(result.durationMs));
+  if (result.timedOut) {
+    return { status: 'timeout', duration_ms, reason: 'typecheck timed out after 2s' };
   }
-
-  if (spawnResult.status !== 0) {
-    // Capture the first non-empty line of stderr/stdout as a compact reason.
-    const combined = ((spawnResult.stderr ?? '') + (spawnResult.stdout ?? '')).trim();
-    const firstLine = combined.split('\n').find((l) => l.trim()) ?? 'typecheck exited non-zero';
+  if (result.exitCode !== 0) {
+    const firstLine = result.fullOutput.split('\n').find((line) => line.trim()) ?? 'typecheck exited non-zero';
     return { status: 'fail', duration_ms, reason: firstLine.slice(0, 256) };
   }
-
   return { status: 'pass', duration_ms };
 }
 
@@ -216,7 +209,7 @@ async function main() {
   }
 
   // G7: run typecheck with 2s timeout (REQ-02)
-  const { status, duration_ms, reason } = runTypecheck(tc.cmd, tc.args);
+  const { status, duration_ms, reason } = await runTypecheck(tc, projectRoot);
 
   // G8: emit JSONL result to stderr
   const remediation =