session-orchestrator 5.4.0 → 5.6.0

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

@@ -109,6 +109,10 @@
  * observed actor could rewrite the gate unreported. Because the file is
  * typically gitignored, `git status` cannot see it anyway — change detection
  * for it is content-hash-based against the snapshot (`formatControlNotice`).
+ * Its sibling control state `<state-dir>/filescopes/**` (the per-agent scope
+ * declarations, #1020) is likewise not on the list: `computeReport` drops it
+ * from the violation set beside the manifest itself, keyed on the ACTIVE
+ * manifest's state dir (`isScopeDeclarationPath`, #1027 Pkt 5).
  *
  * The hook's OWN snapshot lives in `$TMPDIR`, never inside the repo, so it is
  * structurally incapable of reporting its own bookkeeping.
@@ -149,18 +153,24 @@ import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
-import { readFileSync, mkdirSync, writeFileSync, renameSync, realpathSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, mkdirSync, writeFileSync, renameSync, realpathSync, statSync } from 'node:fs';
 
 import { readStdin, writeStdoutLineSync } from '../scripts/lib/io.mjs';
-import { resolveProjectDir } from '../scripts/lib/platform.mjs';
-import { findScopeFile, pathMatchesPattern } from '../scripts/lib/hardening.mjs';
+import { resolveSessionRoot } from '../scripts/lib/platform.mjs';
+import { pathMatchesPattern } from '../scripts/lib/hardening.mjs';
 // #1057 — `sessionAgeMs` and its private `clockAgeMs` helper MOVED to the lib so
 // hooks/enforce-scope.mjs can read the same session clock without a hook->hook
 // import. Re-exported below, so this hook's public surface — and
 // tests/hooks/post-bash-write-verify.test.mjs, which imports the named export —
 // is unchanged. Two byte-identical copies of a clock is exactly the one-fact-two-
 // copies class this repo keeps paying for.
-import { sessionAgeMs, PEER_RECORD_PREFIX, isPeerRecordId } from '../scripts/lib/scope-gate.mjs';
+import {
+  sessionAgeMs,
+  PEER_RECORD_PREFIX,
+  isPeerRecordId,
+  isScopeDeclarationPath,
+  findOwnScopeFile,
+} from '../scripts/lib/scope-gate.mjs';
 // #1153 P1 — the same process-local ownership check hooks/enforce-scope.mjs
 // applies at Gate 3b. This hook reads the SAME working-copy `wave-scope.json`,
 // so without it a peer session's manifest drives this session's advisories.
@@ -313,6 +323,45 @@ export function parsePorcelainZ(raw) {
   return out;
 }
 
+/**
+ * Rebase toplevel-relative porcelain paths onto the SESSION ROOT.
+ *
+ * `git status --porcelain` names paths relative to the git TOPLEVEL, while
+ * `allowedPaths`, the ignore list and the manifest path are relative to the
+ * session root — since #1492 the LAUNCH DIR, which in a session started from a
+ * repo subdirectory (`<mono>/packages/foo`) sits below the toplevel. Judged
+ * unrebased, an in-scope write to `packages/foo/src/new.mjs` failed `src/**`
+ * (false positive) and a write to `<mono>/src/evil.mjs` matched it (false
+ * negative). A path under the prefix loses it; every other path is outside the
+ * project root and is spelled `../…` from the session root — the same category
+ * enforce-scope Gate 6 denies, and a spelling no allowedPaths entry can grant
+ * (see {@link isOutsideSessionRoot}).
+ *
+ * @param {string[]} paths toplevel-relative, forward slashes
+ * @param {string} prefix session root relative to the toplevel ('' = same dir)
+ * @returns {string[]}
+ */
+export function rebaseToSessionRoot(paths, prefix) {
+  const clean = typeof prefix === 'string' ? prefix.replace(/\/+$/, '') : '';
+  // '' = the session root IS the toplevel; '..'/absolute cannot come from
+  // `--show-prefix` and would make the arithmetic meaningless — leave as is.
+  if (clean === '' || clean.startsWith('..') || clean.startsWith('/')) return paths;
+  const head = `${clean}/`;
+  const ups = clean.split('/').map(() => '..').join('/');
+  return paths.map((p) => (p.startsWith(head) ? p.slice(head.length) : `${ups}/${p}`));
+}
+
+/**
+ * Is this (session-root-relative) path outside the project root — a `../…`
+ * spelling produced by {@link rebaseToSessionRoot}? Never in scope.
+ *
+ * @param {string} relPath
+ * @returns {boolean}
+ */
+export function isOutsideSessionRoot(relPath) {
+  return relPath === '..' || relPath.startsWith('../');
+}
+
 /**
  * Is a repo-relative path covered by the wave's `allowedPaths`?
  *
@@ -359,14 +408,11 @@ export { PEER_RECORD_PREFIX };
  * @param {unknown} wave the manifest's `wave` field
  * @returns {Array<{ id: string, files: string[] }>}
  */
-export function readPeerScopeRecords(stateDir, wave) {
-  if (typeof stateDir !== 'string' || stateDir === '') return [];
-  if (typeof wave !== 'number' || !Number.isInteger(wave) || wave <= 0) return [];
+export function readPeerScopeRecords(stateDir, wave, raw = readPeerSidecarRaw(stateDir, wave)) {
+  if (typeof raw !== 'string') return [];
   let parsed;
   try {
-    parsed = JSON.parse(
-      readFileSync(path.join(stateDir, 'filescopes', `wave-${wave}.scopes.json`), 'utf8'),
-    );
+    parsed = JSON.parse(raw);
   } catch {
     return [];
   }
@@ -380,18 +426,115 @@ export function readPeerScopeRecords(stateDir, wave) {
     .map((r) => ({ id: r.id, files: r.files.filter((f) => typeof f === 'string') }));
 }
 
+/**
+ * The raw bytes of a wave's aggregate scope sidecar, or null (absent,
+ * unreadable, or no usable state dir / wave). Read ONCE per call so the bytes
+ * that are hashed ({@link bindPeerSidecar}) are the bytes that are parsed.
+ *
+ * @param {string} stateDir
+ * @param {unknown} wave
+ * @returns {string|null}
+ */
+export function readPeerSidecarRaw(stateDir, wave) {
+  if (typeof stateDir !== 'string' || stateDir === '') return null;
+  if (typeof wave !== 'number' || !Number.isInteger(wave) || wave <= 0) return null;
+  try {
+    return readFileSync(path.join(stateDir, 'filescopes', `wave-${wave}.scopes.json`), 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Bind the aggregate sidecar's content to the manifest it was written for
+ * (#1504 point 5). The sidecar carried no integrity anchor: a `peer-session-*`
+ * record appended AFTER dispatch downgraded matching violations to a peer-write
+ * notice, because the control hash covers only `wave-scope.json`.
+ *
+ * The anchor is the trusted snapshot's `scopeState` — the one record this hook
+ * already treats as control state. The coordinator's order is materialize →
+ * assert-disjoint → union → write manifest, so the sidecar is final by the time
+ * the manifest is; the hash is therefore (re)bound whenever the MANIFEST hash
+ * changes (or no binding exists yet), and must hold while the manifest stands.
+ * No coordinator step and no new field: a materializer-written digest would sit
+ * in a file the same actor can rewrite, which binds nothing.
+ *
+ *   manifest changed / no prior binding  → bind the current hash, honour records
+ *   same manifest, same sidecar hash     → honour records
+ *   same manifest, sidecar now absent    → nothing to honour; keep the binding so
+ *                                          a re-created sidecar still mismatches
+ *   same manifest, DIFFERENT sidecar     → `tampered`: honour NO peer record
+ *                                          (fail toward reporting) and keep the
+ *                                          ORIGINAL binding until the manifest is
+ *                                          rewritten; the notice fires ONCE per
+ *                                          mismatching sidecar hash (`notify`)
+ *
+ * Once, not per call: a legitimate mid-wave Peer-Scope-Union rewrites the sidecar
+ * while `--union` (which excludes peer records) leaves the manifest bytes
+ * unchanged, so `tampered` holds for the rest of the wave. Repeating the ⚠ on
+ * every Bash call would be an always-on signal (HR-101). The marker
+ * `sidecarNotified` is persisted in the trusted snapshot by the caller only on
+ * the path that emits; a further change of the sidecar (a new hash) notifies again.
+ *
+ * A snapshot written before this field existed has no `sidecarHash` and binds
+ * silently on its first call — the same one-time adoption the control hash had.
+ *
+ * NAMED CEILING: a sidecar changed BEFORE this hook first observes the manifest
+ * (no trusted snapshot yet) is bound as found; so is one rewritten together with
+ * the manifest (that path already raises the control-file notice). A forged
+ * COMPLETE snapshot record is believed — `trustedScopeState`'s residual.
+ *
+ * @param {{ hash: string, sidecarHash?: unknown }|null} prevScopeState trusted prior state
+ * @param {string} manifestHash this call's manifest hash
+ * @param {string} sidecarHash this call's sidecar hash, or 'absent'
+ * @returns {{ sidecarHash: string, tampered: boolean, notify: boolean, sidecarNotified?: string }}
+ *   the hash to persist, the verdict, whether to emit the mismatch notice, and
+ *   (when tampered) the marker to persist once it has been emitted
+ */
+export function bindPeerSidecar(prevScopeState, manifestHash, sidecarHash) {
+  const bound = prevScopeState?.sidecarHash;
+  if (!prevScopeState || prevScopeState.hash !== manifestHash || typeof bound !== 'string') {
+    return { sidecarHash, tampered: false, notify: false };
+  }
+  if (bound === sidecarHash || sidecarHash === 'absent') {
+    return { sidecarHash: bound, tampered: false, notify: false };
+  }
+  return {
+    sidecarHash: bound,
+    tampered: true,
+    notify: prevScopeState.sidecarNotified !== sidecarHash,
+    sidecarNotified: sidecarHash,
+  };
+}
+
+/**
+ * Render the sidecar-mismatch notice (#1504 point 5) — an alarm (⚠), because the
+ * consequence is that agreed peer writes now report as violations.
+ *
+ * @param {string} relSidecarPath
+ * @returns {string}
+ */
+export function formatSidecarMismatchNotice(relSidecarPath) {
+  return `bash-write-verify: ${relSidecarPath} changed since wave-scope.json was written — `
+    + 'its peer-session-* records are NOT honoured (writes under them report as violations) '
+    + 'until the manifest is rewritten (#1504 point 5).';
+}
+
 /**
  * Which peer record — if any — declared this path?
  *
  * Same matcher as `isInScope`, so a peer's declaration is read exactly the way
- * the wave's own `allowedPaths` are.
+ * the wave's own `allowedPaths` are — and the same outside-root guard as
+ * `computeReport`: a `../…` path is outside the project root, which no peer
+ * record can grant any more than `allowedPaths` can (a peer glob over every
+ * `.md` file would otherwise file `<mono>/NOTES.md` as an agreed peer write).
  *
  * @param {string} relPath
  * @param {Array<{ id: string, files: string[] }>} peerRecords
  * @returns {string|null} the peer record id, or null
  */
 export function peerRecordFor(relPath, peerRecords) {
-  if (!Array.isArray(peerRecords)) return null;
+  if (!Array.isArray(peerRecords) || isOutsideSessionRoot(relPath)) return null;
   for (const record of peerRecords) {
     if (record.files.some((p) => pathMatchesPattern(relPath, p))) return record.id;
   }
@@ -466,14 +609,22 @@ export function snapshotPathFor(repoRoot) {
 export function computeReport({ dirtyPaths, allowedPaths, snapshot, signature, scopeMtimeMs = null, mtimeMs = null, scopeRelPath = null }) {
   const outOfScope = dirtyPaths
     .filter((p) => !isIgnoredPath(p))
-    .filter((p) => !isInScope(p, allowedPaths))
+    // A `../…` path (outside the project root, see rebaseToSessionRoot) is never
+    // in scope — not even under a broad glob that would happen to match it.
+    .filter((p) => isOutsideSessionRoot(p) || !isInScope(p, allowedPaths))
     // The wave-scope.json control file is out-of-scope by construction (it is
     // never under allowedPaths) but its CHANGES are reported via the content-hash
     // control-notice path, not here. Excluding it keeps the mtime re-baseline
     // filter from reporting the scope file against ITSELF — its mtime always
     // equals scopeMtimeMs, so the MED-3 `>=` boundary would otherwise flag it on
     // every first run (#938 MED-3 follow-through).
-    .filter((p) => p !== scopeRelPath);
+    .filter((p) => p !== scopeRelPath)
+    // Its sibling control state, `<state-dir>/filescopes/` (the per-agent scope
+    // declarations `materialize-wave-scope.mjs` writes once per wave), is no
+    // wave territory either — excluded the same way, not via
+    // IGNORED_PATH_PATTERNS, so the exemption follows THIS manifest's state dir
+    // instead of granting all four harness dirs (#1027 Pkt 5).
+    .filter((p) => !isScopeDeclarationPath(p, scopeRelPath));
 
   const rebaselined = !snapshot || snapshot.signature !== signature;
   const seen = rebaselined || !Array.isArray(snapshot?.paths) ? new Set() : new Set(snapshot.paths);
@@ -515,7 +666,9 @@ export function computeReport({ dirtyPaths, allowedPaths, snapshot, signature, s
  * @returns {string}
  */
 export function formatMessage(report, allowedCount) {
-  const shown = report.slice(0, MAX_REPORTED_PATHS);
+  const shown = report
+    .slice(0, MAX_REPORTED_PATHS)
+    .map((p) => (isOutsideSessionRoot(p) ? `${p} (outside project root)` : p));
   const more = report.length - shown.length;
   const tail = more > 0 ? ` (+${more} more)` : '';
   const msg =
@@ -608,12 +761,13 @@ export function formatSnapshotMissingNotice({ sessionAge = null, scopeAge = null
 // ---------------------------------------------------------------------------
 
 /**
- * Collect the working-tree dirty set. Returns null when git is unavailable, the
+ * Collect the working-tree dirty set, rebased onto the session root
+ * ({@link rebaseToSessionRoot}). Returns null when git is unavailable, the
  * directory is not a repo, or the call times out — all of which mean "no signal
  * to report", never a warning.
  *
- * @param {string} repoRoot
- * @returns {string[]|null}
+ * @param {string} repoRoot the session root
+ * @returns {string[]|null} session-root-relative paths (`../…` = outside it)
  */
 function readDirtyPaths(repoRoot) {
   try {
@@ -630,7 +784,16 @@ function readDirtyPaths(repoRoot) {
       ['--no-optional-locks', 'status', '--porcelain', '-z', '--no-renames', '--untracked-files=all'],
       { cwd: repoRoot, encoding: 'utf8', timeout: GIT_TIMEOUT_MS, maxBuffer: GIT_MAX_BUFFER, stdio: ['ignore', 'pipe', 'ignore'] },
     );
-    return parsePorcelainZ(raw);
+    // Porcelain paths are toplevel-relative; everything they are judged against
+    // is session-root-relative. A `.git` AT the session root makes it the
+    // toplevel (prefix ''), so the extra spawn is paid only by a session
+    // launched from a repo subdirectory.
+    const prefix = existsSync(path.join(repoRoot, '.git'))
+      ? ''
+      : execFileSync('git', ['rev-parse', '--show-prefix'], {
+        cwd: repoRoot, encoding: 'utf8', timeout: GIT_TIMEOUT_MS, stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+    return rebaseToSessionRoot(parsePorcelainZ(raw), prefix);
   } catch {
     return null;
   }
@@ -807,7 +970,10 @@ async function main() {
   // G2 — only Bash calls carry the bypass risk this hook watches.
   if (input.tool_name !== 'Bash') return;
 
-  const repoRootRaw = resolveProjectDir();
+  // #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 repoRootRaw = resolveSessionRoot(input.cwd);
   let repoRoot;
   try {
     repoRoot = realpathSync(repoRootRaw);
@@ -833,7 +999,14 @@ async function main() {
   // G3 — no wave scope → nothing defines "outside". #938: if a previous call
   // RECORDED a scope state, the control file's disappearance is itself a
   // control-file change and gets one visible (non-alarming) notice.
-  const scopePath = findScopeFile(repoRoot);
+  //
+  // #1504 point 6 — the first manifest that is not provably a peer's, so a
+  // peer's higher-precedence manifest no longer hides this session's own one;
+  // only when every candidate is foreign does the first come back, and G3b
+  // below keeps its stand-down and its rebind notice unchanged.
+  const ownIds = new Set(readProcessLocalSessionIds({ hookInput: input }));
+  const located = findOwnScopeFile(repoRoot, ownIds, classifyManifestSession);
+  const scopePath = located.path ?? located.foreignPath;
   if (!scopePath) {
     if (prevScopeState && prevScopeState.hash !== 'absent') {
       writeSnapshot(snapFile, {
@@ -857,7 +1030,7 @@ async function main() {
   } catch {
     /* raw stays null (unreadable) or scope stays null (unparseable) */
   }
-  if (raw === null) return; // file vanished between findScopeFile and read
+  if (raw === null) return; // file vanished between findOwnScopeFile and read
 
   // The control-file identity of THIS call, computed BEFORE the G3b
   // stand-down (W4/F7). Ordering is the whole fix: G3b used to `return` above
@@ -878,6 +1051,16 @@ async function main() {
       : 'unparseable',
     gateOn: scope ? scope?.gates?.['bash-write-verify'] !== false : true,
   };
+  // #1504 point 5 — bind the aggregate sidecar to this manifest (see
+  // `bindPeerSidecar`). Part of `currentScopeState` so EVERY snapshot write
+  // below, stand-down paths included, carries the binding forward.
+  const sidecarRaw = readPeerSidecarRaw(path.dirname(scopePath), scope?.wave);
+  const sidecarBinding = bindPeerSidecar(
+    prevScopeState,
+    currentScopeState.hash,
+    sidecarRaw === null ? 'absent' : createHash('sha1').update(sidecarRaw).digest('hex').slice(0, 16),
+  );
+  currentScopeState.sidecarHash = sidecarBinding.sidecarHash;
 
   // G3b (#1153 P1) — is this manifest even MINE?
   //
@@ -898,7 +1081,6 @@ async function main() {
   // CLI, Cursor today) the own-id set is empty, so this gate is permanently
   // `'unknown'` = full pre-#1153 behaviour there.
   {
-    const ownIds = new Set(readProcessLocalSessionIds({ hookInput: input }));
     const { verdict, manifestIds } = classifyManifestSession(scope ?? {}, ownIds);
     if (verdict === 'foreign') {
       // Observability only — one event per stand-down decision, awaited so the
@@ -1072,6 +1254,9 @@ async function main() {
     },
   });
 
+  // The mismatch notice below is emitted on this path only, so its once-marker
+  // is persisted here and nowhere else (see `bindPeerSidecar`).
+  if (sidecarBinding.tampered) currentScopeState.sidecarNotified = sidecarBinding.sidecarNotified;
   writeSnapshot(snapFile, { ...nextSnapshot, scopeState: currentScopeState });
 
   const messages = [];
@@ -1091,7 +1276,17 @@ async function main() {
   // reachable. Such a write is agreed, not a bypass. Split it out of the violation report and
   // name it, so the peer's file is countable without being an alarm. Sidecar
   // absent ⇒ `peerRecords` is empty ⇒ every path stays a violation, unchanged.
-  const peerRecords = readPeerScopeRecords(path.dirname(scopePath), scope.wave);
+  // #1504 point 5 — a sidecar changed under a standing manifest is untrusted:
+  // no peer record is honoured, and the mismatch is named.
+  const peerRecords = sidecarBinding.tampered
+    ? []
+    : readPeerScopeRecords(path.dirname(scopePath), scope.wave, sidecarRaw);
+  if (sidecarBinding.notify) {
+    messages.push(formatSidecarMismatchNotice(
+      path.relative(repoRoot, path.join(path.dirname(scopePath), 'filescopes', `wave-${scope.wave}.scopes.json`)),
+    ));
+    warn = true;
+  }
   const violations = [];
   for (const relPath of report) {
     const peerId = peerRecordFor(relPath, peerRecords);

package/hooks/post-edit-validate.mjs

@@ -35,8 +35,13 @@ import { shouldRunHook } from './_lib/profile-gate.mjs';
 import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 
 import { readStdin } from '../scripts/lib/io.mjs';
-import { resolveProjectDir } from '../scripts/lib/platform.mjs';
-import { findScopeFile, gateEnabled } from '../scripts/lib/hardening.mjs';
+import { resolveSessionRoot } from '../scripts/lib/platform.mjs';
+import { gateEnabled } from '../scripts/lib/hardening.mjs';
+import { findOwnScopeFile } from '../scripts/lib/scope-gate.mjs';
+import {
+  classifyManifestSession,
+  readProcessLocalSessionIds,
+} from '../scripts/lib/session-identity/own-session.mjs';
 import { readConfigFile, parseSessionConfig } from '../scripts/lib/config.mjs';
 
 // ---------------------------------------------------------------------------
@@ -184,7 +189,9 @@ async function main() {
   const ext = path.extname(filePath).toLowerCase();
   if (!TS_EXTS.has(ext)) process.exit(0);
 
-  const projectRoot = resolveProjectDir();
+  // The SESSION root the scope guards use (#1492, #1504 point 4) — not the
+  // launch dir, which stays put while a session works in an entered worktree.
+  const projectRoot = resolveSessionRoot(input?.cwd);
 
   // Compute relative path (REQ-03)
   const absFilePath = path.isAbsolute(filePath)
@@ -192,8 +199,11 @@ async function main() {
     : path.resolve(projectRoot, filePath);
   const relPath = path.relative(projectRoot, absFilePath);
 
-  // G5: per-gate toggle — skip if post-edit-validate gate is disabled
-  const scopeFile = findScopeFile(projectRoot);
+  // G5: per-gate toggle — skip if post-edit-validate gate is disabled. Only
+  // THIS session's manifest may switch it off: a peer's manifest in the same
+  // working copy is skipped, and a peer-only result means no toggle (#1504).
+  const ownIds = new Set(readProcessLocalSessionIds({ hookInput: input }));
+  const { path: scopeFile } = findOwnScopeFile(projectRoot, ownIds, classifyManifestSession);
   if (scopeFile && !gateEnabled(scopeFile, 'post-edit-validate')) {
     process.exit(0);
   }