session-orchestrator 3.22.0 → 3.23.0

package/hooks/on-session-start.mjs

@@ -52,6 +52,8 @@ import {
 } from '../scripts/lib/session-registry.mjs';
 import { detectColdStart, consumeMarker } from '../scripts/lib/cold-start-detector.mjs';
 import { parseSessionId } from '../scripts/lib/session-id.mjs';
+import { readTelemetryState, resolveConsent, isCiEnv } from '../scripts/lib/telemetry/consent.mjs';
+import { loadOwnerConfig } from '../scripts/lib/owner-yaml.mjs';
 
 const execFileAsync = promisify(execFile);
 
@@ -79,6 +81,19 @@ const execFileAsync = promisify(execFile);
 // re-introduce the bug.
 const bannerLines = [];
 
+/**
+ * Coordinator-directed context for the single end-of-hook flush (#1138).
+ *
+ * The banner above is for the OPERATOR (`systemMessage`); this is for the
+ * MODEL (`hookSpecificOutput.additionalContext`). Both leave in the SAME JSON
+ * object for the same reason the banner was consolidated: Claude Code surfaces
+ * only the FIRST JSON object a SessionStart hook writes to stdout, so a second
+ * `writeSync` would be silently discarded.
+ *
+ * @type {string|null}
+ */
+let pendingAdditionalContext = null;
+
 /**
  * Queue one or more banner lines for the single end-of-hook flush.
  * @param {string|null|undefined} line — multi-line strings are pushed verbatim
@@ -89,7 +104,46 @@ function pushBanner(line) {
 }
 
 /**
- * Emit every queued banner line as ONE systemMessage envelope.
+ * Render a session id compactly for a banner line.
+ *
+ * Semantic ids (`main-2026-08-23-deep-1`) are already short and are printed
+ * verbatim — they carry the branch and the mode, which is exactly what an
+ * operator needs to recognise a peer. A UUID (Claude Code's `session_id` on
+ * hosts where no semantic id was resolved) is truncated to its first 8 chars:
+ * long enough to disambiguate the handful of peers a repo can have, short
+ * enough that three of them fit on one banner line.
+ *
+ * Ceiling: 8 chars is ~4 billion values against at most a few dozen live
+ * sessions per host — revisit only if two peers ever collide in a banner.
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+function shortSessionId(id) {
+  if (typeof id !== 'string' || id.length === 0) return '?';
+  return id.length > 24 ? id.slice(0, 8) : id;
+}
+
+/**
+ * Queue the ONE `additionalContext` string for the single end-of-hook flush.
+ * Last writer wins; there is deliberately no accumulation, because every
+ * character here costs context on every session start.
+ * @param {string|null|undefined} text
+ */
+function setAdditionalContext(text) {
+  if (typeof text !== 'string' || text.length === 0) return;
+  pendingAdditionalContext = text;
+}
+
+/**
+ * Emit the queued banner lines AND any queued additionalContext as ONE JSON
+ * envelope.
+ *
+ * Both keys are valid siblings of one hook-output object: the shipped Claude
+ * Code binary (v2.1.241) documents `systemMessage` ("Display a message to the
+ * user (all hooks)") and `hookSpecificOutput.additionalContext` ("Text injected
+ * into model context") as fields of the same "Hook JSON Output" object, and its
+ * output validator recognises both keys on that one object.
  *
  * Uses `fs.writeSync(1, …)` rather than `console.log`: the top-level guard
  * calls `process.exit(0)`, which discards anything still sitting in libuv's
@@ -101,11 +155,22 @@ function pushBanner(line) {
  * Idempotent: a second call after a flush is a no-op.
  */
 function flushBanner() {
-  if (bannerLines.length === 0) return;
-  const payload = JSON.stringify({ systemMessage: bannerLines.join('\n') });
+  const hasBanner = bannerLines.length > 0;
+  const hasContext = typeof pendingAdditionalContext === 'string' && pendingAdditionalContext.length > 0;
+  if (!hasBanner && !hasContext) return;
+
+  const envelope = {};
+  if (hasBanner) envelope.systemMessage = bannerLines.join('\n');
+  if (hasContext) {
+    envelope.hookSpecificOutput = {
+      hookEventName: 'SessionStart',
+      additionalContext: pendingAdditionalContext,
+    };
+  }
   bannerLines.length = 0;
+  pendingAdditionalContext = null;
   try {
-    writeSync(1, `${payload}\n`);
+    writeSync(1, `${JSON.stringify(envelope)}\n`);
   } catch { /* stdout closed — the hook is informational and never blocks */ }
 }
 
