session-orchestrator 3.22.0 → 3.24.0

package/hooks/on-session-end.mjs

@@ -10,7 +10,13 @@
  * `session.started` had no terminal partner.
  *
  * JSONL format (`.orchestrator/metrics/events.jsonl`):
- *   {"timestamp":<ISO>,"event":"orchestrator.session.ended","session_id":"...","reason":"<reason>","duration_ms":<int>}
+ *   {"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.
+ *    `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,15 +36,22 @@ 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 { backfillAbandonedSession } from '../scripts/lib/session-close-backfill.mjs';
+import {
+  backfillAbandonedSession,
+  backfillCompletedFromStateMd,
+} from '../scripts/lib/session-close-backfill.mjs';
 import {
   readLockDetailed,
   release,
   loadOwnerProof,
   OWNER_PROOF_RELPATH,
 } from '../scripts/lib/session-lock.mjs';
+import { parseSessionId } from '../scripts/lib/session-id.mjs';
 import { deregisterSelf, logSweepEvent } from '../scripts/lib/session-registry.mjs';
+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)
@@ -72,11 +85,29 @@ async function readStdinJson() {
 }
 
 /**
- * Resolve this session's id + duration + semantic id. Stdin session_id wins;
- * otherwise fall back to `.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.
+ * Resolve this session's id + duration + semantic id. A stdin session_id wins
+ * ONLY when it parses as a UUID; otherwise fall back to
+ * `.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
+ * `parseSessionId(fromStdin)?.format === 'uuid'` and otherwise mints a
+ * `randomUUID()`; `current-session.json`, `session.lock` and the host registry
+ * are therefore ALWAYS keyed by a UUID. This reader used to accept ANY
+ * non-empty stdin string, so a harness that passed a non-UUID id
+ * (`{"session_id":"not-a-uuid"}`) resolved a key that matches nothing written
+ * at start: the raw-ID ownership compare below (:330) fails, the lock is
+ * neither released nor reconciled, and it LEAKS until its TTL expires. Same
+ * for `deregisterSelf()`, whose registry file is named after the id
+ * `registerSelf()` used. Mirroring the writer's rule here makes the fallback
+ * (which reads exactly those artifacts) the single source of the identity.
+ * The ownership compare itself stays an exact string `===` — this changes
+ * WHICH id is compared, never HOW.
  *
  * `semanticSessionId` is read from current-session.json (present since #587):
  * it is the SEMANTIC id (`<branch>-<date>-<mode>-<n>`) that sessions.jsonl is
@@ -92,13 +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;
-  let sessionId = (typeof fromStdin === 'string' && fromStdin.length > 0) ? fromStdin : null;
+  // UUID-only, exactly as the writer decides it (see the docblock above).
+  const rawStdinId = parseSessionId(fromStdin)?.format === 'uuid' ? fromStdin : null;
+  let sessionId = rawStdinId;
 
   let recordedId = null;
   let semanticSessionId = null;
@@ -121,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
@@ -135,7 +199,350 @@ 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,
+  };
+}
+
+/**
+ * POST budget for the close-time telemetry flush (ms).
+ *
+ * NAMED CEILING, and the reason it is BELOW the module default POST_TIMEOUT_MS
+ * (3000): the two timeouts fail differently.
+ *
+ *   - This one expiring is LOSSLESS. `flush()` catches the abort and routes the
+ *     record into the bounded offline queue; the daily fallback
+ *     (`shouldDailyFlush`) drains it on a later session.
+ *   - The HARNESS timeout expiring is LOSSY. Claude Code kills the hook process
+ *     mid-flight, so the enqueue never runs and the record is simply gone —
+ *     which is the exact failure #1138 exists to remove.
+ *
+ * So the internal bound must stay comfortably under the harness bound, not
+ * merely below it. Budget (hooks/hooks.json `SessionEnd.timeout: 10` s, raised
+ * from 5 with this change): up to 500 ms stdin + a backfill measured at a
+ * ~845 ms median (its TAIL, not its median, is what would collide) + lock
+ * release + deregistration, then this 2 s. That leaves several seconds of slack
+ * for the backfill tail while still covering a normal round-trip many times
+ * over.
+ *
+ * Revisit if the hooks.json SessionEnd timeout changes — the pin lives in
+ * tests/hooks/on-session-end.test.mjs.
+ */
+const TELEMETRY_FLUSH_TIMEOUT_MS = 2000;
+
+/**
+ * Read `persistence` from the repo's Session Config. Defaults to `true` — the
+ * same default `scripts/lib/config.mjs` applies — so an unreadable or absent
+ * CLAUDE.md (or its Codex alias AGENTS.md) never silently disables the flush.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<boolean>}
+ */
+async function readPersistence(projectRoot) {
+  try {
+    const md = await readConfigFile(projectRoot);
+    return parseSessionConfig(md).persistence !== false;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Reduce a `flush()` result to the two-field breadcrumb the event carries.
+ *
+ * `reason` is normalised to its head token because `flush()` may return
+ * `build-error: <message>`, and a raw error message is unbounded free text in a
+ * stream whose whole purpose is aggregation by class.
+ *
+ * @param {{sent?: boolean, queued?: boolean, reason?: string}|null|undefined} res
+ * @returns {{outcome: 'sent'|'queued'|'gated'|'skipped', reason: string}}
+ */
+function classifyFlush(res) {
+  const reason = String(res?.reason ?? 'unknown').split(':')[0];
+  if (res?.sent === true) return { outcome: 'sent', reason };
+  if (res?.queued === true) return { outcome: 'queued', reason };
+  if (reason === 'gated') return { outcome: 'gated', reason };
+  return { outcome: 'skipped', reason };
+}
+
+/**
+ * #1138 — the MECHANICAL telemetry flush.
+ *
+ * Until now the close-time flush existed only as prose in
+ * `skills/session-end/SKILL.md` § Phase 3.45, i.e. it ran only when the
+ * coordinator LLM happened to execute that phase. Measured 2026-08-23: 588
+ * session closes across 13 repos produced 82 ingest records (~14%). A hook is
+ * the only caller that fires on EVERY close, including the ones that never
+ * reach `/close` at all.
+ *
+ * Strictly best-effort: never throws, and bounded by TELEMETRY_FLUSH_TIMEOUT_MS.
+ * The consent gate lives INSIDE `flush()` (`resolveConsent()` is its first
+ * statement) — this function deliberately does not re-implement it, so there is
+ * exactly one place where "may we send?" is decided.
+ *
+ * Always emits `orchestrator.telemetry.flush` with `{ outcome, reason }` and
+ * NOTHING else — no payload, no anon_id. Per `.claude/rules/host-resources.md`
+ * HR-105, a mechanism whose firing rate nothing records cannot be falsified;
+ * this event is what makes the flush rate measurable next time.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<void>}
+ */
+async function flushTelemetry(projectRoot) {
+  let result;
+  try {
+    result = (await readPersistence(projectRoot))
+      ? classifyFlush(await flush({
+        metricsDir: path.join(projectRoot, '.orchestrator', 'metrics'),
+        timeoutMs: TELEMETRY_FLUSH_TIMEOUT_MS,
+      }))
+      // `persistence: false` means this session leaves no durable local trace;
+      // a telemetry ping is a durable record too, so it honours the same switch.
+      : { outcome: 'skipped', reason: 'persistence-disabled' };
+  } catch {
+    result = { outcome: 'skipped', reason: 'error' };
+  }
+
+  // `result` is passed through verbatim: it holds EXACTLY {outcome, reason}, so
+  // no payload field can leak into the event by accident.
+  try {
+    await emitEvent('orchestrator.telemetry.flush', result);
+  } catch { /* observability is best-effort */ }
+}
+
+/**
+ * #1068 AC2 — emit ONE canonically queryable outcome per backfill attempt.
+ *
+ * Until now a backfill result reached exactly one place:
+ * `.orchestrator/metrics/session-close-backfill.log`, a side-log no lifecycle
+ * consumer reads and no staleness/integrity check joins against. The event
+ * stream is where every other lifecycle fact already lives, so the outcome goes
+ * there too — carrying IDENTITY (`session_id` raw UUID + the record id the
+ * backfill acted on + the attested semantic id), ACTION, and, when the action
+ * was an error, its REASON. The side-log is unchanged and remains the verbose
+ * copy; this is the queryable one.
+ *
+ * `kind` distinguishes the two backfill classes, which share the log file and
+ * would otherwise be indistinguishable in aggregate: `'abandoned'`
+ * (`backfillAbandonedSession`) vs `'state-md-completed'`
+ * (`backfillCompletedFromStateMd`).
+ *
+ * Every id key is OMITTED when unknown — never `""`, never a guess (#1068 AC1).
+ * Best-effort throughout: observability must never block teardown.
+ *
+ * @param {'abandoned'|'state-md-completed'} kind
+ * @param {{action?: string, sessionId?: string|null, supersedes?: string, error?: string}|null|undefined} result
+ * @param {{sessionId: string|null, semanticSessionId: string|null}} ids
+ * @returns {Promise<void>}
+ */
+async function emitBackfillOutcome(kind, result, { sessionId, semanticSessionId }) {
+  try {
+    const recordId = typeof result?.sessionId === 'string' ? result.sessionId : null;
+    await emitEvent('orchestrator.session.backfill_completed', {
+      kind,
+      action: typeof result?.action === 'string' ? result.action : 'unknown',
+      ...(sessionId !== null ? { session_id: sessionId } : {}),
+      ...(semanticSessionId !== null ? { semantic_session_id: semanticSessionId } : {}),
+      ...(recordId !== null ? { record_id: recordId } : {}),
+      ...(typeof result?.supersedes === 'string' ? { supersedes: result.supersedes } : {}),
+      ...(typeof result?.error === 'string' ? { reason: result.error } : {}),
+    });
+  } 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' };
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -148,16 +555,56 @@ 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.
-  await emitEvent('orchestrator.session.ended', {
-    ...(sessionId !== null ? { session_id: sessionId } : {}),
+  //
+  // #1068 AC1 — the terminal event carries the raw UUID *and* the semantic id
+  // whenever the latter is ATTESTED, so a lifecycle outcome is joinable by
+  // identity from events.jsonl alone (previously only `session.lock.acquired`
+  // carried both, and only ~1/3 of sessions emit one). The key is OMITTED, never
+  // written as `""` or `null`, when `resolveSession()` could not attest it —
+  // "identity unresolved" must stay visibly unresolved rather than become a
+  // guessed id (#1068 AC1's explicit "niemals eine geratene ID"). Note the
+  // 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.
+  // #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
@@ -172,7 +619,21 @@ async function main() {
   //     historical migration CLI) is NEVER passed here: a foreign lock that is live
   //     at hook-time is, by definition, a real active session, not stale history.
   try {
-    await backfillAbandonedSession({ repoRoot: projectRoot, sessionId, semanticSessionId });
+    const res = await backfillAbandonedSession({ repoRoot: projectRoot, sessionId, semanticSessionId });
+    await emitBackfillOutcome('abandoned', res, { sessionId, semanticSessionId });
+  } catch { /* best-effort — never block teardown */ }
+
+  // (a2) #429 — STATE.md `status: completed` self-heal. Orthogonal to (a)
+  //      above and to THIS session's own id: it reads STATE.md directly and
+  //      repairs a PAST session whose `status: completed` was set (by hand or
+  //      otherwise) without session-end's Phase 3.7 ever writing the matching
+  //      sessions.jsonl record — the exact state `commands/close.md`'s
+  //      Pre-Check then reads as "already finalized" forever after. Cheap
+  //      no-op on the overwhelmingly common path (STATE.md status is
+  //      'active'/'paused'/'idle', or the record already exists).
+  try {
+    const res = await backfillCompletedFromStateMd({ repoRoot: projectRoot });
+    await emitBackfillOutcome('state-md-completed', res, { sessionId, semanticSessionId });
   } catch { /* best-effort — never block teardown */ }
 
   // (b) Deterministic lock release — ONLY a lock whose raw/native session_id
@@ -276,7 +737,7 @@ async function main() {
             await emitEvent('orchestrator.session.lock.released', {
               session_id: sessionId,
               lock_session_id: lock.session_id,
-              semantic_session_id: semanticSessionId,
+              ...(semanticSessionId !== null ? { semantic_session_id: semanticSessionId } : {}),
               end_reason: reason,
               caller: 'on-session-end',
               outcome: benignAlreadyGone ? 'already-gone' : 'deleted',
@@ -348,6 +809,12 @@ async function main() {
       logSweepEvent({ event: 'deregister-failed', session_id: sessionId, error: err?.message ?? String(err) });
     }
   }
+
+  // (d) #1138 — mechanical telemetry flush. Deliberately LAST: it is the only
+  //     step here that may touch the network, so every local-fs guarantee above
+  //     (backfill, lock release, deregistration) is already durable before the
+  //     hook spends any of its remaining budget on a POST.
+  await flushTelemetry(projectRoot);
 }
 
 // Exit 0 always — informational hook must never block session teardown.