session-orchestrator 5.8.0 → 5.10.0

package/hooks/enforce-scope.mjs

@@ -107,12 +107,12 @@ import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 let isPathInside;
 let relativeFromRoot;
 let resolveProjectDir;
-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 resolveScopeContext;
 let pathMatchesPattern;
 let suggestForScopeViolation;
 let readJson;
@@ -202,7 +202,7 @@ async function bootstrap() {
 
   ({ readStdin, emitAllow, emitDeny, emitWarn } = modules.io);
   ({ isPathInside, relativeFromRoot } = modules.pathUtils);
-  ({ resolveProjectDir, resolveSessionRoot, launchDirFromEnv } = modules.platform);
+  ({ resolveProjectDir, launchDirFromEnv } = modules.platform);
   ({ pathMatchesPattern, suggestForScopeViolation } = modules.hardening);
   ({ readJson } = modules.common);
   ({
@@ -212,6 +212,7 @@ async function bootstrap() {
     gradeScopeEntry,
     canonicalizeGrantPrefix,
     findOwnScopeFile,
+    resolveScopeContext,
   } = modules.scopeGate);
   ({ readProcessLocalSessionIds, classifyManifestSession } = modules.sessionIdentity);
 }
@@ -230,38 +231,18 @@ async function main() {
   // Gate 2: file_path must be a non-empty string
   if (!filePath || typeof filePath !== 'string') return emitAllow();
 
-  // #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.
-  let projectRoot;
-  try {
-    projectRoot = await fs.realpath(projectRootRaw);
-  } catch {
-    projectRoot = projectRootRaw;
-  }
-
-  // `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).
+  // Control state follows the session coordinator; relative grants follow
+  // the actual isolated agent checkout. Entered coordinator worktrees are
+  // discovered only through bounded reciprocal Git metadata and own identity.
   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 context = resolveScopeContext({ cwd: input.cwd, ownIds, classify: classifyManifestSession });
+  if (context.error) return emitDeny('Scope coordinator cannot be resolved', context.error);
+  const projectRootRaw = context.writeRoot;
+  let projectRoot;
+  try { projectRoot = await fs.realpath(projectRootRaw); }
+  catch { projectRoot = projectRootRaw; }
+  const manifestRoot = context.manifestRoot;
+  const located = context;
   const scopePath = located.path ?? located.foreignPath;
   if (!scopePath) {
     await recordHiddenManifestOncePerWave({ projectRootRaw, projectRoot, ownIds, filePath });
@@ -354,7 +335,7 @@ async function main() {
             wave: scope.wave,
             file_path: filePath,
           },
-          { repoRoot: projectRoot },
+          { repoRoot: manifestRoot },
         );
       } catch { /* observability is best-effort — never blocks the decision */ }
       return emitAllow();
@@ -395,10 +376,10 @@ async function main() {
           role: scope.role,
           parseOk,
           scopeMtimeMs: await mtimeMsOf(scopePath),
-          sessionStartMs: sessionStartedAtMs(projectRoot),
+          sessionStartMs: sessionStartedAtMs(manifestRoot),
         })
       : null;
-  const scopeRelRaw = relativeFromRoot(projectRoot, scopePath);
+  const scopeRelRaw = relativeFromRoot(manifestRoot, scopePath);
   const scopeHint = (scopeRelRaw ?? scopePath).split(path.sep).join('/');
 
   /**
@@ -514,7 +495,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 });
+      await recordRefusedGrantOncePerWave({ scope, scopePath, projectRoot: manifestRoot, 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 ` +
@@ -566,9 +547,9 @@ async function main() {
     // not grant the path (Discovery's `allowedPaths: []`) that is a DENY.
     // #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 memoryDirs = await ownMemoryDirs([resolveProjectDir(), manifestRoot]);
     const caller = classifyCaller(input);
-    if (caller !== 'subagent' && memoryDirs.some((dir) => isInsideDir(resolvedPath, dir))) {
+    if (!context.isolated && caller !== 'subagent' && memoryDirs.some((dir) => isInsideDir(resolvedPath, dir))) {
       // One event per decision point, awaited before emitAllow() —
       // emitAllow() calls process.exit(), which would discard a pending append.
       try {
@@ -589,7 +570,7 @@ async function main() {
             // `'coordinator'` = `agent_type` without `agent_id`.
             discriminator: caller,
           },
-          { repoRoot: projectRoot },
+          { repoRoot: manifestRoot },
         );
       } catch { /* observability is best-effort — never blocks the decision */ }
       return emitAllow();