@@ -349,6 +414,10 @@ async function resolveSessionId(input, projectRoot) {
  *
  * Returns the candidate string on success, null on any failure. Never throws.
  *
+ * Contract (#1066, "Minimal"): the semantic id is a best-effort, host-wide
+ * monotonic LABEL, never an ownership key — ownership stays `(raw session_id,
+ * owner proof)`, and the two identity forms are never interchangeable.
+ *
  * Used by both branches of resolveSessionId() so the semantic_session_id
  * field on the session.lock is consistently populated regardless of whether
  * the SessionStart stdin payload provided a UUID (Claude Code) or nothing
@@ -359,7 +428,7 @@ async function resolveSessionId(input, projectRoot) {
  */
 async function deriveSemanticCandidate({ projectRoot, mode }) {
   try {
-    const { resolveSemanticSessionId } = await import('../scripts/lib/session-id.mjs');
+    const { resolveSemanticSessionId, parseSessionId } = await import('../scripts/lib/session-id.mjs');
     const { discoverActiveSessions } = await import('../scripts/lib/session-discovery.mjs');
     const { execSync } = await import('node:child_process');
 
@@ -387,10 +456,28 @@ async function deriveSemanticCandidate({ projectRoot, mode }) {
       discoverActiveSessions(projectRoot).catch(() => []),
       readRegistry().catch(() => []),
     ]);
-    const registrySessions = registryEntries.map((r) => ({
-      sessionId: r.session_id,
-      mode: r.mode ?? 'session',
-    }));
+
+    // Registry census (#1066 AC1): the registry keeps the two identity forms in
+    // SEPARATE fields — `session_id` is the RAW id (a UUID on Claude Code) and
+    // `semantic_session_id` is the label. resolveSemanticSessionId counts only
+    // semantic candidates, so projecting `session_id` alone made the host-wide
+    // registry contribute NOTHING to the n-increment, and two sessions on one
+    // host could mint the same label. Preference order per entry:
+    //   1. `semantic_session_id`, when it parses as semantic;
+    //   2. `session_id`, ONLY when it itself parses as semantic (Codex/Cursor
+    //      may write a semantic raw id).
+    // A legacy v1 entry (no `semantic_session_id`, UUID `session_id`) matches
+    // neither and is dropped — a UUID is never reintroduced as a candidate.
+    const semanticLabelOf = (entry) => {
+      for (const candidate of [entry?.semantic_session_id, entry?.session_id]) {
+        if (parseSessionId(candidate)?.format === 'semantic') return candidate;
+      }
+      return null;
+    };
+    const registrySessions = registryEntries.flatMap((r) => {
+      const label = semanticLabelOf(r);
+      return label === null ? [] : [{ sessionId: label, mode: r.mode ?? 'session' }];
+    });
     const activeSessions = [...localSessions, ...registrySessions];
 
     return await resolveSemanticSessionId({
@@ -467,6 +554,60 @@ async function emitHostBanner(projectRoot) {
   }
 }
 
+/**
+ * The one-time telemetry-consent instruction handed to the coordinator (#1138).
+ *
+ * Deliberately terse: it is injected into the model context on EVERY session
+ * start until the operator decides, so every character is a recurring cost.
+ * It names the phase rather than restating it, so the AUQ wording stays
+ * single-sourced in `skills/session-start/SKILL.md` § Phase 6.8.
+ */
+const CONSENT_NUDGE =
+  'Telemetrie-Consent ist auf diesem Host unentschieden. Stelle JETZT, vor jeder anderen Arbeit, '
+  + 'genau einmal die consent-neutrale AskUserQuestion aus skills/session-start/SKILL.md § Phase 6.8 '
+  + '(zwei Optionen, keine "(Recommended)"-Markierung; Codex/Cursor: nummerierte Liste) und rufe danach '
+  + 'grantConsent() bzw. denyConsent() aus scripts/lib/telemetry/consent.mjs. Danach nie wieder fragen.';
+
+/**
+ * #1138 — queue the consent nudge when, and only when, this host has no
+ * telemetry decision on record.
+ *
+ * WHY A HOOK AT ALL. Phase 6.8 was prose only: it fired when the coordinator
+ * happened to reach line ~1060 of a 1230-line skill, after 24 other phases.
+ * Measured 2026-08-23: 0 records from any host other than the author's.
+ *
+ * WHY `isCiEnv` AND NOT `isHeadless`. `isHeadless()` answers "can THIS process
+ * prompt on a TTY?" — and this process is a hook whose stdout is a pipe, so it
+ * would answer `true` unconditionally and the nudge could never fire. Measured
+ * in a plain non-TTY subprocess on this host, 2026-08-23:
+ *   `isHeadless()=true isCiEnv()=false stdout.isTTY=undefined`
+ * The question that actually matters here is a different one: "is there an
+ * operator who can answer an AskUserQuestion?" The prompting happens in the
+ * live session, not in this process, so TTY-ness of the hook is irrelevant and
+ * `isCiEnv()` — the fail-closed "this is unattended automation" probe — is the
+ * correct gate. (The same trap sits in the Phase 6.8 prose, which passes
+ * `interactive: !isHeadless()` from a `node -e` subprocess whose stdout is also
+ * a pipe: it would have resolved `prompt:false` every time even if executed.)
+ *
+ * `resolveConsent` remains the single decision point: `prompt` is true only for
+ * a host with no stored decision, no env override, and no fleet flag.
+ *
+ * Never throws — a failure here must not affect session start.
+ */
+function maybeQueueConsentNudge() {
+  try {
+    if (isCiEnv(process.env)) return;
+    const consent = resolveConsent({
+      env: process.env,
+      ownerConfig: loadOwnerConfig().config,
+      state: readTelemetryState().record,
+      interactive: true,
+    });
+    if (consent.prompt !== true) return;
+    setAdditionalContext(CONSENT_NUDGE);
+  } catch { /* best effort — the nudge is informational, never blocks */ }
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -699,16 +840,74 @@ async function main() {
       const allActive = await discoverActiveSessions(projectRoot);
       const mechanicalPeers = allActive.filter((s) => s.sessionId !== sessionId);
       if (mechanicalPeers.length > 0) {
+        // #1137 part 1 — say WHERE, not just how many. discoverActiveSessions()
+        // walks EVERY path `git worktree list` reports, which includes worktrees
+        // another coordinator parked outside this working copy (e.g. under
+        // /private/tmp/…). Measured 2026-08-23: all 4 reported "peers" were the
+        // 4 registered worktrees, none of them in this checkout — and the old
+        // wording ("active in same repo") read as 4 sessions competing for THIS
+        // directory. The surface is deliberately unchanged (a foreign-worktree
+        // session IS a peer of this repo); only the label and the per-peer
+        // detail are, so the operator can tell the two apart at a glance.
         const summary = mechanicalPeers
           .slice(0, 3)
-          .map((p) => `${p.sessionId}:${p.mode ?? 'session'}`)
+          .map((p) => {
+            const where = p.worktreePath ? path.basename(p.worktreePath) : '?';
+            // #1151 — carry the peer's MODE when the source recorded one.
+            // `worktree:id` says where a peer sits but not what it is doing,
+            // and the operator's next decision (wait / promote / proceed)
+            // turns on exactly that: a `deep` peer holding this worktree set
+            // is a different situation from a `discovery` one. Guarded rather
+            // than assumed — sessionFromLock() passes `lock.mode` verbatim, so
+            // a lock written without the field yields undefined here, while
+            // sessionFromRegistryEntry() always defaults it to 'session'.
+            const mode = typeof p.mode === 'string' && p.mode.length > 0 ? `:${p.mode}` : '';
+            return `${where}:${shortSessionId(p.sessionId)}${mode}`;
+          })
           .join(', ');
         const overflow = mechanicalPeers.length > 3 ? ` +${mechanicalPeers.length - 3} more` : '';
-        pushBanner(`🔍 Mechanical peer-detection: ${mechanicalPeers.length} active in same repo (${summary}${overflow})`);
+        pushBanner(`🔍 Mechanical peer-detection: ${mechanicalPeers.length} active in this repo's worktree set (${summary}${overflow})`);
       }
     } catch { /* best effort — banner is informational, never blocks */ }
   }
 
+  // Phase 4 measurement probes — the mechanical caller (#1128).
+  //
+  // `skills/session-start/SKILL.md` § Phase 4 names 18 probes with module paths
+  // and entry functions. Measured 2026-08-23 at `4f6404e`, 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,
+  // never wired.
+  //
+  // Placement is deliberate: AFTER the backfill (so `sessions-staleness` and
+  // `sessions-integrity` measure the reconstructed ledger, not the stale one)
+  // and BEFORE flushBanner() (so probe findings ride the single systemMessage
+  // envelope instead of adding a second stdout object Claude Code would
+  // discard — see the bannerLines docstring and HR-106).
+  //
+  // Best-effort exactly like `backfillOnSessionStart` above: the runner has no
+  // rejecting path of its own, and this try/catch is defence-in-depth so a
+  // future regression inside it still cannot block a session start.
+  // Escape hatch: SO_DISABLE_STARTUP_PROBES=1.
+  //
+  // `enable-host-banner: false` silences the DISPLAY, never the MEASUREMENT.
+  // The documented opt-out ("a user who silenced session-start banners has
+  // opted out of ALL session-start banners") governs `pushBanner` and nothing
+  // else: the probes still run and `orchestrator.probes.completed` is still
+  // written, because the defect this wiring repairs is precisely that nobody
+  // could tell whether the probes had ever run (HR-105). Gating the run on a
+  // display preference would rebuild that blind spot behind a config key.
+  if (process.env.SO_DISABLE_STARTUP_PROBES !== '1') {
+    try {
+      const { runSessionStartProbes } = await import('../scripts/lib/session-start-probes.mjs');
+      const probeRun = await runSessionStartProbes({ repoRoot: projectRoot });
+      if (bannerData) {
+        for (const line of probeRun.bannerLines) pushBanner(line);
+      }
+    } catch { /* hook must remain non-blocking */ }
+  }
+
   const payload = {
     platform,
     project: projectName,
@@ -738,6 +937,10 @@ async function main() {
   }
   await emitEvent('orchestrator.session.started', payload);
 
+  // #1138 — one-time telemetry-consent nudge. Queued (never written) here so it
+  // rides the single stdout envelope below.
+  maybeQueueConsentNudge();
+
   // Single flush — see the bannerLines docstring for why this must stay the
   // only stdout write in the hook.
   flushBanner();

package/hooks/on-stop.mjs

@@ -16,7 +16,8 @@
  * 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":"...","wave":<int>,"branch":"...","commit":"...","duration_ms":<int>}
+ *   Stop:        {"timestamp":<ISO>,"event":"orchestrator.session.stopped","session_id":"...","semantic_session_id":"...","wave":<int>,"branch":"...","commit":"...","duration_ms":<int>}
+ *                (`session_id` / `semantic_session_id` are omitted when unresolvable — #1068 AC1.)
  *   SubagentStop: {"timestamp":<ISO>,"event":"orchestrator.agent.stopped","agent":"<name>"}
  */
 
@@ -29,6 +30,7 @@ if (!shouldRunHook('on-stop')) process.exit(0);
 
 import { emitEvent } from '../scripts/lib/events.mjs';
 import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+import { parseSessionId } from '../scripts/lib/session-id.mjs';
 import { heartbeat, logSweepEvent } from '../scripts/lib/session-registry.mjs';
 import { updateHeartbeat } from '../scripts/lib/session-lock.mjs';
 
@@ -216,17 +218,39 @@ async function readWaveNumber(projectRoot) {
 // ---------------------------------------------------------------------------
 
 /**
- * Resolve this session's id. Stdin payload wins. If Claude Code did not pass
- * one (Codex / Cursor paths, or older harnesses), fall back to
- * `.orchestrator/current-session.json` which on-session-start.mjs writes.
+ * Resolve this session's id + its attested semantic id. A stdin payload id wins
+ * ONLY when it parses as a UUID. If Claude Code did not pass one (Codex /
+ * Cursor paths, or older harnesses) — or passed something that is not a UUID —
+ * fall back to `.orchestrator/current-session.json` which on-session-start.mjs
+ * writes.
+ *
+ * #1091 / Kanevry#66 — WRITER/READER SYMMETRY, same defect class as
+ * `hooks/on-session-end.mjs`: `on-session-start.mjs` accepts a stdin raw id
+ * only when `parseSessionId(fromStdin)?.format === 'uuid'` and otherwise mints
+ * a `randomUUID()`, so every artifact this hook then addresses by id (the host
+ * registry entry, `session.lock`) is keyed by a UUID. Passing a non-UUID stdin
+ * string through meant `heartbeat()` and `updateHeartbeat()` addressed a key
+ * that was never written: the registry entry silently went un-refreshed (and
+ * aged into the zombie sweep) while the lock heartbeat no-oped on an ownership
+ * mismatch.
+ *
+ * `semanticSessionId` (#1068 AC1) is read from the SAME file and is deliberately
+ * gated on the resolved id BEING the recorded one — `current-session.json` is a
+ * single repo-global file describing whichever session most recently ran
+ * SessionStart, so an unrelated window's turn-end must not inherit a live
+ * peer's semantic identity (the #863 defect (c) contamination shape, mirrored
+ * here from `hooks/on-session-end.mjs`).
  *
  * @param {object|null} input
  * @param {string} projectRoot
- * @returns {Promise<string|null>}
+ * @returns {Promise<{sessionId: string|null, semanticSessionId: string|null}>}
  */
 async function resolveSessionId(input, projectRoot) {
   const fromStdin = input?.session_id ?? input?.sessionId ?? null;
-  if (typeof fromStdin === 'string' && fromStdin.length > 0) return fromStdin;
+  let sessionId = parseSessionId(fromStdin)?.format === 'uuid' ? fromStdin : null;
+
+  let recordedId = null;
+  let semanticSessionId = null;
   try {
     const raw = await fs.readFile(
       path.join(projectRoot, '.orchestrator', 'current-session.json'),
@@ -234,10 +258,20 @@ async function resolveSessionId(input, projectRoot) {
     );
     const parsed = JSON.parse(raw);
     if (typeof parsed.session_id === 'string' && parsed.session_id.length > 0) {
-      return parsed.session_id;
+      recordedId = parsed.session_id;
+    }
+    if (typeof parsed.semantic_session_id === 'string' && parsed.semantic_session_id.length > 0) {
+      semanticSessionId = parsed.semantic_session_id;
     }
   } catch { /* missing or unparseable is fine */ }
-  return null;
+
+  if (sessionId === null) sessionId = recordedId;
+
+  const isRecordedSession = sessionId !== null && sessionId === recordedId;
+  return {
+    sessionId,
+    semanticSessionId: isRecordedSession ? semanticSessionId : null,
+  };
 }
 
 /**
@@ -250,7 +284,7 @@ async function handleStop(input) {
   const wave = await readWaveNumber(projectRoot);
   const { commit, branch } = await gitInfo(projectRoot);
 
-  const sessionId = await resolveSessionId(input, projectRoot);
+  const { sessionId, semanticSessionId } = await resolveSessionId(input, projectRoot);
 
   // v3.1.0 multi-session registry (#169), corrected in #1047 — REFRESH the
   // registry entry here; never remove it.
@@ -323,8 +357,13 @@ async function handleStop(input) {
   // Single emission path: emitEvent writes the canonical {timestamp, event, ...payload}
   // JSONL record AND fires the optional Clank webhook with the SAME event name — no
   // more bare-`stop` (JSONL) vs dotted-`stopped` (webhook) divergence.
+  // #1068 AC1 — carry the attested semantic id alongside the raw UUID so a
+  // turn-end outcome is joinable by identity from events.jsonl alone. Omitted
+  // (never `""`/`null`) when unattested: an unresolved identity stays visibly
+  // unresolved rather than becoming a guessed id.
   await emitEvent('orchestrator.session.stopped', {
     ...(sessionId !== null ? { session_id: sessionId } : {}),
+    ...(semanticSessionId !== null ? { semantic_session_id: semanticSessionId } : {}),
     wave,
     ...(branch !== null ? { branch } : {}),
     ...(commit !== null ? { commit } : {}),

package/hooks/post-subagent-discovery-validator.mjs

@@ -30,6 +30,19 @@
  * Why read the transcript: the SubagentStop stdin payload has NO output_text
  * field. The agent's text lives in `input.transcript_path`.
  *
+ * Output channels — THREE writes, TWO different recipients:
+ *   - `discovery_validator_violation` in .orchestrator/metrics/events.jsonl,
+ *     and the stderr WARN → the COORDINATOR's only copy of the finding. PSA-006
+ *     makes REJECTING the unverified claim his duty, so these two are the
+ *     channels that carry the rule's enforcement path.
+ *   - stdout `hookSpecificOutput.additionalContext` → the STOPPING SUBAGENT
+ *     (which continues and may self-correct), NOT the coordinator — a hook is
+ *     structurally unable to address him. See the measured delivery note at the
+ *     hookSpecificOutput write below for the shipped-binary evidence.
+ *   All three are pinned together by the "all three channels fire" test in
+ *   tests/hooks/post-subagent-discovery-validator.test.mjs — do not collapse
+ *   the coordinator-visible pair into additionalContext.
+ *
  * Exit codes: 0 always (informational, never blocking).
  */
 
@@ -594,12 +607,30 @@ async function main() {
   }
 
   if (alreadyWarned) {
-    // Events logged above; suppress additionalContext to prevent coordinator loop.
+    // Events logged above; suppress the repeat additionalContext for this
+    // already-warned real context. (Recipient is the stopping subagent, not the
+    // coordinator — see the delivery note at the hookSpecificOutput write below.)
     return;
   }
 
-  // v2.1.163+ additionalContext: feed the warning back to the coordinator turn
-  // so the finding is visible inline, not just in stderr + events.jsonl.
+  // v2.1.163+ additionalContext: surface the finding inline, not just in
+  // stderr + events.jsonl.
+  //
+  // The recipient is the SUBAGENT that just stopped — NOT the coordinator.
+  // Measured in the shipped binary (Claude Code 2.1.241, 2026-08-23): the
+  // SubagentStop hookSpecificOutput schema reads "additionalContext is
+  // non-error feedback delivered to the subagent; the subagent continues so it
+  // can act on it", and the emitter picks its target with
+  // `i.agentId ? "SubagentStop" : "Stop"`, yielding a `hook_additional_context`
+  // message into that agent's own loop. So this text lands in the transcript of
+  // the agent whose claims it is about, one moment after that agent is done.
+  //
+  // Worth knowing before "fixing" the path: PSA-006 asks the COORDINATOR to
+  // reject unverified distributional claims, and this channel never reaches
+  // him. His copy of the finding is events.jsonl + stderr, not this write.
+  // Whether he SHOULD receive it is a product question (#1116) — changing the
+  // route is not a comment edit.
+  //
   // Non-blocking — exit 0 always. Decision:"block" must never be set here.
   process.stdout.write(JSON.stringify({
     hookSpecificOutput: {

package/hooks/post-tool-batch-wave-signal.mjs

@@ -41,6 +41,7 @@ if (!shouldRunHook('post-tool-batch-wave-signal')) process.exit(0);
 
 import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
 import { emitEvent } from '../scripts/lib/events.mjs';
+import { findScopeFile } from '../scripts/lib/scope-gate.mjs';
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -135,17 +136,25 @@ async function resolveSessionIdForHeartbeat(input, sessionFile) {
 }
 
 /**
- * Resolve the current wave number from .claude/wave-scope.json `.wave`.
+ * Resolve the current wave number from the wave-scope manifest's `.wave`.
  * Returns 0 when the file is absent or unparseable, mirroring the
  * pre-bash-memory-propose-audit.mjs G5 precedent ("wave defaults to 0 when
  * wave-scope.json absent"). The file is deleted mid-session at Quality phase
  * transitions and final cleanup, so absence is an expected, non-error state.
  *
+ * The manifest is located via `findScopeFile()` (#1082), the same precedence
+ * every other consumer uses — `.pi` > `.cursor` > `.codex` > `.claude`. The
+ * previous hard-coded `.claude/` path made this hook's whole wave-lifecycle
+ * fallback structurally dead on Codex CLI, Cursor and pi: the manifest exists,
+ * it just is not under `.claude/`, so every batch read 0 and no
+ * `orchestrator.wave.started`/`completed` event was ever emitted there.
+ *
  * @param {string} projectDir
  * @returns {Promise<number>}
  */
 async function resolveWaveNumber(projectDir) {
-  const waveFile = path.join(projectDir, '.claude', 'wave-scope.json');
+  const waveFile = findScopeFile(projectDir);
+  if (waveFile === null) return 0;
   try {
     const raw = await readFile(waveFile, 'utf8');
     const data = JSON.parse(raw);