session-orchestrator 5.3.0 → 5.5.0

package/hooks/_lib/lock-bootstrap.mjs

@@ -25,11 +25,11 @@
  *     ttl_hours:            number,
  *   }
  *
- * The current scripts/lib/session-lock.mjs (pre-I3) writes the v1 shape
- * (no last_heartbeat, no semantic_session_id). This helper layers v2 fields
- * on top via an atomic tmp+rename overwrite — when I3 ships its v2 schema,
- * this helper's overlay becomes a no-op (the field is already there) and
- * everything continues to work.
+ * scripts/lib/session-lock.mjs `buildLock()` has written `last_heartbeat`
+ * itself since Epic #583 W2-I3 (`last_heartbeat` = `started_at` at genesis).
+ * This helper's tmp+rename overlay therefore re-writes an identical
+ * `last_heartbeat`, and its remaining job is `semantic_session_id`, which
+ * `acquire()` / `forceAcquire()` are not given here.
  *
  * @module hooks/_lib/lock-bootstrap
  */
@@ -55,6 +55,10 @@ import { writeJsonAtomicSync } from '../../scripts/lib/io.mjs';
  */
 export const SAME_LOGICAL_SESSION_SOURCES = new Set(['resume', 'clear', 'compact']);
 
+/** 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;
+
 /**
  * Bootstrap the session.lock for this hook invocation.
  *
@@ -189,6 +193,13 @@ export async function bootstrapLock({
       // session-lock.mjs; matching only the new one keeps this force-branch
       // reachable.
       acquireResult.reason === 'stale-heartbeat' ||
+      // A lock file that is not a lock record (invalid JSON or not the lock
+      // shape) can never be a live lock — every writer writes atomically — so
+      // it is reclaimed like a stale one, with one stderr WARN below. Before
+      // acquire() reported 'corrupt' it answered 'active' / existingLock:null,
+      // which this predicate could never force: one damaged file wedged every
+      // new session in the repo.
+      acquireResult.reason === 'corrupt' ||
       (acquireResult.reason === 'active' &&
         acquireResult.existingLock &&
         (acquireResult.existingLock.session_id === sessionId ||
@@ -201,12 +212,41 @@ export async function bootstrapLock({
             acquireResult.existingLock.session_id === predecessorSessionId)))
     );
 
+  // Recorded on the acquired event below, so a takeover of a stale or corrupt
+  // lock is countable — its stderr WARN is discarded by the harness (#1401).
+  let reclaimed = null;
   if (!acquireResult.ok && shouldForce) {
+    const reclaimingCorrupt = acquireResult.reason === 'corrupt';
+    const forcedFrom = acquireResult.reason;
+    // A session resuming its OWN stale lock (same raw id after > ttl idle) is
+    // a refresh, not a takeover — counting it would inflate the very figure
+    // `reclaimed` exists to make countable.
+    const priorOwner = acquireResult.existingLock?.session_id;
     try {
-      acquireResult = forceAcquireFn({ sessionId, mode, ttlHours, repoRoot });
+      // A stale or corrupt lock is reclaimed single-winner (#1494): two starts
+      // that both saw it used to force it, both got ok:true, and the later
+      // rename won. With onlyIfNotLive the loser gets the winner's live lock
+      // back as 'active' and bails into the conflict signal below. The same-
+      // session refresh of a LIVE lock keeps the unconditional overwrite.
+      const reclaim = forcedFrom === 'stale-heartbeat' || forcedFrom === 'corrupt';
+      acquireResult = forceAcquireFn({ sessionId, mode, ttlHours, repoRoot, ...(reclaim ? { onlyIfNotLive: true } : {}) });
     } catch {
       return null;
     }
+    if (
+      acquireResult?.ok === true &&
+      (forcedFrom === 'corrupt' || (forcedFrom === 'stale-heartbeat' && priorOwner !== sessionId))
+    ) {
+      reclaimed = forcedFrom;
+    }
+    if (reclaimingCorrupt) {
+      // The file's content is not echoed: it is unbounded and may be anything.
+      process.stderr.write(
+        acquireResult && acquireResult.ok === true
+          ? '⚠ lock-bootstrap: .orchestrator/session.lock was not a valid lock record — reclaimed for this session\n'
+          : `⚠ lock-bootstrap: .orchestrator/session.lock is not a valid lock record and could not be reclaimed (${acquireResult?.reason ?? 'unknown'}) — this session runs without a lock\n`,
+      );
+    }
   }
 
   // Any other non-ok reason (parallel-conflict, fs-error, other-session-active)
@@ -221,6 +261,20 @@ export async function bootstrapLock({
   // failure is swallowed and the bail proceeds. The return contract is unchanged —
   // bootstrapLock STILL returns null on this path.
   if (!acquireResult || acquireResult.ok !== true) {
+    // #1494 / #599: a lock path that exists but cannot be read (EACCES, or a
+    // directory) is never reclaimed — but it is no longer silent either. The
+    // WARN is discarded by the harness, so the read_anomaly event (the one
+    // SessionEnd already emits for the same state) is the countable trace.
+    if (acquireResult && acquireResult.reason === 'unreadable') {
+      process.stderr.write(
+        `⚠ lock-bootstrap: .orchestrator/session.lock exists but cannot be read (${acquireResult.error ?? 'unknown'}) — this session runs without a lock\n`,
+      );
+      await emitBestEffort(_emitEventImpl, 'orchestrator.session.lock.read_anomaly', {
+        session_id: sessionId,
+        status: 'unreadable',
+        ...(typeof acquireResult.error === 'string' ? { error: acquireResult.error } : {}),
+      });
+    }
     if (
       acquireResult &&
       acquireResult.reason === 'active' &&
@@ -236,19 +290,46 @@ export async function bootstrapLock({
 
   // Step 2: enrich the lock with v2 fields (last_heartbeat + semantic_session_id).
   // We re-read the file fresh (acquire() just wrote it) and overlay the new
-  // fields, then atomically tmp+rename. When I3 lands and acquire() writes the
-  // v2 shape natively, this overlay becomes idempotent (already-present fields
-  // get overwritten with identical values).
+  // fields, then atomically tmp+rename. acquire() already writes
+  // last_heartbeat (Epic #583 W2-I3), so that half of the overlay re-writes an
+  // identical value; semantic_session_id is the half that adds information.
   const lockFile = path.join(repoRoot, '.orchestrator', 'session.lock');
+  let raw;
+  // ENOENT right after ok:true is most likely a racer holding OUR fresh lock in
+  // its tombstone: a second start that saw the same stale lock renames it
+  // aside, finds it live and links it back within microseconds
+  // (session-lock.mjs reclaimIfNotLive). Reading once and giving up left the
+  // lock ours but without semantic_session_id, owner proof and lock.acquired
+  // (#1494 review: two racers are enough). Bounded: 5 retries × 10 ms, so a lock
+  // that is really gone costs this hook at most ~50 ms. Measured 2026-10-02
+  // (2000 live-restore reclaims, load average ~9): the racer's rename→link-back
+  // window was p50 0.34 ms, p99 2.4 ms, max 31.7 ms. Ceiling (BV-004): a window
+  // longer than ~50 ms still ends in the lockless-enrichment null above;
+  // revisit if lock.acquired goes missing for sessions that own the lock.
+  for (let attempt = 0; raw === undefined; attempt += 1) {
+    try {
+      raw = fs.readFileSync(lockFile, 'utf8');
+    } catch (err) {
+      if (err?.code !== 'ENOENT' || attempt >= ENRICH_READ_RETRIES) return null;
+      await new Promise((resolve) => setTimeout(resolve, ENRICH_READ_RETRY_MS));
+    }
+  }
   let baseLock;
   try {
-    const raw = fs.readFileSync(lockFile, 'utf8');
     baseLock = JSON.parse(raw);
     if (typeof baseLock !== 'object' || baseLock === null) return null;
   } catch {
-    // Lock vanished between write and read — best-effort, return null.
     return null;
   }
+  // The file can belong to another session by now. The reclaim above is
+  // single-winner since #1494 (tombstone rename + link-create in
+  // forceAcquire's onlyIfNotLive), but a plain forceAcquire — the same-session
+  // refresh, an operator's Phase-1.2 force-take — still overwrites
+  // unconditionally, and a link-back that loses to a third writer drops the
+  // lock it was restoring (session-lock.mjs reclaimIfNotLive, ceiling 2).
+  // Enriching a foreign lock would stamp OUR label onto ITS record and write
+  // an owner proof that verifies against it, so it is left as is.
+  if (baseLock.session_id !== sessionId) return null;
 
   const startedAt = typeof baseLock.started_at === 'string'
     ? baseLock.started_at
@@ -301,27 +382,38 @@ export async function bootstrapLock({
     }
   } catch { /* best-effort — a missing proof never breaks session-start */ }
 