@@ -642,7 +623,7 @@ async function main() {
   // `emitAllow()` (`process.exit(0)`, no log, no event), so whether it ever fired
   // was unfalsifiable after the fact.
   const carveoutCaller = classifyCaller(input);
-  if (carveoutCaller !== 'subagent' && isCoordinatorCarveout(normalizedRel, projectRoot, scopePath)) {
+  if (!context.isolated && carveoutCaller !== 'subagent' && isCoordinatorCarveout(normalizedRel, projectRoot, scopePath)) {
     // One event per decision point, awaited before emitAllow() — emitAllow()
     // calls process.exit(), which would discard a pending append.
     try {
@@ -659,7 +640,7 @@ async function main() {
           file_path: normalizedRel,
           discriminator: carveoutCaller,
         },
-        { repoRoot: projectRoot },
+        { repoRoot: manifestRoot },
       );
     } catch { /* observability is best-effort — never blocks the decision */ }
     return emitAllow();

package/hooks/hooks-codex.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v5.8.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v5.10.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.8.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v5.10.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

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

@@ -156,7 +156,6 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync, mkdirSync, writeFileSync, renameSync, realpathSync, statSync } from 'node:fs';
 
 import { readStdin, writeStdoutLineSync } from '../scripts/lib/io.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
@@ -169,7 +168,8 @@ import {
   PEER_RECORD_PREFIX,
   isPeerRecordId,
   isScopeDeclarationPath,
-  findOwnScopeFile,
+  resolveScopeContext,
+  canonicalizeGrantPrefix,
 } 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`,
@@ -371,11 +371,23 @@ export function isOutsideSessionRoot(relPath) {
  *
  * @param {string} relPath
  * @param {string[]} allowedPaths
+ * @param {string|null} [writeRoot] actual checkout root for absolute grants
  * @returns {boolean}
  */
-export function isInScope(relPath, allowedPaths) {
+export function isInScope(relPath, allowedPaths, writeRoot = null) {
   if (!Array.isArray(allowedPaths) || allowedPaths.length === 0) return false;
-  return allowedPaths.some((p) => typeof p === 'string' && pathMatchesPattern(relPath, p));
+  return allowedPaths.some((p) => {
+    if (typeof p !== 'string') return false;
+    if (!path.isAbsolute(p)) return pathMatchesPattern(relPath, p);
+    if (typeof writeRoot !== 'string' || !path.isAbsolute(writeRoot) || path.isAbsolute(relPath) || isOutsideSessionRoot(relPath)) return false;
+    // Match the canonical target, as PreToolUse does, but never let an absolute
+    // grant suppress reporting for a path escaping the observed checkout.
+    const root = canonicalizeGrantPrefix(writeRoot);
+    const target = canonicalizeGrantPrefix(path.resolve(root, relPath));
+    const relative = path.relative(root, target);
+    if (path.isAbsolute(relative) || isOutsideSessionRoot(relative.split(path.sep).join('/'))) return false;
+    return pathMatchesPattern(target, p);
+  });
 }
 
 /**
@@ -599,6 +611,7 @@ export function snapshotPathFor(repoRoot) {
  * @param {object} args
  * @param {string[]} args.dirtyPaths     repo-relative paths from git status
  * @param {string[]} args.allowedPaths   wave allowedPaths
+ * @param {string|null} [args.writeRoot] actual checkout root for absolute grants
  * @param {object|null} args.snapshot    previous `{ signature, paths[] }`, or null
  * @param {string} args.signature        current scope signature
  * @param {number|null} [args.scopeMtimeMs] mtime (ms) of wave-scope.json, or null
@@ -606,12 +619,12 @@ export function snapshotPathFor(repoRoot) {
  *   dirty path; null = not attributable (deleted path / stat failure)
  * @returns {{ report: string[], nextSnapshot: { signature: string, paths: string[] }, rebaselined: boolean }}
  */
-export function computeReport({ dirtyPaths, allowedPaths, snapshot, signature, scopeMtimeMs = null, mtimeMs = null, scopeRelPath = null }) {
+export function computeReport({ dirtyPaths, allowedPaths, snapshot, signature, scopeMtimeMs = null, mtimeMs = null, scopeRelPath = null, writeRoot = null }) {
   const outOfScope = dirtyPaths
     .filter((p) => !isIgnoredPath(p))
     // 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))
+    .filter((p) => isOutsideSessionRoot(p) || !isInScope(p, allowedPaths, writeRoot))
     // 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
@@ -970,18 +983,22 @@ async function main() {
   // G2 — only Bash calls carry the bypass risk this hook watches.
   if (input.tool_name !== 'Bash') return;
 
-  // #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);
-  } catch {
-    repoRoot = repoRootRaw;
+  // Coordinator control state and isolated-agent write targets may live in
+  // different working copies; the shared guard context resolves both.
+  const ownIds = new Set(readProcessLocalSessionIds({ hookInput: input }));
+  const context = resolveScopeContext({ cwd: input.cwd, ownIds, classify: classifyManifestSession });
+  if (context.error) {
+    emitMessages([`bash-write-verify: scope coordinator unresolved (${context.error})`], true);
+    return;
   }
-
-  const snapFile = snapshotPathFor(repoRoot);
+  const repoRootRaw = context.writeRoot;
+  let repoRoot;
+  try { repoRoot = realpathSync(repoRootRaw); }
+  catch { repoRoot = repoRootRaw; }
+  // Isolated snapshots bind both trees: two agents never share report-once state,
+  // and reselecting a coordinator cannot inherit another manifest's trust.
+  const snapFile = snapshotPathFor(context.isolated
+    ? `${repoRoot}\0${context.manifestRoot}\0${context.path ?? context.foreignPath ?? ""}` : repoRoot);
   const snapshot = readSnapshot(snapFile);
   // The ONE trust decision (see `trustedScopeState`). Every downstream use of a
   // "previous" value reads this binding, so no code path can accidentally act on
@@ -1004,8 +1021,7 @@ async function main() {
   // 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 located = context;
   const scopePath = located.path ?? located.foreignPath;
   if (!scopePath) {
     if (prevScopeState && prevScopeState.hash !== 'absent') {
@@ -1096,7 +1112,7 @@ async function main() {
             own_session: [...ownIds],
             wave: scope?.wave,
           },
-          { repoRoot },
+          { repoRoot: context.manifestRoot },
         );
       } catch { /* observability is best-effort — never blocks the decision */ }
 
@@ -1156,7 +1172,7 @@ async function main() {
   // `toContain('out-of-scope.mjs')` test to say otherwise.
   const missingSnapshotNotice = prevScopeState === null
     ? formatSnapshotMissingNotice({
-      sessionAge: sessionAgeMs(repoRoot),
+      sessionAge: sessionAgeMs(context.manifestRoot),
       scopeAge: typeof scopeMtimeMs === 'number' ? Date.now() - scopeMtimeMs : null,
       reason: snapshot === null ? 'absent' : 'untrusted',
     })
@@ -1239,6 +1255,7 @@ async function main() {
   const { report, nextSnapshot } = computeReport({
     dirtyPaths,
     allowedPaths,
+    writeRoot: repoRoot,
     // `prevRecord`, not `snapshot`: an untrusted record's report-once list is a
     // forgeable claim about what was already reported (see the binding above).
     snapshot: prevRecord,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "5.8.0",
+  "version": "5.10.0",
   "description": "Your coding agents get an agreed plan, a check after each round of changes and a handover to the next session. Plan, Go, Close: /session reads your repo and agrees the scope, /go runs the work in waves with your tests and typecheck after each implementation wave, /close runs the full gate, verifies, commits and files the rest as issues. Scope and destructive-command guards, crash-safe resume, learnings you approve. For Claude Code, Codex CLI, Cursor and Pi.",
   "type": "module",
   "homepage": "https://session-orchestrator.com",
@@ -96,7 +96,7 @@
     "@vitest/coverage-v8": "^4.1.11",
     "eslint": "^10.2.1",
     "husky": "^9.1.7",
-    "lint-staged": "^15.2.10",
+    "lint-staged": "^16.4.0",
     "prettier": "^3.0.0",
     "vitest": "^4.1.11"
   },

package/scripts/emit-session.mjs

@@ -48,6 +48,7 @@ import {
   aliasLegacyEndedAt,
   normalizeWaveKeys,
 } from './lib/session-schema.mjs';
+import { stableHostname } from './lib/host-identity.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
 
 /**
@@ -297,6 +298,20 @@ async function main() {
     recordSessionId: repaired.session_id,
   });
 
+  // #1054: origin belongs to the session, not the later mirror writer.
+  // Only the owned new-record path may derive this machine's identity:
+  // resolveOwnSessionUuid gates shared markers, while --session-uuid is the
+  // caller's explicit assertion that this is its own session (not proof of a
+  // historical import's origin). Incoming raw_session_id signals replayed
+  // provenance: leave its host unknown rather than guess. Explicit host keys,
+  // including null/empty values, always win. Never backfill existing records.
+  const carriesOrigin = ['raw_session_id', 'host_id', 'host', 'host_class']
+    .some((key) => Object.prototype.hasOwnProperty.call(repaired, key));
+  if (ownUuid && !carriesOrigin) {
+    const hostId = stableHostname();
+    if (hostId) repaired = { ...repaired, host_id: hostId };
+  }
+
   // An explicit session_start_ref that is not a full sha (#1443) names a
   // DIFFERENT commit once the short form becomes ambiguous. Dropped with a WARN
   // rather than rejected: the record is the load-bearing artefact, and the

package/scripts/lib/ci-status-banner.mjs

@@ -1089,8 +1089,23 @@ async function checkGithub(repoRoot, deps = {}) {
     };
   }
 
+  // #856: lifecycle and conclusion are separate facts. Failure retains
+  // priority even in an inconsistent row; only completed success grants green.
+  // Counts are additive diagnostics, never a new status or gate authority.
+  const checkRunCounts = { success: 0, failure: 0, inProgress: 0, queued: 0, cancelled: 0, skipped: 0, neutral: 0, waiting: 0, other: 0 };
+  for (const run of checkRuns) {
+    if (run?.conclusion === 'failure' || run?.conclusion === 'action_required') checkRunCounts.failure++;
+    else if (run?.status === 'completed' && run?.conclusion === 'success') checkRunCounts.success++;
+    else if (run?.status === 'completed' && run?.conclusion === 'cancelled') checkRunCounts.cancelled++;
+    else if (run?.status === 'completed' && run?.conclusion === 'skipped') checkRunCounts.skipped++;
+    else if (run?.status === 'completed' && run?.conclusion === 'neutral') checkRunCounts.neutral++;
+    else if (['waiting', 'pending', 'requested'].includes(run?.status) && run?.conclusion === null) checkRunCounts.waiting++;
+    else if (run?.status === 'in_progress' && run?.conclusion === null) checkRunCounts.inProgress++;
+    else if (run?.status === 'queued' && run?.conclusion === null) checkRunCounts.queued++;
+    else checkRunCounts.other++;
+  }
   const failedRun = checkRuns.find(
-    (r) => r.conclusion === 'failure' || r.conclusion === 'action_required',
+    (r) => r?.conclusion === 'failure' || r?.conclusion === 'action_required',
   );
 
   if (failedRun) {
@@ -1101,11 +1116,12 @@ async function checkGithub(repoRoot, deps = {}) {
       details: {
         cliUsed: 'gh',
         reason: 'lastGreen-not-implemented-for-github',
+        checkRunCounts,
       },
     };
   }
 
-  const allSuccess = checkRuns.every((r) => r.conclusion === 'success');
+  const allSuccess = checkRunCounts.success === checkRuns.length;
   if (allSuccess) {
     return {
       status: 'green',
@@ -1116,13 +1132,24 @@ async function checkGithub(repoRoot, deps = {}) {
     };
   }
 
-  // Some runs pending / in-progress / etc.
+  const states = [
+    ['inProgress', 'check-runs-in-progress'],
+    ['queued', 'check-runs-queued'],
+    ['cancelled', 'check-runs-cancelled'],
+    ['skipped', 'check-runs-skipped'],
+    ['neutral', 'check-runs-neutral'],
+    ['waiting', 'check-runs-waiting'],
+    ['other', 'check-runs-unrecognised'],
+  ].filter(([key]) => checkRunCounts[key] > 0);
+  // Successes may accompany one unknown state; counts expose the whole mix.
+  const reason = states.length === 1 ? states[0][1] : 'check-runs-mixed';
   return {
     status: 'unknown',
     ok: false,
     details: {
       cliUsed: 'gh',
-      reason: 'check-runs-not-complete',
+      reason,
+      checkRunCounts,
     },
   };
 }
@@ -1189,6 +1216,7 @@ async function checkGithub(repoRoot, deps = {}) {
  *     cliUsed: 'glab'|'gh',
  *     reason?: string,
  *     error?: string,
+ *     checkRunCounts?: { success: number, failure: number, inProgress: number, queued: number, cancelled: number, skipped: number, neutral: number, waiting: number, other: number },
  *     matchedRef?: string,
  *     candidateCount?: number,
  *     candidateStatuses?: string[],
@@ -1202,7 +1230,12 @@ async function checkGithub(repoRoot, deps = {}) {
  * #857 "several contradicting pipelines" and "only foreign-ref pipelines"
  * findings — and the #1390 "same-sha rows the ref preference set aside"
  * (`droppedCount`/`droppedStatuses`) — are delivered through ADDITIVE `details`
- * fields and `details.reason`,
+ * fields and `details.reason`. GitHub's `checkRunCounts` counts each row once:
+ * `failure` includes action_required; `other` includes malformed/inconsistent
+ * rows and unsupported statuses/conclusions. Non-success reasons are
+ * check-runs-in-progress, check-runs-queued, check-runs-cancelled,
+ * check-runs-skipped, check-runs-neutral, check-runs-waiting (#1526),
+ * check-runs-unrecognised, or check-runs-mixed (multiple non-success kinds),
  * never as a new status value — consumers fail open on an unknown status string
  * and the session-start renderer prints nothing for one.
  */

package/scripts/lib/events-schema.mjs

@@ -239,5 +239,13 @@ export function validateEventRecord(record) {
     );
   }
 
+  if (
+    ['orchestrator.quality_gate.passed', 'orchestrator.quality_gate.failed'].includes(record.event) &&
+    Object.hasOwn(record, 'wave_number') &&
+    (!Number.isSafeInteger(record.wave_number) || record.wave_number <= 0)
+  ) {
+    errors.push('quality_gate wave_number must be a positive safe integer when present');
+  }
+
   return { valid: errors.length === 0, errors };
 }

package/scripts/lib/gates/gate-full.mjs

@@ -227,4 +227,10 @@ if (failed) {
   }
 }
 
+// stderr is asynchronous when piped (pre-push/offload capture). Drain queued
+// writes before the forced exit; natural exit would retain kill-ladder timers.
+await Promise.all([
+  new Promise((resolve) => process.stdout.write('', resolve)),
+  new Promise((resolve) => process.stderr.write('', resolve)),
+]);
 process.exit(failed ? 2 : 0);

package/scripts/lib/gates/gate-helpers.mjs

@@ -565,6 +565,8 @@ export function extractTestCounts(output) {
   const EMPTY = { passed: 0, failed: 0, total: 0, files: null };
   if (!output) return EMPTY;
 
+  // Colored Vitest labels must match the same summaries as piped plain text.
+  output = output.replace(ANSI_ESCAPE, '');
   const lines = output.split('\n');
   const summaryLines = lines.filter((line) => TEST_SUMMARY_LINE.test(line));
   const scope = summaryLines.length > 0 ? summaryLines[summaryLines.length - 1] : output;

package/scripts/lib/named-vault-resolver.mjs

@@ -209,7 +209,7 @@ export function canonicalSuffixesFromVaults(vaults, envOverride) {
  *
  * First-match-wins; caller is responsible for WARN on ambiguity if needed.
  *
- * @param {string} repoSlug — e.g. 'bernhard-group/foo'
+ * @param {string} repoSlug — e.g. 'example-org/foo'
  * @param {Array<{name:string, suffix:string, root:string, match:{'org-prefix'?:string}}>} vaults
  * @returns {{name:string, suffix:string, root:string, match:object}|null}
  */

package/scripts/lib/owner-yaml.mjs

@@ -41,6 +41,9 @@
  *     mode: 'off' | 'warn' | 'strict'  (applied only when weaker than the committed mode;
  *                            precedence env SO_VAULT_INTEGRATION > this > committed.
  *                            An invalid value drops ONLY this section, see loadOwnerConfig)
+ *   drift-check:            (optional; host-local path exceptions — #937)
+ *     foreign-host-prefixes: string[] (narrow absolute directory prefixes;
+ *                            missing matching paths warn, unmatched paths error)
  *   vault-dirs:             (optional list; per-directory vault-dir — agents/vault#319)
  *     - path: string                       (the vault directory)
  *       match: { path-prefix: string }     (required; cwd directory prefix, first match wins)
@@ -54,7 +57,7 @@
  *   validateOwnerSections(obj) — pure validation, no I/O; bucketed per section (#820)
  *   validateOwnerConfig(obj)   — pure validation, no I/O; thin wrapper over validateOwnerSections
  *   loadOwnerConfig({path?})   — reads file; per-section tolerance for OPTIONAL
- *                                sections (paths/dispatcher/vault-integration/vaults/
+ *                                sections (paths/dispatcher/vault-integration/drift-check/vaults/
  *                                baselines/vault-dirs) — #820
  *   writeOwnerConfig(config, {path?}) — validates, writes YAML, creates dir
  *   getDefaults()              — returns sensible default config object
@@ -218,7 +221,7 @@ const REQUIRED_SECTIONS = /** @type {const} */ (['owner', 'tone', 'efficiency',
  * override", so a dropped section simply leaves the committed gate in force.
  */
 export const OPTIONAL_OBJECT_SECTIONS = /** @type {const} */ (
-  Object.freeze(['paths', 'dispatcher', 'vault-integration'])
+  Object.freeze(['paths', 'dispatcher', 'vault-integration', 'drift-check'])
 );
 
 /**
@@ -397,6 +400,33 @@ export function validateOwnerSections(obj) {
     sections['hardware-sharing'] = { valid: errors.length === 0, errors };
   }
 
+  // Host-local exception list only; invalid entries drop the entire section.
+  {
+    const errors = [];
+    const drift = obj['drift-check'];
+    if (drift !== undefined && drift !== null) {
+      if (!isPlainObject(drift)) {
+        errors.push('drift-check must be an object when present');
+      } else if (drift['foreign-host-prefixes'] !== undefined) {
+        const prefixes = drift['foreign-host-prefixes'];
+        if (!Array.isArray(prefixes)) {
+          errors.push('drift-check.foreign-host-prefixes must be an array');
+        } else {
+          for (const prefix of prefixes) {
+            const parts = typeof prefix === 'string' ? prefix.split('/').filter(Boolean) : [];
+            if (typeof prefix !== 'string' || !prefix.startsWith('/') ||
+                !/^\/[A-Za-z0-9._/-]+$/.test(prefix) || prefix.includes('//') ||
+                parts.some((part) => part === '.' || part === '..') ||
+                parts.length < 3 || (['Users', 'home'].includes(parts[0]) && parts.length < 4)) {
+              errors.push('drift-check.foreign-host-prefixes entries must be narrow absolute directory prefixes (no roots, home directories, traversal or globs)');
+            }
+          }
+        }
+      }
+    }
+    sections['drift-check'] = { valid: errors.length === 0, errors };
+  }
+
   // ── paths (optional; host-local path overrides — #653) ───────────────────────
   {
     const errors = [];
@@ -627,7 +657,7 @@ export function validateOwnerConfig(obj) {
  * Per-section tolerance (#820): an invalid REQUIRED section (owner, tone,
  * efficiency, hardware-sharing) still discards the whole file (legacy
  * behaviour, unchanged). An invalid OPTIONAL object section (paths,
- * dispatcher, vault-integration) is instead replaced by its default value — the rest of the
+ * dispatcher, vault-integration, drift-check) is instead replaced by its default value — the rest of the
  * file survives, `source` becomes `'partial'`, and the drop is reported via
  * `droppedSections` + a stderr WARN. OPTIONAL list sections (vaults,
  * baselines, vault-dirs) are passed through UNTOUCHED even when strict-invalid — their

package/scripts/lib/platform.mjs

@@ -13,7 +13,7 @@
  * NOTHING in this module touches the filesystem at import time.
  */
 
-import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, statSync, lstatSync, opendirSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { resolvePluginRoot as _resolvePluginRootRobust } from './plugin-root.mjs';
@@ -458,6 +458,75 @@ export function resolveSessionRoot(cwd, toplevel = '') {
   return launch !== '' && _isStrictlyInside(launch, root) ? launch : root;
 }
 
+/** Read small Git metadata after rejecting nonregular or symlink entries. */
+function readWorktreeMetadata(file) {
+  const info = lstatSync(file);
+  if (!info.isFile() || info.size > 8192) throw new TypeError('Invalid worktree metadata');
+  return readFileSync(file, 'utf8').trim();
+}
+
+function worktreeBinding(root) {
+  const text = readWorktreeMetadata(path.join(root, '.git'));
+  const match = /^gitdir: (.+)$/.exec(text);
+  if (!match) throw new TypeError('Invalid worktree pointer');
+  const gitDir = _canonical(path.resolve(root, match[1]));
+  const commonDir = _canonical(path.resolve(gitDir, readWorktreeMetadata(path.join(gitDir, 'commondir'))));
+  if (path.dirname(gitDir) !== path.join(commonDir, 'worktrees')) throw new TypeError('Invalid worktree admin directory');
+  const backPointer = _canonical(readWorktreeMetadata(path.join(gitDir, 'gitdir')));
+  if (backPointer !== _canonical(path.join(root, '.git'))) throw new TypeError('Worktree pointer mismatch');
+  return { gitDir, commonDir };
+}
+
+/**
+ * Verified Claude harness agent checkout, or null for every ordinary checkout.
+ * Keeps resolveSessionRoot's lifecycle contract unchanged (#1504 items 1–2).
+ * @param {string} cwd
+ * @returns {{writeRoot: string, commonDir: string}|null}
+ */
+export function isolatedAgentCheckout(cwd) {
+  const root = typeof cwd === 'string' ? dotGitAncestor(cwd) : '';
+  if (!root || _liftHarnessAgentWorktree(root) === root) return null;
+  try {
+    const binding = worktreeBinding(root);
+    const launchRoot = _liftHarnessAgentWorktree(root);
+    const dotGit = path.join(launchRoot, '.git');
+    const launchCommon = lstatSync(dotGit).isDirectory()
+      ? _canonical(dotGit) : worktreeBinding(launchRoot).commonDir;
+    if (binding.commonDir !== launchCommon) return null;
+    return { writeRoot: _canonical(root), commonDir: binding.commonDir };
+  } catch { return null; }
+}
+
+/**
+ * Enumerate reciprocal worktree roots in one Git admin directory, without a
+ * recursive scan. Ceiling: 256 entries / 8 KiB metadata; revisit if a real repo
+ * exceeds this. An incomplete enumeration is an error, never a clean absence.
+ * @param {string} commonDir
+ * @returns {{roots: string[], error: string|null}}
+ */
+export function registeredWorktreeRoots(commonDir) {
+  const roots = new Set();
+  let dir;
+  try {
+    dir = opendirSync(path.join(commonDir, 'worktrees'));
+    let count = 0;
+    for (let entry; (entry = dir.readSync()) !== null;) {
+      if (++count > 256) return { roots: [], error: 'worktree-limit' };
+      if (!entry.isDirectory()) continue;
+      const admin = path.join(commonDir, 'worktrees', entry.name);
+      try {
+        const pointer = readWorktreeMetadata(path.join(admin, 'gitdir'));
+        if (!path.isAbsolute(pointer) || path.basename(pointer) !== '.git') continue;
+        const root = _canonical(path.dirname(pointer));
+        const binding = worktreeBinding(root);
+        if (binding.commonDir === commonDir && binding.gitDir === _canonical(admin)) roots.add(root);
+      } catch { /* stale or invalid registration cannot lend authority */ }
+    }
+    return { roots: [...roots], error: null };
+  } catch { return { roots: [], error: 'worktree-discovery-unreadable' }; }
+  finally { if (dir) dir.closeSync(); }
+}
+
 // ---------------------------------------------------------------------------
 // resolveEventsLedgerRoot (#1514 point 1)
 // ---------------------------------------------------------------------------