session-orchestrator 3.23.0 → 3.24.0

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 v3.24.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 v3.23.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v3.24.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

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? }.
@@ -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,6 +357,194 @@ 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
 // ---------------------------------------------------------------------------
@@ -317,7 +555,8 @@ async function main() {
 
   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

package/hooks/on-session-start.mjs

@@ -124,6 +124,30 @@ function shortSessionId(id) {
   return id.length > 24 ? id.slice(0, 8) : id;
 }
 
+/**
+ * GH#67 — render the provenance marker for ONE mechanically-detected peer.
+ *
+ * `discoverActiveSessions()` annotates registry-sourced peers additively
+ * (`registryOnly` / `lockSuperseded` / `lockOwnerId`); lock-sourced peers carry
+ * none of the three, so they render byte-identically to the pre-GH#67 banner.
+ *
+ * `lockSuperseded: true` means a LIVE lock at THIS root is held by a different
+ * raw session_id than the registry entry — the common cause is a finished task
+ * whose SessionEnd never ran, leaving a fresh-but-orphaned registry record.
+ * It is a HINT, never a verdict: the session lock is advisory, so the entry may
+ * equally be a live peer that lost the acquire race (#1085). The marker is
+ * therefore purely additive — it never removes the peer, and never changes the
+ * count or the WARN decision (HR-106).
+ *
+ * @param {{registryOnly?:boolean, lockSuperseded?:boolean, lockOwnerId?:string|null}} peer
+ * @returns {string} '' for a lock-sourced peer, else a bracketed marker.
+ */
+function supersessionMarker(peer) {
+  if (!peer || peer.registryOnly !== true) return '';
+  if (peer.lockSuperseded === true) return ' [registry-only, superseded]';
+  return ' [registry-only]';
+}
+
 /**
  * Queue the ONE `additionalContext` string for the single end-of-hook flush.
  * Last writer wins; there is deliberately no accumulation, because every
@@ -380,6 +404,12 @@ async function resolveSessionId(input, projectRoot) {
           if (Object.prototype.hasOwnProperty.call(prev, 'last_batch')) {
             preserved.last_batch = prev.last_batch;
           }
+          // #1193 — the final-wave completion marker must survive a
+          // clear/compact too: dropping it re-arms a duplicate SessionEnd
+          // `orchestrator.wave.completed` for a wave already closed.
+          if (Object.prototype.hasOwnProperty.call(prev, 'last_wave_completed')) {
+            preserved.last_wave_completed = prev.last_wave_completed;
+          }
         }
       } catch { /* absent / unparseable → no preservation (reset) */ }
     }
@@ -738,6 +768,11 @@ async function main() {
   } catch { /* hook must remain non-blocking */ }
 
   let peers = [];
+  // GH#67 consumer half — how many mechanically-detected peers were registry-
+  // sourced entries that a LIVE lock at this root supersedes. Counted for the
+  // session.started payload below; NEVER subtracted from any peer count
+  // (HR-106: the banner reports the number the verdict judged).
+  let mechanicalPeersSuperseded = 0;
   try {
     await sweepZombies().catch(() => ({ removed: [], logged: 0 }));
     try {
@@ -839,6 +874,7 @@ async function main() {
       const { discoverActiveSessions } = await import('../scripts/lib/session-discovery.mjs');
       const allActive = await discoverActiveSessions(projectRoot);
       const mechanicalPeers = allActive.filter((s) => s.sessionId !== sessionId);
+      mechanicalPeersSuperseded = mechanicalPeers.filter((p) => p.lockSuperseded === true).length;
       if (mechanicalPeers.length > 0) {
         // #1137 part 1 — say WHERE, not just how many. discoverActiveSessions()
         // walks EVERY path `git worktree list` reports, which includes worktrees
@@ -862,11 +898,14 @@ async function main() {
             // 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}`;
+            return `${where}:${shortSessionId(p.sessionId)}${mode}${supersessionMarker(p)}`;
           })
           .join(', ');
         const overflow = mechanicalPeers.length > 3 ? ` +${mechanicalPeers.length - 3} more` : '';
         pushBanner(`🔍 Mechanical peer-detection: ${mechanicalPeers.length} active in this repo's worktree set (${summary}${overflow})`);
+        if (mechanicalPeersSuperseded > 0) {
+          pushBanner(`   ${mechanicalPeersSuperseded} of them registry-only and superseded by this root's live lock — likely a finished task without SessionEnd (GH#67). Still counted above: the session lock is advisory.`);
+        }
       }
     } catch { /* best effort — banner is informational, never blocks */ }
   }
@@ -914,6 +953,10 @@ async function main() {
     branch,
     session_id: sessionId,
     peer_count: peers.length,
+    // GH#67 — additive: how many mechanically-detected peers a live lock at
+    // this root supersedes. `peer_count` is deliberately unchanged; this field
+    // makes the supersession rate measurable instead of inferred (HR-105).
+    peers_superseded: mechanicalPeersSuperseded,
   };
   if (bannerData) {
     payload.host_class = bannerData.host.host_class;
@@ -935,7 +978,12 @@ async function main() {
     payload.memory_pressure_pct_free = bannerData.resources.memory_pressure_pct_free ?? null;
     payload.peer_sessions_count = bannerData.resources.peer_sessions_count ?? null;
   }
-  await emitEvent('orchestrator.session.started', payload);
+  // #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.started', payload);
+  } catch { /* telemetry never blocks the hook (#1183) */ }
 
   // #1138 — one-time telemetry-consent nudge. Queued (never written) here so it
   // rides the single stdout envelope below.