session-orchestrator 5.4.0 → 5.5.0

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.4.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.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v5.4.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/on-session-start.mjs

@@ -1098,8 +1098,10 @@ async function main() {
 
   // Phase 4 measurement probes — the mechanical caller (#1128).
   //
-  // `skills/session-start/SKILL.md` § Phase 4 names 19 probes with module paths
-  // and entry functions. Measured 2026-08-23 at `4f6404e`, not one of them had
+  // `skills/session-start/SKILL.md` § Phase 4 names 20 probes with module paths
+  // and entry functions (2026-10-02; the `PROBES` registry in
+  // `scripts/lib/session-start-probes.mjs` is the count's source of truth).
+  // Measured 2026-08-23 at `4f6404e` (a smaller family then), not one of them had
   // a caller anywhere in hooks/, npm scripts, .gitlab-ci.yml or .husky/ — the
   // only caller was the prose itself, and across 336 recorded session starts
   // there was no event proving any of them had ever run. Built, documented,