session-orchestrator 5.0.0 → 5.2.0

package/scripts/lib/scope-echo.mjs

@@ -37,11 +37,11 @@
  *   node scripts/lib/scope-echo.mjs --help
  */
 
-import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 
 import { digestSha256Short } from './crypto-digest-utils.mjs';
+import { isMainModule } from './is-main-module.mjs';
 
 /** Marker the agent must emit. Case-sensitive by design — a lowercase lookalike is not an echo. */
 export const SCOPE_ECHO_MARKER = 'SCOPE-DIGEST:';
@@ -49,6 +49,15 @@ export const SCOPE_ECHO_MARKER = 'SCOPE-DIGEST:';
 /** Event name for the post-wave verdict. */
 export const SCOPE_ECHO_EVENT = 'orchestrator.wave_dispatch.scope_echo_checked';
 
+/** The SEND-side record `hooks/pre-task-scope-disjoint.mjs` writes per dispatch. */
+export const SCOPE_CHECKED_EVENT = 'orchestrator.wave_dispatch.scope_checked';
+
+/** The DEGRADATION record `scripts/materialize-wave-scope.mjs` writes per wave. */
+export const SCOPE_MATERIALIZED_EVENT = 'orchestrator.wave_dispatch.scope_materialized';
+
+/** The per-WAVE join verdict `--verify` emits. */
+export const SCOPE_VERIFIED_EVENT = 'orchestrator.wave_dispatch.scope_verified';
+
 /** Max characters retained for `agent_id` in the payload (same clamp as the send-side hook). */
 const AGENT_ID_MAX = 120;
 
