session-orchestrator 5.2.0 → 5.3.0

package/scripts/check-sessions-integrity.mjs

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+// scripts/check-sessions-integrity.mjs
+//
+// CLI front-end for `checkSessionsIntegrity` (GitLab #1417).
+//
+// WHY THIS EXISTS:
+//   session-end step 4a (`skills/session-end/session-metrics-write.md`) has to
+//   prove that the session record it JUST appended to
+//   `.orchestrator/metrics/sessions.jsonl` is schema-valid AND renderable by
+//   vault-mirror — step 4 before it only proves the line is JSON. The #1408
+//   record parsed fine and was still invalid (`ended_at` instead of
+//   `completed_at`, four required fields missing), so vault-mirror dropped it as
+//   `skipped-invalid` and that session got no vault note; nobody was told until
+//   the NEXT session-start banner. Until now the check existed only as a
+//   `node --input-type=module -e` one-liner inside the skill body, because the
+//   function had no CLI entry point (`scripts/repair-invalid-sessions.mjs` is a
+//   REPAIR path whose `--dry-run` exit reports repairability, not validity).
+//
+// WHAT IT CHECKS (exactly what the banner checks — no second opinion here):
+//   every parseable record in the ledger is run through `validateSession()` AND
+//   through vault-mirror's real render path. `--session-id` narrows the VERDICT
+//   to one record; other sessions' findings are still printed (they are not this
+//   close's to fix) but never decide the exit code.
+//
+// WHY A MISSING RECORD EXITS 1 (the deliberate call, #1417):
+//   `checkSessionsIntegrity` is silent both when a named record is sound and
+//   when it does not exist — "no finding" cannot tell those apart. Reporting the
+//   absent case as success would make this guard fail-open in precisely the
+//   shape it exists to catch: a close that proceeds with NO ledger record, one
+//   notch worse than the #1408 invalid one. So with `--session-id` the ledger is
+//   additionally read for that id and its absence is a named failure ("record
+//   not found"), never a silent pass. Without `--session-id` there is no id to
+//   be absent, and an empty/missing ledger is simply nothing to judge (exit 0).
+//
+// USAGE:
+//   node scripts/check-sessions-integrity.mjs [--repo-root <path>] [--session-id <id>] [--json]
+//
+// EXIT CODES:
+//   0  every judged record validates and mirrors
+//   1  a judged record is schema-invalid, is dropped by vault-mirror, or (with
+//      --session-id) is not in the ledger at all
+//   2  tool error — unknown/incomplete flag, or an unreadable repo root
+//
+// Node stdlib only apart from two repo-local imports; safe to call from a hook,
+// a skill body or CI without any dependency install.
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { checkSessionsIntegrity, SESSIONS_PATH } from './lib/sessions-integrity-banner.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
+
+const SELF_DIR = dirname(fileURLToPath(import.meta.url));
+
+const HELP_TEXT = `check-sessions-integrity.mjs — session-ledger schema + vault-mirror gate (#1417)
+
+USAGE
+  node scripts/check-sessions-integrity.mjs [options]
+
+DESCRIPTION
+  Runs every parseable record in .orchestrator/metrics/sessions.jsonl through
+  validateSession() AND through vault-mirror's real render path — the same two
+  populations the session-start banner reports. A record can pass one and fail
+  the other, so both are checked and reported separately.
+
+  This is the command form of session-end step 4a: after appending a session
+  record, prove it is sound BEFORE the close continues.
+
+OPTIONS
+  --repo-root <path>   Repo root holding .orchestrator/metrics/ (default: cwd).
+  --session-id <id>    Judge only the record(s) carrying this session_id. Other
+                       sessions' findings are still printed but never decide the
+                       exit code — they are pre-existing, not this close's to fix.
+                       An id with NO record in the ledger is a FAILURE (exit 1),
+                       not a silent pass: absent and sound are indistinguishable
+                       to the checker, and the fail-open reading is the dangerous
+                       one.
+  --json               Emit one JSON result object on stdout (diagnostics stay
+                       on stderr).
+  --help, -h           Show this help and exit.
+  --version            Print the package version and exit.
+
+EXIT CODES
+  0  every judged record validates and mirrors
+  1  a judged record is schema-invalid, is dropped by vault-mirror, or (with
+     --session-id) is not in the ledger at all
+  2  tool error — unknown/incomplete flag, or an unreadable repo root
+
+EXAMPLES
+  node scripts/check-sessions-integrity.mjs
+  node scripts/check-sessions-integrity.mjs --session-id main-2026-09-21-session-4
+  node scripts/check-sessions-integrity.mjs --json | jq '.findings'
+`;
+
+/**
+ * Parse argv. Returns `error` (a message) instead of throwing, so the caller
+ * owns the exit code.
+ *
+ * @param {string[]} argv
+ * @returns {{opts: {repoRoot: string|null, sessionId: string|null, json: boolean,
+ *            help: boolean, version: boolean}, error: string|null}}
+ */
+export function parseArgs(argv) {
+  const opts = { repoRoot: null, sessionId: null, json: false, help: false, version: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case '--repo-root':
+      case '--session-id': {
+        const value = argv[i + 1];
+        // A flag whose value is missing — or is itself the next flag — must be a
+        // usage error, never a silently empty filter that judges nothing.
+        if (typeof value !== 'string' || value === '' || value.startsWith('--')) {
+          return { opts, error: `${arg} requires a value` };
+        }
+        if (arg === '--repo-root') opts.repoRoot = value;
+        else opts.sessionId = value;
+        i += 1;
+        break;
+      }
+      case '--json':
+        opts.json = true;
+        break;
+      case '--help':
+      case '-h':
+        opts.help = true;
+        break;
+      case '--version':
+        opts.version = true;
+        break;
+      default:
+        return { opts, error: `unknown flag: ${arg}` };
+    }
+  }
+  return { opts, error: null };
+}
+
+/**
+ * Count the ledger records carrying `sessionId`. Unparseable lines are skipped —
+ * the same posture the banner takes: this judges schema integrity, not file
+ * corruption.
+ *
+ * @param {string} repoRoot
+ * @param {string} sessionId
+ * @returns {number}
+ */
+function countLedgerRecords(repoRoot, sessionId) {
+  const filePath = join(repoRoot, SESSIONS_PATH);
+  if (!existsSync(filePath)) return 0;
+  let matched = 0;
+  for (const line of readFileSync(filePath, 'utf8').split('\n')) {
+    if (line.trim() === '') continue;
+    let record;
+    try {
+      record = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (record && typeof record === 'object' && record.session_id === sessionId) matched += 1;
+  }
+  return matched;
+}
+
+/**
+ * Run the check and return a plain result object. Never throws; never exits.
+ *
+ * @param {{repoRoot?: string, sessionId?: string|null}} [opts]
+ * @returns {{ok: boolean, exitCode: 0|1|2, repoRoot: string, sessionId: string|null,
+ *            total: number|null, matched: number|null, severity: 'warn'|'alert'|null,
+ *            message: string|null, findings: {kind: string, line: number, sessionId: string, error: string}[],
+ *            error: string|null}}
+ */
+export function runSessionsIntegrityCheck({ repoRoot, sessionId = null } = {}) {
+  const root = resolve(repoRoot ?? process.cwd());
+  const base = {
+    ok: false,
+    exitCode: 2,
+    repoRoot: root,
+    sessionId: sessionId ?? null,
+    total: null,
+    matched: null,
+    severity: null,
+    message: null,
+    findings: [],
+    error: null,
+  };
+
+  try {
+    if (!existsSync(root) || !statSync(root).isDirectory()) {
+      return { ...base, error: `repo root is not a directory: ${root}` };
+    }
+  } catch (err) {
+    return { ...base, error: `repo root unreadable: ${err?.message ?? String(err)}` };
+  }
+
+  const banner = checkSessionsIntegrity({ repoRoot: root });
+
+  const findings = banner
+    ? [
+        ...banner.schemaInvalid.map((f) => ({ kind: 'schema-invalid', ...f })),
+        ...banner.mirrorSkipped.map((f) => ({ kind: 'mirror-skipped', ...f })),
+      ]
+    : [];
+
+  const result = {
+    ...base,
+    total: banner ? banner.total : null,
+    severity: banner ? banner.severity : null,
+    message: banner ? banner.message : null,
+    findings,
+  };
+
+  if (sessionId === null || sessionId === undefined) {
+    // No filter: every finding decides.
+    const ok = findings.length === 0;
+    return { ...result, ok, exitCode: ok ? 0 : 1 };
+  }
+
+  const matched = countLedgerRecords(root, sessionId);
+  const mine = findings.filter((f) => f.sessionId === sessionId);
+
+  if (matched === 0) {
+    return {
+      ...result,
+      matched,
+      ok: false,
+      exitCode: 1,
+      error:
+        `no record with session_id "${sessionId}" in ${SESSIONS_PATH} — ` +
+        'it was never written, or it was written under a different id. ' +
+        'Re-emit it via scripts/emit-session.mjs.',
+    };
+  }
+
+  const ok = mine.length === 0;
+  return { ...result, matched, ok, exitCode: ok ? 0 : 1 };
+}
+
+function readVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(join(SELF_DIR, '..', 'package.json'), 'utf8'));
+    return typeof pkg.version === 'string' ? pkg.version : 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+// CLI entry — only when run directly, never on import (an import must do
+// nothing: this module is loaded by tests and is reachable from hook code).
+if (isMainModule(import.meta.url)) {
+  const { opts, error } = parseArgs(process.argv.slice(2));
+
+  if (error !== null) {
+    process.stderr.write(`[check-sessions-integrity] ${error}\n`);
+    process.stderr.write('Run with --help for usage.\n');
+    process.exit(2);
+  }
+
+  if (opts.help) {
+    process.stdout.write(HELP_TEXT);
+    process.exit(0);
+  }
+
+  if (opts.version) {
+    process.stdout.write(`${readVersion()}\n`);
+    process.exit(0);
+  }
+
+  const repoRootArg =
+    opts.repoRoot === null ? undefined : isAbsolute(opts.repoRoot) ? opts.repoRoot : resolve(process.cwd(), opts.repoRoot);
+
+  const result = runSessionsIntegrityCheck({ repoRoot: repoRootArg, sessionId: opts.sessionId });
+
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    process.exit(result.exitCode);
+  }
+
+  // The banner text covers EVERY record, including other sessions' pre-existing
+  // findings — printed for visibility, even when the verdict below is clean.
+  if (result.message) process.stderr.write(`${result.message}\n`);
+  if (result.error) process.stderr.write(`[check-sessions-integrity] ${result.error}\n`);
+
+  if (result.exitCode === 2) process.exit(2);
+
+  if (result.ok) {
+    const scope = result.sessionId ? `record "${result.sessionId}"` : 'every ledger record';
+    process.stdout.write(`[check-sessions-integrity] OK — ${scope} validates and mirrors\n`);
+    process.exit(0);
+  }
+
+  const scope = result.sessionId ? `session "${result.sessionId}"` : 'the sessions ledger';
+  process.stderr.write(
+    `[check-sessions-integrity] FAIL — ${scope} is not sound. ` +
+      'Re-emit the affected record(s) via scripts/emit-session.mjs ' +
+      '(bulk repair: node scripts/repair-invalid-sessions.mjs --apply).\n',
+  );
+  process.exit(1);
+}

