session-orchestrator 5.11.0 → 5.13.0

package/hooks/_lib/lock-bootstrap.mjs

@@ -35,8 +35,10 @@
  */
 
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { writeJsonAtomicSync } from '../../scripts/lib/io.mjs';
+import { readNavigatorLease } from '../../scripts/lib/fleet-protocol.mjs';
 
 /**
  * Native SessionStart `source` values that are a RE-ENTRY into the same logical
@@ -55,6 +57,184 @@ import { writeJsonAtomicSync } from '../../scripts/lib/io.mjs';
  */
 export const SAME_LOGICAL_SESSION_SOURCES = new Set(['resume', 'clear', 'compact']);
 
+/**
+ * Native `source` values on which a fleet lead's lease keeps this session out
+ * of the MAIN checkout (#1635). A subset of SAME_LOGICAL_SESSION_SOURCES:
+ * `compact` keeps the lock it already holds, `startup` stays untouched. A
+ * session that yielded holds none: the yield leaves a #1651 release marker, so
+ * its later `compact` stays lockless too (#1747).
+ *
+ * @type {ReadonlySet<string>}
+ */
+const LEAD_YIELD_SOURCES = new Set(['clear', 'resume']);
+
+/**
+ * Native `source` values on which a lock this same raw session released on
+ * purpose stays released (#1651). A subset of SAME_LOGICAL_SESSION_SOURCES:
+ * `clear` starts new work and takes a lock as before, `startup` too.
+ *
+ * @type {ReadonlySet<string>}
+ */
+const RELEASED_LOCK_STAYS_RELEASED_SOURCES = new Set(['resume', 'compact']);
+
+/**
+ * #1651 — true when `sessionId` left a release marker in this repo. Never
+ * throws: a missing module or any error reads as "no marker" (the pre-#1651
+ * acquire path).
+ *
+ * @param {string} repoRoot
+ * @param {string} sessionId
+ * @returns {Promise<boolean>}
+ */
+async function hasOwnReleaseMarker(repoRoot, sessionId) {
+  try {
+    const { hasReleaseMarker } = await import('../../scripts/lib/session-lock.mjs');
+    return hasReleaseMarker({ repoRoot, sessionId }) === true;
+  } catch {
+    return false;
+  }
+}
+
+/** #1747 — `reason` of a release marker the lead yield writes. */
+const LEAD_YIELD_REASON = 'lead-yield';
+
+/**
+ * #1747 — the #1651 marker body for `sessionId`, or null. Never throws.
+ *
+ * @param {string} repoRoot
+ * @param {string} sessionId
+ * @returns {Promise<object|null>}
+ */
+async function readOwnReleaseMarker(repoRoot, sessionId) {
+  try {
+    const { readReleaseMarker } = await import('../../scripts/lib/session-lock.mjs');
+    return readReleaseMarker({ repoRoot, sessionId });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * #1747 — a lead yield is a release too: leave the #1651 marker for `sessionId`,
+ * tagged `reason: 'lead-yield'`, so a later `compact` or `resume` of this same
+ * session stays lockless while the lead's lease is active (compact is no yield
+ * source, and without the marker it took the free lock). Once the lease is
+ * gone, re-entry acquires and acquire() removes the marker as before. Never
+ * throws; a failed write is one stderr WARN and leaves the pre-#1747 behaviour.
+ *
+ * A marker that is already there and was not written by a yield stays as it is:
+ * without `reason` it is an explicit release (release-session-lock.mjs), which
+ * keeps its #1651 behaviour after the lease ends. Rewriting it as `lead-yield`
+ * made the next compaction after the lease take the lock back (review of !244,
+ * M1). An unreadable marker is kept for the same reason: the branch below
+ * already reads it as explicit.
+ *
+ * @param {string} repoRoot
+ * @param {string} sessionId
+ * @returns {Promise<void>}
+ */
+async function writeOwnReleaseMarker(repoRoot, sessionId) {
+  if (await hasOwnReleaseMarker(repoRoot, sessionId)) {
+    const existing = await readOwnReleaseMarker(repoRoot, sessionId);
+    if (existing?.reason !== LEAD_YIELD_REASON) return;
+  }
+  let reason;
+  try {
+    const { writeReleaseMarker } = await import('../../scripts/lib/session-lock.mjs');
+    const result = writeReleaseMarker({ repoRoot, sessionId, reason: LEAD_YIELD_REASON });
+    if (result?.ok !== true) reason = result?.reason ?? 'unknown';
+  } catch (err) {
+    reason = err?.message ?? 'unknown';
+  }
+  if (reason !== undefined) {
+    process.stderr.write(
+      `⚠ lock-bootstrap: no release marker after the lead yield (${reason}) — a compaction may take the lock again\n`,
+    );
+  }
+}
+
+/**
+ * #1641 — the Claude Code process id this hook runs under, or null. The value
+ * comes from `CLAUDE_PID`, but it counts ONLY when that process is this hook's
+ * direct parent: the variable is inherited by everything a Claude session
+ * starts, so a Codex child launched from a session's Bash would otherwise carry
+ * the parent's pid into its own SessionStart (`hooks-codex.json` matches
+ * resume|clear|compact) and take over the parent's LIVE lock (REFUTE review,
+ * reproduced against the real acquire/forceAcquire).
+ *
+ * Measured 2026-10-15 (claude 2.1.300, macOS): a SessionStart hook launched as
+ * `sh run-node.sh <hook>` runs node with `process.ppid === CLAUDE_PID` and the
+ * parent's comm `claude` — both shells exec. A Codex hook's parent is Codex or
+ * its shell, never Claude, so it reads null here. Depth 1, deliberately: a
+ * depth-2 walk would admit a hook whose parent is a Codex process that bash
+ * exec'd straight under Claude. Spawn-free.
+ *
+ * #1717: Claude runs each hook as `/bin/sh -c "<command>"`. On Linux/WSL
+ * /bin/sh is dash, and the WSL dash 0.5.12 FORKS a single `-c` command
+ * instead of exec'ing it, so node's parent was that intermediate sh and this
+ * read null on every hook (measured 2026-10-21 on win-wsl, 3/3 runs; with an
+ * `exec ` prefix the ppid matched). Every run-node.sh command in
+ * `hooks/hooks.json` therefore starts with `exec sh …`; run-node.sh itself
+ * execs node on every branch, so both hops are exec and depth 1 holds.
+ * The other manifests (hooks-codex/-cursor/-pi.json) deliberately keep the
+ * plain form: only a Claude hook can match its own CLAUDE_PID, so the prefix
+ * would buy nothing there (their parent is that harness either way).
+ * Measured 2026-10-21 on macOS: /bin/sh (bash 3.2) and /bin/dash (dash-16)
+ * both match ppid with AND without `exec`, and exit status 2, stderr and stdin
+ * pass through unchanged in both forms — the prefix costs nothing there.
+ * Ceiling (BV-004): a harness whose launcher is not `/bin/sh -c` (or that
+ * wraps the command in a further shell) still reads null and keeps the
+ * pre-#1641 behaviour (fail-closed). Revisit if `reclaimed: own-process`
+ * never appears on a host where /clear without SessionEnd does.
+ *
+ * The process survives `/clear` while the raw session id is minted anew, so
+ * this is the witness of "the same terminal session" that the label and the
+ * raw id cannot give.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {number} [ppid] — this process' parent pid (DI for tests).
+ * @returns {number|null}
+ */
+export function readClaudePid(env = process.env, ppid = process.ppid) {
+  const raw = typeof env?.CLAUDE_PID === 'string' ? env.CLAUDE_PID.trim() : '';
+  if (!/^[1-9][0-9]{0,9}$/.test(raw)) return null;
+  const pid = Number(raw);
+  return Number.isSafeInteger(pid) && pid === ppid ? pid : null;
+}
+
+/**
+ * #1641 — true when `lock` was written under the Claude Code process this hook
+ * runs under, on this host. Only then may a lock with a DIFFERENT raw id count
+ * as our own predecessor (startup → /clear mints a new raw id in the same
+ * process). #1746 judges the `claude_pid`/`host` pair current-session.json
+ * carries with this same predicate, so both witnesses mean the same thing.
+ *
+ * Why the pid alone is enough, without a start time: both sides come from
+ * readClaudePid(), which admits a pid only as the writer hook's DIRECT parent.
+ * So the lock's pid names the Claude process that wrote it, and equal to ours
+ * it names either this process or a dead one whose pid the OS recycled to us —
+ * not another live Claude process in the same pid namespace.
+ * The host check keeps a lock on a shared filesystem from another machine out.
+ * Ceilings (BV-004), named rather than claimed closed: (1) two pid namespaces
+ * that report the same hostname (WSL2 distros, a container and its host on one
+ * checkout) can hold equal pids; (2) an in-process agent team whose teammates
+ * each ran SessionStart under one Claude process (measured: subagents fire no
+ * SessionStart). Revisit when either shape works in a shared checkout.
+ *
+ * @param {object|null} lock
+ * @param {number|null} claudePid — from readClaudePid().
+ * @returns {Promise<boolean>}
+ */
+async function isSameClaudeProcess(lock, claudePid) {
+  if (typeof claudePid !== 'number' || !lock || lock.claude_pid !== claudePid) return false;
+  try {
+    const { hostnamesMatch, lockHostCandidate } = await import('../../scripts/lib/host-identity.mjs');
+    return hostnamesMatch(lockHostCandidate(lock), os.hostname());
+  } catch {
+    return false;
+  }
+}
+
 /** Re-reads of a just-acquired lock that answers ENOENT, and the pause between them (#1494). */
 const ENRICH_READ_RETRIES = 5;
 const ENRICH_READ_RETRY_MS = 10;
@@ -81,14 +261,34 @@ const ENRICH_READ_RETRY_MS = 10;
  *   Only consulted for the same-logical-session force-refresh below; every
  *   existing caller that omits it keeps its pre-#1091 behaviour exactly.
  * @param {string|null} [opts.predecessorSessionId=null] — the raw `session_id`
- *   recorded in `.orchestrator/current-session.json` by our OWN previous run of
- *   this hook. It is the third, load-bearing conjunct of the re-entry
+ *   the last session start in this checkout recorded in
+ *   `.orchestrator/current-session.json` — our own previous run of this hook
+ *   unless a peer started here since (every start rewrites the file, #1746).
+ *   It is the third, load-bearing conjunct of the re-entry
  *   force-refresh below: without it a same-host semantic-label collision (#1066)
  *   lets one session take over a live peer's lock. Omitting it (the default)
  *   disables the re-entry force-refresh entirely — fail-closed.
+ * @param {{ claude_pid?: unknown, host?: unknown }|null} [opts.predecessorProcess=null]
+ *   — the `claude_pid`/`host` pair the writer of that `current-session.json`
+ *   recorded (#1746), unvalidated. The #1635 lead yield takes
+ *   `predecessorSessionId` for our own predecessor only when this pair names
+ *   our own Claude Code process (isSameClaudeProcess); null or any mismatch
+ *   yields.
+ * @param {number|null} [opts.claudePid=null] — the Claude Code process id from
+ *   readClaudePid() (#1641). Stamped on the lock as `claude_pid`; a lock that
+ *   carries this same pid on this host is our own predecessor after /clear, for
+ *   the re-entry force-refresh AND the #1635 lead-yield release. Null (Codex,
+ *   Cursor, tests that omit it) leaves both exactly as before.
  * @param {Function} [opts._acquireImpl] — DI for tests (defaults to importing acquire from session-lock.mjs).
  * @param {Function} [opts._forceAcquireImpl] — DI for tests (defaults to importing forceAcquire from session-lock.mjs).
  * @param {Function} [opts._emitEventImpl] — DI for tests (defaults to importing emitEvent from events.mjs).
+ * @param {(context: string, banner: string) => void} [opts.onNotice] — receives
+ *   the model notice and the operator banner line when the lock is deliberately
+ *   NOT taken because a fleet lead holds the main checkout (#1635), or because
+ *   this raw id released its lock on purpose and the source is `resume` /
+ *   `compact` (#1651).
+ * @param {Function} [opts._readLeaseImpl] — DI for tests (defaults to readNavigatorLease from fleet-protocol.mjs).
+ * @param {Function} [opts._releaseImpl] — DI for tests (defaults to release from session-lock.mjs).
  * @returns {Promise<object|null>} the enriched v2 lock body on success, null on any failure.
  */
 export async function bootstrapLock({
@@ -99,15 +299,92 @@ export async function bootstrapLock({
   ttlHours = 4,
   nativeSource = null,
   predecessorSessionId = null,
+  predecessorProcess = null,
+  claudePid = null,
   _acquireImpl,
   _forceAcquireImpl,
   _emitEventImpl,
+  onNotice,
+  _readLeaseImpl = readNavigatorLease,
+  _releaseImpl,
 } = {}) {
   // Sanity-check required inputs. Anything missing → bail silently.
   if (typeof repoRoot !== 'string' || repoRoot.length === 0) return null;
   if (typeof sessionId !== 'string' || sessionId.length === 0) return null;
   if (typeof mode !== 'string' || mode.length === 0) return null;
 
+  // #1635: after /clear or resume in the MAIN checkout, a lead's active lease
+  // means the lead runs headless jobs here — our lock would make its slot check
+  // report the repo as occupied. Yield instead of acquiring, and give back a
+  // lock this same raw id already holds here.
+  const leadHolder = await leadHoldingMainCheckout({
+    repoRoot,
+    sessionId,
+    predecessorSessionId,
+    predecessorProcess,
+    claudePid,
+    nativeSource,
+    readLease: _readLeaseImpl,
+  });
+  if (leadHolder !== null) {
+    // Released: a lock with our own raw id (a resume where the harness kept the
+    // id), or one written under our own Claude Code process (#1641 — startup →
+    // /clear mints a new raw id in the same process). Never a lock whose only
+    // "it was us" witness is current-session.json: every session start in this
+    // checkout rewrites that file, so a peer's /clear or resume would release a
+    // LIVE foreign lock. A predecessor from before #1641 carries no
+    // `claude_pid` and still stays until its TTL.
+    await releaseOwnLockForLead({ repoRoot, sessionId, claudePid, releaseImpl: _releaseImpl });
+    await writeOwnReleaseMarker(repoRoot, sessionId);
+    if (typeof onNotice === 'function') {
+      // The lease reader admits only [A-Za-z0-9._-] ids, so the id is banner-safe.
+      const sid8 = leadHolder.slice(0, 8);
+      try {
+        onNotice(
+          `Haupt-Checkout belegt durch Lead ${sid8}, arbeite im Worktree`,
+          `🧭 Haupt-Checkout belegt durch Lead ${sid8} — kein Session-Lock, arbeite im Worktree`,
+        );
+      } catch { /* the notice is informational */ }
+    }
+    return null;
+  }
+
+  // #1651: this raw session gave its lock back on purpose
+  // (scripts/release-session-lock.mjs), typically so a headless run can use
+  // the slot. A compaction or resume of that same session is not new work and
+  // must not take the lock again; startup and clear acquire as before. The
+  // marker is removed by the session's next deliberate acquire().
+  // #1747: a marker the lead yield above wrote counts only while a lead lease
+  // is still active; once the lead is gone the session acquires again.
+  if (
+    typeof nativeSource === 'string' &&
+    RELEASED_LOCK_STAYS_RELEASED_SOURCES.has(nativeSource) &&
+    (await hasOwnReleaseMarker(repoRoot, sessionId))
+  ) {
+    const marker = await readOwnReleaseMarker(repoRoot, sessionId);
+    const yielded = marker?.reason === LEAD_YIELD_REASON;
+    const leadId = yielded ? await activeLeadSessionId(_readLeaseImpl) : null;
+    if (!yielded || leadId !== null) {
+      if (typeof onNotice === 'function') {
+        try {
+          if (yielded) {
+            const sid8 = leadId.slice(0, 8);
+            onNotice(
+              `Haupt-Checkout belegt durch Lead ${sid8}, arbeite im Worktree`,
+              `🧭 Haupt-Checkout belegt durch Lead ${sid8} — kein Session-Lock, arbeite im Worktree`,
+            );
+          } else {
+            onNotice(
+              'Session-Lock wurde in dieser Session bewusst freigegeben und nach dem Neueinstieg nicht neu angelegt',
+              'ℹ Session-Lock bewusst freigegeben — nach dem Neueinstieg nicht neu angelegt',
+            );
+          }
+        } catch { /* the notice is informational */ }
+      }
+      return null;
+    }
+  }
+
   // Resolve DI shims at call time so test mocks can replace the imports.
   let acquireFn = _acquireImpl;
   let forceAcquireFn = _forceAcquireImpl;
@@ -181,10 +458,23 @@ export async function bootstrapLock({
   // live lock, conjunct (c) holds for the wrong session. `current-session.json`
   // carries no session field of its own (see
   // `.claude/rules/identity-and-locks.md` § shared repo artefacts), which is
-  // exactly why this is a ceiling and not a proof. Revisit when the lock or
-  // current-session.json carries a durable logical-session id of its own.
+  // exactly why this is a ceiling and not a proof.
+  //
+  // #1641 — (b) never holds after /clear: resolveSessionId() mints the label
+  // anew as maxN+1, because the predecessor's own lock is counted (measured
+  // 2026-10-15: lock `…-session-1`, new label `…-session-2`). The process-bound
+  // alternative replaces (b)+(c) with ONE witness the lock itself carries:
+  // `claude_pid` equal to the Claude Code process this hook runs under, on this
+  // host (isSameClaudeProcess). It needs no repo-global artefact, so the
+  // ceiling above does not apply to it. (a) still gates it.
   const isSameLogicalReentry =
     typeof nativeSource === 'string' && SAME_LOGICAL_SESSION_SOURCES.has(nativeSource);
+  const ownProcessPredecessor =
+    acquireResult.ok !== true &&
+    acquireResult.reason === 'active' &&
+    isSameLogicalReentry &&
+    acquireResult.existingLock?.session_id !== sessionId &&
+    (await isSameClaudeProcess(acquireResult.existingLock, claudePid));
 
   const shouldForce =
     acquireResult.ok !== true && (
@@ -200,6 +490,7 @@ export async function bootstrapLock({
       // which this predicate could never force: one damaged file wedged every
       // new session in the repo.
       acquireResult.reason === 'corrupt' ||
+      ownProcessPredecessor ||
       (acquireResult.reason === 'active' &&
         acquireResult.existingLock &&
         (acquireResult.existingLock.session_id === sessionId ||
@@ -238,6 +529,9 @@ export async function bootstrapLock({
       (forcedFrom === 'corrupt' || (forcedFrom === 'stale-heartbeat' && priorOwner !== sessionId))
     ) {
       reclaimed = forcedFrom;
+    } else if (acquireResult?.ok === true && ownProcessPredecessor) {
+      // #1641: countable, so the rate of /clear takeovers can be measured.
+      reclaimed = 'own-process';
     }
     if (reclaimingCorrupt) {
       // The file's content is not echoed: it is unbounded and may be anything.
@@ -348,6 +642,10 @@ export async function bootstrapLock({
       typeof semanticSessionId === 'string' && semanticSessionId.length > 0
         ? semanticSessionId
         : (typeof baseLock.session_id === 'string' ? baseLock.session_id : sessionId),
+    // #1641: the process-bound witness a later /clear in this same process
+    // recognises its predecessor by (isSameClaudeProcess). Absent, not null,
+    // when the harness sets no CLAUDE_PID.
+    ...(typeof claudePid === 'number' ? { claude_pid: claudePid } : {}),
   };
 
   {
@@ -383,6 +681,15 @@ export async function bootstrapLock({
   } catch { /* best-effort — a missing proof never breaks session-start */ }
 
   // Step 3: best-effort observability breadcrumb.
+  // #1636 Pkt 2: a live peer that works here while its lock sits in another
+  // checkout is invisible to acquire(); record it (true/false/null) so its rate
+  // is measured before any conflict banner exists. Absent only if the reader
+  // itself cannot be loaded.
+  let foreignWorkRoot;
+  try {
+    const { foreignWorkRootIn } = await import('./hook-root.mjs');
+    foreignWorkRoot = foreignWorkRootIn(repoRoot, sessionId);
+  } catch { /* the measurement is best-effort */ }
   await emitBestEffort(_emitEventImpl, 'orchestrator.session.lock.acquired', {
     session_id: enriched.session_id,
     semantic_session_id: enriched.semantic_session_id,
@@ -391,11 +698,134 @@ export async function bootstrapLock({
     host: enriched.host,
     ttl_hours: enriched.ttl_hours,
     ...(reclaimed ? { reclaimed } : {}),
+    ...(foreignWorkRoot !== undefined ? { foreign_work_root: foreignWorkRoot } : {}),
   });
 
   return enriched;
 }
 
+/**
+ * #1635 — on a lead yield, release the main checkout's lock IFF it carries our
+ * own raw `session_id`, or was written under our own Claude Code process on this
+ * host (#1641, isSameClaudeProcess); any other lock is never touched. The delete
+ * goes through session-lock.mjs `release()` under the LOCK's raw id with the
+ * repo's persisted owner proof, so release() re-checks both the id and the proof
+ * itself. Never throws; a failed release is one stderr WARN and changes nothing
+ * else — the caller still skips the acquire.
+ *
+ * @param {{ repoRoot: string, sessionId: string, claudePid?: number|null, releaseImpl?: Function }} args
+ * @returns {Promise<void>}
+ */
+async function releaseOwnLockForLead({ repoRoot, sessionId, claudePid = null, releaseImpl }) {
+  let reason = null;
+  try {
+    const lockMod = await import('../../scripts/lib/session-lock.mjs');
+    const existing = lockMod.readLock({ repoRoot });
+    if (!existing || typeof existing.session_id !== 'string') return;
+    if (existing.session_id !== sessionId && !(await isSameClaudeProcess(existing, claudePid))) return;
+    const result = (releaseImpl ?? lockMod.release)({
+      sessionId: existing.session_id,
+      repoRoot,
+      proof: lockMod.loadOwnerProof({ repoRoot }),
+    });
+    if (!result || result.ok !== true) reason = result?.reason ?? 'unknown';
+    else if (result.deleted !== true) reason = result.reason ?? 'not-deleted';
+    else if (result.verified === false) reason = 'lock-still-present';
+  } catch (err) {
+    reason = err?.message ?? 'unknown';
+  }
+  if (reason !== null) {
+    process.stderr.write(
+      `⚠ lock-bootstrap: own session.lock could not be released for the fleet lead (${reason}) — it blocks the lead until its TTL\n`,
+    );
+  }
+}
+
+/**
+ * #1635 — the session id of a fleet lead whose ACTIVE lease keeps this session
+ * out of the main checkout, or null when the lock is taken as before.
+ *
+ * Non-null only when ALL hold: `nativeSource` is clear/resume; `repoRoot/.git`
+ * is a directory (the main worktree — a linked worktree or submodule has a
+ * `.git` FILE, no subprocess needed); `repoRoot/.orchestrator/runtime/fleet`
+ * is a directory (the lease is HOST-global, this marks the repos the fleet
+ * works in); the lease reads `active`; and its `session_id` is neither our
+ * raw id nor our predecessor's (the lead's own tab after /clear has a new raw
+ * id while the lease still carries the old one — it keeps the old behaviour).
+ *
+ * #1746 — "our predecessor's" needs a process witness. `predecessorSessionId`
+ * comes from current-session.json, which every session start in this checkout
+ * rewrites: once the lead started here LAST, its raw id was every other tab's
+ * "predecessor", and their /clear took the lock (LSO #778, twice on
+ * 2026-10-22). The id counts only when `predecessorProcess` names our own
+ * Claude Code process on this host (isSameClaudeProcess, the #1641 witness).
+ * Cost, accepted: the lead's own tab now also yields when the entry carries no
+ * witness — no readable CLAUDE_PID (Codex, Cursor) or a file written before
+ * #1746. Harmless: the lead works through its lease, not this lock. (When
+ * another session started in between, the tab yielded before #1746 already:
+ * the file then names that session.)
+ * Ceiling (BV-004): a dead lead process whose pid the OS recycled to our
+ * Claude process still reads as "ours" (the same residual isSameClaudeProcess
+ * names) and takes the lock as before #1746.
+ *
+ * Fail direction: every other outcome — no lease (no fleet: silent), an
+ * expired lease, an unreadable one (one stderr WARN), any exception — returns
+ * null, i.e. the pre-#1635 acquire path. It never blocks the session.
+ *
+ * @param {{ repoRoot: string, sessionId: string, predecessorSessionId: string|null, predecessorProcess: object|null, claudePid: number|null, nativeSource: string|null, readLease: Function }} args
+ * @returns {Promise<string|null>}
+ */
+async function leadHoldingMainCheckout({ repoRoot, sessionId, predecessorSessionId, predecessorProcess, claudePid, nativeSource, readLease }) {
+  try {
+    if (typeof nativeSource !== 'string' || !LEAD_YIELD_SOURCES.has(nativeSource)) return null;
+    if (!isDirectory(path.join(repoRoot, '.git'))) return null;
+    if (!isDirectory(path.join(repoRoot, '.orchestrator', 'runtime', 'fleet'))) return null;
+    const verdict = await readLease();
+    if (verdict?.state === 'unreadable') {
+      process.stderr.write(
+        `⚠ lock-bootstrap: navigator lease unreadable (${verdict.reason ?? 'unknown'}) — lead occupancy not measurable, taking the lock as before\n`,
+      );
+      return null;
+    }
+    if (verdict?.state !== 'active') return null;
+    const leadId = verdict.lease?.session_id;
+    if (typeof leadId !== 'string' || leadId.length === 0) return null;
+    if (leadId === sessionId) return null;
+    if (leadId === predecessorSessionId && (await isSameClaudeProcess(predecessorProcess, claudePid))) return null;
+    return leadId;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * #1747 — the session id of an ACTIVE fleet-lead lease, or null for every
+ * other outcome (none, expired, unreadable, a throwing reader). The marker
+ * was written only in the main checkout under a foreign lead, so the lease
+ * alone decides here. Never throws.
+ *
+ * @param {Function} readLease
+ * @returns {Promise<string|null>}
+ */
+async function activeLeadSessionId(readLease) {
+  try {
+    const verdict = await readLease();
+    const leadId = verdict?.state === 'active' ? verdict.lease?.session_id : null;
+    return typeof leadId === 'string' && leadId.length > 0 ? leadId : null;
+  } catch {
+    return null;
+  }
+}
+
+/** True when `p` is a directory itself (lstat: a symlink does not count). Never throws. */
+function isDirectory(p) {
+  try {
+    return fs.lstatSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Emit one event; every failure is swallowed so a missing events module never
  * breaks the hook (observability is best-effort).

package/hooks/_lib/orchestrator-ignore.mjs

@@ -52,6 +52,9 @@ export const GENERATED_IGNORE = [
   '!*/',
   '!/bootstrap.lock',
   '!/metrics/learnings.jsonl',
+  // #1516: the inbox-role store and its receipts travel with learnings.jsonl.
+  '!/metrics/learnings-inbox.jsonl',
+  '!/metrics/learnings-inbox-ingested.jsonl',
   '!/metrics/sessions.jsonl',
   '!/metrics/README.md',
   '!/policy/quality-gates.json',

package/hooks/_lib/subagent-transcript.mjs

@@ -27,7 +27,7 @@
  *      claim, with an `occurrences` count (#1198: the fleet's worst repo held
  *      3,360 records over 205 distinct `claim_text` values = duplication
  *      factor 16.4, measured 2026-09-06 over
- *      `extern/aiat-barrierefrei-engine/.orchestrator/metrics/events.jsonl`).
+ *      a consumer repo's `.orchestrator/metrics/events.jsonl`).
  *
  * @module hooks/_lib/subagent-transcript
  */
@@ -495,7 +495,7 @@ const MAX_OBSERVATIONS = 50;
  * of them was measured as a live false-positive class.
  *
  * Measured 2026-09-06 over the 205 DISTINCT `claim_text` values in
- * `~/Projects/extern/aiat-barrierefrei-engine/.orchestrator/metrics/events.jsonl`
+ * a consumer repo's `.orchestrator/metrics/events.jsonl`
  * (the fleet's worst-affected repo; command in the module test header):
  * 201/205 re-fire on the pre-#1218 matcher, of which 35 are markdown table
  * rows and 9 are ATX headings — 44 firings, 21.9% of the corpus, with a true

package/hooks/_lib/vcs-create-matcher.mjs

@@ -88,11 +88,11 @@
  * ## Named ceilings (BV-004)
  *
  *   - A create call reached only through a command substitution
- *     (`x=$(glab issue create …)`) is NOT matched: the substitution body never
- *     becomes a segment of its own. Unchanged since before #1106. Likewise a
- *     create carried as an interpreter PAYLOAD (`bash -c 'glab issue create'`)
- *     — `resolveSegmentVerb` reports the payload string, but this matcher does
- *     not recurse into it. Revisit either if the shape shows up in the overflow
+ *     (`x=$(glab issue create …)`) IS matched since #1667: the shared lexer
+ *     hoists the substitution body into a segment of its own. A create carried
+ *     as an interpreter PAYLOAD (`bash -c 'glab issue create'`) is still NOT
+ *     matched — `resolveSegmentVerb` reports the payload string, but this
+ *     matcher does not recurse into it. Revisit if the shape shows up in the overflow
  *     triage of a per-session counter file
  *     (`.orchestrator/runtime/issue-budget/<hash>.json`, #1141) or in a
  *     transcript census of real create calls.
@@ -115,11 +115,10 @@
  *     `hooks/pre-bash-issue-budget.mjs` treats it exactly like a loop body —
  *     deny in `strict`, report the undercount in `warn`. The remaining ceiling
  *     is the option grammar, named at {@link xargsDrivenRemainder}.
- *   - A paren glued to the verb (`(glab issue create …)`) is not reached: it
- *     lexes as the single word `(glab`. This is `command-blocker.mjs`'s own
- *     named ceiling on `COMMAND_POSITION_KEYWORDS` (#1145), inherited here
- *     rather than re-patched — peeling the paren belongs in the lexer, whose
- *     tokens five consumers read positionally.
+ *   - A subshell paren before the verb (`(glab issue create …)`) IS reached
+ *     since #1667: the lexer turns an unquoted word-initial `(` and its `)`
+ *     into statement breaks — the fix landed in the lexer, as this ceiling
+ *     asked, not as a re-patch here.
  *   - {@link matchesBypass} still compares from token index 0, NOT from the
  *     resolved verb index. So a wrapped create (`nohup gh pr create --dry-run`)
  *     is gated even when `gh pr create --dry-run` is a bypass entry. That is
@@ -514,9 +513,10 @@ const CAT_SUBST_RE = /^\$\(cat\s+(\S+)\)$/;
 /**
  * Read the value of a flag in `names` (`--x v`, `--x=v`, `-x v`). When the flag
  * repeats, the LAST value wins — the pflag semantics `gh`/`glab` apply.
- * An UNQUOTED `$(cat p)` is split by the lexer into `$(cat` + `p)`; that pair is
- * rejoined so the substitution survives, in both the `--x $(cat p)` and the
- * `--x=$(cat p)` spelling.
+ * An UNQUOTED `$(cat p)` reaches this function as ONE token: since #1667 the
+ * lexer keeps a substitution's raw text in the outer word (and hoists its body
+ * as a statement of its own), so `--x $(cat p)` and `--x=$(cat p)` need no
+ * rejoining.
  *
  * @param {Array<{ text: string, quoted: boolean }>} tokens
  * @param {string[]} names
@@ -537,10 +537,6 @@ function flagValue(tokens, names) {
       } else {
         continue;
       }
-      if (value === '$(cat' && typeof tokens[i + 1]?.text === 'string') {
-        value = `$(cat ${tokens[i + 1].text}`;
-        i += 1;
-      }
       found = value;
       break;
     }

package/hooks/cwd-change-restore.mjs

@@ -31,6 +31,7 @@ import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 
 import { getProjectDir } from '../scripts/lib/platform.mjs';
 import { atomicMutateJson } from './_lib/atomic-json.mjs';
+import { resolveOwnLockRoot } from './_lib/hook-root.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -88,7 +89,10 @@ async function main() {
     new_cwd: newCwd,
   };
 
-  const sessionFile = path.join(getProjectDir(), '.orchestrator', 'current-session.json');
+  // #1605 B5 — annotate THIS session's current-session.json where
+  // on-session-start.mjs put it (the entered worktree after a /clear there),
+  // found by the lock carrying the raw payload id; launch dir otherwise.
+  const sessionFile = path.join(resolveOwnLockRoot(input, getProjectDir()), '.orchestrator', 'current-session.json');
 
   const result = await atomicMutateJson(sessionFile, {}, (current) => {
     const existing = Array.isArray(current.cwd_changes)

package/hooks/enforce-commands.mjs

@@ -317,9 +317,10 @@ async function main() {
   // (#1194).
   //
   // CEILING (BV-004): on a harness that exports no session env var and puts no
-  // `session_id` in the hook payload (Codex CLI, Cursor today) both tiers are
-  // empty, so this gate is permanently `'unknown'` = enforce = pre-#1153
-  // behaviour there. Revisit when those hook payloads carry a session id.
+  // `session_id` in the hook payload (Cursor today) both tiers are empty, so
+  // this gate is permanently `'unknown'` = enforce = pre-#1153 behaviour there.
+  // Codex CLI does send `session_id` (measured 2026-10-20, codex-cli 0.160.1,
+  // #1691), so a manifest bound to another id classifies `'foreign'` there.
   {
     // `ownIds` is the process-local set built above G3.
     const { verdict, manifestIds } = classifyManifestSession(scope, ownIds);