@@ -212,6 +221,308 @@ export function scopeEchoPayload(verdict, meta = {}) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// --verify — join the two halves of one wave ON THE DIGEST (#1092)
+// ---------------------------------------------------------------------------
+
+/**
+ * Closed verdict enum. Order is PRECEDENCE, not preference — the first matching
+ * row wins, and every (file, dispatch, echo) triple lands on exactly one row:
+ *
+ *   duplicate-claim      ≥2 DISTINCT agent ids claimed one digest at dispatch.
+ *                        That is agent A's scope reported for agent B, and it is
+ *                        a defect whatever the other two bits say — so it is
+ *                        checked first.
+ *   echoed-not-injected  an echo names a digest NO dispatch claimed.
+ *   digest-unknown       no scope FILE on disk carries this digest: the record
+ *                        exists but the artefact that would ground it does not
+ *                        (a scope file rewritten or reconciled away after the
+ *                        dispatch).
+ *   matched              file ∧ dispatch ∧ echo.
+ *   injected-not-echoed  file ∧ dispatch, no echo — the normal state DURING a
+ *                        wave, before the reports land.
+ *   injection-missing    file ∧ neither — a scope file no dispatch claimed and
+ *                        no agent echoed. This is AC-2: the omitted injection.
+ *
+ * Every member is kebab-case. `echo-only` is NOT one of the six: it is the
+ * DEGRADED value every verdict collapses to when the wave's transport is
+ * unobservable (see {@link verifyWaveScope}), so it is never produced by the
+ * precedence chain above and never belongs in this array.
+ *
+ * `injection-missing` was spelled `injection_missing` until 2026-09-16 — the
+ * one snake_case member of an otherwise kebab-case enum. Ledger records written
+ * before that date may still carry the old spelling in `by_verdict`; there is no
+ * dual-emit, so a consumer reading historical rows must accept both keys.
+ */
+export const SCOPE_VERDICTS = Object.freeze([
+  'duplicate-claim',
+  'echoed-not-injected',
+  'digest-unknown',
+  'matched',
+  'injected-not-echoed',
+  'injection-missing',
+]);
+
+/** A well-formed digest. Anything else is ignored rather than joined on. */
+const DIGEST_RE = /^[0-9a-f]{8}$/;
+
+/**
+ * Parse a JSONL ledger leniently: a malformed line is skipped, never thrown on
+ * — and COUNTED, which is the load-bearing half.
+ *
+ * A crashed writer leaves a truncated final line (`{"event":"…","wave":4` with
+ * no closing brace) — a measured shape in this repo's own ledger. Skipping it
+ * silently truncates the join, and a truncated join reports
+ * `dispatches N / injected N / echoed N` with every digest `matched`: a CLEAN
+ * wave, from the instrument built to detect silent failure. The count is what
+ * separates "nothing was wrong" from "I could not read part of the evidence".
+ *
+ * A malformed line is any NON-BLANK line that does not yield a plain object:
+ * one that does not start with `{`, one `JSON.parse` rejects, and one that
+ * parses to an array or a scalar. Blank lines are not malformed — a trailing
+ * newline is the normal end of a JSONL file.
+ *
+ * @param {string} raw
+ * @returns {{records: Array<Record<string, unknown>>, malformed: number}}
+ */
+function parseJsonl(raw) {
+  /** @type {Array<Record<string, unknown>>} */
+  const records = [];
+  let malformed = 0;
+  if (typeof raw !== 'string') return { records, malformed };
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    if (trimmed[0] !== '{') {
+      malformed += 1;
+      continue;
+    }
+    try {
+      const rec = JSON.parse(trimmed);
+      if (rec !== null && typeof rec === 'object' && !Array.isArray(rec)) records.push(rec);
+      else malformed += 1;
+    } catch {
+      malformed += 1; // a half-written line is not a verdict — but it is not nothing either
+    }
+  }
+  return { records, malformed };
+}
+
+/**
+ * Digest every per-agent scope file of one wave — shape (a) of the two scope
+ * shapes (CLAUDE.md / AGENTS.md § allowedPaths).
+ *
+ * @param {string} stateDir
+ * @param {number} wave
+ * @param {{readDir?: typeof readdirSync, readFile?: typeof readFileSync}} [io]
+ * @returns {Map<string, string[]>} digest → agent ids (file basenames)
+ */
+export function digestScopeFiles(stateDir, wave, { readDir = readdirSync, readFile = readFileSync } = {}) {
+  const out = new Map();
+  const dir = resolve(String(stateDir), 'filescopes', `wave-${wave}`);
+  let names;
+  try {
+    names = readDir(dir);
+  } catch {
+    return out; // no directory yet is not a failure — it is "nothing materialized"
+  }
+  for (const name of names) {
+    const file = typeof name === 'string' ? name : name?.name;
+    if (typeof file !== 'string' || !file.endsWith('.json')) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(readFile(join(dir, file), 'utf8'));
+    } catch { continue; }
+    if (!Array.isArray(parsed) || normalizeScopePaths(parsed).length === 0) continue;
+    const digest = scopeDigest(parsed);
+    const ids = out.get(digest) ?? [];
+    ids.push(file.slice(0, -'.json'.length));
+    out.set(digest, ids);
+  }
+  return out;
+}
+
+/**
+ * Verify ONE wave's FILE-SCOPE injection end to end.
+ *
+ * ## Why the join key is the DIGEST and never `agent_id`
+ *
+ * Measured 2026-09-16 over this host's `.orchestrator/metrics/events.jsonl`
+ * corpus: 609 `scope_checked` records against 51 `scope_echo_checked`, and the
+ * two agent-id sets OVERLAP IN ZERO ELEMENTS — the send side records the
+ * dispatch tool's `description` plus `subagent_type`
+ * (`"i-3 #1353 refund event (session-orchestrator:code-implementer)"`), the
+ * receive side the coordinator's short handle (`"i-3"`). One session showed 23
+ * echoes against 18 injections and the halves could not be joined at all. The
+ * digest is the one value both halves derive from the SAME artefact, so it joins
+ * them by construction.
+ *
+ * ## Observability, not enforcement
+ *
+ * Every verdict exits 0. This tool reports; the wave-executor turns
+ * `injection-missing` / `duplicate-claim` into a STATE.md deviation
+ * (`wave-loop-review.md` step 3d-bis), never into a block.
+ *
+ * ## A partial read is never a clean wave
+ *
+ * `malformed_lines` counts the ledger lines that could not be parsed (a crashed
+ * writer's truncated append is the measured shape). It is ALWAYS present,
+ * including as `0`: the ledger read either happened or the file was absent, and
+ * both are measurements. A non-zero count means the join ran on INCOMPLETE
+ * evidence — the counts and verdicts below are a floor, not a census — and the
+ * human table says so beside them.
+ *
+ * ## Transport degradation
+ *
+ * On a platform with no `PreToolUse` `Agent` matcher (Codex, Cursor, Pi) the
+ * send-side record cannot exist at all, so a missing dispatch is NOT evidence of
+ * a missing injection. When the wave's `scope_materialized` record says
+ * `transport_observable: false`, `transport` reads `unobservable` and every
+ * verdict degrades to `echo-only` — the receive half is all the platform can
+ * carry, and reporting `injection-missing` there would be an accusation derived
+ * from an instrument that is not installed.
+ *
+ * @param {object} params
+ * @param {number} params.wave
+ * @param {string} params.stateDir
+ * @param {string} [params.session]    semantic (or raw) session id to filter on
+ * @param {string} [params.eventsPath] defaults to `.orchestrator/metrics/events.jsonl`
+ * @param {typeof readFileSync} [params.readFile]
+ * @param {typeof readdirSync} [params.readDir]
+ * @returns {{wave: number, transport: 'observable'|'unobservable', dispatches: number,
+ *            injected: number, echoed: number, malformed_lines: number,
+ *            by_verdict: Record<string, number>,
+ *            agents: Array<{agent_id: string, verdict: string, digest: string}>}}
+ */
+export function verifyWaveScope({
+  wave,
+  stateDir,
+  session,
+  eventsPath,
+  readFile = readFileSync,
+  readDir = readdirSync,
+}) {
+  const ledgerPath = eventsPath || join('.orchestrator', 'metrics', 'events.jsonl');
+  let records = [];
+  let malformedLines = 0;
+  try {
+    ({ records, malformed: malformedLines } = parseJsonl(readFile(ledgerPath, 'utf8')));
+  } catch { /* no ledger yet — every count is legitimately 0 */ }
+
+  const mine = (rec) => {
+    if (rec.wave !== wave) return false;
+    if (!session) return true;
+    return rec.semantic_session_id === session || rec.session_id === session;
+  };
+
+  /** @type {Map<string, Set<string>>} digest → distinct dispatching agent ids */
+  const dispatchIds = new Map();
+  /** @type {Map<string, string>} digest → first echoing agent id */
+  const echoIds = new Map();
+  let dispatches = 0;
+  let injected = 0;
+  let echoed = 0;
+  // A wave may be materialized more than once (#1103); the LAST record wins,
+  // because that is the state the dispatches below actually ran against.
+  let transportObservable = null;
+
+  for (const rec of records) {
+    if (rec.event === SCOPE_MATERIALIZED_EVENT && mine(rec)) {
+      if (typeof rec.transport_observable === 'boolean') transportObservable = rec.transport_observable;
+      continue;
+    }
+    if (rec.event === SCOPE_CHECKED_EVENT && mine(rec)) {
+      dispatches += 1;
+      if (rec.injected === true) injected += 1;
+      const digest = rec.scope_digest;
+      if (typeof digest === 'string' && DIGEST_RE.test(digest)) {
+        const ids = dispatchIds.get(digest) ?? new Set();
+        ids.add(typeof rec.agent_id === 'string' ? rec.agent_id : 'unnamed-agent');
+        dispatchIds.set(digest, ids);
+      }
+      continue;
+    }
+    if (rec.event === SCOPE_ECHO_EVENT && mine(rec)) {
+      if (rec.echoed === true) echoed += 1;
+      // The agent's OWN claim first (`actual_digest`); the coordinator-side
+      // expectation only as a fallback, so a mismatched echo still joins to the
+      // scope file it was checked against rather than vanishing from the report.
+      const digest = [rec.actual_digest, rec.expected_digest]
+        .find((d) => typeof d === 'string' && DIGEST_RE.test(d));
+      if (digest !== undefined && !echoIds.has(digest)) {
+        echoIds.set(digest, typeof rec.agent_id === 'string' ? rec.agent_id : 'unnamed-agent');
+      }
+    }
+  }
+
+  const fileIds = digestScopeFiles(stateDir, wave, { readDir, readFile });
+  const digests = [...new Set([...fileIds.keys(), ...dispatchIds.keys(), ...echoIds.keys()])].sort();
+
+  const unobservable = transportObservable === false;
+  /** @type {Record<string, number>} */
+  const byVerdict = {};
+  const agents = digests.map((digest) => {
+    const claimants = dispatchIds.get(digest);
+    const hasDispatch = claimants !== undefined && claimants.size > 0;
+    const hasEcho = echoIds.has(digest);
+    const hasFile = fileIds.has(digest);
+
+    let verdict;
+    if (hasDispatch && claimants.size > 1) verdict = 'duplicate-claim';
+    else if (hasEcho && !hasDispatch) verdict = 'echoed-not-injected';
+    else if (!hasFile) verdict = 'digest-unknown';
+    else if (hasDispatch && hasEcho) verdict = 'matched';
+    else if (hasDispatch) verdict = 'injected-not-echoed';
+    else verdict = 'injection-missing';
+    if (unobservable) verdict = 'echo-only';
+
+    byVerdict[verdict] = (byVerdict[verdict] ?? 0) + 1;
+    const agentId = (hasDispatch ? [...claimants].sort().join(' + ') : null)
+      ?? echoIds.get(digest)
+      ?? (fileIds.get(digest) ?? []).join(' + ')
+      ?? 'unknown';
+    return { agent_id: agentId, verdict, digest };
+  });
+
+  return {
+    wave,
+    transport: unobservable ? 'unobservable' : 'observable',
+    dispatches,
+    injected,
+    echoed,
+    malformed_lines: malformedLines,
+    by_verdict: byVerdict,
+    agents,
+  };
+}
+
+/**
+ * Telemetry payload for a `--verify` run. Counts, closed enums and 8-hex digests
+ * ONLY — no agent id, no path, no prompt text: this record travels over the same
+ * unredacted Clank Event-Bus webhook as its two halves, and an `agent_id` is a
+ * free-form coordinator string that has carried private project slugs before.
+ *
+ * `malformed_lines` travels with the counts and, like them, is ALWAYS present
+ * including as `0` — it is the denominator's honesty check: without it a join
+ * that silently dropped half the ledger is indistinguishable in the record from
+ * a wave where nothing went wrong (`.claude/rules/host-resources.md` § HR-105).
+ *
+ * @param {ReturnType<typeof verifyWaveScope>} report
+ * @returns {Record<string, unknown>}
+ */
+export function scopeVerifiedPayload(report) {
+  return {
+    wave: report.wave,
+    transport_observable: report.transport === 'observable',
+    dispatches: report.dispatches,
+    injected: report.injected,
+    echoed: report.echoed,
+    malformed_lines: report.malformed_lines ?? 0,
+    by_verdict: report.by_verdict,
+    digests: report.agents.map((a) => a.digest),
+  };
+}
+
 // ---------------------------------------------------------------------------
 // CLI
 // ---------------------------------------------------------------------------