package/scripts/dialectic-deriver.mjs

@@ -49,6 +49,7 @@ import { readPeerCards } from './lib/peer-cards/reader.mjs';
 import { filterRealSessions } from './lib/session-schema/filters.mjs';
 import { readCanonicalSessions } from './lib/sessions-canonical.mjs';
 import { recordDialecticRun } from './lib/learnings/evolve-telemetry.mjs';
+import { DEFAULT_BUDGET_TOKENS } from './lib/config/dialectic.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -57,8 +58,11 @@ import { recordDialecticRun } from './lib/learnings/evolve-telemetry.mjs';
 /** Allowed LLM model identifiers. Per #506 EARS unwanted-behaviour: fail-fast on others. */
 export const ALLOWED_MODELS = Object.freeze(['haiku', 'sonnet', 'opus']);
 
-/** Default per-call budget (input + output tokens). Per #506 AC2. */
-export const DEFAULT_BUDGET = Object.freeze({ input: 8000, output: 4000 });
+/**
+ * Default per-call budget (input + output tokens). Per #506 AC2; the input
+ * ceiling is `DEFAULT_BUDGET_TOKENS` from the config parser (SSOT, #1380).
+ */
+export const DEFAULT_BUDGET = Object.freeze({ input: DEFAULT_BUDGET_TOKENS, output: 4000 });
 
 /** Industry-standard heuristic: ~4 chars per token for English prose. */
 const CHARS_PER_TOKEN = 4;
