session-orchestrator 4.1.0 → 4.2.0

package/scripts/lib/resource-probe/evaluate.mjs

@@ -61,6 +61,14 @@
  * of starts is a broken instrument to be re-aimed, not a policy to obey.
  */
 
+// `session-shape.mjs` is the ONE exported `agents-per-wave` resolver; this
+// module used to carry a private third copy. Import-graph note (this file is
+// hook-reachable via `hooks/_lib/hook-import-set.json`): `session-shape.mjs`
+// statically imports only `session-schema/constants.mjs`, a pure-data leaf, and
+// defers `events.mjs` to a lazy `await import()` — so nothing runs at module
+// load here that did not run before.
+import { resolveAgentCap } from '../session-shape.mjs';
+
 // ---------------------------------------------------------------------------
 // Verdict precedence helper
 // ---------------------------------------------------------------------------
@@ -252,29 +260,19 @@ function concurrencySignal(snapshot, concWarn) {
 }
 
 /**
- * Resolve an `agentsPerWave` option value into a plain numeric cap, or `null`
- * when no cap should apply. Mirrors `resolveApwCap()` in
- * `../wave-resource-gate.mjs` — kept as a local pure helper here rather than
- * a cross-module import since both sites are ≤10 lines and evolve
- * independently per their own gate's options shape.
+ * The session type this module resolves `agents-per-wave` FOR: none.
  *
- * `evaluate()` has no session-mode input in scope, so the object shape
- * resolves to `cap.default` — the documented HR-003 convention writes the
- * override as `<default> (mode: <higher-ceiling>)`, i.e. `default` is the
- * MORE restrictive of the pair, so this can only under-apply a looser
- * mode-specific ceiling, never let a heavy repo exceed its base cap.
+ * `evaluate()` has no session-mode input in scope, so it deliberately asks
+ * `resolveAgentCap` for no type and takes the `.default` fallback. The HR-003
+ * convention writes the override as `<default> (mode: <higher-ceiling>)`, i.e.
+ * `default` is the MORE restrictive of the pair — under-applying a looser
+ * mode-specific ceiling is safe, while passing a guessed `'deep'` here would
+ * silently RAISE a heavy repo's ceiling to the deep override on a loaded host.
+ * Naming the absence is what keeps that from being written by accident.
  *
- * @param {number|{default: number, [mode: string]: number}|*} cap
- * @returns {number|null}
+ * @type {undefined}
  */
-function resolveAgentsPerWaveCap(cap) {
-  if (typeof cap === 'number') return Number.isFinite(cap) ? cap : null;
-  if (cap !== null && typeof cap === 'object' && !Array.isArray(cap)) {
-    const def = cap.default;
-    return typeof def === 'number' && Number.isFinite(def) ? def : null;
-  }
-  return null;
-}
+const MODE_BLIND_SESSION_TYPE = undefined;
 
 /**
  * Evaluate a snapshot against `resource-thresholds` (from Session Config #166)
@@ -423,7 +421,7 @@ export function evaluate(snapshot, thresholds, options = {}) {
   // the live-probe signals already computed.
   // ---------------------------------------------------------------------------
   const { heavyRepo, agentsPerWave } = options;
-  const resolvedApwCap = resolveAgentsPerWaveCap(agentsPerWave);
+  const resolvedApwCap = resolveAgentCap(agentsPerWave, MODE_BLIND_SESSION_TYPE);
   if (heavyRepo === true && resolvedApwCap !== null) {
     cap = cap === null ? resolvedApwCap : Math.min(cap, resolvedApwCap);
   }

package/scripts/lib/rules-sync.mjs

@@ -121,7 +121,7 @@ function listManifestCategories(indexContent) {
  * @param {string|null} explicitArchetype
  * @returns {{archetype: string|null, known: boolean}}
  */
