@lyupro/codex-bridge 0.6.9 → 0.6.11

package/src/home/lib/meta/context-only.mjs

@@ -0,0 +1,43 @@
+/**
+ * Judges startup-context references and unread repository coordinates in scout responses.
+ * Plan_60 D1: honest answers about handed context need no command, unlike the 2026-09-16
+ * dead sandbox; a marker must never excuse invented addresses or an unsourced answer.
+ */
+import { QUESTION_KIND } from '../runner/question-kind.mjs';
+
+export function allStartupContext(questions) {
+  return Array.isArray(questions) && questions.length > 0
+    && questions.every((question) => question?.kind === QUESTION_KIND.STARTUP_CONTEXT);
+}
+
+export function contextOnlyGap({ questions, result, commandsExecuted }) {
+  const answers = Array.isArray(result?.answers) ? result.answers : [];
+  const byId = new Map();
+  for (const answer of answers) {
+    const id = String(answer?.question_id || '').trim().toUpperCase();
+    if (id && !byId.has(id)) byId.set(id, answer);
+  }
+  const unsourced = (Array.isArray(questions) ? questions : [])
+    .filter((question) => question?.kind === QUESTION_KIND.STARTUP_CONTEXT)
+    .filter((question) => {
+      const answer = byId.get(String(question.id || '').trim().toUpperCase());
+      return !Array.isArray(answer?.evidence)
+        || !answer.evidence.some((item) => /^startup:\s*\S/.test(String(item ?? '')));
+    })
+    .map((question) => question.id);
+  if (unsourced.length) {
+    return `responses to startup-context questions without a startup:<source> reference: ${unsourced.join(', ')}`;
+  }
+  if (commandsExecuted !== 0) return null;
+  const references = answers.flatMap((answer) => Array.isArray(answer?.evidence) ? answer.evidence : []);
+  references.push(...(Array.isArray(result?.findings) ? result.findings : []).map((finding) => finding?.where));
+  for (const reference of references) {
+    const text = String(reference ?? '');
+    if (text.startsWith('startup:')) continue;
+    const coordinate = text.match(/\S*\.[A-Za-z0-9]+:\d+/)?.[0];
+    if (coordinate) {
+      return `scout cited ${coordinate.slice(0, 60)} without executing a command: an address nobody read`;
+    }
+  }
+  return null;
+}

package/src/home/lib/meta/events.mjs

@@ -14,6 +14,15 @@ import { safeSlice } from './paths.mjs';
  */
 const LIMIT_RE = /rate[\s_-]*limit|usage[\s_-]*limit|quota|too many requests|\b429\b/i;
 
+// Plan_60 D2: add a new measured sample only together with its verbatim fixture.
+const UNAVAILABLE_SAMPLES = [
+  {
+    cli: 'codex-cli 0.159.0',
+    measured: '2026-10-03',
+    pattern: /^unexpected status 401 Unauthorized: Missing bearer or basic authentication in header\b/,
+  },
+];
+
 const record = (value) => value && typeof value === 'object' && !Array.isArray(value);
 
 const compact = (value, max = 300) =>
