session-orchestrator 3.24.0 → 4.0.0

package/hooks/enforce-commands.mjs

@@ -65,6 +65,10 @@ let readJson;
 let findScopeFile;
 let extractBashWriteTargets;
 let pathMatchesPattern;
+/** @type {typeof import('../scripts/lib/session-identity/own-session.mjs').readProcessLocalSessionIds} */
+let readProcessLocalSessionIds;
+/** @type {typeof import('../scripts/lib/session-identity/own-session.mjs').classifyManifestSession} */
+let classifyManifestSession;
 /**
  * The `command-blocker.mjs` namespace, imported DIRECTLY (not via the
  * hardening.mjs barrel — which does not carry the `headFallback` recovery, and
@@ -150,6 +154,10 @@ async function bootstrap() {
         headFallback: true,
         requires: ['commandMatchesBlocked', 'suggestForCommandBlock'],
       },
+      // #1153 P1. Bound through the same loader as every other repo dependency,
+      // so a SyntaxError in the identity module banners GUARD INACTIVE instead
+      // of link-crashing this hook into a silent fail-open (#993).
+      sessionIdentity: { specifier: lib('session-identity/own-session.mjs') },
     },
     {
       hookName: HOOK_NAME,
@@ -163,6 +171,7 @@ async function bootstrap() {
   ({ resolveProjectDir } = modules.platform);
   ({ readJson } = modules.common);
   ({ findScopeFile, extractBashWriteTargets, pathMatchesPattern } = modules.hardening);
+  ({ readProcessLocalSessionIds, classifyManifestSession } = modules.sessionIdentity);
   blocker = modules.blocker;
   degradedLabels = degraded;
 }
@@ -245,6 +254,66 @@ async function main() {
   } catch {
     scope = {};
   }
+  // G3b (#1153 P1) — is this manifest even MINE?
+  //
+  // `wave-scope.json` lives in the WORKING COPY, not in the session, so two live
+  // sessions sharing one checkout read the SAME file. Before this gate, session
+  // A's `blockedCommands` decided session B's Bash calls, with a deny reason
+  // pointing at a wave plan B does not own (#1082, the sibling defect
+  // hooks/enforce-scope.mjs Gate 3b closed for Edit/Write under #1123).
+  //
+  // Deliberately AFTER the parse block: a corrupt manifest folds to `{}`, hence
+  // no ids, hence `'unknown'` — and keeps being enforced. `'own'` and
+  // `'unknown'` fall through completely unchanged; a legacy manifest without a
+  // `session` field stays enforced. Only what is PROVABLY foreign stands down.
+  //
+  // IDENTITY TIER: `readProcessLocalSessionIds` (hook payload +
+  // `CLAUDE_CODE_SESSION_ID`) and deliberately NOT `readOwnSessionIds`, whose
+  // third tier is the repo-global `session.lock` — one file shared by every
+  // session in the checkout, which made a peer's manifest classify as `'own'`
+  // (#1194).
+  //
+  // CEILING (BV-004): on a harness that exports no session env var and puts no
+  // `session_id` in the hook payload (Codex CLI, Cursor today) both tiers are
+  // empty, so this gate is permanently `'unknown'` = enforce = pre-#1153
+  // behaviour there. Revisit when those hook payloads carry a session id.
+  {
+    // `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 }));
+    const { verdict, manifestIds } = classifyManifestSession(scope, ownIds);
+    if (verdict === 'foreign') {
+      // Observability only, and deliberately NOT emitWarn: this branch is hit on
+      // every Bash call of the non-owning session, so a stderr line per call
+      // would be noise. Awaited before the allow — flushNotices() exits the
+      // process, which would discard a pending append.
+      try {
+        const { emitEvent } = await import('../scripts/lib/events.mjs');
+        await emitEvent(
+          'orchestrator.scope.foreign_session_ignored',
+          {
+            hook: HOOK_NAME,
+            manifest: scopePath,
+            manifest_session: manifestIds,
+            own_session: [...ownIds],
+            wave: scope.wave,
+            command,
+          },
+          { repoRoot: projectRoot },
+        );
+      } catch { /* observability is best-effort — never blocks the decision */ }
+      return flushNotices(notices);
+    }
+  }
+
+  // ADVERSARIAL CEILING: `wave-scope.json` is a file ANY process in this working
+  // copy can write, so writing a foreign id into it is a per-file kill switch for
+  // this session's own gate. Accepted because "no manifest" already means allow
+  // (G3), so a foreign manifest grants nothing an `rm` would not — but the change
+  // MUST stay visible: see post-bash-write-verify's control-file notice (#938),
+  // which is the only thing that distinguishes this from a legitimate peer wave.
+
   const enforcement = scope.enforcement || 'strict';
   const blockedCommands = Array.isArray(scope.blockedCommands)
     ? scope.blockedCommands