-function resolveArchetype(repoRoot, explicitArchetype) {
+export function resolveArchetype(repoRoot, explicitArchetype) {
   if (explicitArchetype) {
     return { archetype: explicitArchetype.trim().toLowerCase(), known: true };
   }
@@ -194,6 +194,12 @@ function escapeRegex(s) {
  * at least one concrete bullet entry. This keeps `/bootstrap --sync-rules`
  * ready for future opt-in categories without requiring CLI changes.
  *
+ * `requiredBasenames` optionally adds explicitly required manifest entries,
+ * regardless of category or archetype scope. The caller supplies this data;
+ * this synchronous writer performs no external lookup. Every requested name
+ * must resolve uniquely in the full manifest before ANY file is written.
+ * Source validation, provenance, local overrides and dry-run still apply.
+ *
  * Vendoring sanitizer (issue #1098): every source file that reaches the write
  * decision is additionally scanned by `scanVendoringLeaks()`, and its findings
  * are collected into the additive `sanitizer[]` array. This runs in
@@ -214,7 +220,8 @@ function escapeRegex(s) {
  *   dryRun?: boolean,
  *   validate?: boolean,
  *   requireProvenance?: boolean,
- *   archetype?: string|null
+ *   archetype?: string|null,
+ *   requiredBasenames?: string[]|null
  * }} opts
  * @returns {{
  *   written: string[],
@@ -233,6 +240,7 @@ export function syncRules({
   validate = true,
   requireProvenance = true,
   archetype = null,
+  requiredBasenames = null,
 } = {}) {
   const written = [];
   const skipped = [];
@@ -268,13 +276,35 @@ export function syncRules({
     ? categories
     : listManifestCategories(indexContent);
   const entries = parseIndex(indexContent, selectedCategories);
+  const fullManifest = parseIndex(indexContent, listManifestCategories(indexContent));
+  const required = new Set();
+  if (requiredBasenames !== null) {
+    if (!Array.isArray(requiredBasenames)) {
+      errors.push({ file: '_index.md', reason: 'requiredBasenames must be an array of unique manifest basenames' });
+    } else {
+      for (const name of requiredBasenames) {
+        if (typeof name !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_.-]*\.md$/.test(name) || required.has(name)) {
+          errors.push({ file: '_index.md', reason: 'invalid or duplicate required basename' });
+          continue;
+        }
+        required.add(name);
+        const matching = fullManifest.filter((entry) => basename(entry.relPath) === name);
+        if (matching.length !== 1) {
+          errors.push({ file: name, reason: 'required basename must resolve uniquely in _index.md' });
+        } else if (!entries.some((entry) => entry.relPath === matching[0].relPath)) {
+          entries.push(matching[0]);
+        }
+      }
+    }
+    if (errors.length > 0) return { written, skipped, preserved, errors, warnings, sanitizer };
+  }
 
   // Resolvability for the See-Also sanitizer is judged against the FULL
   // manifest, not `selectedCategories`: an archetype-scoped rule is a
   // legitimate citation target in every repo whose archetype matches, so
   // narrowing this to the current selection would report false leaks.
   const manifestBasenames = new Set(
-    parseIndex(indexContent, listManifestCategories(indexContent)).map((e) => basename(e.relPath)),
+    fullManifest.map((e) => basename(e.relPath)),
   );
 
   if (entries.length === 0) {
@@ -297,7 +327,7 @@ export function syncRules({
 
     // Archetype filter (issue #722 Epic A Wave 3) — evaluated before any
     // file IO, so a skip never triggers a spurious "source file not found".
-    if (archetypes !== null) {
+    if (archetypes !== null && !required.has(basename(relPath))) {
       if (!resolvedArchetype.known) {
         skipped.push({ file: relPath, reason: 'archetype-unknown' });
         continue;

package/scripts/lib/session-close-backfill.mjs

@@ -25,7 +25,8 @@
  * `'abandoned'` — the session itself claims to have finished normally).
  *
  * ── ID BRIDGE ────────────────────────────────────────────────────────────────
- *   sessions.jsonl records are keyed by SEMANTIC ids (`main-2026-05-27-session-1`).
+ *   Legacy sessions.jsonl records are keyed by semantic ids; native records
+ *   use the harness UUID with a separate `semantic_session_id` label.
  *   events.jsonl carries the harness UUID on `session.started` / `stop` / `ended`.
  *   The bridge is the `orchestrator.session.lock.acquired` event, which is the
  *   only record carrying BOTH `session_id` (UUID) and `semantic_session_id`.
@@ -62,6 +63,12 @@ import { validateSession as defaultValidateSession } from './session-schema/vali
 import { serializeSessionLineChecked as defaultSerialize } from './session-schema.mjs';
 import { resolveStateMdPath as defaultResolveStateMdPath } from './state-md/frontmatter-mutators.mjs';
 import { parseStateMd as defaultParseStateMd } from './state-md/yaml-parser.mjs';
+import { canonicalizeSessions } from './sessions-canonical.mjs';
+// Leaf constants module (no imports of its own) and ALREADY in the hook import
+// set via session-schema/validator.mjs — importing it here adds no new file to
+// the SessionStart/SessionEnd hook graph. The profile enum must not be
+// re-literalled: `VALID_SESSION_PROFILES` is its SSOT (GitLab #1252).
+import { VALID_SESSION_PROFILES } from './session-schema/constants.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -84,6 +91,16 @@ const UNMEASURED_SESSION_TYPE = 'unknown';
 
 const EVENT_STARTED = 'orchestrator.session.started';
 const EVENT_LOCK_ACQUIRED = 'orchestrator.session.lock.acquired';
+/**
+ * `orchestrator.session.shape_resolved` (`scripts/lib/session-shape.mjs`) — the
+ * ONLY event emitted AFTER the operator picked a mode, so it is the only
+ * measurement of what this session actually was. `lock.acquired.mode` fires at
+ * SessionStart, BEFORE `/session <type>` is typed, which is why nearly every
+ * abandoned stub carried `_session_type_inferred: true`; and no other event
+ * carries `session_profile` at all, so an abandoned ultradeep run was
+ * indistinguishable from an abandoned deep one.
+ */
+const EVENT_SHAPE_RESOLVED = 'orchestrator.session.shape_resolved';
 // Both names for one generation (GitLab #1234): `hooks/on-stop.mjs` now emits
 // `orchestrator.turn.stopped` as the canonical name and keeps the legacy
 // `orchestrator.session.stopped` (with `deprecated: true`) beside it until
@@ -178,7 +195,8 @@ function canonicalIso(value, fallbackMs) {
  */
 function collectSessionEvents(events, { sessionId, semanticSessionId }) {
   const uuids = new Set();
-  if (isUuid(sessionId)) uuids.add(sessionId);
+  const nativeId = isUuid(sessionId) ? sessionId : null;
+  if (nativeId) uuids.add(nativeId);
 
   let mode = null;
   let semanticFromLock = null;
@@ -190,25 +208,72 @@ function collectSessionEvents(events, { sessionId, semanticSessionId }) {
   // SessionEnd hook had already recorded under its semantic id. Measured
   // 2026-09-02 @ c3ab480: 8 such duplicate pairs in sessions.jsonl.
   let semanticFromEvents = null;
+  // Plan-time shape measurement (see EVENT_SHAPE_RESOLVED). Latest wins — a
+  // session may re-resolve its shape, and the last resolution is the one it ran.
+  // "Latest" is only decidable for a record that CARRIES a parseable timestamp:
+  // an undated one has no place in the order, so it may never displace a dated
+  // reading (the earlier `Number.isNaN(ts) => ordered` inverted exactly that and
+  // let an undated record win over a later, well-dated one).
+  let shapeSessionType = null;
+  let shapeSessionProfile = null;
+  let shapeTs = null;
+  // True while the readings above come from an UNDATED record — kept only for
+  // lack of a dated one, and surfaced so the caller can mark it low-confidence.
+  let shapeUndated = false;
 
   // First pass — bridge the UUID set + carry mode + semantic id. lock.acquired
-  // is the original bridge; session.ended is the #1167 addition.
+  // is the original bridge; session.ended is the #1167 addition;
+  // shape_resolved is the plan-time type/profile measurement.
   for (const ev of events) {
     const isLock = ev.event === EVENT_LOCK_ACQUIRED;
     const isEnded = ev.event === EVENT_ENDED && typeof ev.semantic_session_id === 'string';
-    if (!isLock && !isEnded) continue;
-    const matchesUuid = isUuid(sessionId) && ev.session_id === sessionId;
-    const matchesSemantic =
+    const isShape = ev.event === EVENT_SHAPE_RESOLVED;
+    if (!isLock && !isEnded && !isShape) continue;
+    const matchesUuid = nativeId && ev.session_id === nativeId;
+    // A label can be reused. Once a native UUID is known, a same-label event
+    // from another UUID must not expand the session whose work we recover.
+    const matchesSemantic = !nativeId && (
       (semanticSessionId && ev.semantic_session_id === semanticSessionId) ||
-      (!isUuid(sessionId) && sessionId && ev.semantic_session_id === sessionId);
+      (sessionId && ev.semantic_session_id === sessionId)
+    );
     if (!matchesUuid && !matchesSemantic) continue;
     if (typeof ev.session_id === 'string') uuids.add(ev.session_id);
     if (isLock) {
       if (typeof ev.mode === 'string') mode = ev.mode;
       if (typeof ev.semantic_session_id === 'string') semanticFromLock = ev.semantic_session_id;
-    } else {
+    } else if (isEnded) {
       semanticFromEvents = ev.semantic_session_id;
     }
+    if (isShape) {
+      const ts = typeof ev.timestamp === 'string' ? Date.parse(ev.timestamp) : NaN;
+      if (!Number.isNaN(ts)) {
+        // Dated record: ordinary latest-wins.
+        if (shapeTs === null || ts >= shapeTs) {
+          if (shapeUndated) {
+            // A dated record outranks an undated one unconditionally. The
+            // undated readings were never orderable, so they are DISCARDED
+            // rather than merged — otherwise a profile read off an undated
+            // record would survive into a dated win it never belonged to.
+            shapeSessionType = null;
+            shapeSessionProfile = null;
+            shapeUndated = false;
+          }
+          shapeTs = shapeTs === null ? ts : Math.max(shapeTs, ts);
+          if (typeof ev.session_type === 'string') shapeSessionType = ev.session_type;
+          // Absent is not empty: the emitter OMITS the key when there is no
+          // profile, so only a present string may overwrite a previous reading.
+          if (typeof ev.session_profile === 'string') shapeSessionProfile = ev.session_profile;
+        }
+      } else if (shapeTs === null && !shapeUndated) {
+        // Undated record: usable only while NO dated record has been seen, and
+        // never as a tie-breaker between two of them.
+        const hasType = typeof ev.session_type === 'string';
+        const hasProfile = typeof ev.session_profile === 'string';
+        if (hasType) shapeSessionType = ev.session_type;
+        if (hasProfile) shapeSessionProfile = ev.session_profile;
+        if (hasType || hasProfile) shapeUndated = true;
+      }
+    }
   }
 
   // Second pass — started + terminal timestamps from every matched UUID.
@@ -247,6 +312,9 @@ function collectSessionEvents(events, { sessionId, semanticSessionId }) {
   return {
     uuids,
     mode,
+    shapeSessionType,
+    shapeSessionProfile,
+    shapeUndated,
     semanticFromLock,
     semanticFromEvents,
     startedAt,
@@ -336,13 +404,37 @@ function synthesizeRecord({ recordId, synthetic, gathered, nowMs, status = 'aban
   // Guard the same monotonic invariant as before: never earlier than started_at.
   const completedIso = new Date(Math.max(startedMs, completedMs)).toISOString();
 
+  // Precedence: the plan-time shape beats the lock's SessionStart `mode`.
+  // `lock.acquired` fires BEFORE the operator types `/session <type>`, so its
+  // mode is at best a carry-over from the previous session; `shape_resolved` is
+  // emitted the moment the confirmed mode became an execution plan, i.e. it is
+  // the only MEASUREMENT of what this session was. Any session that reached
+  // plan time is therefore no longer `_session_type_inferred`.
+  // An unknown value in either source is IGNORED, never written — the record
+  // then stays `unknown` + inferred rather than carrying an unvalidatable type.
   let sessionType = UNMEASURED_SESSION_TYPE;
   let inferred = true;
-  if (gathered.mode && MEASURED_SESSION_MODES.has(gathered.mode)) {
+  if (gathered.shapeSessionType && MEASURED_SESSION_MODES.has(gathered.shapeSessionType)) {
+    sessionType = gathered.shapeSessionType;
+    // A shape record with a missing/unparseable timestamp is taken only for
+    // lack of a dated one, and it cannot be proven to be the LAST resolution —
+    // so the type is used but stays flagged `_session_type_inferred: true`.
+    inferred = gathered.shapeUndated === true;
+  } else if (gathered.mode && MEASURED_SESSION_MODES.has(gathered.mode)) {
     sessionType = gathered.mode;
     inferred = false;
   }
 
+  // `session_profile` — WRITTEN ONLY WHEN MEASURED. Absent is not empty: a
+  // `null`/`''` on the record would read as "measured, no profile", which is
+  // exactly the honesty defect the enum-plus-omission contract exists to avoid
+  // (VALID_SESSION_PROFILES, session-schema/constants.mjs).
+  const sessionProfile =
+    typeof gathered.shapeSessionProfile === 'string'
+      && VALID_SESSION_PROFILES.includes(gathered.shapeSessionProfile)
+      ? gathered.shapeSessionProfile
+      : null;
+
   const startedFound = typeof gathered.startedAt === 'string';
   const branchFound = typeof gathered.branch === 'string' && gathered.branch.length > 0;
 
@@ -375,6 +467,7 @@ function synthesizeRecord({ recordId, synthetic, gathered, nowMs, status = 'aban
     _backfill_incomplete_fields: incomplete,
   };
   if (branchFound) record.branch = gathered.branch;
+  if (sessionProfile) record.session_profile = sessionProfile;
   if (inferred) {
     record._session_type_inferred = true;
     // GitLab #1234 — BACKFILLER HONESTY, half landed 2026-09-06.
@@ -452,6 +545,48 @@ function isBackfillStub(record) {
   return BACKFILL_STUB_STATUSES.has(record.status);
 }
 
+/**
+ * Find the newest ledger record for one physical session. Shared by the close
+ * precheck and backfill dedupe; no file I/O or mutation.
+ *
+ * Native identity wins over the attribution label. A conflicting native UUID
+ * vetoes a label match. Legacy records without a native join remain readable;
+ * when both start times are known they must name the same instant.
+ *
+ * @param {object[]} records parsed JSONL records, in append order
+ * @param {{sessionId?: string|null, semanticSessionId?: string|null, startedAt?: string|null}} ids
+ * @returns {object|null} existing record, or null when no identity matches
+ */
+export function findRecordedSession(records, { sessionId = null, semanticSessionId = null, startedAt = null } = {}) {
+  // Identity strength cannot resurrect an overwritten/superseded stub. Use
+  // the canonical reader, while retaining append order across surviving keys.
+  const canonical = new Set(canonicalizeSessions(records));
+  const nativeId = isUuid(sessionId) ? sessionId : isUuid(semanticSessionId) ? semanticSessionId : null;
+  const label = semanticSessionId || sessionId;
+  const startMs = typeof startedAt === 'string' ? Date.parse(startedAt) : NaN;
+  let legacyMatch = null;
+  for (let i = records.length - 1; i >= 0; i--) {
+    const record = records[i];
+    if (!canonical.has(record)) continue;
+    if (!record || typeof record !== 'object' || Array.isArray(record)
+      || typeof record.session_id !== 'string' || !record.session_id) continue;
+    const nativeKeys = [record.session_id, record.raw_session_id].filter(isUuid);
+    if (nativeId && nativeKeys.length > 0) {
+      if (nativeKeys.every((id) => id === nativeId)) return record;
+      continue;
+    }
+    if (!label || (record.session_id !== label && record.semantic_session_id !== label)) continue;
+    // A backfill's fallback timestamp is explicitly unmeasured; treating it as
+    // a conflicting start would defeat idempotence on the very next close.
+    const incompleteStart = Array.isArray(record._backfill_incomplete_fields)
+      && record._backfill_incomplete_fields.includes('started_at');
+    const recordStart = !incompleteStart && typeof record.started_at === 'string' ? Date.parse(record.started_at) : NaN;
+    if (Number.isFinite(startMs) && Number.isFinite(recordStart) && startMs !== recordStart) continue;
+    legacyMatch ??= record;
+  }
+  return legacyMatch;
+}
+
 /**
  * Classify what sessions.jsonl already holds for this identity (#1068 AC3/AC4).
  *
@@ -469,23 +604,12 @@ function isBackfillStub(record) {
  *
  * @param {Function} readFileSync
  * @param {string} sessionsPath
- * @param {{recordId: string, sessionId: string|null}} ids
+ * @param {{recordId: string, sessionId: string|null, semanticSessionId?: string|null, startedAt?: string|null}} ids
  */
-function classifyExisting(readFileSync, sessionsPath, { recordId, sessionId }) {
+function classifyExisting(readFileSync, sessionsPath, { recordId, sessionId, semanticSessionId = recordId, startedAt = null }) {
   const sessionRecords = readJsonlSafe(readFileSync, sessionsPath);
-  // Both keys count: the semantic record id, and — defensively — a prior record
-  // keyed directly by the UUID.
-  const uuidKey = isUuid(sessionId) ? sessionId : null;
-  const byId = (id) =>
-    id === null ? [] : sessionRecords.filter((r) => r && r.session_id === id);
-  // Key preference is UNCHANGED from the pre-#1068 dedupe: the semantic
-  // recordId wins whenever any record carries it, and the UUID key is only the
-  // defensive fallback.
-  const semanticMatches = byId(recordId);
-  const matches = semanticMatches.length > 0 ? semanticMatches : byId(uuidKey);
-  if (matches.length === 0) return { kind: 'absent' };
-
-  const newest = matches[matches.length - 1];
+  const newest = findRecordedSession(sessionRecords, { sessionId, semanticSessionId, startedAt });
+  if (!newest) return { kind: 'absent' };
   if (isBackfillStub(newest)) {
     return { kind: 'stub', matchedId: newest.session_id, stubId: newest.session_id };
   }
@@ -650,6 +774,15 @@ export async function backfillAbandonedSession({
         if (dupe) return dupe;
       }
 
+      // Dedupe rejected any foreign native identity above. Do not now reuse
+      // that session's semantic key: canonical readers collapse by session_id.
+      // Keep the existing legacy key convention unless the key is occupied.
+      const semanticRecordId = recordId;
+      if (isUuid(sessionId) && recordId !== sessionId
+        && readJsonlSafe(readFileSync, sessionsPath).some((record) => record?.session_id === recordId)) {
+        recordId = sessionId;
+      }
+
       // -- Liveness guard — never overwrite a FOREIGN live lock, and never ----
       // record OUR OWN live lock as 'abandoned' (#863 defect 1). Before this
       // fix, the guard below only ever ran when `foreign` was true — the
@@ -720,6 +853,7 @@ export async function backfillAbandonedSession({
         nowMs,
         rawSessionId: isUuid(sessionId) ? sessionId : null,
       });
+      if (recordId !== semanticRecordId) record.semantic_session_id = semanticRecordId;
       let validated;
       try {
         validated = validateSession(record);
@@ -831,17 +965,12 @@ export async function backfillAbandonedSession({
  *   as "otherwise 0, flagged in `_backfill_incomplete_fields`" — the same
  *   contract the abandoned path already carries and the same reason it exists.
  *
- *   CONSTRAINT specific to this path: STATE.md's `session` field is already
- *   the SEMANTIC id, never the raw harness UUID — unlike
- *   `backfillAbandonedSession` (which usually receives the UUID directly from
- *   SessionEnd stdin), this function has no UUID to seed `collectSessionEvents`'s
- *   `uuids` set with. Events therefore only surface here when a
- *   `lock.acquired` breadcrumb bridges the UUID to this exact semantic id
- *   (`ev.semantic_session_id === recordId`) — the SAME bridge condition
- *   `backfillAbandonedSession`'s synthetic-id fallback exists to handle when
- *   ABSENT. Without that bridge, `gathered` stays empty and the record still
- *   validates (started_at/completed_at both fall back to `now`, flagged
- *   incomplete) — degraded but never blocked.
+ *   A native `session-id` in STATE.md seeds event correlation directly and
+ *   keys the new record; `session` is retained as `semantic_session_id`.
+ *   Legacy STATE.md without a native UUID keeps its semantic record key and
+ *   needs a lock.acquired/session.ended bridge to recover UUID-scoped events.
+ *   Without either identity route, timestamps fall back to `now` and are
+ *   flagged incomplete rather than fabricated from STATE.md body prose.
  *
  * Never throws. Returns one of:
  *   { action: 'backfilled', sessionId, record }              — written to disk
@@ -910,31 +1039,43 @@ export async function backfillCompletedFromStateMd({
         return { action: 'skipped-not-completed', status: stateStatus ?? null };
       }
 
-      const recordId = parsed.frontmatter?.session;
-      if (typeof recordId !== 'string' || recordId.length === 0) {
+      const semanticSessionId = parsed.frontmatter?.session;
+      if (typeof semanticSessionId !== 'string' || semanticSessionId.length === 0) {
         return { action: 'skipped-no-session-id' };
       }
+      const stateSessionId = parsed.frontmatter?.['session-id'];
+      const nativeId = isUuid(stateSessionId) ? stateSessionId : isUuid(semanticSessionId) ? semanticSessionId : null;
+      let recordId = nativeId ?? semanticSessionId;
 
       // -- Dedupe, or SUPERSEDE a backfill stub (#1068 AC3) ---------------------
       // This is the authoritative writer of the pair: STATE.md's own
       // `status: completed` is the session's truth claim about itself, and it
-      // arrives with an identity-complete key (the semantic id). When the only
+      // arrives with the native UUID or legacy semantic key. When the only
       // thing on file for that identity is a reconstructed `abandoned` stub,
       // the stub is a measurement this record refutes — so we append the fuller
       // record (carrying `supersedes: <stub id>`) instead of skipping. An
       // authoritative record already on file still short-circuits exactly as
       // before.
       const sessionsPath = path.join(repoRoot, ...SESSIONS_REL);
-      const existing = classifyExisting(readFileSync, sessionsPath, { recordId, sessionId: recordId });
+      const existing = classifyExisting(readFileSync, sessionsPath, {
+        recordId,
+        sessionId: nativeId,
+        semanticSessionId,
+        startedAt: parsed.frontmatter?.started_at,
+      });
       if (existing.kind === 'canonical') {
         return { action: 'skipped-already-recorded', sessionId: existing.matchedId };
       }
       const supersedes = existing.kind === 'stub' ? existing.stubId : null;
+      // Preserve a matched stub's key for its append-only replacement. Without
+      // event timestamps or a raw join on a legacy stub, a new UUID key would
+      // leave two canonical sessions: its supersedes proof is unattestable.
+      if (supersedes) recordId = supersedes;
 
       // -- Derive whatever is derivable from events.jsonl (never STATE.md body) -
       const eventsPath = path.join(repoRoot, ...EVENTS_REL);
       const events = readJsonlSafe(readFileSync, eventsPath);
-      const gathered = collectSessionEvents(events, { sessionId: null, semanticSessionId: recordId });
+      const gathered = collectSessionEvents(events, { sessionId: nativeId, semanticSessionId });
 
       // -- Synthesize + validate (round-trip gate) BEFORE any disk mutation ----
       const record = synthesizeRecord({
@@ -953,6 +1094,7 @@ export async function backfillCompletedFromStateMd({
         // same fail-quiet posture as `isUuid(sessionId) ? sessionId : null`.
         rawSessionId: gathered.uuids?.size === 1 ? [...gathered.uuids][0] : null,
       });
+      if (nativeId && semanticSessionId !== nativeId) record.semantic_session_id = semanticSessionId;
       let validated;
       try {
         validated = validateSession(record);