session-orchestrator 3.23.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/enforce-scope.mjs

@@ -9,10 +9,12 @@
  *   G1  tool filter — only Edit/Write/MultiEdit are gated
  *   G2  file_path present + string
  *   G3  wave-scope.json exists
- *   G3b (#1123) the manifest belongs to THIS session — a manifest that
+ *   G3b (#1123, #1194) the manifest belongs to THIS session — a manifest that
  *       PROVABLY names another live session in this shared working copy is not
  *       ours to enforce; allow + emit one event. Runs AFTER the parse so a
- *       corrupt manifest still fails closed.
+ *       corrupt manifest still fails closed. Identity is PROCESS-LOCAL only
+ *       (hook payload + CLAUDE_CODE_SESSION_ID), never the repo-global
+ *       `session.lock` — see the gate's own block for why.
  *   G4  path-guard gate enabled
  *   G5  enforcement != "off"
  *   G5b (#792) allowlist-first: an EXPLICIT absolute allowedPaths entry that
@@ -102,8 +104,10 @@ let readJson;
 let classifyEmptyScope;
 let suggestForEmptyScope;
 let sessionStartedAtMs;
-// #1123 — "is this manifest even mine?" (G3b).
-let readOwnSessionIds;
+// #1123 — "is this manifest even mine?" (G3b). Process-local identity only
+// (#1194): the repo-global `session.lock` tier is shared by every session in the
+// checkout and would classify a peer's manifest as ours.
+let readProcessLocalSessionIds;
 let classifyManifestSession;
 
 const PLUGIN_ROOT = path.resolve(import.meta.dirname, '..');
@@ -180,7 +184,7 @@ async function bootstrap() {
   ({ findScopeFile, pathMatchesPattern, suggestForScopeViolation } = modules.hardening);
   ({ readJson } = modules.common);
   ({ classifyEmptyScope, suggestForEmptyScope, sessionStartedAtMs } = modules.scopeGate);
-  ({ readOwnSessionIds, classifyManifestSession } = modules.sessionIdentity);
+  ({ readProcessLocalSessionIds, classifyManifestSession } = modules.sessionIdentity);
 }
 
 async function main() {
@@ -251,13 +255,38 @@ async function main() {
   // without a `session` field is `'unknown'` and stays enforced: only what is
   // PROVABLY foreign is treated as foreign.
   //
+  // IDENTITY TIER (#1194): `readProcessLocalSessionIds` — the hook payload and
+  // `CLAUDE_CODE_SESSION_ID` — and deliberately NOT `readOwnSessionIds`, whose
+  // third tier is the repo-global `session.lock`. That lock is ONE file shared
+  // by every session in the checkout, so unioning it made a peer's manifest
+  // match a peer-written lock id and classify as `'own'`: Gate 7 then denied the
+  // second session's legitimate writes — the exact lockout G3b exists to end.
+  // A better signal REPLACES a worse one (`host-resources.md` § HR-102).
+  //
+  // The trade this buys, accepted rather than hidden: a session that wrote a
+  // PEER's id into its OWN manifest (it lost the `bootstrapLock()` race, so
+  // `sessionAttribution()` handed it the peer's lock id) now reads `'foreign'`
+  // and its own guard stands down. The defense is on the WRITER side — the
+  // manifest writer must omit the `session` keys when the lock does not name it
+  // (`skills/wave-executor/wave-loop.md` § Scope Manifest, "Verify the binding
+  // names YOU before you write it") — not on this reader.
+  //
+  // 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 G3b is permanently `'unknown'` = enforce = pre-#1123 behaviour
+  // there. Revisit when Codex/Cursor hook payloads carry a session id.
+  //
   // ACCEPTED RESIDUAL, named rather than hidden: `session` is a plain field in a
   // file any process in this working copy can write, so writing a foreign id
   // into it switches this guard off for that manifest. That is the SAME power
   // `enforcement: "off"` already grants in the same file — this gate adds no new
   // authority, and the manifest is the coordinator's own artefact either way.
   {
-    const ownIds = readOwnSessionIds(projectRoot, { hookInput: input });
+    // `new Set(...)` is load-bearing: `readProcessLocalSessionIds` returns a
+    // string[], and `classifyManifestSession` does `ownIds instanceof Set ?
+    // ownIds : new Set()` — a bare array would silently become EMPTY, making
+    // every manifest read `unknown`.
+    const ownIds = new Set(readProcessLocalSessionIds({ hookInput: input }));
     const { verdict, manifestIds } = classifyManifestSession(scope, ownIds);
     if (verdict === 'foreign') {
       // Observability only, and deliberately NOT emitWarn: this branch is hit on

package/hooks/hooks-codex.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v3.23.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.23.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

@@ -11,7 +11,12 @@
  *
  * JSONL format (`.orchestrator/metrics/events.jsonl`):
  *   {"timestamp":<ISO>,"event":"orchestrator.session.ended","session_id":"...","semantic_session_id":"...","reason":"<reason>","duration_ms":<int>}
- *   (`session_id` / `semantic_session_id` are omitted when unresolvable — #1068 AC1.)
+ *   (`session_id` / `semantic_session_id` are omitted when unresolvable — #1068 AC1.
+ *    `duration_ms` likewise: it is written ONLY when the ending session IS the
+ *    one `current-session.json` records AND a start timestamp parsed. A
+ *    fabricated `0` reads as a measured zero-length session and is
+ *    indistinguishable from one — 1082 of 1498 fleet records (72,2 %) carried
+ *    exactly that zero, measured 2026-09-02. Omit, never fabricate.)
  *
  * Exit codes: 0 always (informational hook — must never block session teardown).
  * stdin: optional JSON { hook_event_name:"SessionEnd", session_id?, reason?, cwd? }.
@@ -30,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,
@@ -46,6 +51,7 @@ import { deregisterSelf, logSweepEvent } from '../scripts/lib/session-registry.m
 import { readConfigFile, parseSessionConfig } from '../scripts/lib/config.mjs';
 import { flush } from '../scripts/lib/telemetry/sync.mjs';
 import { attemptLockReconciliation } from './_lib/lock-reconcile.mjs';
+import { atomicMutateJson } from './_lib/atomic-json.mjs';
 
 // ---------------------------------------------------------------------------
 // stdin reading (inline — SessionEnd hooks exit 0 always, never deny)
@@ -84,6 +90,9 @@ async function readStdinJson() {
  * `.orchestrator/current-session.json` (written by on-session-start.mjs).
  * duration_ms is only computed when the ENDING session is the one recorded in
  * current-session.json — never fabricated for a mismatched / unknown session.
+ * Not measurable ⇒ `durationMs: null`, and the caller then OMITS the key
+ * entirely (#1193 W5 F1, the last site of the omit-never-fabricate class this
+ * session removed from `session.stopped` and `agent.stopped`).
  *
  * #1091 / Kanevry#66 — WRITER/READER SYMMETRY. `on-session-start.mjs`
  * (`resolveSessionId`, :316-317) accepts a stdin raw id only when
@@ -114,14 +123,42 @@ async function readStdinJson() {
  * session therefore resolves `semanticSessionId: null` rather than inheriting
  * another live session's backfill identity.
  *
+ * #1193 W4a review F-A — `isRecordedSession` is computed from the RAW stdin
+ * UUID, NEVER from the resolved `sessionId`. The old order was
+ * `if (sessionId === null) sessionId = recordedId;` followed by
+ * `sessionId === recordedId`, which is SELF-FULFILLING: whenever stdin carried
+ * no session_id (or a non-UUID one), the fallback assigned the file's own id
+ * and the compare then trivially succeeded. Reproduced twice 2026-09-02 —
+ * peer-owned `current-session.json` (`last_wave: 3`) plus stdin
+ * `{"reason":"other"}` emitted `wave.completed` for the PEER's wave and wrote
+ * `last_wave_completed: 3` into the PEER's file, after which the peer's own
+ * SessionEnd stayed silent. The same vacuous predicate had always gated
+ * `durationMs` and `semanticSessionId`, so the #863 guard was hollow on that
+ * path too. One root fix (BV-003) for all three consumers: a `null` raw id
+ * means "not attestable" ⇒ `false`.
+ *
+ * WHY `sessionId` STILL FALLS BACK while the predicate does not. The two are
+ * deliberately asymmetric. `sessionId` is the hook's ACTOR identity — the id
+ * `deregisterSelf()` and the lock-release ownership compare use, and its
+ * current-session.json fallback is a named contract pinned by
+ * `tests/hooks/on-session-end.test.mjs` ("falls back to current-session.json
+ * session_id when stdin omits it"). `isRecordedSession` is an OWNERSHIP
+ * ASSERTION about a repo-global file; an assertion may never be derived from
+ * the very value it is asserting about. So the fallback stays for the emitted
+ * `session_id` field, and every claim that speaks FOR the recorded session
+ * (`duration_ms`, `semantic_session_id`, the final `wave.completed`) is gated
+ * on the strict raw compare instead. Precedent: `hooks/on-stop.mjs`
+ * `resolveStopDuration()`, which refuses the resolved id for the same reason.
+ *
  * @param {object|null} input
  * @param {string} projectRoot
- * @returns {Promise<{sessionId: string|null, semanticSessionId: string|null, durationMs: number}>}
+ * @returns {Promise<{sessionId: string|null, semanticSessionId: string|null, durationMs: number|null, isRecordedSession: boolean, rawStdinId: string|null}>}
  */
 async function resolveSession(input, projectRoot) {
   const fromStdin = input?.session_id ?? input?.sessionId ?? null;
   // UUID-only, exactly as the writer decides it (see the docblock above).
-  let sessionId = parseSessionId(fromStdin)?.format === 'uuid' ? fromStdin : null;
+  const rawStdinId = parseSessionId(fromStdin)?.format === 'uuid' ? fromStdin : null;
+  let sessionId = rawStdinId;
 
   let recordedId = null;
   let semanticSessionId = null;
@@ -144,13 +181,17 @@ async function resolveSession(input, projectRoot) {
     }
   } catch { /* missing or unparseable is fine */ }
 
+  // Actor-identity fallback ONLY — see the docblock's asymmetry note. This
+  // value must NEVER feed the ownership predicate below.
   if (sessionId === null) sessionId = recordedId;
 
-  // Only trust the recorded start time when the ending session IS the recorded one.
-  const isRecordedSession = sessionId !== null && sessionId === recordedId;
+  // Only trust the recorded start time when the ending session IS the recorded
+  // one — decided on the RAW stdin id, so an absent/non-UUID id is `false`
+  // rather than self-fulfilling (F-A).
+  const isRecordedSession = rawStdinId !== null && rawStdinId === recordedId;
   const durationMs = startedAtMs !== null && isRecordedSession
     ? Math.max(0, Date.now() - startedAtMs)
-    : 0;
+    : null;
 
   // #863 defect (c) — same guard as durationMs above: only surface the
   // recorded semantic id when THIS ending session is genuinely the one
@@ -158,7 +199,16 @@ async function resolveSession(input, projectRoot) {
   // contamination scenario this closes.
   const resolvedSemanticSessionId = isRecordedSession ? semanticSessionId : null;
 
-  return { sessionId, semanticSessionId: resolvedSemanticSessionId, durationMs };
+  // `rawStdinId` is returned so a LATER read of current-session.json can
+  // re-verify ownership against the same identity (W4c Q1-LOW-TOCTOU) instead
+  // of trusting an attestation made against an earlier read of the file.
+  return {
+    sessionId,
+    semanticSessionId: resolvedSemanticSessionId,
+    durationMs,
+    isRecordedSession,
+    rawStdinId,
+  };
 }
 
 /**
@@ -307,17 +357,206 @@ async function emitBackfillOutcome(kind, result, { sessionId, semanticSessionId
   } catch { /* observability is best-effort */ }
 }
 
+/**
+ * Emit `orchestrator.wave.final_refused` — the SIBLING event to
+ * `orchestrator.wave.completed` for every refusal path inside
+ * {@link emitFinalWaveCompleted} (#1201 Part B / Discovery D8). Deliberately
+ * a separate event name rather than `orchestrator.wave.completed` carrying
+ * `emitted:false`: existing consumers of `.completed` treat every row as a
+ * finished wave, and overloading it would silently corrupt that count.
+ *
+ * Wrapped in its OWN try/catch — independent of the caller's outer
+ * try/catch — so a telemetry failure on ONE refusal path can never surface
+ * as a failure of teardown, matching the best-effort contract every other
+ * emit in this SessionEnd hook already carries.
+ *
+ * @param {{sessionId: string|null, semanticSessionId: string|null}} ids
+ * @param {'not-recorded'|'clear'|'resume'|'unreadable'|'session-id-mismatch'|'no-wave'|'already-completed'|'exception'} reason
+ * @param {number} [waveNumber] - only when `last_wave` was resolved to a
+ *        positive number before the refusal (currently only `already-completed`).
+ * @returns {Promise<void>}
+ */
+async function emitFinalRefused({ sessionId, semanticSessionId }, reason, waveNumber) {
+  try {
+    await emitEvent('orchestrator.wave.final_refused', {
+      ...(sessionId !== null ? { session_id: sessionId } : {}),
+      ...(semanticSessionId !== null ? { semantic_session_id: semanticSessionId } : {}),
+      reason,
+      ...(typeof waveNumber === 'number' ? { wave_number: waveNumber } : {}),
+      emitted_by: 'on-session-end',
+    });
+  } catch { /* best-effort — a refusal record must never itself block teardown */ }
+}
+
+/**
+ * Emit the FINAL `orchestrator.wave.completed` of the session (#1193).
+ *
+ * `hooks/post-tool-batch-wave-signal.mjs` closes wave N-1 only at an N-1→N
+ * transition, so the LAST wave of every session never received a completion —
+ * measured fleet-wide 2026-09-02 as 296 gaps over 296 wave runs (1018 started
+ * vs 722 completed), i.e. EXACTLY one missing final completion per run. The
+ * comment that claimed the coordinator emitted it at session close described a
+ * step that never existed. SessionEnd is that emitter.
+ *
+ * Deliberately SessionEnd-only: `on-stop.mjs` is not mirrored, so the ledger
+ * keeps the closed-vs-abandoned split measurable.
+ *
+ * Idempotent via the `last_wave_completed` high-water mark, written by both
+ * emitters and preserved across clear/compact by `on-session-start.mjs`.
+ * Emits nothing when `last_wave` is absent or 0 — an Express-Path or
+ * coordinator-direct session never batched, and zero waves is the correct
+ * reading there, not a gap.
+ *
+ * OWNERSHIP-GATED (#1193 review F1). `.orchestrator/current-session.json` is a
+ * single repo-global file describing whichever session most recently ran
+ * SessionStart — routinely a DIFFERENT, still-live session when two windows
+ * share this working copy. Emitting unguarded would (a) close a PEER's live
+ * wave with a completion the peer never reached, and (b) write
+ * `last_wave_completed` into the peer's file, so the peer's own SessionEnd then
+ * stays silent — preserving the very #1193 gap this closes, on the wrong
+ * session. So this reuses the SAME `isRecordedSession` predicate
+ * `resolveSession()` applies to `durationMs` and `semanticSessionId` (#863
+ * defect (c)); when it is false, nothing is emitted and nothing is written.
+ *
+ * REASON-GATED for `/clear` AND `resume` (#1193 review F2 + W4c Q3-MED-2). The
+ * SessionEnd matcher is empty, so `/clear` fires this hook mid-wave while the
+ * LOGICAL session continues (`hooks/on-session-start.mjs:383` preserves
+ * `last_wave` / `last_wave_completed` across exactly that). A `resume` is the
+ * SAME class — start preserves the marker across a resume of the same logical
+ * session just as it does across a clear — and resume is the MORE common of the
+ * two (fleet n = 1498 `session.ended`, 2026-09-02: 12 resume vs 9 clear).
+ * Closing the live wave on either is premature, and the preserved marker would
+ * then suppress the real completion later. Fleet `session.ended` reasons, re-measured
+ * 2026-09-02 over every repo's `.orchestrator/metrics/events.jsonl` under
+ * `~/Projects` (glob written as a path segment on purpose — a literal star
+ * followed by a slash would close this comment), except
+ * `EventDrop.at-deps-2026-09` — n = 1335: 1286 other, 27 completed, 12 resume,
+ * 8 clear, 1 error, 1 close. (Same denominator and date as the
+ * `session.ended` row in `docs/audits/2026-09-02-fleet-instruments.md`; the two
+ * disagreed by ~150 before W4a F-F because each counted a different repo set.)
+ *
+ * Strictly best-effort: never throws, never blocks teardown.
+ *
+ * SIX silent refusal paths (#1201 Part B / Discovery D8 — one more than the
+ * issue's original five) previously returned with no trace anywhere: per
+ * `.claude/rules/host-resources.md` § HR-105, a refusal that writes nothing
+ * is unfalsifiable. Every refusal now emits a SIBLING event,
+ * `orchestrator.wave.final_refused`, via {@link emitFinalRefused} — never
+ * `orchestrator.wave.completed` itself with an `emitted:false` flag, because
+ * that event's consumers treat every row as a finished wave (D8's explicit
+ * recommendation). Each emit is wrapped in its OWN try/catch inside
+ * `emitFinalRefused` so telemetry can never block teardown, on top of this
+ * function's own outer catch (which now also emits `reason: 'exception'`,
+ * best-effort).
+ *
+ * @param {string} projectRoot
+ * @param {{sessionId: string|null, semanticSessionId: string|null,
+ *          isRecordedSession: boolean, reason: string,
+ *          rawStdinId: string|null}} ctx
+ * @returns {Promise<{emitted: true, wave_number: number}|{emitted: false, reason: string}>}
+ *          The return value is informational only — every branch has already
+ *          persisted its own outcome via `orchestrator.wave.completed` or
+ *          `orchestrator.wave.final_refused` by the time this resolves.
+ */
+async function emitFinalWaveCompleted(
+  projectRoot,
+  { sessionId, semanticSessionId, isRecordedSession, reason, rawStdinId },
+) {
+  const ids = { sessionId, semanticSessionId };
+  try {
+    // F1 — never speak for a session current-session.json does not describe.
+    if (!isRecordedSession) {
+      await emitFinalRefused(ids, 'not-recorded');
+      return { emitted: false, reason: 'not-recorded' };
+    }
+    // F2 — `/clear` ends the HARNESS session, not the logical one. `resume` is
+    // the SAME class (W4c Q3-MED-2): `on-session-start.mjs` preserves
+    // `last_wave` / `last_wave_completed` across a resume of the same logical
+    // session exactly as it does across a clear, and resume is the MORE common
+    // of the two (fleet n=1498, 2026-09-02: 12 resume vs 9 clear).
+    if (reason === 'clear' || reason === 'resume') {
+      await emitFinalRefused(ids, reason);
+      return { emitted: false, reason };
+    }
+    const sessionFile = path.join(projectRoot, '.orchestrator', 'current-session.json');
+    let parsed = null;
+    try {
+      parsed = JSON.parse(await fs.readFile(sessionFile, 'utf8'));
+    } catch {
+      // absent or malformed → nothing attestable to close
+      await emitFinalRefused(ids, 'unreadable');
+      return { emitted: false, reason: 'unreadable' };
+    }
+
+    // W4c Q1-LOW-TOCTOU — `isRecordedSession` was attested against the FIRST
+    // read of this file (in `resolveSession()`); the values acted on below come
+    // from this SECOND read. Re-verify ownership here rather than inheriting a
+    // stale attestation. A genuine swap BETWEEN the two reads is not testable
+    // without a seam, and none is added for it — the peer-id case pins the
+    // re-check, and this predicate is what makes the window harmless.
+    if (rawStdinId === null || parsed?.session_id !== rawStdinId) {
+      await emitFinalRefused(ids, 'session-id-mismatch');
+      return { emitted: false, reason: 'session-id-mismatch' };
+    }
+
+    const lastWave = parsed?.last_wave;
+    if (typeof lastWave !== 'number' || !(lastWave > 0)) {
+      await emitFinalRefused(ids, 'no-wave');
+      return { emitted: false, reason: 'no-wave' };
+    }
+    // W4c Q3-MED-3(iii) / Q3-LOW-4 — strictly ABOVE the high-water mark, not
+    // merely different from it: a marker AHEAD of `last_wave` (written by the
+    // batch hook's explicit `wave-complete{N}` branch) means this wave is
+    // already closed, and a non-integer marker (`'3'`, `null`) counts as
+    // ABSENT rather than as "different".
+    const marker = Number.isInteger(parsed?.last_wave_completed) ? parsed.last_wave_completed : 0;
+    if (!(lastWave > marker)) {
+      await emitFinalRefused(ids, 'already-completed', lastWave);
+      return { emitted: false, reason: 'already-completed' };
+    }
+
+    await emitEvent('orchestrator.wave.completed', {
+      ...(sessionId !== null ? { session_id: sessionId } : {}),
+      ...(semanticSessionId !== null ? { semantic_session_id: semanticSessionId } : {}),
+      wave_number: lastWave,
+      reason: 'session-end',
+      emitted_by: 'on-session-end',
+    });
+
+    // Monotone, exactly as the batch hook's `maxWave()` — the mark may only
+    // ever rise, whichever of the three writers gets here last (W4c Q3-MED-3).
+    const markResult = await atomicMutateJson(sessionFile, {}, (current) => ({
+      ...current,
+      last_wave_completed: Number.isInteger(current?.last_wave_completed)
+        && current.last_wave_completed > lastWave
+        ? current.last_wave_completed
+        : lastWave,
+    }), 'ose');
+    // The wave.completed EVENT above already fired regardless — this only
+    // withholds the shared-file high-water mark on a non-ENOENT failure.
+    if (!markResult.ok) {
+      console.error(`on-session-end: last_wave_completed mark skipped (${markResult.reason})`);
+    }
+    return { emitted: true, wave_number: lastWave };
+  } catch {
+    // best-effort — a SessionEnd hook must never block teardown
+    await emitFinalRefused(ids, 'exception');
+    return { emitted: false, reason: 'exception' };
+  }
+}
+
 // ---------------------------------------------------------------------------
 // main
 // ---------------------------------------------------------------------------
 
 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';
-  const { sessionId, semanticSessionId, durationMs } = await resolveSession(input, projectRoot);
+  const { sessionId, semanticSessionId, durationMs, isRecordedSession, rawStdinId } =
+    await resolveSession(input, projectRoot);
 
   // Single emission path: emitEvent writes the canonical {timestamp, event, ...payload}
   // JSONL record AND fires the optional Clank webhook with the SAME event name.
@@ -332,13 +571,40 @@ async function main() {
   // attestation bar is the #863 defect (c) guard inside `resolveSession()`: an
   // ending session that is NOT the one current-session.json describes resolves
   // `semanticSessionId: null` and therefore emits no key here.
-  await emitEvent('orchestrator.session.ended', {
-    ...(sessionId !== null ? { session_id: sessionId } : {}),
-    ...(semanticSessionId !== null ? { semantic_session_id: semanticSessionId } : {}),
+  // #1193 — close the last wave BEFORE the terminal session event, so the
+  // ledger's wave lifecycle is balanced within the session's own window. Gated
+  // on the SAME `isRecordedSession` attestation as the identity keys above, and
+  // skipped for `reason === 'clear'` and `reason === 'resume'` alike — both end
+  // the HARNESS session while the LOGICAL one continues; see the emitter's docblock.
+  //
+  // #1201 Part B — the return is `{emitted:true, wave_number}` or
+  // `{emitted:false, reason}`, but it is intentionally NOT branched on here:
+  // both outcomes already persisted themselves (`orchestrator.wave.completed`
+  // or the sibling `orchestrator.wave.final_refused`) before this call
+  // resolves, so nothing downstream in this hook needs to react to it.
+  await emitFinalWaveCompleted(projectRoot, {
+    sessionId,
+    semanticSessionId,
+    isRecordedSession,
     reason,
-    duration_ms: durationMs,
+    rawStdinId,
   });
 
+  // #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.
+  try {
+    await emitEvent('orchestrator.session.ended', {
+      ...(sessionId !== null ? { session_id: sessionId } : {}),
+      ...(semanticSessionId !== null ? { semantic_session_id: semanticSessionId } : {}),
+      reason,
+      // Omit-never-fabricate: only a MEASURED span is written. `null` here means
+      // the ending session is not the recorded one (or no start time parsed) —
+      // absence must stay absence, not become a zero-length session.
+      ...(Number.isFinite(durationMs) && durationMs >= 0 ? { duration_ms: durationMs } : {}),
+    });
+  } catch { /* telemetry never blocks the hook (#1183) */ }
+
   // -------------------------------------------------------------------------
   // C1 (#724) — Close-through backfill + deterministic lock release.
   // Both are STRICTLY best-effort: a SessionEnd hook must never block teardown