@@ -129,6 +138,8 @@ function transportErrorOf(event) {
   const status = payload.status ?? nested.status ?? null;
   const marker = [errorType, message].join(' ');
   const quota = Number(status) === 429 || LIMIT_RE.test(marker);
+  const unavailable = !quota && event.type === 'turn.failed' &&
+    UNAVAILABLE_SAMPLES.some((sample) => sample.pattern.test(message));
   const reason = compact(
     [errorType, message, status === null || status === undefined ? '' : `status ${status}`]
       .filter(Boolean)
@@ -137,7 +148,7 @@ function transportErrorOf(event) {
       (typeof event.error?.message === 'string' ? event.error.message : '') ||
       event.type,
   );
-  return { event, payload, status, error_type: errorType, message, quota, reason };
+  return { event, payload, status, error_type: errorType, message, quota, unavailable, reason };
 }
 
 /**
@@ -150,7 +161,8 @@ export function readEvents(runDir) {
   const accounting = usageOf(events);
   const started = events.find((event) => event.type === 'thread.started' && event.thread_id);
   const errors = events.map(transportErrorOf).filter(Boolean);
-  const transport_error = errors.find((error) => error.quota) || errors[0] || null;
+  const transport_error = errors.find((error) => error.quota) ||
+    errors.find((error) => error.unavailable) || errors[0] || null;
   return {
     events,
     // The file was written, whatever it holds. Pass 2 judges a run by this: a stream the

package/src/home/lib/meta/launch-rows.mjs

@@ -23,6 +23,27 @@ function retentionReply(runDir) {
   return `Retention: freed ${formatBytes(bytes)} from ${runs} runs older than ${days} days`;
 }
 
+function attemptReply(runDir) {
+  const retryOf = readJson(path.join(runDir, 'status.json'))?.retry_of;
+  if (typeof retryOf !== 'string' || !retryOf.trim()) return null;
+  const runsRoot = path.dirname(runDir);
+  const key = (name) => process.platform === 'win32' ? name.toLowerCase() : name;
+  const seen = new Set([key(path.basename(runDir))]);
+  let previous = retryOf;
+  let attempt = 1;
+  // Plan_75 D1, 2026-10-03 TradeForge: show retries without trusting broken provenance links.
+  for (let hops = 0; hops < 50; hops += 1) {
+    if (typeof previous !== 'string' || !previous || /[/\\]/.test(previous)
+      || previous === '.' || previous === '..' || seen.has(key(previous))) break;
+    const status = readJson(path.join(runsRoot, previous, 'status.json'));
+    if (!status) break;
+    seen.add(key(previous));
+    attempt += 1;
+    previous = status.retry_of;
+  }
+  return `Attempt: ${attempt} of this pass — retry of ${retryOf}`;
+}
+
 // Five copies of Retention missed writeFailure(), so both reply assemblers share this point.
 // The 2026-09-16 dead Codex sandbox incident is why the launcher probes the sandbox at all.
 export function launchRows(runDir) {
@@ -33,6 +54,8 @@ export function launchRows(runDir) {
     const reason = line(probe.reason, 160) || 'no reason recorded';
     rows.push(`Sandbox probe: inconclusive — ${reason} The run started without a sandbox check.`);
   }
+  const attempt = attemptReply(runDir);
+  if (attempt) rows.push(attempt);
   return rows;
 }
 

package/src/home/lib/meta/paths.mjs

@@ -114,7 +114,7 @@ export const samePath = (declared, touched) => {
 };
 
 /**
- * One --scope pattern as a regular expression. Deliberately a small glob dialect and not a
+ * One scope pattern as a regular expression. Deliberately a small glob dialect and not a
  * dependency: `**` crosses directory boundaries, `*` and `?` stop at `/`, matching is
  * case-insensitive because Windows paths arrive in whatever case Codex felt like using.
  * A slash right after `**` is optional, so `src/**` covers `src/a.ts` too — otherwise the

package/src/home/lib/meta/reply.mjs

@@ -2,7 +2,8 @@
  * Renders the reply lines a dispatcher is allowed to return, one format per agent.
  *
  * AGENTS adds reply strategies to the shared agent registry: for each one it describes how
- * to tell the result file is filled in and which reply strategy below renders it. FAIL and LIMIT bypass the per-agent strategy — a run that
+ * to tell the result file is filled in and which reply strategy below renders it.
+ * FAIL, LIMIT and UNAVAILABLE bypass the per-agent strategy — a run that
  * produced nothing has nothing agent-specific left to say.
  *
  * The lines built here ARE the reply. Agents forward this text verbatim instead of
@@ -14,6 +15,7 @@ import { AGENTS as AGENT_DEFINITIONS } from '../agents.mjs';
 import { changedPaths, line, readText } from './paths.mjs';
 import { splitRunChanges } from './environment.mjs';
 import { scoutCoverage } from './verdict.mjs';
+import { orderInputName } from '../order-schema.mjs';
 
 /** What the run itself changed, and what the tooling around it changed while it worked. */
 const runChanges = (runDir) =>
@@ -24,6 +26,11 @@ const runChanges = (runDir) =>
 
 const readCommand = (runDir) => `codex-bridge read ${runDir}`;
 
+function stripVerdict(value) {
+  // Run 2026-10-01_114244_plan72-r3q-live-probe-20261001 repeated OK because the model prefixed its summary.
+  return String(value ?? '').replace(/^(?:OK|FAIL|LIMIT|UNAVAILABLE)(?: — | - |: )/, '');
+}
+
 export const AGENTS = {
   'codex-scout': {
     ...AGENT_DEFINITIONS['codex-scout'],
@@ -54,7 +61,7 @@ function scoutReply(ctx) {
   const unknowns = (r.unknowns || []).filter(Boolean);
   const coverage = scoutCoverage(ctx.runDir, r);
   return [
-    `OK — ${line(r.answer, 160)}`,
+    `OK — ${line(stripVerdict(r.answer), 160)}`,
     // Any explicit question gets a coverage line, including a valid one-question order.
     ...(coverage ? [`Coverage: ${coverage}`] : []),
     `Key finding: ${top ? `${line(top.fact, 130)} (${line(top.where, 60)})` : 'no findings listed'}`,
@@ -68,6 +75,7 @@ function buildReply(ctx) {
   const { work: touchedPaths, environment } = runChanges(ctx.runDir);
   const paths = touchedPaths.slice(0, 3).join(', ');
   const flags = readText(path.join(ctx.runDir, 'flags.txt')).split(/\r?\n/).filter(Boolean);
+  const gaps = readText(path.join(ctx.runDir, 'flags-coverage.txt')).split(/\r?\n/).filter((gap) => gap.trim());
   // A multi-line verification is several commands, and collapsing them into one 60-character
   // line cut the last one mid-word: the reply named a command nobody could run.
   const commands = String(r.verify_command ?? '')
@@ -90,7 +98,7 @@ function buildReply(ctx) {
     ? `${paths ? `${paths} · ` : ''}changes were made by an earlier run of this task`
     : paths || 'worktree untouched';
   return [
-    `OK — ${line(r.summary, 300)}`,
+    `OK — ${line(stripVerdict(r.summary), 300)}`,
     `Files: ${touchedPaths.length} changed · ${files}`,
     // Only when something outside the run wrote to the tree. Subtracting those paths from the
     // verdict without naming them would hide a real edit behind a pattern.
@@ -99,6 +107,9 @@ function buildReply(ctx) {
       : []),
     `Verification: ${verify} — ${verdict}`,
     `Flags: ${flags.length ? `${flags.length} TODO/skip — ${line(flags.slice(0, 3).join(' | '), 140)}` : 'none'}`,
+    ...(gaps.length
+      ? [`Flags coverage: incomplete — ${line(gaps[0], 120)}${gaps.length > 1 ? ` (+${gaps.length - 1} more)` : ''}`]
+      : []),
     `Report: ${ctx.file('report.md')} · Log: ${readCommand(ctx.runDir)}`,
   ];
 }
@@ -133,7 +144,7 @@ function advisorReply(ctx) {
     const risks = r.predicted_risks || [];
     return [
       r.sufficient
-        ? 'OK — scope: sufficient; continue this run with --phase advise'
+        ? `OK — scope: sufficient; continue this run with ${orderInputName('phase')} advise`
         : `OK — scope: insufficient; ${missing.length} paths named`,
       ...(missing.length ? [`Missing: ${line(missing.join(', '), 160)}`] : []),
       `Predicted risks: ${risks.length}${risks[0] ? ` — ${risks[0].id} ${line(risks[0].risk, 120)}` : ''}`,
@@ -223,3 +234,27 @@ export function limitReply(ctx, meta) {
   rows.push(`Log: ${readCommand(ctx.runDir)}`);
   return rows;
 }
+
+/** Plan_60 D2: pre-start and post-start refusals share the same handoff contract. */
+export function unavailableRows(signal) {
+  return [
+    'UNAVAILABLE — Codex is not available (missing or signed out); ' +
+      'hand the task to the next executor, do not retry',
+    `Signal: ${line(signal, 170)}`,
+    'Operator check: codex --version; codex login status (sign in with codex login)',
+  ];
+}
+
+export function unavailableReply(ctx, meta) {
+  const rows = unavailableRows(meta.reason);
+  if (ctx.agent === 'codex-build') {
+    const { work: touched } = runChanges(ctx.runDir);
+    rows.push(
+      `Worktree: ${
+        touched.length ? `has unfinished changes (${touched.length}), see git-after.txt` : 'no new changes'
+      }`,
+    );
+  }
+  rows.push(`Log: ${readCommand(ctx.runDir)}`);
+  return rows;
+}

package/src/home/lib/meta/run-state.mjs

@@ -12,6 +12,7 @@ import path from 'node:path';
 import { changedPaths, line, normalizePath, readJson, readText, size } from './paths.mjs';
 import { withLaunchRows } from './launch-rows.mjs';
 import { runLiveness } from './run-liveness.mjs';
+import { removeFlagBaselineCopies } from '../runner/flag-baseline.mjs';
 
 /**
  * Run state on disk, merged over whatever is already there. A killed runner leaves no
@@ -115,6 +116,8 @@ export function markAbandoned(runsRoot, currentTree) {
     }
     try {
       writeStatus(runDir, patch);
+      // Plan_60 D3a: a dead worker cannot remove its start copies; keep the manifest for inspection.
+      if (patch.state === 'abandoned') removeFlagBaselineCopies(runDir);
       changed.push({ run: entry.name, state: patch.state });
     } catch {
       // A folder that cannot be written to is not worth failing a fresh run over.

package/src/home/lib/meta/verdict.mjs

@@ -28,6 +28,7 @@ import { startupGap } from './startup.mjs';
 import { transportGap } from './transport.mjs';
 import { reasonFrom } from './reason.mjs';
 import { adviceGap } from './advice-status.mjs';
+import { allStartupContext, contextOnlyGap } from './context-only.mjs';
 import { compareSnapshots } from './snapshot-format.mjs';
 import { readSnapshot, runSnapshotChanges, snapshotRefusal } from './run-snapshots.mjs';
 
@@ -156,7 +157,7 @@ function substanceLength(text) {
 
 const questionsOf = (runDir) => {
   const parsed = readJson(path.join(runDir, 'questions.json'));
-  return Array.isArray(parsed) ? parsed.filter((q) => q && q.id) : [];
+  return Array.isArray(parsed) ? parsed : [];
 };
 
 /** Answers indexed by question id, first one wins; ids come back in whatever case Codex used. */
@@ -175,8 +176,8 @@ const answersById = (result) => {
  * single-answer check. Every branch here exists because a schema alone accepted the run that
  * answered in coordinates.
  */
-function scoutCoverageGap(runDir, result) {
-  const questions = questionsOf(runDir);
+function scoutCoverageGap(orderedQuestions, result) {
+  const questions = orderedQuestions.filter((q) => q && q.id);
   const show = (list) => list.slice(0, 8).join(', ');
 
   if (!questions.length) {
@@ -211,7 +212,7 @@ function scoutCoverageGap(runDir, result) {
 
 /** `1/1 sub-questions`, or null for legacy runs with no questions.json artifact. */
 export function scoutCoverage(runDir, result) {
-  const questions = questionsOf(runDir);
+  const questions = questionsOf(runDir).filter((q) => q && q.id);
   if (!questions.length) return null;
   const byId = answersById(result);
   const answered = questions.filter((q) => String(byId.get(q.id)?.answer || '').trim()).length;
@@ -288,9 +289,10 @@ export function resolveStatus({ resultOk, exit, agent, result, runDir, events })
     // This branch already knows why the run died: the CLI said so itself, with a status. Letting
     // the ordered reason speak here would answer a transport question with the model's older
     // complaint about the task — a LIMIT that never mentions quota is the same "verdict says the
-    // wrong thing" defect this module exists to remove.
+    // wrong thing" defect this module exists to remove. Plan_60 D2: UNAVAILABLE only on a measured
+    // signed-out sample (events.mjs); an unfamiliar failure stays FAIL with its raw CLI text.
     return {
-      status: transportError.quota ? 'LIMIT' : 'FAIL',
+      status: transportError.quota ? 'LIMIT' : transportError.unavailable ? 'UNAVAILABLE' : 'FAIL',
       reason: transportError.reason,
     };
   }
@@ -318,19 +320,25 @@ export function resolveStatus({ resultOk, exit, agent, result, runDir, events })
   // Answers that never arrived, or arrived as coordinates. Scout-only, and per-question
   // only when questions.json is absent — see scoutCoverageGap().
   if (agent === 'codex-scout') {
+    const questions = questionsOf(runDir);
     // The 2026-09-16 dead sandbox produced nonempty evidence without reading code. Require an
     // execution fact first: checking whether evidence paths existed falsely rejected 64/151 runs.
     // Only a run that left a stream can prove it: an archived run from before `--json` has none and
     // is judged by the contract of its day; a `--json` run missing its stream already failed above.
-    if (eventData.hasStream && eventData.commands_executed === 0) {
+    // Plan_60 D1 exempts only orders whose every question asks about handed startup context.
+    if (eventData.hasStream && eventData.commands_executed === 0 && !allStartupContext(questions)) {
       return {
         status: 'FAIL',
         reason: 'scout executed no command, so no answer rests on reading the code; '
           + 'check stderr.log for sandbox refusals before changing the order',
       };
     }
-    const gap = scoutCoverageGap(runDir, result);
+    const gap = scoutCoverageGap(questions, result);
     if (gap) return { status: 'FAIL', reason: gap };
+    const contextGap = contextOnlyGap({
+      questions, result, commandsExecuted: eventData.hasStream ? eventData.commands_executed : null,
+    });
+    if (contextGap) return { status: 'FAIL', reason: contextGap };
   }
   // Plan_59 D3/D4/D5/D10: a schema-valid agreement still needs evidence and decision checks.
   // Place the advisor judge before the build-only scope check, alongside the other agent contracts.

package/src/home/lib/model-family.mjs

@@ -0,0 +1,38 @@
+/**
+ * Parses model families by id structure, Plan_67 D5, without a model id literal in code:
+ * an id table would become stale with every model release and create false mismatch warnings.
+ * D5 (b) treats unparsed ids as no evidence, rather than as matches or violations.
+ */
+
+// These are host aliases, not model ids or family pins (Plan_67 D5).
+export const NON_FAMILY_ALIASES = Object.freeze(['inherit', 'default', 'opusplan']);
+
+const isAsciiLetters = (value) => value.length > 0 && !/[^A-Za-z]/.test(value);
+
+export function modelFamily(value) {
+  if (typeof value !== 'string') return null;
+  const tokens = value.replace(/\[[^\[\]]*\]$/, '').split(/[-.@]/);
+  const claudeIndex = tokens.findIndex((token) => token.toLowerCase() === 'claude');
+  if (claudeIndex !== -1) {
+    const family = tokens.slice(claudeIndex + 1).find(isAsciiLetters);
+    return family ? family.toLowerCase() : null;
+  }
+  if (tokens.length !== 1 || !isAsciiLetters(tokens[0])) return null;
+  const family = tokens[0].toLowerCase();
+  return NON_FAMILY_ALIASES.includes(family) ? null : family;
+}
+
+export function compareModelFamilies({ pinFamily, modelIds }) {
+  const families = new Set();
+  let unparsed = 0;
+  for (const id of modelIds) {
+    const family = modelFamily(id);
+    if (family === null) unparsed += 1;
+    else families.add(family);
+  }
+  const parsed = [...families];
+  const verdict = pinFamily === null || parsed.length === 0
+    ? 'undetermined'
+    : parsed.some((family) => family !== pinFamily) ? 'violation' : 'match';
+  return { verdict, parsed, unparsed };
+}

package/src/home/lib/observation-ledger.mjs

@@ -0,0 +1,145 @@
+/** Keeps, per key, the last observation apart from the last confirmed violation and the last confirmed match.
+ * Plan_67 D8 separates these facts to cure the eternal witness warning: an undetermined observation
+ * cannot clear a violation, while a later confirmed match can. Adapters own causes and severity.
+ */
+import fs from 'node:fs';
+import { writeHomeJsonAtomic } from './atomic-json.mjs';
+import { withHomeFileLock } from './file-lock.mjs';
+import { stateDirWriter } from './home-write.mjs';
+import { parseJsonText } from './json-file.mjs';
+
+export const HISTORY_LIMIT = 20;
+const VERDICTS = new Set(['violation', 'match', 'undetermined']);
+const has = (object, key) => Object.hasOwn(object, key);
+const plainObject = (value) => value !== null && typeof value === 'object'
+  && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+
+function fields(value, required, optional = []) {
+  return plainObject(value) && required.every((key) => has(value, key))
+    && Reflect.ownKeys(value).every((key) => required.includes(key) || optional.includes(key));
+}
+
+function jsonValue(value, ancestors = new Set()) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return true;
+  if (typeof value === 'number') return Number.isFinite(value);
+  if ((!Array.isArray(value) && !plainObject(value)) || ancestors.has(value)) return false;
+  ancestors.add(value);
+  const valid = Array.isArray(value)
+    ? Array.from(value).every((item) => jsonValue(item, ancestors))
+    : Reflect.ownKeys(value).every((key) => typeof key === 'string' && jsonValue(value[key], ancestors));
+  ancestors.delete(value);
+  return valid;
+}
+
+function isoTimestamp(value) {
+  if (typeof value !== 'string' || !Number.isFinite(Date.parse(value))) return false;
+  const parts = /^(\d{4}|[+-]\d{6})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.exec(value);
+  if (!parts) return false;
+  const [, year, month, day, hour, minute, second] = parts.map(Number);
+  const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+  const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  return month >= 1 && month <= 12 && day >= 1 && day <= days[month - 1]
+    && hour < 24 && minute < 60 && second < 60;
+}
+
+function validObservation(value, maxSeq) {
+  return fields(value, ['seq', 'verdict', 'at', 'detail'], ['data'])
+    && Number.isInteger(value.seq) && value.seq > 0 && value.seq <= maxSeq
+    && VERDICTS.has(value.verdict) && isoTimestamp(value.at) && typeof value.detail === 'string'
+    && (!has(value, 'data') || (plainObject(value.data) && jsonValue(value.data)));
+}
+
+function validEntry(entry, maxSeq) {
+  if (!fields(entry, ['lastObservation', 'lastViolation', 'lastMatch', 'history'])
+    || !validObservation(entry.lastObservation, maxSeq)
+    || !Array.isArray(entry.history) || entry.history.length > HISTORY_LIMIT) return false;
+  const lastSeq = entry.lastObservation.seq;
+  if (entry.lastViolation !== null && (!validObservation(entry.lastViolation, lastSeq)
+    || entry.lastViolation.verdict !== 'violation')) return false;
+  if (entry.lastMatch !== null && (!validObservation(entry.lastMatch, lastSeq)
+    || entry.lastMatch.verdict !== 'match')) return false;
+  let previous = 0;
+  for (const observation of entry.history) {
+    if (!validObservation(observation, lastSeq) || observation.verdict !== 'violation'
+      || observation.seq <= previous) return false;
+    previous = observation.seq;
+  }
+  if (entry.lastViolation === null ? entry.history.length !== 0 : previous !== entry.lastViolation.seq) return false;
+  const slot = entry.lastObservation.verdict === 'violation' ? entry.lastViolation
+    : entry.lastObservation.verdict === 'match' ? entry.lastMatch : null;
+  return entry.lastObservation.verdict === 'undetermined' || slot?.seq === lastSeq;
+}
+
+export function emptyLedger() {
+  return { format: 1, seq: 0, entries: {} };
+}
+
+export function normalizeLedger(parsed) {
+  if (!fields(parsed, ['format', 'seq', 'entries']) || parsed.format !== 1
+    || !Number.isInteger(parsed.seq) || parsed.seq < 0 || !plainObject(parsed.entries)) return null;
+  return Reflect.ownKeys(parsed.entries).every((key) => typeof key === 'string' && key.length > 0
+    && validEntry(parsed.entries[key], parsed.seq)) ? parsed : null;
+}
+
+export function reduceObservation(ledger, { key, verdict, at, detail, data }) {
+  if (!VERDICTS.has(verdict)) throw new TypeError('verdict must be violation, match or undetermined');
+  if (typeof key !== 'string' || key.length === 0) throw new TypeError('key must be a non-empty string');
+  if (!isoTimestamp(at)) throw new TypeError('at must be an ISO timestamp');
+  if (typeof detail !== 'string') throw new TypeError('detail must be a string');
+  if (data !== undefined && (!plainObject(data) || !jsonValue(data))) {
+    throw new TypeError('data must be a plain JSON object');
+  }
+  if (!normalizeLedger(ledger)) throw new TypeError('ledger must be a valid observation ledger');
+  const seq = ledger.seq + 1;
+  if (seq === ledger.seq) throw new TypeError('ledger sequence cannot increment');
+  const observation = { seq, verdict, at, detail };
+  if (data !== undefined) observation.data = structuredClone(data);
+  const previous = has(ledger.entries, key) ? ledger.entries[key]
+    : { lastObservation: null, lastViolation: null, lastMatch: null, history: [] };
+  const entry = { ...previous, lastObservation: observation };
+  if (verdict === 'violation') {
+    entry.lastViolation = observation;
+    entry.history = [...previous.history, observation].slice(-HISTORY_LIMIT);
+  } else if (verdict === 'match') {
+    entry.lastMatch = observation;
+  }
+  return { format: 1, seq, entries: { ...ledger.entries, [key]: entry } };
+}
+
+export function entryState(entry) {
+  if (!entry) return 'unobserved';
+  if (entry.lastViolation) {
+    return entry.lastMatch?.seq > entry.lastViolation.seq ? 'recovered' : 'violation';
+  }
+  return entry.lastMatch ? 'clean' : 'undetermined';
+}
+
+export function readLedgerFile(file, { normalize = normalizeLedger } = {}) {
+  let source;
+  try {
+    source = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    return error.code === 'ENOENT' ? emptyLedger() : { corrupt: true };
+  }
+  try {
+    return normalize(parseJsonText(file, source)) ?? { corrupt: true };
+  } catch {
+    return { corrupt: true };
+  }
+}
+
+export async function updateLedgerFile({ stateDir, id, file, normalize, update }) {
+  const writer = stateDirWriter(stateDir);
+  // Plan_67 D8: allocation of seq and publication share the registered artifact's lock.
+  return withHomeFileLock(writer, id, `${file}.lock`, async () => {
+    const current = readLedgerFile(file, { normalize });
+    if (current.corrupt) throw new Error(`Cannot update corrupt observation ledger: ${file}`);
+    const next = update(current);
+    writeHomeJsonAtomic(writer, id, file, next);
+    return next;
+  }, { description: 'observation ledger' });
+}
+
+export async function recordObservation({ stateDir, id, file, observation }) {
+  return updateLedgerFile({ stateDir, id, file, update: (current) => reduceObservation(current, observation) });
+}