package/hooks/hooks-codex.json

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

package/hooks/hooks-cursor.json

@@ -112,6 +112,11 @@
             "type": "command",
             "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/post-tooluse-frontend-slop.mjs\"",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/post-edit-import-probe.mjs\"",
+            "timeout": 5
           }
         ]
       },
@@ -139,6 +144,11 @@
             "type": "command",
             "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/post-tooluse-frontend-slop.mjs\"",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/post-edit-import-probe.mjs\"",
+            "timeout": 5
           }
         ]
       }

package/hooks/hooks-pi.json

@@ -85,6 +85,11 @@
             "type": "command",
             "command": "sh \"$PI_PLUGIN_ROOT/hooks/run-node.sh\" \"$PI_PLUGIN_ROOT/hooks/post-tooluse-frontend-slop.mjs\"",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$PI_PLUGIN_ROOT/hooks/run-node.sh\" \"$PI_PLUGIN_ROOT/hooks/post-edit-import-probe.mjs\"",
+            "timeout": 5
           }
         ]
       },

package/hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v3.24.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v4.0.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {
@@ -135,6 +135,11 @@
             "type": "command",
             "command": "sh \"$CLAUDE_PLUGIN_ROOT/hooks/run-node.sh\" \"$CLAUDE_PLUGIN_ROOT/hooks/post-tooluse-frontend-slop.mjs\"",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CLAUDE_PLUGIN_ROOT/hooks/run-node.sh\" \"$CLAUDE_PLUGIN_ROOT/hooks/post-edit-import-probe.mjs\"",
+            "timeout": 5
           }
         ]
       },

package/hooks/loop-guard.mjs

@@ -33,7 +33,7 @@ import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
 
-import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+import { getProjectDir } from '../scripts/lib/platform.mjs';
 import { emitEvent } from '../scripts/lib/events.mjs';
 import { writeJsonAtomicSync } from '../scripts/lib/io.mjs';
 import { _parseLoopGuard } from '../scripts/lib/config/loop-guard.mjs';
