session-orchestrator 3.22.0 → 3.23.0

package/hooks/hooks-cursor.json

@@ -1,24 +1,205 @@
 {
-  "_comment": "Cursor IDE hook mapping reference. Configure hooks in Cursor Settings > Hooks.",
-  "_note": "Cursor hooks fire at different lifecycle points than Claude Code. See docs/cursor-setup.md for details.",
-  "_limitation": "SessionStart greeting (session-start skill) is NOT available on Cursor. Cursor has no conversation-start lifecycle event equivalent to Claude Code's UserPromptSubmit hook. Session initialisation must be triggered manually.",
-  "_enforcement": "reference-only",
-  "_enforcement_note": "MACHINE-READABLE STATUS (#919): every entry below is an intended mapping, NOT live enforcement. No Cursor payload adapter exists (Pi has scripts/lib/pi-hook-bridge.mjs; Cursor has nothing), so each handler short-circuits on a Cursor-shaped payload and writes 0 bytes with exit 0. Operator decision 2026-07-31: gap registered, not closed. The machine-readable counterpart of this key is DOCUMENTED_ASYMMETRIES.handlerAsymmetries.cursor in scripts/lib/validate/check-hooks-symmetry.mjs, which Check 6 counts per event; the projection that makes that comparison non-vacuous is DOCUMENTED_ASYMMETRIES.cursorEventMap.",
-  "_issues": ["#919", "#946"],
+  "_comment": "Cursor IDE hook mapping. Event names are Cursor-native; commands receive Claude/Codex-compatible hook JSON on stdin after scripts/lib/cursor-hook-bridge.mjs normalises the payload. CURSOR_PLUGIN_ROOT is set by the bridge; CURSOR_RULES_DIR is the compatibility alias used by plugin-root resolution.",
+  "_enforcement": "live",
+  "_enforcement_note": "LIVE via scripts/lib/cursor-hook-bridge.mjs and .cursor/hooks.json. The bridge maps Cursor stdin onto tool_name / tool_input and maps emitDeny envelopes onto Cursor { permission }. afterFileEdit remains post-hoc (cannot prevent an edit already written).",
+  "_issues": ["#919"],
   "hooks": {
-    "afterFileEdit": {
-      "script": "hooks/enforce-scope.mjs",
-      "enforcement": "none",
-      "issue": "#919",
-      "mapsToClaudeEvent": "PostToolUse",
-      "note": "Post-hoc scope warning — Cursor fires AFTER the edit (not before), so this maps onto PostToolUse, never PreToolUse. Cannot prevent out-of-scope edits, only warn — and today not even that: on a Cursor afterFileEdit payload enforce-scope.mjs writes 0 bytes to stdout AND stderr with exit 0 (measured 2026-07-31), because it reads Claude Code's PreToolUse field names."
-    },
-    "beforeShellExecution": {
-      "script": "hooks/enforce-commands.mjs",
-      "enforcement": "none",
-      "issue": "#919",
-      "mapsToClaudeEvent": "PreToolUse",
-      "note": "NOT WIRED (#919) — silent no-op on a Cursor payload, NOT a block. The handler reads Claude Code's PreToolUse field names (tool_name === 'Bash', tool_input.command) and emits a Claude Code PreToolUse envelope (hookSpecificOutput.permissionDecision). Fed a Cursor beforeShellExecution payload it short-circuits at gate G1 and writes 0 bytes to stdout AND stderr with exit 0 — the harness sees no decision, so the command runs. Cursor needs an input/output adapter like scripts/lib/pi-hook-bridge.mjs; none exists. Treat this entry as the intended mapping, not as live enforcement."
-    }
+    "sessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/on-session-start.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "sessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/on-session-end.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "beforeShellExecution": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/pre-bash-destructive-guard.mjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/pre-bash-staging-fence.mjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/pre-bash-memory-propose-audit.mjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/pre-bash-sessions-ledger-guard.mjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/pre-bash-templates-first.mjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/pre-bash-issue-budget.mjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/enforce-commands.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "preToolUse": [
+      {
+        "matcher": "Write|StrReplace|TabWrite|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/enforce-scope.mjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/config-protection.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "afterShellExecution": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/post-bash-write-verify.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "postToolUse": [
+      {
+        "matcher": "Write|StrReplace|TabWrite|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/post-edit-validate.mjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/post-tooluse-frontend-slop.mjs\"",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/loop-guard.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "afterFileEdit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/post-edit-validate.mjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/post-tooluse-frontend-slop.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "postToolUseFailure": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/post-tool-failure-corrective-context.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/on-stop.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "subagentStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/subagent-telemetry.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "subagentStop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/on-stop.mjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/subagent-telemetry.mjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/post-subagent-discovery-validator.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
   }
 }

package/hooks/hooks-pi.json

@@ -20,7 +20,7 @@
           {
             "type": "command",
             "command": "sh \"$PI_PLUGIN_ROOT/hooks/run-node.sh\" \"$PI_PLUGIN_ROOT/hooks/on-session-end.mjs\"",
-            "timeout": 5
+            "timeout": 10
           }
         ]
       }

package/hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v3.22.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v3.23.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {
@@ -25,7 +25,7 @@
           {
             "type": "command",
             "command": "sh \"$CLAUDE_PLUGIN_ROOT/hooks/run-node.sh\" \"$CLAUDE_PLUGIN_ROOT/hooks/on-session-end.mjs\"",
-            "timeout": 5
+            "timeout": 10
           }
         ]
       }

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,14 +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,
   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';
 
 // ---------------------------------------------------------------------------
@@ -72,11 +79,26 @@ 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
@@ -98,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;
@@ -138,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
 // ---------------------------------------------------------------------------
@@ -152,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,
   });
@@ -172,7 +353,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 +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',
@@ -348,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.