-  // Step 3: best-effort observability breadcrumb. Failures are swallowed
-  // so a missing events module never breaks the hook.
+  // Step 3: best-effort observability breadcrumb.
+  await emitBestEffort(_emitEventImpl, 'orchestrator.session.lock.acquired', {
+    session_id: enriched.session_id,
+    semantic_session_id: enriched.semantic_session_id,
+    mode: enriched.mode,
+    pid: enriched.pid,
+    host: enriched.host,
+    ttl_hours: enriched.ttl_hours,
+    ...(reclaimed ? { reclaimed } : {}),
+  });
+
+  return enriched;
+}
+
+/**
+ * Emit one event; every failure is swallowed so a missing events module never
+ * breaks the hook (observability is best-effort).
+ *
+ * @param {Function|undefined} emitImpl — the `_emitEventImpl` test seam.
+ * @param {string} name
+ * @param {object} payload
+ * @returns {Promise<void>}
+ */
+async function emitBestEffort(emitImpl, name, payload) {
   try {
-    let emitFn = _emitEventImpl;
+    let emitFn = emitImpl;
     if (!emitFn) {
       const eventsMod = await import('../../scripts/lib/events.mjs');
       emitFn = eventsMod.emitEvent;
     }
-    if (typeof emitFn === 'function') {
-      await emitFn('orchestrator.session.lock.acquired', {
-        session_id: enriched.session_id,
-        semantic_session_id: enriched.semantic_session_id,
-        mode: enriched.mode,
-        pid: enriched.pid,
-        host: enriched.host,
-        ttl_hours: enriched.ttl_hours,
-      });
-    }
+    if (typeof emitFn === 'function') await emitFn(name, payload);
   } catch { /* observability is best-effort */ }
-
-  return enriched;
 }
 
 /**

package/hooks/config-protection.mjs

@@ -81,7 +81,7 @@ const PROTECTED_PATTERNS = [
   /^tsconfig.*\.json$/, // tsconfig.json, tsconfig.base.json, tsconfig.build.json, …
   /^\.prettierrc(?:\..+)?$/, // .prettierrc, .prettierrc.json, .prettierrc.js, …
   /^prettier\.config\.(?:js|cjs|mjs)$/,
-  /^commitlint\.config\.(?:js|cjs|mjs|ts)$/,
+  /^commitlint(?:\.ci)?\.config\.(?:js|cjs|mjs|ts)$/, // + the strict CI config (commitlint.ci.config.mjs)
 ];
 
 /**

package/hooks/enforce-commands.mjs

@@ -95,9 +95,10 @@ import { pathToFileURL } from 'node:url';
 /** @type {typeof import('../scripts/lib/io.mjs').emitAllow} */ let emitAllow;
 /** @type {typeof import('../scripts/lib/io.mjs').emitDeny} */ let emitDeny;
 /** @type {typeof import('../scripts/lib/io.mjs').emitWarn} */ let emitWarn;