@@ -309,19 +313,21 @@ export function buildPrompt(payload, model, randomNonce = () => randomBytes(4).t
     '',
     '```diff',
     '# target: user',
-    '<full proposed body of USER.md, replacing existing content>',
+    '<the `## ` sections of USER.md you change or add>',
     '```',
     '',
     '```diff',
     '# target: agent',
-    '<full proposed body of AGENT.md, replacing existing content>',
+    '<the `## ` sections of AGENT.md you change or add>',
     '```',
     '',
     'Rules:',
     '- Emit at most one block per target. Omit a target entirely when no update is warranted.',
-    '- The block body is the FULL replacement body — not a unified diff hunk.',
+    '- The block body is a set of whole `## ` sections — not a unified diff hunk. It is merged per section:',
+    '  omitted sections stay UNCHANGED (nothing is deleted), so emit ONLY the sections you change or newly',
+    '  ground, and reuse an existing heading verbatim to update that section.',
     '- Preserve existing peer-card frontmatter; do not include `---` frontmatter lines in your block.',
-    '- Do not invent new sections that are not grounded in the supplied learnings or sessions.',
+    '- Do not invent sections without evidence from the supplied learnings or sessions — nothing downstream rejects them.',
     `- Operate within the dialectic budget appropriate for model '${model}'.`,
     '',
   ].join('\n');
