session-orchestrator 5.11.0 → 5.13.0

package/hooks/on-session-start.mjs

@@ -29,23 +29,26 @@
  */
 
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
-import { writeSync } from 'node:fs';
+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 } from '../scripts/lib/fleet-protocol.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.
@@ -817,15 +870,23 @@ async function main() {
   // null on its own error paths, which would silently re-open the nudge.
   const hostBannerEnabled = await isHostBannerEnabled(projectRoot);
   let bannerData = null;
+  // #1559: a git repository with no bootstrap.lock — neither at its toplevel
+  // nor under projectRoot (a bootstrapped sub-project) — has one first step,
+  // /bootstrap; /go and /close do not work before it. Judged at the toplevel
+  // too, so a session started in a subdirectory of a bootstrapped repo is not
+  // told to bootstrap again; outside a git repository there is nothing to set up.
+  const needsBootstrap = Boolean(topLevel)
+    && !existsSync(path.join(topLevel, '.orchestrator', 'bootstrap.lock'))
+    && !existsSync(path.join(projectRoot, '.orchestrator', 'bootstrap.lock'));
   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
-    // while the operator picks his moment), then derive-and-report from Session
-    // Config / STATE.md / git, and only then the tool. The banner carries the
-    // ORDER, not an absolute; full routing + exceptions in
-    // .claude/rules/ask-via-tool.md.
-    pushBanner('🎯 Decide: operator verb (/go) > derive+report > AUQ if blocking (.claude/rules/ask-via-tool.md).');
+    // AUQ-001 in plain words (#1559): name the command when nothing is
+    // blocked, read available answers from config / STATE.md / git, and ask
+    // only when blocked — then with the question tool, never as a prose list.
+    // Before bootstrap, the setup step replaces it as the first action.
+    pushBanner(needsBootstrap
+      ? 'ℹ New here? Start with /bootstrap — it sets up this repo for session-orchestrator.'
+      : '🎯 Next step: name the command (/go, /close) when nothing is blocked; read answers from config, STATE.md or git; when blocked, ask with the question tool, never as a prose list.');
   }
 
   // F1.3 cold-start abandonment fix (PRD 2026-05-21). Emit a one-shot
@@ -864,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 ??
@@ -897,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 */ }
 
@@ -965,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.
@@ -973,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.
@@ -996,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
@@ -1011,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` : '';
@@ -1040,7 +1130,8 @@ async function main() {
   // Gated like the peer lines above: no host banner → no navigator line. A read
   // failure must never block the hook — the helper is fail-closed itself, the
   // try/catch only guards against the unexpected.
-  if (bannerData) {
+  // #1559: solo users without fleet integration see no fleet line.
+  if (bannerData && fleetIntegrationEnabled()) {
     try {
       pushBanner(navigatorBannerLine(await readNavigatorLease()));
     } catch { /* swallow — hook must remain non-blocking */ }
@@ -1165,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
@@ -1186,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',
     })