-let resolveProjectDir;
+let resolveSessionRoot;
 let readJson;
-let findScopeFile;
+// #1504 point 6 — bound from scope-gate below.
+let findOwnScopeFile;
 let extractBashWriteTargets;
 let pathMatchesPattern;
 /** @type {typeof import('../scripts/lib/session-identity/own-session.mjs').readProcessLocalSessionIds} */
@@ -165,7 +166,8 @@ function bannerProjectDir() {
  * the entry-point catch banners.
  *
  * `hardening.mjs` is bound (no headFallback — it carries relative imports) for
- * `findScopeFile` / `extractBashWriteTargets` / `pathMatchesPattern`; the two
+ * `extractBashWriteTargets` / `pathMatchesPattern` (and `scope-gate.mjs` for
+ * `findOwnScopeFile`, #1504 point 6); the two
  * command-matching primitives come from the direct `blocker` namespace, which is
  * the only entry that opts into the `git show HEAD:` recovery. Because hardening
  * transitively imports command-blocker (via scope-gate.mjs), a broken command-blocker
@@ -184,6 +186,9 @@ async function bootstrap() {
       platform: { specifier: lib('platform.mjs') },
       common: { specifier: lib('common.mjs') },
       hardening: { specifier: lib('hardening.mjs') },
+      // #1504 point 6 — `findOwnScopeFile`. Already reachable through the
+      // hardening barrel, so no new module edge.
+      scopeGate: { specifier: lib('scope-gate.mjs') },
       blocker: {
         specifier: lib('command-blocker.mjs'),
         headFallback: true,
@@ -203,9 +208,10 @@ async function bootstrap() {
   );
 
   ({ readStdin, emitAllow, emitDeny, emitWarn } = modules.io);
-  ({ resolveProjectDir } = modules.platform);
+  ({ resolveSessionRoot } = modules.platform);
   ({ readJson } = modules.common);
-  ({ findScopeFile, extractBashWriteTargets, pathMatchesPattern } = modules.hardening);
+  ({ extractBashWriteTargets, pathMatchesPattern } = modules.hardening);
+  ({ findOwnScopeFile } = modules.scopeGate);
   ({ readProcessLocalSessionIds, classifyManifestSession } = modules.sessionIdentity);
   blocker = modules.blocker;
   degradedLabels = degraded;
@@ -275,10 +281,22 @@ async function main() {
     );
   }
 
-  const projectRoot = resolveProjectDir();
-
-  // G3 — no scope file → allow
-  const scopePath = findScopeFile(projectRoot);
+  // #1492 — the SESSION's working copy, not the launch dir `$CLAUDE_PROJECT_DIR`
+  // keeps after `EnterWorktree` (the manifest lives in the worktree). See
+  // `resolveSessionRoot` in scripts/lib/platform.mjs.
+  const projectRoot = resolveSessionRoot(input.cwd);
+
+  // `new Set(...)` is load-bearing: `readProcessLocalSessionIds` returns a
+  // string[], and `classifyManifestSession` does `ownIds instanceof Set ?
+  // ownIds : new Set()` — a bare array would silently become EMPTY.
+  const ownIds = new Set(readProcessLocalSessionIds({ hookInput: input }));
+
+  // G3 — no scope file → allow. #1504 point 6: the first manifest that is not
+  // provably a peer's, so a peer's higher-precedence `.pi`/`.cursor`/`.codex`
+  // manifest no longer hides this session's own one; only when every candidate
+  // is foreign does the first come back, and G3b below stands down as before.
+  const located = findOwnScopeFile(projectRoot, ownIds, classifyManifestSession);
+  const scopePath = located.path ?? located.foreignPath;
   if (!scopePath) return flushNotices(notices);
 
   // SECURITY-REQ-08: read scope file exactly once; use the parsed object
@@ -313,10 +331,7 @@ async function main() {
   // empty, so this gate is permanently `'unknown'` = enforce = pre-#1153
   // behaviour there. Revisit when those hook payloads carry a session id.
   {
-    // `new Set(...)` is load-bearing: `readProcessLocalSessionIds` returns a
-    // string[], and `classifyManifestSession` does `ownIds instanceof Set ?
-    // ownIds : new Set()` — a bare array would silently become EMPTY.
-    const ownIds = new Set(readProcessLocalSessionIds({ hookInput: input }));
+    // `ownIds` is the process-local set built above G3.
     const { verdict, manifestIds } = classifyManifestSession(scope, ownIds);
     if (verdict === 'foreign') {
       // Observability only, and deliberately NOT emitWarn: this branch is hit on

package/hooks/enforce-scope.mjs

@@ -107,7 +107,12 @@ import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 let isPathInside;
 let relativeFromRoot;
 let resolveProjectDir;
-let findScopeFile;
+let resolveSessionRoot;
+// The launch dir the harness states — platform.mjs's one definition of the env
+// chain, so the relocation trace below cannot drift from the clamp (#1504).
+let launchDirFromEnv;
+// #1504 point 6 — the manifest that governs THIS session; bound from scope-gate below.
+let findOwnScopeFile;
 let pathMatchesPattern;
 let suggestForScopeViolation;
 let readJson;
@@ -197,8 +202,8 @@ async function bootstrap() {
 
   ({ readStdin, emitAllow, emitDeny, emitWarn } = modules.io);
   ({ isPathInside, relativeFromRoot } = modules.pathUtils);
-  ({ resolveProjectDir } = modules.platform);
-  ({ findScopeFile, pathMatchesPattern, suggestForScopeViolation } = modules.hardening);
+  ({ resolveProjectDir, resolveSessionRoot, launchDirFromEnv } = modules.platform);
+  ({ pathMatchesPattern, suggestForScopeViolation } = modules.hardening);
   ({ readJson } = modules.common);
   ({
     classifyEmptyScope,
@@ -206,6 +211,7 @@ async function bootstrap() {
     sessionStartedAtMs,
     gradeScopeEntry,
     canonicalizeGrantPrefix,
+    findOwnScopeFile,
   } = modules.scopeGate);
   ({ readProcessLocalSessionIds, classifyManifestSession } = modules.sessionIdentity);
 }
@@ -224,7 +230,13 @@ async function main() {
   // Gate 2: file_path must be a non-empty string
   if (!filePath || typeof filePath !== 'string') return emitAllow();
 
-  const projectRootRaw = resolveProjectDir();
+  // #1492 — the SESSION's working copy, not the launch dir: after
+  // `EnterWorktree`, `$CLAUDE_PROJECT_DIR` still names the dir the session was
+  // launched in, while the manifest lives in the worktree. Never above the launch
+  // dir; a harness subagent worktree (`isolation: "worktree"`) is lifted to the
+  // launch checkout it sits under — still unenforced in an entered-worktree
+  // session (named ceiling in `resolveSessionRoot`, scripts/lib/platform.mjs).
+  const projectRootRaw = resolveSessionRoot(input.cwd);
 
   // Resolve symlinks in the project root itself so that realpath(file) comparisons
   // are consistent. On macOS /tmp → /private/tmp; mismatches would cause false denials.
@@ -235,9 +247,26 @@ async function main() {
     projectRoot = projectRootRaw;
   }
 
-  // Gate 3: no wave-scope.json → nothing to enforce
-  const scopePath = findScopeFile(projectRoot);
-  if (!scopePath) return emitAllow();
+  // `new Set(...)` is load-bearing: `readProcessLocalSessionIds` returns a
+  // string[], and `classifyManifestSession` does `ownIds instanceof Set ?
+  // ownIds : new Set()` — a bare array would silently become EMPTY, making
+  // every manifest read `unknown`. Process-local only (#1194, see Gate 3b).
+  const ownIds = new Set(readProcessLocalSessionIds({ hookInput: input }));
+
+  // Gate 3: no wave-scope.json → nothing to enforce.
+  //
+  // #1504 point 6 — the first manifest that is not provably a peer's, in the
+  // `.pi` > `.cursor` > `.codex` > `.claude` order. `findScopeFile` stopped at
+  // the first file that exists, so a peer's `.pi`/`.cursor` manifest made Gate
+  // 3b stand down and this session's own `.claude/wave-scope.json` was never
+  // read. Only when EVERY candidate is foreign does the first of them come back
+  // (`foreignPath`), so Gate 3b's stand-down below stays unchanged.
+  const located = findOwnScopeFile(projectRoot, ownIds, classifyManifestSession);
+  const scopePath = located.path ?? located.foreignPath;
+  if (!scopePath) {
+    await recordHiddenManifestOncePerWave({ projectRootRaw, projectRoot, ownIds, filePath });
+    return emitAllow();
+  }
 
   // SECURITY-REQ-08: read scope file once; pass parsed object to all subsequent checks
   //
@@ -305,11 +334,7 @@ async function main() {
   // `enforcement: "off"` already grants in the same file — this gate adds no new
   // authority, and the manifest is the coordinator's own artefact either way.
   {
-    // `new Set(...)` is load-bearing: `readProcessLocalSessionIds` returns a
-    // string[], and `classifyManifestSession` does `ownIds instanceof Set ?
-    // ownIds : new Set()` — a bare array would silently become EMPTY, making
-    // every manifest read `unknown`.
-    const ownIds = new Set(readProcessLocalSessionIds({ hookInput: input }));
+    // `ownIds` is the process-local set built above Gate 3.
     const { verdict, manifestIds } = classifyManifestSession(scope, ownIds);
     if (verdict === 'foreign') {
       // Observability only, and deliberately NOT emitWarn: this branch is hit on
@@ -489,6 +514,7 @@ async function main() {
   if (matchedGrant !== null) {
     const grade = gradeScopeEntry(matchedGrant, { resolve: canonicalizeGrantPrefix });
     if (grade?.verdict === 'error') {
+      await recordRefusedGrantOncePerWave({ scope, scopePath, projectRoot, input, grant: matchedGrant, grade, filePath: resolvedPath });
       return emitWarn(
         `Gate 5b honoured an out-of-repo grant that scripts/validate-wave-scope.mjs would REFUSE ` +
           `before dispatch — allowedPaths ${grade.message}. The write to '${resolvedPath}' is ` +
@@ -538,7 +564,9 @@ async function main() {
     // dispatched wave agent's. See {@link classifyCaller} for the measurement.
     // A subagent falls through to the gates below — under a manifest that does
     // not grant the path (Discovery's `allowedPaths: []`) that is a DENY.
-    const memoryDirs = await ownMemoryDirs(projectRootRaw, projectRoot);
+    // #1492: the LAUNCH dir too — the harness keys auto-memory on the path it
+    // was launched with, which after `EnterWorktree` is no longer the root.
+    const memoryDirs = await ownMemoryDirs([resolveProjectDir(), projectRootRaw, projectRoot]);
     const caller = classifyCaller(input);
     if (caller !== 'subagent' && memoryDirs.some((dir) => isInsideDir(resolvedPath, dir))) {
       // One event per decision point, awaited before emitAllow() —
@@ -652,6 +680,155 @@ async function main() {
   return emitAllow();
 }
 
+/**
+ * #1485 point 1 — the catch event for Gate 5b's WARN branch, ONCE per wave.
+ *
+ * `scripts/validate-wave-scope.mjs` has no mechanical caller; the Gate 5b WARN
+ * is the only place a refused grant is seen at all, and a `systemMessage` is not
+ * countable. Owner decision 2026-10-02, option (b): the FIRST WARN of a wave
+ * writes `orchestrator.scope.refused_grant_allowed`, so "how many waves ran on
+ * a manifest the validator would refuse" becomes a ledger query (HR-105). The
+ * WARN itself is unchanged and still fires on every write.
+ *
+ * DEDUPE: a marker `.orchestrator/tmp/gate5b-refused-grant/<session>-w<wave>`
+ * created with `flag: 'wx'` (O_CREAT|O_EXCL). Exclusive create is atomic, so of
+ * two hook processes racing on the first WARN exactly one wins and emits — no
+ * lock, no read-modify-write. The session joins the key because wave numbers
+ * restart in every session sharing this working copy. `.orchestrator/tmp/` is
+ * gitignored; one marker per (session, wave) that ever hit a refused grant.
+ *
+ * Any marker failure OTHER than EEXIST (unwritable dir, ENOTDIR) still emits:
+ * over-reporting a rare event beats re-creating the silent gap this closes.
+ *
+ * COST: runs only on the Gate 5b `error` branch — an ordinary in-repo write
+ * never reaches it, so the hot path pays nothing. NAMED CEILING (BV-004): a
+ * legacy manifest without a session id and a payload without one share the key
+ * `no-session-w<N>` across sessions; revisit if such manifests are still seen.
+ *
+ * Never throws — observability must not change the WARN.
+ *
+ * @param {{scope: Record<string, unknown>, scopePath: string, projectRoot: string,
+ *   input: Record<string, unknown>, grant: string, grade: {code?: string},
+ *   filePath: string}} facts
+ * @returns {Promise<void>}
+ */
+async function recordRefusedGrantOncePerWave({ scope, scopePath, projectRoot, input, grant, grade, filePath }) {
+  try {
+    const session = String(
+      scope.session_id ?? scope.session ?? input?.session_id ?? process.env.CLAUDE_CODE_SESSION_ID ?? 'no-session',
+    );
+    const key = `${session}-w${scope.wave ?? 'unknown'}`.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 160);
+    const markerDir = path.join(projectRoot, '.orchestrator', 'tmp', 'gate5b-refused-grant');
+    try { await fs.mkdir(markerDir, { recursive: true }); } catch { /* the create below decides */ }
+    try {
+      await fs.writeFile(path.join(markerDir, key), `${new Date().toISOString()}\n`, { flag: 'wx' });
+    } catch (e) {
+      if (e?.code === 'EEXIST') return; // this wave already reported
+    }
+    const { emitEvent } = await import('../scripts/lib/events.mjs');
+    await emitEvent(
+      'orchestrator.scope.refused_grant_allowed',
+      {
+        hook: HOOK_NAME,
+        manifest: scopePath,
+        wave: scope.wave,
+        grant,
+        code: grade?.code,
+        file_path: filePath,
+      },
+      { repoRoot: projectRoot },
+    );
+  } catch { /* observability is best-effort — never changes the WARN */ }
+}
+
+/**
+ * #1504 point 3 — the catch event for a session root that HID an active wave,
+ * ONCE per (session, wave, session root).
+ *
+ * `resolveSessionRoot()` answers with the repo the payload `cwd` sits in. A wave
+ * agent that `cd`s into a nested or sibling repo (or a session that entered a
+ * worktree) therefore resolves a root without a manifest, and Gate 3 allows
+ * every write there while the wave's manifest sits at the launch dir, unread.
+ * The revisit trigger `resolveSessionRoot` names for exactly that relocation
+ * ("an `orchestrator.scope.*` record") could never fire: this allow left no
+ * trace. Behaviour stays ALLOW — this is the trace, not a new deny.
+ *
+ * Fires only when BOTH hold, so the ordinary no-manifest allow — every write in
+ * every repo without a wave — stays silent (HR-101):
+ *   1. the harness states a launch dir and it is not the resolved session root;
+ *   2. the launch root carries a manifest that is not provably a peer's
+ *      ({@link findOwnScopeFile}: own, or unbound/legacy — one that WOULD have
+ *      been enforced). A peer's manifest at the launch root hides nothing of ours.
+ *
+ * COST on the hot path: rung 1 is an env read plus a string compare — no
+ * filesystem call while the session root IS the launch dir, i.e. for every
+ * session that never left its checkout. One `realpath` when only the spelling
+ * differs (macOS `/var` → `/private/var`); the ≤4 `existsSync` of rung 2 only
+ * for a genuinely relocated root.
+ *
+ * DEDUPE: the {@link recordRefusedGrantOncePerWave} pattern — an exclusive
+ * create (`flag: 'wx'`) of `<launch>/.orchestrator/tmp/scope-root-relocated/<key>`.
+ * The event goes to the LAUNCH repo's ledger, where the wave's other records
+ * live. The session root's basename joins the key so a second relocated repo in
+ * one wave is reported too. NAMED CEILING (BV-004): two relocated roots sharing a
+ * basename in one wave report once; revisit if a record ever names the wrong repo.
+ *
+ * Never throws — observability must not change the allow.
+ *
+ * @param {{projectRootRaw: string, projectRoot: string, ownIds: Set<string>,
+ *   filePath: string}} facts
+ * @returns {Promise<void>}
+ */
+async function recordHiddenManifestOncePerWave({ projectRootRaw, projectRoot, ownIds, filePath }) {
+  try {
+    const launchRaw = launchDirFromEnv();
+    if (launchRaw === '') return;
+    const launchResolved = path.resolve(launchRaw);
+    if (launchResolved === projectRootRaw || launchResolved === projectRoot) return;
+    let launch;
+    try {
+      launch = await fs.realpath(launchResolved);
+    } catch {
+      return; // a launch dir that does not exist holds no manifest
+    }
+    if (launch === projectRoot) return;
+
+    const { path: manifest } = findOwnScopeFile(launch, ownIds, classifyManifestSession);
+    if (!manifest) return;
+
+    let scope = {};
+    try {
+      const parsed = JSON.parse(await fs.readFile(manifest, 'utf8'));
+      if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) scope = parsed;
+    } catch { /* unreadable → keyed and reported as wave `unknown` */ }
+
+    const session = String(scope.session_id ?? scope.session ?? [...ownIds][0] ?? 'no-session');
+    const key = `${session}-w${scope.wave ?? 'unknown'}-${path.basename(projectRoot)}`
+      .replace(/[^A-Za-z0-9._-]/g, '_')
+      .slice(0, 160);
+    const markerDir = path.join(launch, '.orchestrator', 'tmp', 'scope-root-relocated');
+    try { await fs.mkdir(markerDir, { recursive: true }); } catch { /* the create below decides */ }
+    try {
+      await fs.writeFile(path.join(markerDir, key), `${new Date().toISOString()}\n`, { flag: 'wx' });
+    } catch (e) {
+      if (e?.code === 'EEXIST') return; // this root already reported for this wave
+    }
+    const { emitEvent } = await import('../scripts/lib/events.mjs');
+    await emitEvent(
+      'orchestrator.scope.manifest_hidden_by_session_root',
+      {
+        hook: HOOK_NAME,
+        manifest,
+        launch_root: launch,
+        session_root: projectRoot,
+        wave: scope.wave,
+        file_path: path.isAbsolute(filePath) ? filePath : path.resolve(projectRoot, filePath),
+      },
+      { repoRoot: launch },
+    );
+  } catch { /* observability is best-effort — never changes the allow */ }
+}
+
 /**
  * `mtimeMs` of a file, or `null` when it cannot be stat'ed.
  *
@@ -679,21 +856,22 @@ async function mtimeMsOf(file) {
 /**
  * #1295 — the Claude Code auto-memory directories that belong to THIS repo.
  *
- * Returns at most two paths, both naming the SAME repo: the encoding of the
- * project root as the harness saw it (`CLAUDE_PROJECT_DIR` / cwd) and — when it
- * differs — the encoding of its realpath. Both are needed because Claude Code
- * encodes the path it was LAUNCHED with, while this hook compares against the
- * canonical root (on macOS `/tmp` → `/private/tmp`). Two encodings of one repo
- * is not a wider grant: a sibling repo's root encodes to neither.
+ * One path per distinct root (per home spelling): the encoding of the launch
+ * dir the harness saw (`CLAUDE_PROJECT_DIR` / cwd), of the session root
+ * (#1492 — a worktree the session entered) and of its realpath. All are needed
+ * because Claude Code encodes the path it was LAUNCHED with, while this hook
+ * compares against the canonical session root (on macOS `/tmp` →
+ * `/private/tmp`). Keeping the launch dir keeps the pre-#1492 grant exactly
+ * (the launch dir WAS the root then); the session-root entries name the
+ * worktree this session works in. A sibling repo's root encodes to none of them.
  *
  * Returns `[]` when the encoder cannot be loaded, so the caller falls through to
  * its deny (fail-closed).
  *
- * @param {string} projectRootRaw — project root as resolved from env/cwd
- * @param {string} projectRoot — its realpath
+ * @param {string[]} candidateRoots — launch dir, session root, its realpath
  * @returns {Promise<string[]>}
  */
-async function ownMemoryDirs(projectRootRaw, projectRoot) {
+async function ownMemoryDirs(candidateRoots) {
   try {
     const [{ encodeProjectDir }, { homedir }] = await Promise.all([
       import('../scripts/lib/wave-transcript-tail.mjs'),
@@ -710,7 +888,7 @@ async function ownMemoryDirs(projectRootRaw, projectRoot) {
     } catch { /* non-existent home — the raw form is all there is */ }
     const homes = new Set([home, homeReal]);
     const roots = new Set(
-      [projectRootRaw, projectRoot].filter((p) => typeof p === 'string' && p.length > 0),
+      candidateRoots.filter((p) => typeof p === 'string' && p.length > 0),
     );
     const dirs = [];
     for (const h of homes) {

package/hooks/hooks-codex.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v5.3.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v5.5.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

package/hooks/hooks-cursor.json

@@ -83,6 +83,11 @@
             "type": "command",
             "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/config-protection.mjs\"",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/pre-edit-sessions-ledger-guard.mjs\"",
+            "timeout": 5
           }
         ]
       }

package/hooks/hooks-pi.json

@@ -38,6 +38,11 @@
             "type": "command",
             "command": "sh \"$PI_PLUGIN_ROOT/hooks/run-node.sh\" \"$PI_PLUGIN_ROOT/hooks/config-protection.mjs\"",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$PI_PLUGIN_ROOT/hooks/run-node.sh\" \"$PI_PLUGIN_ROOT/hooks/pre-edit-sessions-ledger-guard.mjs\"",
+            "timeout": 5
           }
         ]
       },