@@ -505,6 +511,26 @@ async function readSteering(repoRoot) {
  * @property {number} [budget]
  */
 
+/**
+ * Record a THROWN abort (`unknown-model`, `subagent-crash`) before the caller
+ * rethrows the original error (#1221). The record is guarded on its own:
+ * `recordDialecticRun()` is best-effort today, but the rethrow contract must
+ * not depend on that staying true — a telemetry failure never replaces the
+ * error the caller is about to rethrow.
+ *
+ * @param {string} repoRoot
+ * @param {'unknown-model' | 'subagent-crash'} status
+ * @param {number} t0 — `Date.now()` at run start
+ * @returns {Promise<void>}
+ */
+async function recordThrownAbort(repoRoot, status, t0) {
+  try {
+    await recordDialecticRun({ repoRoot, status, durationMs: Date.now() - t0 });
+  } catch {
+    /* swallowed on purpose — see docblock */
+  }
+}
+
 /**
  * Run the deriver loop: load inputs → build payload → check budget → dispatch
  * agent → parse response → guard empty-card. Returns a structured verdict.
@@ -546,15 +572,20 @@ export async function runDialecticDeriver({
 
   // #1206 — telemetry start marker for the mechanical `orchestrator.dialectic.
   // completed` emits below. Mechanical (measured), not the coordinator's own
-  // typed DURATION_MS placeholder — covers every return path THIS function
-  // can determine on its own; see the module header for the two abort classes
-  // (`unknown-model`, thrown above; `subagent-crash`) and APPLY-mode success
-  // that only the skill-prose caller can record (merge + Agent() dispatch
-  // both happen one layer up, outside this pure pipeline).
+  // typed DURATION_MS placeholder — covers every outcome THIS function can
+  // see: the returns, and since #1221 the two THROWN aborts (`unknown-model`,
+  // `subagent-crash`), recorded at the throw point before the original error
+  // is rethrown. Only APPLY-mode success stays with the skill-prose caller —
+  // the merge happens one layer up, outside this pure pipeline.
   const t0 = Date.now();
 
   // Gate 1: model fail-fast. Throws Error with the canonical message.
-  validateModel(model);
+  try {
+    validateModel(model);
+  } catch (err) {
+    await recordThrownAbort(repoRoot, 'unknown-model', t0);
+    throw err;
+  }
 
   // Load inputs (best-effort, never throws on missing).
   const [learnings, sessions, peerCardsResult, steering] = await Promise.all([
@@ -611,7 +642,13 @@ export async function runDialecticDeriver({
 
   // Dispatch — DI boundary. Caller wires the real Agent({...}) wrapper or a mock.
   const maxTokens = typeof budget?.output === 'number' ? budget.output : DEFAULT_BUDGET.output;
-  const response = await dispatchAgent({ model, prompt, maxTokens });
+  let response;
+  try {
+    response = await dispatchAgent({ model, prompt, maxTokens });
+  } catch (err) {
+    await recordThrownAbort(repoRoot, 'subagent-crash', t0);
+    throw err;
+  }
 
   const text = typeof response?.text === 'string' ? response.text : '';
   const { diff } = parseResponse(text);

package/scripts/emit-session.mjs

@@ -40,11 +40,16 @@ import {
   CURRENT_SESSION_SCHEMA_VERSION,
   clampTimestampsMonotonic,
   aliasLegacyEndedAt,
+  normalizeWaveKeys,
 } from './lib/session-schema.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
 
 export { serializeSessionLineChecked };
 
+// A FULL object name only (SHA-1 or SHA-256 repo). A short sha or a symbolic
+// ref (`HEAD`, a branch) would resolve to a DIFFERENT commit when read later.
+const FULL_SHA_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+
 function parseArgs(argv) {
   const args = { file: '.orchestrator/metrics/sessions.jsonl', entry: null };
   for (let i = 0; i < argv.length; i++) {
@@ -118,6 +123,14 @@ async function main() {
     );
   }
 
+  //   3. Alias legacy per-wave agent-count keys (`agents_completed`, …) onto
+  //      their canonical `agent_count_*` spelling (#1390 P1), non-clobbering.
+  //      ONLY this pass of normalizeSession runs on the write path: the rest
+  //      would tag a missing `schema_version` as 0 (validateSession stamps the
+  //      current version) and apply top-level aliases that validateSession's
+  //      contract deliberately does not.
+  repaired = normalizeWaveKeys(repaired);
+
   // `memory_cleanup_at` derivation (#699 follow-up — Disziplin statt Mechanik).
   // The flag used to be a boolean the coordinator-LLM remembered to pass at
   // session-end; it was forgotten on 2026-08-14 and the cadence marker stalled
@@ -154,71 +167,104 @@ async function main() {
     }
   }
 
-  // `session_profile` derivation (#1247 — GitLab issue "key the effective-sizing
-  // row on waves x profile"). The mandatory write path is the coordinator
-  // composing `$METRICS_ENTRY` in prose (session-metrics-write.md), which never
-  // reliably set this field — so it is read here instead, from this repo's own
-  // STATE.md frontmatter via `readSessionProfile()` (scripts/lib/state-md.mjs).
+  // STATE.md-derived enrichment — ONE read, ONE parse, ONE ownership check for
+  // both fields below.
+  //
+  // `session_profile` (#1247 — GitLab issue "key the effective-sizing row on
+  // waves x profile"). The mandatory write path is the coordinator composing
+  // `$METRICS_ENTRY` in prose (session-metrics-write.md), which never reliably
+  // set this field — so it is read here instead, from this repo's own STATE.md
+  // frontmatter via `readSessionProfile()` (scripts/lib/state-md.mjs).
+  //
+  // `session_start_ref` (#1339 P8) — frontmatter `session-start-ref`, the HEAD
+  // sha the wave-executor pinned at session start. `/evolve analyze` needs it
+  // for an attributable `<start>..<end>` commit range; without it, it falls
+  // back to a time window that also attributes a PARALLEL session's commits to
+  // this one (skills/evolve/references/evolve-analyze-mode.md). Only a full
+  // hex sha (FULL_SHA_RE) is adopted; anything else is omitted with a WARN.
+  // Ceiling: the frontmatter parser coerces an all-decimal-digit value to a
+  // number, so such a sha (p ~ 7e-9) is omitted, never adopted as a number.
+  // NO END REF, deliberately: this runs at session-end Phase 3.7, BEFORE the
+  // Phase 4 close commit exists, so HEAD here would cut the session's own
+  // commit out of its range. Consumers use HEAD + `--until=<completed_at>`.
+  // Revisit when a post-commit writer exists that can stamp `session_end_ref`.
   //
-  // Precedence: an EXPLICIT `session_profile` KEY on the incoming record (even
-  // `null`) wins and is never overwritten — same "explicit assertion beats
-  // derivation" convention as `memory_cleanup_at` above. Absence of a profile in
-  // STATE.md (readSessionProfile returns null) leaves the field OMITTED —
-  // never coerced to `''`/`'none'`/a literal `"null"` string.
+  // Precedence: an EXPLICIT key on the incoming record (even `null`) wins and
+  // is never overwritten — same "explicit assertion beats derivation"
+  // convention as `memory_cleanup_at` above. Absence in STATE.md leaves the
+  // field OMITTED — never coerced to `''`/`'none'`/a literal `"null"` string.
   //
   // OWNERSHIP: STATE.md belongs to the session named in its OWN frontmatter
   // (`session:`), which in a shared working copy need not be the session this
   // record describes — two parallel sessions, or a `/close` run after a
   // foreign `/plan` session left its STATE.md behind (see
   // `.claude/rules/parallel-sessions.md`). Filing session B's waves under
-  // session A's profile is exactly the cross-contamination #1247 removes, only
-  // inverted. So the profile is adopted ONLY when the frontmatter `session`
-  // equals this record's `session_id`; on any mismatch (or an unprovable
-  // ownership, i.e. no `session` key) the field is OMITTED — never guessed.
+  // session A's profile — or A's start ref — is exactly the cross-contamination
+  // both fields exist to remove. So they are adopted ONLY when the frontmatter
+  // `session` equals this record's `session_id`; on any mismatch (or an
+  // unprovable ownership, i.e. no `session` key) they are OMITTED — never guessed.
   //
   // FAIL-SAFE: the read is enrichment; the session record is the load-bearing
   // artefact. Any failure reading or parsing STATE.md (EISDIR when the path is
-  // a directory, EACCES/EPERM, a truncated file) omits the field and lets the
+  // a directory, EACCES/EPERM, a truncated file) omits the fields and lets the
   // record through — it must never be the reason `sessions.jsonl` gains no
   // line at all.
-  if (!Object.prototype.hasOwnProperty.call(repaired, 'session_profile')) {
+  const hasOwn = (key) => Object.prototype.hasOwnProperty.call(repaired, key);
+  const needsProfile = !hasOwn('session_profile');
+  const needsStartRef = !hasOwn('session_start_ref');
+  if (needsProfile || needsStartRef) {
     let stateMdContents = '';
     try {
       const stateMdPath = resolveStateMdPath(process.cwd());
       if (existsSync(stateMdPath)) stateMdContents = readFileSync(stateMdPath, 'utf8');
     } catch (err) {
       process.stderr.write(
-        `emit-session: WARN could not read STATE.md for session_profile derivation ` +
-          `(${err?.message ?? err}); omitting session_profile\n`
+        `emit-session: WARN could not read STATE.md for session_profile/session_start_ref ` +
+          `derivation (${err?.message ?? err}); omitting both\n`
       );
       stateMdContents = '';
     }
     // No initialiser: both the try and the catch below assign `profile`.
     let profile;
+    let startRef = null;
     let owner = null;
     try {
       profile = readSessionProfile(stateMdContents);
-      const parsed = parseStateMd(stateMdContents);
-      const rawOwner = parsed?.frontmatter?.session;
+      const fm = parseStateMd(stateMdContents)?.frontmatter;
+      const rawOwner = fm?.session;
       owner = typeof rawOwner === 'string' && rawOwner.trim().length > 0 ? rawOwner.trim() : null;
+      const rawRef = fm?.['session-start-ref'];
+      if (typeof rawRef === 'string' && FULL_SHA_RE.test(rawRef.trim())) {
+        startRef = rawRef.trim();
+      } else if (needsStartRef && rawRef !== undefined && rawRef !== null && rawRef !== '') {
+        process.stderr.write(
+          `emit-session: WARN STATE.md session-start-ref=${rawRef} is not a full hex sha; ` +
+            `omitting session_start_ref\n`
+        );
+      }
     } catch (err) {
       process.stderr.write(
-        `emit-session: WARN could not parse STATE.md for session_profile derivation ` +
-          `(${err?.message ?? err}); omitting session_profile\n`
+        `emit-session: WARN could not parse STATE.md for session_profile/session_start_ref ` +
+          `derivation (${err?.message ?? err}); omitting both\n`
       );
       profile = null;
+      startRef = null;
     }
-    if (profile !== null) {
+    const derived = {};
+    if (needsProfile && profile !== null) derived.session_profile = profile;
+    if (needsStartRef && startRef !== null) derived.session_start_ref = startRef;
+    const derivedKeys = Object.keys(derived);
+    if (derivedKeys.length > 0) {
       if (owner !== null && owner === repaired.session_id) {
-        repaired = { ...repaired, session_profile: profile };
+        repaired = { ...repaired, ...derived };
       } else {
         // A visible omission: silence here is indistinguishable from "STATE.md
-        // carries no profile", and a foreign STATE.md in this working copy is
-        // precisely what the operator wants to know about.
+        // carries no such field", and a foreign STATE.md in this working copy
+        // is precisely what the operator wants to know about.
         process.stderr.write(
-          `emit-session: WARN STATE.md session_profile=${profile} belongs to ` +
-            `session=${owner ?? '<absent>'}, not session_id=${repaired.session_id ?? '<unknown>'}; ` +
-            `omitting session_profile\n`
+          `emit-session: WARN STATE.md ${derivedKeys.map((k) => `${k}=${derived[k]}`).join(' ')} ` +
+            `belongs to session=${owner ?? '<absent>'}, not session_id=${repaired.session_id ?? '<unknown>'}; ` +
+            `omitting ${derivedKeys.join(', ')}\n`
         );
       }
     }