session-orchestrator 3.21.0 → 3.23.0

package/hooks/on-session-end.mjs

@@ -10,7 +10,8 @@
  * `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.)
  *
  * Exit codes: 0 always (informational hook — must never block session teardown).
  * stdin: optional JSON { hook_event_name:"SessionEnd", session_id?, reason?, cwd? }.
@@ -30,16 +31,20 @@ 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,
-  isLockLive,
   loadOwnerProof,
-  isLockOwnedByProof,
   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';
 
 // ---------------------------------------------------------------------------
@@ -74,29 +79,40 @@ 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.
+ *
+ * #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
  * keyed by, and the id the backfill (C1 #724) uses when the stdin session_id is
- * a harness UUID with no lock.acquired bridge.
+ * a harness UUID with no lock.acquired bridge. It is never a lock-release
+ * ownership identity; only the raw/native `sessionId` may release a live lock.
  *
  * #863 defect (c) — `semanticSessionId` is gated by the SAME "ending session
  * IS the recorded one" check as `durationMs` above. `current-session.json` is
  * a single repo-global file: it always reflects whichever session most
  * recently ran SessionStart, which may be a DIFFERENT, still-live session
- * when multiple windows share this repo. Before this fix, a foreign
- * terminating window (its own stdin `session_id` explicitly present, but NOT
- * equal to the recorded session) still inherited the CURRENTLY-recorded
- * session's `semantic_session_id` unconditionally — main()'s `ownBySemantic`
- * check then matched that OTHER, still-running session's lock and released
- * it. Gating this field closes that window: an unrelated/mismatched ending
- * session now resolves `semanticSessionId: null`, so `ownBySemantic` can
- * never accidentally fire on someone else's identity.
+ * when multiple windows share this repo. An unrelated/mismatched ending
+ * session therefore resolves `semanticSessionId: null` rather than inheriting
+ * another live session's backfill identity.
  *
  * @param {object|null} input
  * @param {string} projectRoot
@@ -104,7 +120,8 @@ async function readStdinJson() {
  */
 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).
+  let sessionId = parseSessionId(fromStdin)?.format === 'uuid' ? fromStdin : null;
 
   let recordedId = null;
   let semanticSessionId = null;
@@ -144,6 +161,152 @@ async function resolveSession(input, projectRoot) {
   return { sessionId, semanticSessionId: resolvedSemanticSessionId, durationMs };
 }
 
+/**
+ * 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 */ }
+}
+
 // ---------------------------------------------------------------------------
 // main
 // ---------------------------------------------------------------------------
@@ -158,8 +321,20 @@ async function main() {
 
   // Single emission path: emitEvent writes the canonical {timestamp, event, ...payload}
   // JSONL record AND fires the optional Clank webhook with the SAME event name.
+  //
+  // #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.
   await emitEvent('orchestrator.session.ended', {
     ...(sessionId !== null ? { session_id: sessionId } : {}),
+    ...(semanticSessionId !== null ? { semantic_session_id: semanticSessionId } : {}),
     reason,
     duration_ms: durationMs,
   });
@@ -178,27 +353,32 @@ 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 */ }
 
-  // (b) Deterministic lock release — ONLY our OWN lock. Match by UUID first,
-  //     then by semantic id (the UUID rotates across clear/compact/resume while
-  //     the semantic id stays stable, #612). A foreign lock is never released.
+  // (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
+  //     exactly matches this ending session's raw/native sessionId. Semantic
+  //     IDs remain lifecycle/backfill metadata and persisted proofs remain an
+  //     additional delete defense, but neither can heal a raw-ID mismatch.
   //
-  //     Epic #724 hardening ("ended logged but lock survived"): the ownership
-  //     match alone left two silent failure modes —
-  //       (1) release() can fail at the fs layer; the swallowed try/catch below
-  //           made this invisible (session.ended is logged, the lock survives).
-  //       (2) when the harness UUID rotates (clear/compact/resume) and
-  //           current-session.json's semantic_session_id is null/stale, BOTH
-  //           ownership checks are false and this branch never runs release()
-  //           at all — the lock survives until the NEXT session-start's own
-  //           reaper sweep discovers it.
-  //     Both are addressed below without loosening the strict
-  //     never-release-a-foreign-lock invariant: release() only ever runs when
-  //     ownership matched; the reconciliation fallback only ever runs through
-  //     reapRepoLock(), which independently NEVER reaps a live lease (and only
-  //     ever reaps on this same host with a dead recorded PID).
+  //     A mismatch routes only through reconciliation. The reaper independently
+  //     never touches a live lease, a cross-host lease, or a lease whose
+  //     recorded PID is still alive on this host; this retains dead/stale-lock
+  //     recovery without granting a SessionEnd hook foreign-lock ownership.
   try {
     // readLockDetailed (additive, see its JSDoc in session-lock.mjs) replaces
     // readLock() here so an unreadable/corrupt lock file is DISTINGUISHABLE
@@ -219,61 +399,15 @@ async function main() {
       } catch { /* observability is best-effort */ }
     } else if (lockDetail.status === 'ok') {
       const lock = lockDetail.lock;
-      const ownByUuid = sessionId !== null && lock.session_id === sessionId;
-      const ownBySemanticStrict =
-        semanticSessionId !== null && lock.semantic_session_id === semanticSessionId;
-      // #863 (d) — lock-shape trap: some on-disk locks store the semantic id
-      // directly in `session_id` with no separate `semantic_session_id` field
-      // at all (the "generated-semantic" acquisition path in
-      // on-session-start.mjs mints `session_id === the semantic id`, and
-      // bootstrapLock's v2 enrichment step never ran for that lock). Without
-      // this fallback, ownBySemanticStrict is dead code for that shape.
-      const ownBySemanticFallback =
-        semanticSessionId !== null && lock.session_id === semanticSessionId;
-      const ownBySemantic = ownBySemanticStrict || ownBySemanticFallback;
-
-      // #987 Part 2 — persisted ownership proof (pid + host + started_at,
-      // written at lock genesis by bootstrapLock Step 2b, see
-      // writeOwnerProof() in session-lock.mjs). loadOwnerProof() is
-      // fail-closed: a missing/corrupt proof file yields null, and a null
-      // proof presented to isLockOwnedByProof() yields false — the hook then
-      // degrades to exactly the pre-#987 (proof-less) behaviour below.
-      const proof = loadOwnerProof({ repoRoot: projectRoot });
-      const ownByProof = isLockOwnedByProof(lock, proof);
-
-      // #906-class fix: the semantic session id
-      // (`<branch>-<date>-<mode>-<n>`) is NOT globally unique — the
-      // id-counter can hand out the SAME id to two different session
-      // processes (live-observed twice on 2026-07-29: `main-2026-07-29-deep-1`
-      // and `main-2026-07-29-session-1`, each assigned to two distinct
-      // sessions). A live lock matched ONLY via a collidable semantic id
-      // (strict OR fallback, never corroborated by a non-collidable factor)
-      // is therefore NEVER trusted for release.
-      //
-      // #987 Part 2 — the discrimination the #906-class fix escalated as
-      // "structurally unobservable" is now OBSERVABLE via the persisted
-      // owner proof: a genuine same-session UUID rotation (clear/compact)
-      // and a foreign same-day semantic collision used to produce the
-      // IDENTICAL shape here (UUID mismatch + semantic match on a live
-      // lock), so the previous fix conservatively left BOTH un-released
-      // (bounded by the ttl_hours reaper). The proof written at lock genesis
-      // (pid + host + started_at — presence-at-genesis, never the collidable
-      // session_id/semantic id, see the FACTOR CHOICE docblock on
-      // isLockOwnedByProof()) is exactly the discriminator that RCR-007
-      // escalation named: on a self-rotation the on-disk lock is FROZEN at
-      // its pre-rotation values (bootstrapLock's shouldForce is false for a
-      // rotated UUID, so it bails without touching the lock), which are the
-      // SAME values the proof captured at genesis → ownByProof is true → the
-      // lock is released correctly. A foreign same-day collision wrote its
-      // lock in a DIFFERENT process at a DIFFERENT millisecond → ownByProof
-      // is false → semanticOnlyLive stays true → no release, the foreign
-      // lease survives (the never-release-a-foreign-lock invariant is
-      // untouched). No proof on disk (pre-#987 sessions, failed proof
-      // write) → ownByProof false → the conservative pre-#987 behaviour.
-      const semanticOnlyLive = !ownByUuid && !ownByProof && ownBySemantic && isLockLive(lock);
-      const releaseEligible = (ownByUuid || ownBySemantic) && !semanticOnlyLive;
-
-      if (releaseEligible) {
+      const ownByRawId = sessionId !== null && lock.session_id === sessionId;
+
+      if (ownByRawId) {
+        // The proof is deliberately passed to release() only after this raw-ID
+        // check. release() validates a supplied proof against its fresh on-disk
+        // read, preserving it as a second defense for the raw-owned path without
+        // allowing proof equality to establish ownership by itself.
+        const proof = loadOwnerProof({ repoRoot: projectRoot });
+
         // Defense-in-depth (#987): when a persisted proof exists, hand it to
         // release() so the delete is double-gated (session_id match AND
         // proof match) at the fs layer too. `proof` is `null` whenever
@@ -284,7 +418,7 @@ async function main() {
         // A 'proof-mismatch' result flows into the existing release_failed
         // breadcrumb below (releaseResult.reason surfaces verbatim).
         const releaseResult = release({
-          sessionId: lock.session_id,
+          sessionId,
           repoRoot: projectRoot,
           proof,
         });
@@ -337,7 +471,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',
@@ -355,16 +489,9 @@ async function main() {
           } catch { /* best-effort — a leftover proof is self-invalidating */ }
         }
       } else {
-        // Root-cause reconciliation fallback: either NEITHER the UUID nor the
-        // semantic id matched the recorded lock, OR the ONLY match was a
-        // collidable semantic comparison (strict or fallback) on a lock that
-        // is still live (semanticOnlyLive). attemptLockReconciliation() is
-        // the extracted, DI-testable seam (Issue #748) — it internally
-        // no-ops when the lease is still live (isLockLive), which is exactly
-        // what makes it safe to route the semanticOnlyLive case here too: it
-        // is otherwise best-effort, and reapRepoLock() never touches a live
-        // lease, a cross-host lease, or a lease whose recorded PID is still
-        // alive on this host.
+        // A raw-ID mismatch never grants release ownership. Reconciliation is
+        // the only remaining cleanup path; it no-ops for a live lock and safely
+        // reaps only eligible dead/stale locks.
         await attemptLockReconciliation({ repoRoot: projectRoot, sessionId, lock });
       }
     }
@@ -416,6 +543,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.