@@ -84,8 +84,8 @@ function readStdinJson() {
  */
 async function loadConfig() {
   const candidates = [
-    path.join(SO_PROJECT_DIR, 'CLAUDE.md'),
-    path.join(SO_PROJECT_DIR, 'AGENTS.md'),
+    path.join(getProjectDir(), 'CLAUDE.md'),
+    path.join(getProjectDir(), 'AGENTS.md'),
   ];
   for (const file of candidates) {
     try {

package/hooks/on-session-end.mjs

@@ -35,7 +35,7 @@ import { shouldRunHook } from './_lib/profile-gate.mjs';
 if (!shouldRunHook('on-session-end')) process.exit(0);
 
 import { emitEvent } from '../scripts/lib/events.mjs';
-import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+import { getProjectDir } from '../scripts/lib/platform.mjs';
 import {
   backfillAbandonedSession,
   backfillCompletedFromStateMd,
@@ -551,7 +551,7 @@ async function emitFinalWaveCompleted(
 
 async function main() {
   const input = await readStdinJson();
-  const projectRoot = SO_PROJECT_DIR;
+  const projectRoot = getProjectDir();
 
   const reason =
     typeof input?.reason === 'string' && input.reason.length > 0 ? input.reason : 'other';

package/hooks/on-session-start.mjs

@@ -42,7 +42,7 @@ if (!shouldRunHook('on-session-start')) process.exit(0);
 import { emitEvent, eventsFilePath } from '../scripts/lib/events.mjs';
 import { maybeRotate } from '../scripts/lib/events-rotation.mjs';
 import { readConfigFile, parseSessionConfig } from '../scripts/lib/config.mjs';
-import { SO_PLATFORM, resolveProjectDir } from '../scripts/lib/platform.mjs';
+import { getPlatform, resolveProjectDir } from '../scripts/lib/platform.mjs';
 import {
   registerSelf,
   detectPeers,
@@ -410,6 +410,13 @@ async function resolveSessionId(input, projectRoot) {
           if (Object.prototype.hasOwnProperty.call(prev, 'last_wave_completed')) {
             preserved.last_wave_completed = prev.last_wave_completed;
           }
+          // #980 — the OPEN half of the wave-diff pair, written by
+          // post-tool-batch-wave-signal.mjs. Dropping it across a /clear leaves
+          // the running wave with no start point, so the next
+          // `orchestrator.wave.completed` silently omits `files_changed`.
+          if (Object.prototype.hasOwnProperty.call(prev, 'wave_start_sha')) {
+            preserved.wave_start_sha = prev.wave_start_sha;
+          }
         }
       } catch { /* absent / unparseable → no preservation (reset) */ }
     }
@@ -705,7 +712,15 @@ async function main() {
   // must never break the hook, which is informational-only.
   const input = await stdinPromise;
   const { sessionId, semanticSessionId, mode } = await resolveSessionId(input, projectRoot);
-  const platform = process.env.SO_PLATFORM ?? SO_PLATFORM;
+  // getPlatform() ALREADY implements the SO_PLATFORM override as step 1 of its
+  // precedence — and, unlike a bare `??`, it validates the value against the
+  // four-platform allowlist and trims it. The former `process.env.SO_PLATFORM ??
+  // getPlatform()` therefore added nothing except the empty-string trap
+  // (`.claude/rules/development.md` § Env-var fallback whitespace trap): a key
+  // exported as `SO_PLATFORM=` is not nullish, so `??` short-circuited and this
+  // hook stamped `platform: ''` on the session event and handed '' down to the
+  // update probe. Measured 2026-09-06 by the codex test below.
+  const platform = getPlatform();
 
   // Epic #583 P3 — mechanical session.lock writer (closes D1+D2+D4 gaps).
   // Bootstrap the session-lock so discoverActiveSessions() picks us up even
@@ -947,6 +962,40 @@ async function main() {
     } catch { /* hook must remain non-blocking */ }
   }
 
+  // Plugin-update probe (#nnn, d7 R2) — "is the plugin that is RUNNING behind
+  // the plugin that is PUBLISHED?".
+  //
+  // MEASURED 2026-09-06: this host ran the marketplace-cache copy at 3.19.0
+  // (installed 2026-08-09) while repo and npm stood at the 3.24 line — five minors,
+  // four weeks, zero warnings, because NO code anywhere compared installed
+  // against available (`grep -rln "registry.npmjs.org\|dist-tags" scripts/
+  // hooks/ skills/` → only scripts/release.mjs, the publisher).
+  //
+  // Placement mirrors the probe block above: BEFORE the payload (the event
+  // carries both versions) and BEFORE flushBanner(), so the line rides the ONE
+  // systemMessage envelope. A second stdout object would be silently discarded
+  // (HR-106) — the failure mode the bannerLines docstring describes.
+  //
+  // Same measurement/display split as the probes: the request and the event
+  // fields happen regardless, `pushBanner` is gated on `bannerData`. Network,
+  // cache and kill-switch behaviour live in the module.
+  let pluginUpdate = null;
+  try {
+    const { checkPluginUpdate } = await import('../scripts/lib/plugin-update-banner.mjs');
+    pluginUpdate = await checkPluginUpdate({
+      cacheDir: path.join(projectRoot, '.orchestrator', 'runtime'),
+      // The probe's own fallback is env-only (SO_PLATFORM, then each harness's
+      // compat var) and cannot run detectPlatform()'s third step, the marker-
+      // directory walk from cwd. This hook already resolved the platform at the
+      // top of run() through exactly that full precedence, so handing it over
+      // makes the remedy instruction MEASURED rather than guessed — a Codex or
+      // Cursor consumer with no compat var set would otherwise be told to run
+      // `/plugin update`, a command its harness does not have.
+      platform,
+    });
+    if (pluginUpdate && bannerData) pushBanner(pluginUpdate.message);
+  } catch { /* hook must remain non-blocking */ }
+
   const payload = {
     platform,
     project: projectName,
@@ -958,6 +1007,34 @@ async function main() {
     // makes the supersession rate measurable instead of inferred (HR-105).
     peers_superseded: mechanicalPeersSuperseded,
   };
+
+  // #nnn — installed/latest plugin version on the session record.
+  //
+  // HR-105: a verdict nothing records is unfalsifiable. `installed` is stamped
+  // on EVERY start (it is a local file read that cannot fail for network
+  // reasons), and `latest` whenever it is known — including the runs where
+  // checkPluginUpdate() stayed silent because the versions matched. Those runs
+  // are the DENOMINATOR of the probe's firing rate; without them the fleet can
+  // only ever see how often it warned, never how often it could have.
+  //
+  // Both keys are OMITTED rather than nulled when unknown (docs/events-schema.md
+  // optional-field convention: absent ≠ zero) — a kill-switched or offline
+  // session must not read as "latest is 0/unknown-but-measured".
+  try {
+    const { readInstalledPluginVersion, readCachedLatest, isUpdateCheckDisabled } =
+      await import('../scripts/lib/plugin-update-banner.mjs');
+    const installedVersion = readInstalledPluginVersion();
+    if (installedVersion) payload.plugin_version_installed = installedVersion;
+    // `latest` is gated on the kill switch, `installed` is not: reading this
+    // repo's own package.json is not the thing an operator switched off.
+    if (!isUpdateCheckDisabled()) {
+      const latestVersion =
+        pluginUpdate?.latest
+        ?? readCachedLatest({ cacheDir: path.join(projectRoot, '.orchestrator', 'runtime') })?.version
+        ?? null;
+      if (latestVersion) payload.plugin_version_latest = latestVersion;
+    }
+  } catch { /* telemetry never blocks the hook */ }
   if (bannerData) {
     payload.host_class = bannerData.host.host_class;
     payload.ram_free_gb = bannerData.resources.ram_free_gb;
@@ -993,6 +1070,30 @@ async function main() {
   // only stdout write in the hook.
   flushBanner();
 
+  // #1229 — refresh the session-lock heartbeat at the END of this hook's run.
+  //
+  // MEASURED (STATE.md deviation 2026-09-05T06:08:46Z): session-20's lock was
+  // reaped as stale at 06:06Z by an UNRELATED session's SessionEnd, its
+  // heartbeat 11.3 h old against a 4 h TTL. The session was not idle — it was
+  // still inside session-start / session-plan, where no heartbeat writer
+  // existed: `updateHeartbeat()` was called only from the wave loop, from
+  // on-stop and from session-end. A session that never reached /go therefore
+  // aged out of its own lock while working.
+  //
+  // bootstrapLock() above stamps `last_heartbeat = started_at` at LOCK GENESIS,
+  // i.e. before the peer scan, the backfill and the Phase-4 probes have run.
+  // Stamping again here moves the clock to the end of the hook and — more
+  // importantly — makes session-start a heartbeat CALL SITE at all, so the
+  // cadence no longer begins only when the first wave starts.
+  //
+  // `updateHeartbeat()` already carries the same-session guard this needs (it
+  // returns false without writing when the lock belongs to another session),
+  // so no `touchIfOwn()` wrapper is warranted — see scripts/lib/session-lock.mjs.
+  try {
+    const { updateHeartbeat } = await import('../scripts/lib/session-lock.mjs');
+    updateHeartbeat({ repoRoot: projectRoot, sessionId });
+  } catch { /* hook must remain non-blocking */ }
+
   // Size-based rotation of events.jsonl (#251). Session-start is the single
   // rotation trigger — per-append overhead is rejected design. Any failure
   // is swallowed: rotation must NEVER block the hook.

package/hooks/on-stop.mjs

@@ -16,7 +16,9 @@
  * JSONL format (`.orchestrator/metrics/events.jsonl`) — emitted via the canonical
  * `emitEvent()` so the JSONL record and the optional Clank webhook always carry the
  * SAME dotted event name (was: bare `stop`/`subagent_stop` in JSONL vs dotted in webhook):
- *   Stop:        {"timestamp":<ISO>,"event":"orchestrator.session.stopped","session_id":"...","semantic_session_id":"...","wave":<int>,"branch":"...","commit":"...","duration_ms":<int>,"duration_source":"session-lock"}
+ *   Stop:        {"timestamp":<ISO>,"event":"orchestrator.turn.stopped","session_id":"...","semantic_session_id":"...","wave":<int>,"branch":"...","commit":"...","duration_ms":<int>,"duration_source":"session-lock"}
+ *                + the SAME payload under the DEPRECATED legacy name (one generation, removal 2027-03-06):
+ *                {"timestamp":<ISO>,"event":"orchestrator.session.stopped",…same fields…,"deprecated":true}
  *                (`session_id` / `semantic_session_id` are omitted when unresolvable — #1068 AC1.
  *                 `duration_ms` + `duration_source` are omitted TOGETHER when no OWNED
  *                 session.lock is readable — never a fabricated 0, see K5 below.)
@@ -46,7 +48,7 @@ import { AGENT_ID_RE, resolveSubagentSidecar } from './_lib/subagent-paths.mjs';
 if (!shouldRunHook('on-stop')) process.exit(0);
 
 import { emitEvent } from '../scripts/lib/events.mjs';
-import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+import { getProjectDir } from '../scripts/lib/platform.mjs';
 import { parseSessionId } from '../scripts/lib/session-id.mjs';
 import { heartbeat, logSweepEvent } from '../scripts/lib/session-registry.mjs';
 import { readLock, updateHeartbeat } from '../scripts/lib/session-lock.mjs';
@@ -366,7 +368,7 @@ function resolveStopDuration(input, projectRoot) {
  * @param {object|null} input
  */
 async function handleStop(input) {
-  const projectRoot = SO_PROJECT_DIR;
+  const projectRoot = getProjectDir();
 
   const wave = await readWaveNumber(projectRoot);
   const { commit, branch } = await gitInfo(projectRoot);
@@ -457,15 +459,38 @@ async function handleStop(input) {
   // #1183 — a malformed record throws EventValidationError BEFORE any side
   // effect (scripts/lib/events.mjs); this hook must never abort on that, so
   // the emit is wrapped rather than left to propagate.
+  //
+  // ── THE RENAME (GitLab #1234) ──────────────────────────────────────────────
+  // `orchestrator.session.stopped` is a TURN counter with a session's name. The
+  // Stop hook fires once per ASSISTANT TURN, not once per session: measured
+  // 2026-09-06 over 90 days, 15.538 records against 2.016 distinct
+  // `session.started` ids = 7,7 per session, with 184 for a single id. Six
+  // consumers read it as a session-lifecycle signal and are wrong by that factor.
+  //
+  // So the same payload now leaves under BOTH names for one generation:
+  //   - `orchestrator.turn.stopped`    — the correct name, what new readers use.
+  //   - `orchestrator.session.stopped` — unchanged shape PLUS `deprecated: true`,
+  //     so an existing reader keeps working and a NEW reader can tell at a glance
+  //     that it picked the legacy name.
+  // Removal of the legacy name: 2027-03-06 (docs/events-schema.md).
+  //
+  // The SubagentStop branch (`orchestrator.agent.stopped`) is deliberately NOT
+  // renamed — it is a different event and its per-agent cardinality is correct.
+  const stoppedPayload = {
+    ...(sessionId !== null ? { session_id: sessionId } : {}),
+    ...(semanticSessionId !== null ? { semantic_session_id: semanticSessionId } : {}),
+    wave,
+    ...(branch !== null ? { branch } : {}),
+    ...(commit !== null ? { commit } : {}),
+    ...duration,
+  };
+
   try {
-    await emitEvent('orchestrator.session.stopped', {
-      ...(sessionId !== null ? { session_id: sessionId } : {}),
-      ...(semanticSessionId !== null ? { semantic_session_id: semanticSessionId } : {}),
-      wave,
-      ...(branch !== null ? { branch } : {}),
-      ...(commit !== null ? { commit } : {}),
-      ...duration,
-    });
+    await emitEvent('orchestrator.turn.stopped', stoppedPayload);
+  } catch { /* telemetry never blocks the hook (#1183) */ }
+
+  try {
+    await emitEvent('orchestrator.session.stopped', { ...stoppedPayload, deprecated: true });
   } catch { /* telemetry never blocks the hook (#1183) */ }
 }
 

package/hooks/operator-steer.mjs

@@ -37,14 +37,14 @@ import { shouldRunHook } from './_lib/profile-gate.mjs';
 // Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
 if (!shouldRunHook('operator-steer')) process.exit(0);
 
-import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+import { getProjectDir } from '../scripts/lib/platform.mjs';
 
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
 
 async function main() {
-  const steerPath = path.join(SO_PROJECT_DIR, '.orchestrator', 'STEER.md');
+  const steerPath = path.join(getProjectDir(), '.orchestrator', 'STEER.md');
 
   // File absent — nothing to do.
   if (!existsSync(steerPath)) return;

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

@@ -163,6 +163,13 @@ import { findScopeFile, pathMatchesPattern } from '../scripts/lib/hardening.mjs'
 // 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';
+// #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.
+import {
+  readProcessLocalSessionIds,
+  classifyManifestSession,
+} from '../scripts/lib/session-identity/own-session.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -854,6 +861,17 @@ async function main() {
   }
   if (raw === null) return; // file vanished between findScopeFile 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
+  // this, so a peer or agent that REBOUND `wave-scope.json` to a fabricated
+  // `session_id` with one `cat >` redirect disarmed this session's gates AND
+  // suppressed the #938 control-file notice at the same time. Deleting the file
+  // was reported (G3 above); rebinding it was not — the louder half of the
+  // tamper trail was the one behind the gate the tamper opens.
+  //
+  // Nothing but the hash/enforcement snapshot is derived here: no path
+  // evaluation, no allowedPaths read, no report — those still wait for the
+  // classification below to judge the manifest ours.
   const relScopePath = path.relative(repoRoot, scopePath) || scopePath;
   const currentScopeState = {
     hash: createHash('sha1').update(raw).digest('hex').slice(0, 16),
@@ -863,6 +881,73 @@ async function main() {
     gateOn: scope ? scope?.gates?.['bash-write-verify'] !== false : true,
   };
 
+  // G3b (#1153 P1) — is this manifest even MINE?
+  //
+  // `wave-scope.json` is a WORKING-COPY artefact; two live sessions in one
+  // checkout read the same bytes. Everything below this point — the path
+  // report, the control-file notice, the snapshot — describes THIS session's
+  // relationship to a wave plan. When the manifest provably names another
+  // session, none of it is about us, and the advisories were a peer's
+  // `allowedPaths` scolding an unrelated session (#1082 / #1123).
+  //
+  // Deliberately AFTER the parse: an unparseable manifest leaves `scope === null`,
+  // which classifies as `'unknown'` and keeps every pre-#1153 behaviour —
+  // including the #938 tamper notices, which must never be reachable via a
+  // manifest a Bash call just corrupted. `'own'` and `'unknown'` (legacy,
+  // unbound, or no resolvable own identity) fall through unchanged.
+  //
+  // CEILING (BV-004): on a harness that supplies no session id at all (Codex
+  // 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
+      // append cannot be lost to the process exiting.
+      try {
+        const { emitEvent } = await import('../scripts/lib/events.mjs');
+        await emitEvent(
+          'orchestrator.scope.foreign_session_ignored',
+          {
+            hook: 'post-bash-write-verify',
+            manifest: scopePath,
+            manifest_session: manifestIds,
+            own_session: [...ownIds],
+            wave: scope?.wave,
+          },
+          { repoRoot },
+        );
+      } catch { /* observability is best-effort — never blocks the decision */ }
+
+      // The stand-down itself is a control-file event when the binding CHANGED
+      // since the last call: the manifest this session was baselined against is
+      // now bound to someone else, which switches every scope gate off. Reported
+      // on the visible channel exactly once — the snapshot below records the new
+      // hash, so a stable foreign manifest (an ordinary peer wave) is silent from
+      // the next call on, and a rebind back to us reports again.
+      if (prevScopeState
+        && prevScopeState.hash !== 'absent'
+        && prevScopeState.hash !== currentScopeState.hash) {
+        writeSnapshot(snapFile, { ...carriedRecord, scopeState: currentScopeState });
+        emitMessages([
+          `bash-write-verify: control file ${relScopePath} changed its SESSION BINDING `
+          + `since the last Bash call (now names ${manifestIds.join(', ') || 'an unnamed session'}) — `
+          + 'this session\'s scope gates are standing down. '
+          + 'Scope-control changes are never exempt from reporting (#938).',
+        ], true);
+      }
+      return;
+    }
+  }
+
+  // ADVERSARIAL CEILING: `wave-scope.json` is a file ANY process in this working
+  // copy can write, so writing a foreign id into it is a per-file kill switch for
+  // this session's own gate. Accepted because "no manifest" already means allow
+  // (G3), so a foreign manifest grants nothing an `rm` would not — but the change
+  // MUST stay visible: see post-bash-write-verify's control-file notice (#938),
+  // which is the only thing that distinguishes this from a legitimate peer wave.
+
   let scopeMtimeMs = null;
   try {
     scopeMtimeMs = statSync(scopePath).mtimeMs;