@@ -229,9 +540,19 @@ const USAGE = `Usage:
       an ${SCOPE_ECHO_EVENT} row to .orchestrator/metrics/events.jsonl
       (best-effort: a failed emit never changes the verdict or the exit code).
 
+  scope-echo --verify --wave <N> --state-dir <dir> [--session <id>]
+             [--events <path>] [--json] [--emit]
+      Join ONE wave's send side (${SCOPE_CHECKED_EVENT}),
+      its scope files and its echoes ON THE DIGEST, and print the per-agent
+      verdict table. --emit additionally appends one ${SCOPE_VERIFIED_EVENT}
+      row per wave (counts and 8-hex digests only).
+      Verdicts: ${SCOPE_VERDICTS.join(' · ')} — plus echo-only when the wave's
+      transport is unobservable.
+
   scope-echo --help
 
-Exit codes: 0 for every verdict, 1 for a missing --scope-file.
+Exit codes: 0 for every verdict, 1 for a missing --scope-file (or, under
+--verify, a missing --wave / --state-dir).
 `;
 
 /**
@@ -259,6 +580,68 @@ function parseArgv(argv) {
   return out;
 }
 
+/**
+ * `--verify` mode — the per-wave join (see {@link verifyWaveScope}).
+ *
+ * Exit 0 for EVERY verdict, including `injection-missing`: this is an
+ * observability tool, and the wave-executor decides what a verdict costs
+ * (`wave-loop-review.md` step 3d-bis writes a STATE.md deviation, never a
+ * block). Exit 1 is reserved for the caller's own mistake — a missing required
+ * flag — per `.claude/rules/cli-design.md`.
+ *
+ * @param {Record<string, string|boolean>} args
+ * @returns {Promise<number>}
+ */
+async function mainVerify(args) {
+  const wave = Number(args.wave);
+  const stateDir = typeof args['state-dir'] === 'string' ? args['state-dir'] : '';
+  if (!Number.isSafeInteger(wave) || wave <= 0 || stateDir === '') {
+    process.stderr.write('scope-echo: --verify requires --wave <positive-int> and --state-dir <dir>\n');
+    process.stderr.write(USAGE);
+    return 1;
+  }
+
+  const report = verifyWaveScope({
+    wave,
+    stateDir,
+    session: typeof args.session === 'string' ? args.session : undefined,
+    eventsPath: typeof args.events === 'string' ? args.events : undefined,
+  });
+
+  if (args.emit) {
+    try {
+      const repoRoot = resolve(stateDir, '..');
+      const { emitEvent, sessionAttribution } = await import('./events.mjs');
+      await emitEvent(
+        SCOPE_VERIFIED_EVENT,
+        { ...scopeVerifiedPayload(report), ...sessionAttribution(repoRoot) },
+        { repoRoot },
+      );
+    } catch (err) {
+      process.stderr.write(`scope-echo: emit failed — ${err?.message ?? err}\n`);
+    }
+  }
+
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(report)}\n`);
+    return 0;
+  }
+  const lines = [
+    `wave ${report.wave} — transport: ${report.transport} — `
+      + `${report.injected}/${report.dispatches} injected, ${report.echoed} echoed`,
+    // A partial read must never read as a clean wave: the counts above are a
+    // FLOOR when lines were dropped, and this is the only place the human table
+    // can say so.
+    ...(report.malformed_lines > 0
+      ? [`  WARNING: ${report.malformed_lines} malformed ledger line(s) skipped — `
+        + 'counts and verdicts below are a floor, not a census']
+      : []),
+    ...report.agents.map((a) => `  ${a.digest}  ${a.verdict.padEnd(20)}  ${a.agent_id}`),
+  ];
+  process.stdout.write(`${lines.join('\n')}\n`);
+  return 0;
+}
+
 /**
  * @param {string[]} [argv]
  * @returns {Promise<number>} process exit code: 0 for every verdict (this is an
@@ -272,6 +655,10 @@ export async function main(argv = process.argv.slice(2)) {
     process.stdout.write(USAGE);
     return 0;
   }
+  // --verify is its own mode and takes no --scope-file: it reads EVERY scope
+  // file of the wave, so the check below must not reject it first.
+  if (args.verify) return mainVerify(args);
+
   const scopeFilePath = typeof args['scope-file'] === 'string' ? args['scope-file'] : '';
   if (!scopeFilePath) {
     process.stderr.write('scope-echo: --scope-file <path> is required\n');
@@ -337,9 +724,7 @@ export async function main(argv = process.argv.slice(2)) {
   return 0;
 }
 
-const invokedAsCli =
-  process.argv[1] !== undefined &&
-  resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url));
+const invokedAsCli = isMainModule(import.meta.url);
 
 if (invokedAsCli) {
   process.exitCode = await main();

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

@@ -14,7 +14,7 @@
  * `scripts/backfill-abandoned-sessions.mjs`.
  *
  * A second, sibling export — `backfillCompletedFromStateMd` — closes a
- * different gap (#429): `commands/close.md`'s Pre-Check treats STATE.md
+ * different gap (#429): `skills/close/SKILL.md`'s Pre-Check treats STATE.md
  * `status: completed` as proof the session-end writer already ran and refuses
  * to invoke it again. When that status was set by hand (or by any path that
  * never reached Phase 3.7), no sessions.jsonl record is EVER written — the
@@ -545,13 +545,38 @@ function isBackfillStub(record) {
   return BACKFILL_STUB_STATUSES.has(record.status);
 }
 
+/**
+ * How far a caller-supplied `started_at` may drift from a legacy-label record's
+ * own `started_at` before the two are judged to name DIFFERENT sessions (#1368).
+ *
+ * Six hours is deliberately wider than any plausible write-lag and narrower
+ * than a day, because the legacy label the drift gate corroborates
+ * (`<branch>-<YYYY-MM-DD>-<mode>-<n>`) ALREADY carries the date: two records
+ * that share a label and sit inside the same six-hour window are the same
+ * session, and two that share a label across a day boundary cannot exist,
+ * because the label's date component would differ.
+ */
+export const STARTED_AT_DRIFT_TOLERANCE_MS = 6 * 3600 * 1000;
+
 /**
  * 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.
+ * vetoes a label match. Legacy records without a native join remain readable.
+ *
+ * `started_at` is a CORROBORATING SIGNAL on the legacy-label path, never an
+ * identity key (#1368). The two timestamps being compared are written by
+ * different producers at different moments — STATE.md's is written by hand
+ * when the coordinator initialises the file (measured 2026-09-13: 48 minutes
+ * after the lock's own `started_at`), while the ledger's comes from the
+ * `session.started` event or from STATE.md itself. Demanding an
+ * EXACT-millisecond match therefore vetoed a correct label match on the only
+ * path that can reach it, which is what made `/close`'s #429 pre-check report
+ * "no matching record" for a session that WAS recorded. Only a drift larger
+ * than {@link STARTED_AT_DRIFT_TOLERANCE_MS} now vetoes — a window, not an
+ * off-switch, so two genuinely different same-label sessions still fail to
+ * match.
  *
  * @param {object[]} records parsed JSONL records, in append order
  * @param {{sessionId?: string|null, semanticSessionId?: string|null, startedAt?: string|null}} ids
@@ -581,7 +606,8 @@ export function findRecordedSession(records, { sessionId = null, semanticSession
     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;
+    if (Number.isFinite(startMs) && Number.isFinite(recordStart)
+      && Math.abs(startMs - recordStart) > STARTED_AT_DRIFT_TOLERANCE_MS) continue;
     legacyMatch ??= record;
   }
   return legacyMatch;
@@ -670,6 +696,21 @@ function checkAlreadyRecorded(readFileSync, sessionsPath, { recordId, sessionId
  *   historical migration CLI only — `hooks/on-session-end.mjs` must NEVER
  *   pass this (a hook-time foreign lock is by definition a real, active
  *   session, not stale history).
+ * @param {boolean} [args.ownSessionIsEnding=false]
+ *   #1376 — the caller IS the session this candidate names, and it is tearing
+ *   itself down right now. An OWN lock that is still live means "this session
+ *   is RUNNING" only when the asker is somebody else: at `SessionEnd` the
+ *   ending session's own heartbeat is by construction fresh (it was refreshed
+ *   minutes ago, TTL 4h), so the `skipped-own-live-lock` branch below rejected
+ *   every unclosed session's own stub and the ledger never got one. Pass
+ *   `true` ONLY from `hooks/on-session-end.mjs`, and ONLY inside the
+ *   `isRecordedSession` guard that already gates `duration_ms` /
+ *   `semantic_session_id` — a FOREIGN terminating window that inherited this
+ *   session's semantic id from the shared `current-session.json` (#863 defect
+ *   (b)) must never set it. The migration CLI and the SessionStart recovery
+ *   path (`scripts/backfill-abandoned-sessions.mjs`) NEVER pass it: there the
+ *   candidate's live own lock genuinely means a running session.
+ *   The FOREIGN-live-lock guard is untouched by this flag.
  * @param {number|null} [args.assumeDeadBeforeMs=null]
  *   #731 — operator-supplied cutoff (ms-since-epoch). A candidate whose
  *   `lastEventMs` strictly predates this value bypasses a foreign live lock
@@ -685,6 +726,7 @@ export async function backfillAbandonedSession({
   now = Date.now(),
   dryRun = false,
   relaxDeadByAge = false,
+  ownSessionIsEnding = false,
   assumeDeadBeforeMs = null,
   deps = {},
 } = {}) {
@@ -827,7 +869,17 @@ export async function backfillAbandonedSession({
         // only ever fires when `foreign` is true). A STALE own lock
         // (isLockLive === false) falls through unchanged — this is a
         // liveness gate, not a blanket own-session off-switch.
-        if (own && isLockLive(lock, nowMs)) {
+        //
+        // #1376 — "own + live" is a RUNNING session only when the caller is
+        // NOT that session's own teardown. At SessionEnd the ending session's
+        // heartbeat is still fresh by construction, so without
+        // `ownSessionIsEnding` this branch swallowed the stub of every session
+        // that never reached /close — the exact gap the close-through backfill
+        // exists to close. The caller carries the attestation (see the param
+        // docblock); this module never re-derives it, because the only signal
+        // available here — the lock's own liveness — is what is being
+        // qualified.
+        if (own && isLockLive(lock, nowMs) && !ownSessionIsEnding) {
           return { action: 'skipped-own-live-lock', sessionId: recordId };
         }
 
@@ -934,7 +986,7 @@ export async function backfillAbandonedSession({
  * matching record (#429).
  *
  * ── THE GAP THIS CLOSES ──────────────────────────────────────────────────
- *   `commands/close.md`'s Pre-Check treats `STATE.md status: completed` as
+ *   `skills/close/SKILL.md`'s Pre-Check treats `STATE.md status: completed` as
  *   PROOF that the session-end skill's Phase 3.7 writer already ran, and
  *   stops before invoking it — including when `status: completed` was set by
  *   hand (or by any path that never reached Phase 3.7). The session then has

package/scripts/lib/state-md.mjs

@@ -10,13 +10,15 @@
  * @see scripts/lib/state-md/mission-status.mjs      parseMissionStatus, parseMissionStatusStrict, MISSION_STATUS_VALUES, writeMissionStatus, setMissionStatus, setMissionStatusDetailed, readMissionStatus, recoverFrontmatterMissionStatusDetailed, writeMissionStatusOnDisk, setMissionStatusOnDisk
  * @see scripts/lib/state-md/recommendations.mjs     parseRecommendations
  *
- * Plus ONE small non-re-export surface: the `session-profile` frontmatter
- * accessors at the bottom of this file (see their docblock for why they are
- * composed here rather than added as a fourth mutator module).
+ * Plus TWO small non-re-export surfaces at the bottom of this file (each with
+ * its own docblock explaining why it is composed here rather than added as a
+ * fourth mutator module): the `session-profile` frontmatter accessors, and the
+ * `started_at` / `session-id` frontmatter SOURCES (#1368).
  */
 
 import { parseStateMd as _parseStateMd } from './state-md/yaml-parser.mjs';
 import { updateFrontmatterFields as _updateFrontmatterFields } from './state-md/frontmatter-mutators.mjs';
+import { readLock as _readLock } from './session-lock.mjs';
 
 export { parseStateMd, serializeStateMd } from './state-md/yaml-parser.mjs';
 
@@ -140,3 +142,82 @@ export function setSessionProfile(contents, profile) {
     [SESSION_PROFILE_FIELD]: profile === null ? null : profile.trim(),
   });
 }
+
+// ---------------------------------------------------------------------------
+// STATE.md frontmatter SOURCES (#1368) — `started_at` / `session-id`.
+//
+// These two helpers exist because the frontmatter they feed is written by the
+// coordinator LLM from prose, and prose with no named source gets written from
+// `new Date()` at WRITE time. `started_at` then names the moment STATE.md was
+// created, not the moment the session began — measured 2026-09-13: 48 minutes
+// apart. Every other producer of that timestamp (the lock's own `started_at`,
+// `orchestrator.session.lock.acquired`, `orchestrator.session.started`) agrees
+// within 1 ms, because all three descend from `buildLock()`. So the lock is
+// the source, and these functions are how the template cites it.
+//
+// They live in this barrel rather than in `state-md/`: the barrel is the
+// documented entry point for STATE.md work, and the edge barrel → session-lock
+// already exists (state-md/frontmatter-mutators.mjs imports `withStateMdLock`
+// from it), so no cycle is created — session-lock.mjs imports nothing from
+// this module or its submodules.
+// ---------------------------------------------------------------------------
+
+/**
+ * The canonical `started_at` for a STATE.md written during THIS session.
+ *
+ * Returns the live lock's `started_at`, normalised to ISO-8601 UTC ("Z"), so
+ * STATE.md, the lock, both lock events and the ledger all name the SAME
+ * instant. Falls back to `new Date().toISOString()` ONLY when no usable lock
+ * exists — a missing lock means `persistence: false`, a lock that could not be
+ * acquired, or a corrupt lock file, and in all three the writer has no better
+ * source than the present moment. The fallback is deliberately silent: it is a
+ * degradation of PRECISION, not a failure.
+ *
+ * Never throws.
+ *
+ * @param {{ repoRoot?: string }} [opts]
+ * @returns {string} ISO-8601 UTC timestamp.
+ */
+export function resolveSessionStartedAt({ repoRoot } = {}) {
+  try {
+    const lock = _readLock({ repoRoot });
+    const raw = lock?.started_at;
+    if (typeof raw === 'string' && raw.length > 0) {
+      const ms = Date.parse(raw);
+      if (Number.isFinite(ms)) return new Date(ms).toISOString();
+    }
+  } catch {
+    /* readLock is no-throw by contract; the contract is not ours to trust */
+  }
+  return new Date().toISOString();
+}
+
+/**
+ * The session ids a STATE.md writer may stamp into frontmatter: `session-id`
+ * (the RAW/native harness id) and `session` (the semantic attribution label),
+ * both read from the live lock.
+ *
+ * Both fields are `null` when no usable lock exists — ABSENCE IS NEVER
+ * COERCED, and a writer must then OMIT the key rather than write a
+ * placeholder. Neither id grants ownership of anything (see
+ * `skills/_shared/state-ownership.md`); `session-id` exists so `/close`'s #429
+ * pre-check can join STATE.md to sessions.jsonl on a native identity instead
+ * of falling through to the label + timestamp path.
+ *
+ * Never throws.
+ *
+ * @param {{ repoRoot?: string }} [opts]
+ * @returns {{ session_id: string|null, semantic_session_id: string|null }}
+ */
+export function resolveSessionIds({ repoRoot } = {}) {
+  const pick = (value) => (typeof value === 'string' && value.trim().length > 0 ? value.trim() : null);
+  try {
+    const lock = _readLock({ repoRoot });
+    return {
+      session_id: pick(lock?.session_id),
+      semantic_session_id: pick(lock?.semantic_session_id),
+    };
+  } catch {
+    return { session_id: null, semantic_session_id: null };
+  }
+}