elanous 0.2.41 → 0.2.43

package/src/self-implement/regate-detail.ts

@@ -38,6 +38,21 @@ export function parseConflictFiles(text: string): string[] {
 
 export type MergeFailureKind = 'base-modified' | 'head-moved' | 'conflict' | 'branch-policy' | 'other';
 
+export const HOST_REGATE_PR_HEAD_FAILURE_CONDITIONS = [
+  'head-unavailable', 'head-mismatch', 'state-unavailable', 'state-not-open',
+  'draft-status-unavailable', 'pr-is-draft', 'base-name-unavailable', 'base-oid-invalid',
+] as const;
+export type HostRegatePrHeadFailureCondition = typeof HOST_REGATE_PR_HEAD_FAILURE_CONDITIONS[number];
+
+export interface HostRegatePrHeadSnapshot {
+  headRefOid: string | null;
+  state: 'OPEN' | 'CLOSED' | 'MERGED' | 'OTHER' | null;
+  isDraft: boolean | null;
+  /** The only raw ref retained is the conventional base; all other non-empty values collapse to `other`. */
+  baseRefName: 'main' | 'other' | null;
+  baseRefOid: string | null;
+}
+
 /** Classify a `gh pr merge` failure so a reader can tell a race from a conflict from a policy block without the raw text. */
 export function classifyMergeFailure(detail: string, expectedHead?: string, actualHead?: string | null): MergeFailureKind {
   if (/base branch was modified/i.test(detail)) return 'base-modified';
@@ -48,12 +63,16 @@ export function classifyMergeFailure(detail: string, expectedHead?: string, actu
   return 'other';
 }
 
-/** One host-regate failure. The optional facts are filled for the pr-head, merge-conflict and merge steps. */
+/** One host-regate failure. The optional facts are filled for PR-head, merge-conflict and merge steps. */
 export interface HostRegateFailure {
   step: string;
   detail: string;
   expectedHead?: string;
   actualHead?: string | null;
+  /** Discrete clauses that failed the initial PR-head readiness check. */
+  failedConditions?: HostRegatePrHeadFailureCondition[];
+  /** Bounded structured facts from the same `gh pr view` used for the check. */
+  prHeadSnapshot?: HostRegatePrHeadSnapshot;
   conflictFiles?: string[];
   /** Number omitted from conflictFiles when the ledger's 200-path bound is reached. */
   conflictFilesOmitted?: number;
@@ -66,12 +85,30 @@ export function regateFailureFacts(failure: unknown): Omit<HostRegateFailure, 's
   const f = failure as Record<string, unknown>;
   const sha = (value: unknown): value is string => typeof value === 'string' && /^[0-9a-f]{40}$/i.test(value);
   const kinds: readonly MergeFailureKind[] = ['base-modified', 'head-moved', 'conflict', 'branch-policy', 'other'];
+  const headConditions: readonly HostRegatePrHeadFailureCondition[] = HOST_REGATE_PR_HEAD_FAILURE_CONDITIONS;
   const conflictFiles = Array.isArray(f.conflictFiles) ? f.conflictFiles.filter((p): p is string => typeof p === 'string') : undefined;
   const priorOmitted = Number.isSafeInteger(f.conflictFilesOmitted) && (f.conflictFilesOmitted as number) > 0 ? f.conflictFilesOmitted as number : 0;
   const conflictFilesOmitted = Math.max(0, (conflictFiles?.length ?? 0) - 200) + priorOmitted;
+  const failedConditions = Array.isArray(f.failedConditions)
+    ? [...new Set(f.failedConditions.filter((condition): condition is HostRegatePrHeadFailureCondition => typeof condition === 'string' && headConditions.includes(condition as HostRegatePrHeadFailureCondition)))].sort()
+    : undefined;
+  const snapshot = f.prHeadSnapshot && typeof f.prHeadSnapshot === 'object' ? f.prHeadSnapshot as Record<string, unknown> : undefined;
+  const states = ['OPEN', 'CLOSED', 'MERGED', 'OTHER'] as const;
+  const prHeadSnapshot = snapshot
+    && (sha(snapshot.headRefOid) || snapshot.headRefOid === null)
+    && ((typeof snapshot.state === 'string' && states.includes(snapshot.state as typeof states[number])) || snapshot.state === null)
+    && (typeof snapshot.isDraft === 'boolean' || snapshot.isDraft === null)
+    && ((snapshot.baseRefName === 'main' || snapshot.baseRefName === 'other') || snapshot.baseRefName === null)
+    && (sha(snapshot.baseRefOid) || snapshot.baseRefOid === null)
+    ? { headRefOid: snapshot.headRefOid as string | null, state: snapshot.state as HostRegatePrHeadSnapshot['state'],
+      isDraft: snapshot.isDraft as boolean | null, baseRefName: snapshot.baseRefName as HostRegatePrHeadSnapshot['baseRefName'],
+      baseRefOid: snapshot.baseRefOid as string | null }
+    : undefined;
   return {
     ...(sha(f.expectedHead) ? { expectedHead: f.expectedHead } : {}),
     ...(sha(f.actualHead) || f.actualHead === null ? { actualHead: f.actualHead as string | null } : {}),
+    ...(failedConditions?.length ? { failedConditions } : {}),
+    ...(prHeadSnapshot ? { prHeadSnapshot } : {}),
     ...(conflictFiles ? { conflictFiles: conflictFiles.slice(0, 200) } : {}),
     ...(conflictFilesOmitted > 0 ? { conflictFilesOmitted } : {}),
     ...(typeof f.mergeFailureKind === 'string' && kinds.includes(f.mergeFailureKind as MergeFailureKind) ? { mergeFailureKind: f.mergeFailureKind as MergeFailureKind } : {}),

package/src/self-implement/rework-child-provider.ts

@@ -0,0 +1,25 @@
+import type { ChildLlmSelection } from '../agent/run-context.js';
+
+export type ProviderAvailability = 'available' | 'unavailable' | 'unknown';
+export type ReworkChildProviderDecision =
+  | { action: 'keep'; selection: ChildLlmSelection; reason: 'not-grok' | 'quota-unknown' | 'quota-usable' | 'no-alternate' }
+  | { action: 'reselect'; selection: ChildLlmSelection; previous: ChildLlmSelection; reason: 'grok-quota-exhausted' | 'grok-credential-missing' };
+
+/** Re-evaluate Grok immediately before a supervisor rework relaunch; unknown quota is never treated as exhaustion. */
+export function reselectChildForRework(input: {
+  current: ChildLlmSelection;
+  grokQuota: 'usable' | 'exhausted' | 'unknown';
+  grokCredential: ProviderAvailability;
+  alternate?: ChildLlmSelection;
+  alternateCredential: ProviderAvailability;
+  alternateQuotaExhausted?: boolean;
+}): ReworkChildProviderDecision {
+  if (input.current.provider !== 'grok') return { action: 'keep', selection: input.current, reason: 'not-grok' };
+  const reason = input.grokQuota === 'exhausted' ? 'grok-quota-exhausted'
+    : input.grokCredential === 'unavailable' ? 'grok-credential-missing' : undefined;
+  if (!reason) return { action: 'keep', selection: input.current, reason: input.grokQuota === 'unknown' ? 'quota-unknown' : 'quota-usable' };
+  if (!input.alternate || input.alternateCredential !== 'available' || input.alternateQuotaExhausted === true) {
+    return { action: 'keep', selection: input.current, reason: 'no-alternate' };
+  }
+  return { action: 'reselect', selection: input.alternate, previous: input.current, reason };
+}

package/src/self-implement/run-chart.ts

@@ -0,0 +1,122 @@
+import { debug } from '../debug/log.js';
+import { appendRunLedgerEntryChecked, loadRunLedger, type RunLedgerEntry } from './run-ledger.js';
+
+export const RUN_DOCTOR_HANDOFF_WAIT_THRESHOLD = 3;
+export const RUN_DOCTOR_HANDOFF_INPUT_PREFIX = '[run-chart handoff=doctor]';
+export const RUN_CHART_MAX_CELLS = 20;
+export const RUN_CHART_READ_CELLS = 5;
+export type RunChartDevice = 'run-supervisor' | 'macrophage' | 'run-doctor' | 'outer-supervisor';
+export interface RunChartCell {
+  runId: string; device: RunChartDevice | 'summary'; stopKey: string; observed: string; verdict: string; action: string;
+  handoff: string | null; why: string; readStopKeys: string[]; waitCount?: number; failureClass?: string;
+}
+export interface RunChartDecision extends Omit<RunChartCell, 'device'> { device: RunChartDevice; dir: string }
+export type RunChartWriteResult = 'recorded' | 'already-recorded' | 'conflicting-verdict' | 'missing-ledger' | 'ledger-write-refused';
+
+function chartEvents(entries: readonly RunLedgerEntry[]): RunLedgerEntry[] {
+  const all = entries.filter((e) => e.event === 'run-chart-cell');
+  const compactedAt = all.reduce((last, entry, index) => entry.data.compacted ? index : last, -1);
+  if (compactedAt < 0) return all;
+  const compacted = all[compactedAt]!;
+  const summaryData = compacted.data.compacted as Record<string, unknown>;
+  const cutoff = typeof summaryData.lastStopKey === 'string' ? summaryData.lastStopKey : '';
+  const cutoffDevice = typeof summaryData.lastDevice === 'string' ? summaryData.lastDevice : '';
+  const cutoffAt = all.findIndex((e) => e.data.device === cutoffDevice && e.data.stopKey === cutoff);
+  const summary: RunLedgerEntry = { ...compacted, data: { device: 'summary', stopKey: `summary:${String(compacted.data.stopKey)}`,
+    observed: `${String(summaryData.count)} earlier chart cells folded`, verdict: 'summary',
+    action: 'compact', handoff: null, why: String(summaryData.verdicts ?? ''), readStopKeys: [] } };
+  return [summary, ...all.slice(cutoffAt >= 0 ? cutoffAt + 1 : compactedAt)];
+}
+
+function toChartCell(runId: string, e: RunLedgerEntry): RunChartCell {
+  return {
+    runId, device: e.data.device as RunChartDevice | 'summary', stopKey: String(e.data.stopKey ?? ''),
+    observed: String(e.data.observed ?? ''), verdict: String(e.data.verdict ?? ''), action: String(e.data.action ?? ''),
+    handoff: typeof e.data.handoff === 'string' ? e.data.handoff : null, why: String(e.data.why ?? ''),
+    readStopKeys: Array.isArray(e.data.readStopKeys) ? e.data.readStopKeys.filter((x): x is string => typeof x === 'string') : [],
+    ...(typeof e.data.waitCount === 'number' ? { waitCount: e.data.waitCount } : {}),
+    ...(typeof e.data.failureClass === 'string' ? { failureClass: e.data.failureClass } : {}),
+  };
+}
+
+export function projectRunChart(runId: string, dir: string): RunChartCell[] {
+  return chartEvents(loadRunLedger(runId, dir) ?? []).map((entry) => toChartCell(runId, entry));
+}
+
+export function readRunChart(runId: string, device: RunChartDevice, dir: string): RunChartCell[] {
+  const entries = loadRunLedger(runId, dir) ?? [];
+  const cells = chartEvents(entries).slice(-RUN_CHART_READ_CELLS).map((e) => toChartCell(runId, e));
+  const metrics = runChartMetrics(entries);
+  try { debug.log('run-chart', 'read', { runId, device, count: cells.length, stopKeys: cells.map((c) => c.stopKey) });
+    debug.log('run-chart', 'metrics', { runId, ...metrics }); } catch { /* observation is fail-soft */ }
+  return cells;
+}
+
+export function runChartMetrics(entries: readonly RunLedgerEntry[]): { emptyHandoffs: number; unreadHandoffs: number; conflictingVerdicts: number } {
+  const cells = entries.filter((e) => e.event === 'run-chart-cell');
+  const emptyHandoffs = cells.filter((e) => !String(e.data.handoff ?? '').trim()).length;
+  const unreadHandoffs = cells.filter((e) => {
+    const handoff = String(e.data.handoff ?? '').trim().toLowerCase();
+    return handoff !== '' && handoff !== 'none'
+      && !cells.some((next) => next.data.readStopKeys instanceof Array && next.data.readStopKeys.includes(String(e.data.stopKey)));
+  }).length;
+  const verdicts = new Map<string, Set<string>>();
+  for (const cell of cells) {
+    const key = `${String(cell.data.device)}\0${String(cell.data.stopKey)}`;
+    const values = verdicts.get(key) ?? new Set<string>(); values.add(String(cell.data.verdict)); verdicts.set(key, values);
+  }
+  const conflictingVerdicts = [...verdicts.values()].filter((values) => values.size > 1).length;
+  return { emptyHandoffs, unreadHandoffs, conflictingVerdicts };
+}
+
+export function recordRunChartDecision(input: RunChartDecision): RunChartWriteResult {
+  const result = appendRunLedgerEntryChecked(input.runId, (entries) => {
+    if (entries === null) return { append: false, result: 'missing-ledger' as const };
+    const existing = entries.find((entry) => entry.event === 'run-chart-cell'
+      && entry.data.device === input.device && entry.data.stopKey === input.stopKey);
+    if (existing) return { append: false, result: existing.data.verdict === input.verdict
+      ? 'already-recorded' as const : 'conflicting-verdict' as const };
+    const current = chartEvents(entries);
+    const overflow = current.length >= RUN_CHART_MAX_CELLS;
+    const foldCount = overflow ? current.length - (RUN_CHART_MAX_CELLS - 2) : 0;
+    const toFold = current.slice(0, foldCount);
+    const append: RunLedgerEntry[] = [];
+    if (toFold.length) {
+      const foldedCells = toFold.filter((e) => e.data.verdict !== 'summary');
+      const priorSummary = toFold.find((e) => e.data.verdict === 'summary');
+      const priorCount = Number(String(priorSummary?.data.observed ?? '').match(/^\d+/)?.[0] ?? 0);
+      const count = priorCount + foldedCells.length;
+      const lastFolded = foldedCells.at(-1);
+      append.push({ timestamp: new Date().toISOString(), runId: input.runId, event: 'run-chart-summary',
+        data: { count, firstStopKey: toFold[0]?.data.stopKey, lastStopKey: lastFolded?.data.stopKey,
+          verdicts: toFold.map((e) => `${String(e.data.device)}:${String(e.data.verdict)}`).join('; ').slice(0, 500) } });
+    }
+    append.push({ timestamp: new Date().toISOString(), runId: input.runId, event: 'run-chart-cell', data: {
+      device: input.device, stopKey: input.stopKey, observed: input.observed.slice(0, 240), verdict: input.verdict,
+      action: input.action, handoff: input.handoff ?? 'none', why: input.why.slice(0, 240), readStopKeys: input.readStopKeys.slice(-RUN_CHART_READ_CELLS),
+      ...(input.waitCount === undefined ? {} : { waitCount: input.waitCount }),
+      ...(input.failureClass === undefined ? {} : { failureClass: input.failureClass }),
+    } });
+    // appendRunLedgerEntryChecked writes one row. Store summary with the decision row as a compact payload.
+    return { append: true, entry: append.length === 1 ? append[0]! : { ...append[1]!, data: { ...append[1]!.data,
+      compacted: { count: append[0]!.data.count, firstStopKey: append[0]!.data.firstStopKey,
+        lastStopKey: append[0]!.data.lastStopKey, lastDevice: toFold.filter((e) => e.data.verdict !== 'summary').at(-1)?.data.device,
+        verdicts: append[0]!.data.verdicts } } } };
+  }, input.dir);
+  const status = result.appended ? 'recorded' : result.result ?? 'ledger-write-refused';
+  if (status === 'recorded') {
+    try { debug.log('run-chart', 'decision', { runId: input.runId, device: input.device, stopKey: input.stopKey,
+      handoff: input.handoff, why: input.why.slice(0, 120) }); } catch { /* observation is fail-soft */ }
+  }
+  return status;
+}
+
+export interface RunChartWaitHandoff { runId: string; stopKey: string; waitCount: number; dir: string; readStopKeys?: string[] }
+export type RunChartWaitHandoffResult = RunChartWriteResult;
+export function recordRunChartWaitHandoff(input: RunChartWaitHandoff): RunChartWaitHandoffResult {
+  const readStopKeys = input.readStopKeys ?? readRunChart(input.runId, 'run-supervisor', input.dir).map((cell) => cell.stopKey);
+  return recordRunChartDecision({ runId: input.runId, device: 'run-supervisor', stopKey: input.stopKey,
+    observed: `consecutive wait decisions=${input.waitCount}`, verdict: 'wait', action: 'wait', handoff: 'run-doctor',
+    why: 'wait streak reached run doctor handoff threshold', readStopKeys,
+    waitCount: input.waitCount, failureClass: 'implement-aborted', dir: input.dir });
+}

package/src/self-implement/run-ledger.ts

@@ -1,4 +1,5 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, statSync, truncateSync, unlinkSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { refuseProductionLedgerWriteInTest } from '../harness/ledger-write-guard.js';
@@ -17,6 +18,8 @@ import { withRunLedgerLock, restoreArchivedRunLedger } from './run-ledger-compac
 
 export interface RunLedgerEntry {
   timestamp?: string;
+  /** Monotonic per-run ordering for graph/traversal events. Legacy rows may omit it. */
+  seq?: number;
   runId: string;
   event: string;
   data: Record<string, unknown>;
@@ -30,6 +33,95 @@ export interface RunLedgerEntry {
   shardIdentityReadFailure?: RunShardIdentityReadFailure;
 }
 
+/** Stable signature for an ordered observed route; callers record the evidence basis separately. */
+export function pathSignatureOf(steps: readonly { readonly from: string; readonly to: string; readonly skipped?: readonly string[] }[]): string {
+  return createHash('sha256').update(JSON.stringify(steps.map(step => [step.from, step.to, step.skipped ?? []]))).digest('hex').slice(0, 12);
+}
+
+const RUN_GRAPH_STEP_EVENTS = new Set([
+  'node-enter', 'node-exit', 'edge-taken', 'node-skipped', 'node-added', 'edge-rerouted',
+  'unit-expanded', 'unit-collapsed', 'pipeline-node-entry', 'pipeline-node-exit', 'graph-edge-taken',
+  'graph.path',
+]);
+
+function isRunGraphStepEvent(entry: RunLedgerEntry): boolean {
+  return RUN_GRAPH_STEP_EVENTS.has(entry.event)
+    || (entry.event === 'applied' && ['add-node', 'reroute', 'zoom-in', 'collapse'].includes(String(entry.data.op)));
+}
+
+/** Assign a monotonic sequence at the locked append boundary; never infer it later from timestamps. */
+function sequenceRunGraphEvent(entry: RunLedgerEntry, max: number): RunLedgerEntry {
+  if (!isRunGraphStepEvent(entry)) return entry;
+  const explicit = entry.seq ?? entry.data.seq;
+  if (typeof explicit === 'number' && Number.isSafeInteger(explicit) && explicit > max) {
+    return { ...entry, seq: explicit, ...(entry.data.seq === undefined ? {} : { data: { ...entry.data, seq: explicit } }) };
+  }
+  if (max >= Number.MAX_SAFE_INTEGER) throw new Error(`run graph event sequence exhausted: ${entry.runId}`);
+  const seq = max + 1;
+  return { ...entry, seq, ...(entry.data.seq === undefined ? {} : { data: { ...entry.data, seq } }) };
+}
+
+/** Read backward to the last sequenced graph step; repeated appends stay O(tail), not O(ledger²). */
+function lastRunGraphEventSequence(runId: string, dir: string): number {
+  const path = runLedgerPath(runId, dir);
+  if (!existsSync(path)) return 0;
+  const fd = openSync(path, 'r');
+  try {
+    const size = statSync(path).size;
+    const chunkSize = 8 * 1024;
+    let end = size;
+    let carry = '';
+    while (end > 0) {
+      const start = Math.max(0, end - chunkSize);
+      const bytes = Buffer.alloc(end - start);
+      readSync(fd, bytes, 0, bytes.length, start);
+      const text = `${bytes.toString('utf8')}${carry}`;
+      const lines = text.split(/\r?\n/);
+      carry = lines[0] ?? '';
+      for (let index = lines.length - 1; index > 0; index -= 1) {
+        const line = lines[index]?.trim();
+        if (!line) continue;
+        let row: RunLedgerEntry;
+        try { row = parseRunLedgerEntry(line, 0, runId); }
+        catch (error) {
+          if (index === lines.length - 1 && !text.endsWith('\n') && isIncompleteJsonPrefix(line)) {
+            throw new Error(`incomplete trailing run ledger entry: ${runId}`);
+          }
+          throw error;
+        }
+        if (!isRunGraphStepEvent(row)) continue;
+        const seq = row.seq ?? row.data.seq;
+        if (typeof seq === 'number' && Number.isSafeInteger(seq) && seq > 0) return seq;
+      }
+      end = start;
+    }
+    if (carry.trim()) {
+      let row: RunLedgerEntry;
+      try { row = parseRunLedgerEntry(carry, 0, runId); }
+      catch (error) {
+        if (isIncompleteJsonPrefix(carry)) throw new Error(`incomplete trailing run ledger entry: ${runId}`);
+        throw error;
+      }
+      if (!isRunGraphStepEvent(row)) return 0;
+      const seq = row.seq ?? row.data.seq;
+      if (typeof seq === 'number' && Number.isSafeInteger(seq) && seq > 0) return seq;
+    }
+    return 0;
+  } finally { closeSync(fd); }
+}
+
+function separateAppendedLedgerLine(path: string, line: string): string {
+  if (!existsSync(path)) return line;
+  const size = statSync(path).size;
+  if (size === 0) return line;
+  const fd = openSync(path, 'r');
+  try {
+    const lastByte = Buffer.alloc(1);
+    readSync(fd, lastByte, 0, 1, size - 1);
+    return lastByte[0] === 0x0a ? line : `\n${line}`;
+  } finally { closeSync(fd); }
+}
+
 export type RunShardIdentityReadFailure = 'malformed-structure' | 'invalid-values';
 
 export interface RunShardIdentity {
@@ -107,6 +199,7 @@ export interface RunOriginData extends Record<string, unknown> {
 }
 
 export type RunLedgerWriter = (entry: RunLedgerEntry) => void;
+export type RunLedgerBatchWriter = (entries: readonly RunLedgerEntry[]) => void;
 export type RunLedgerReader = (path: string, encoding?: 'utf8') => string | Buffer;
 
 /** A live PTY lacks its producer correlation id, or that id lacks an observable JSONL ledger. */
@@ -712,12 +805,21 @@ export function appendRunLedgerEntry(entry: RunLedgerEntry, dir = runLedgerDir()
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   const live = runLedgerPath(entry.runId, dir);
   const devProject = process.env.ELANOUS_DEV_PROJECT;
-  const row = entry.devProject === undefined && typeof devProject === 'string' && devProject.startsWith('prj-')
-    ? { ...entry, devProject }
-    : entry;
   withRunLedgerLock(dir, entry.runId, () => {
-    const line = `${JSON.stringify(row)}\n`;
-    if (!restoreArchivedRunLedger(dir, entry.runId, line)) appendFileSync(live, line, 'utf8');
+    let sequenced = entry;
+    if (isRunGraphStepEvent(entry)) {
+      // Restore a compacted ledger before choosing its next sequence so appends keep the
+      // same per-run order across the live/archive boundary.
+      restoreArchivedRunLedger(dir, entry.runId);
+      sequenced = sequenceRunGraphEvent(entry, lastRunGraphEventSequence(entry.runId, dir));
+    }
+    const sequencedRow = sequenced.devProject === undefined && typeof devProject === 'string' && devProject.startsWith('prj-')
+      ? { ...sequenced, devProject }
+      : sequenced;
+    const line = `${JSON.stringify(sequencedRow)}\n`;
+    const appendLine = isRunGraphStepEvent(entry) ? separateAppendedLedgerLine(live, line) : line;
+    if (!isRunGraphStepEvent(entry) && restoreArchivedRunLedger(dir, entry.runId, appendLine)) return;
+    appendFileSync(live, appendLine, 'utf8');
   });
   try {
     recordRunRequestVsEffectiveFromLedger(entry.runId, dir, entry);
@@ -726,6 +828,48 @@ export function appendRunLedgerEntry(entry: RunLedgerEntry, dir = runLedgerDir()
   }
 }
 
+/** Append one run's structural graph events as a rollback-protected ledger batch. */
+export function appendRunLedgerEntries(entries: readonly RunLedgerEntry[], dir = runLedgerDir()): void {
+  if (entries.length === 0) return;
+  const runId = entries[0]!.runId;
+  if (!runId || entries.some((entry) => entry.runId !== runId)) throw new Error('run ledger batch must have one runId');
+  if (entries.some((entry) => !isRunGraphStepEvent(entry))) throw new Error('run ledger batch accepts graph-step events only');
+  if (refuseProductionLedgerWriteInTest(dir, 'run-ledger')) return;
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const live = runLedgerPath(runId, dir);
+  const devProject = process.env.ELANOUS_DEV_PROJECT;
+  withRunLedgerLock(dir, runId, () => {
+    restoreArchivedRunLedger(dir, runId);
+    let lastSequence = lastRunGraphEventSequence(runId, dir);
+    const rows = entries.map((entry) => {
+      const sequenced = sequenceRunGraphEvent(entry, lastSequence);
+      lastSequence = sequenced.seq ?? (typeof sequenced.data.seq === 'number' ? sequenced.data.seq : lastSequence);
+      return sequenced.devProject === undefined && typeof devProject === 'string' && devProject.startsWith('prj-')
+        ? { ...sequenced, devProject }
+        : sequenced;
+    });
+    const lines = rows.map((row) => `${JSON.stringify(row)}\n`).join('');
+    const appendLine = separateAppendedLedgerLine(live, lines);
+    const existed = existsSync(live);
+    const sizeBefore = existed ? statSync(live).size : 0;
+    try {
+      appendFileSync(live, appendLine, 'utf8');
+    } catch (error) {
+      try {
+        if (existed) truncateSync(live, sizeBefore);
+        else if (existsSync(live)) unlinkSync(live);
+      } catch (rollbackError) {
+        throw new AggregateError([error, rollbackError], `run ledger batch append and rollback failed: ${runId}`);
+      }
+      throw error;
+    }
+  });
+  for (const entry of entries) {
+    try { recordRunRequestVsEffectiveFromLedger(runId, dir, entry); }
+    catch { /* This comparison is observation and cannot fail a committed batch. */ }
+  }
+}
+
 /** Caller decision inside `appendRunLedgerEntryChecked`: either `append` exactly one entry, or skip with `result`. */
 export type RunLedgerCheckedAppendDecision<T> =
   | { append: false; result: T }
@@ -790,7 +934,8 @@ export function appendRunLedgerEntryChecked<T>(
 ): RunLedgerCheckedAppendOutcome<T> {
   if (refuseProductionLedgerWriteInTest(dir, 'run-ledger')) return { appended: false, result: null, refusal: 'ledger-write-refused' as const };
   return withRunLedgerLock(dir, runId, () => {
-    const decision = decide(loadRunLedger(runId, dir));
+    const existing = loadRunLedger(runId, dir);
+    const decision = decide(existing);
     if (!decision.append) return { appended: false, result: decision.result, refusal: null };
     const entry = decision.entry;
     if (entry.runId !== runId) {
@@ -798,11 +943,16 @@ export function appendRunLedgerEntryChecked<T>(
     }
     const live = runLedgerPath(entry.runId, dir);
     const devProject = process.env.ELANOUS_DEV_PROJECT;
-    const row = entry.devProject === undefined && typeof devProject === 'string' && devProject.startsWith('prj-')
-      ? { ...entry, devProject }
-      : entry;
+    const isGraphStep = isRunGraphStepEvent(entry);
+    if (isGraphStep) restoreArchivedRunLedger(dir, runId);
+    const sequenced = isGraphStep ? sequenceRunGraphEvent(entry, lastRunGraphEventSequence(runId, dir)) : entry;
+    const row = sequenced.devProject === undefined && typeof devProject === 'string' && devProject.startsWith('prj-')
+      ? { ...sequenced, devProject }
+      : sequenced;
     const line = `${JSON.stringify(row)}\n`;
-    if (!restoreArchivedRunLedger(dir, entry.runId, line)) appendFileSync(live, line, 'utf8');
+    const appendLine = isGraphStep ? separateAppendedLedgerLine(live, line) : line;
+    if (!isGraphStep && restoreArchivedRunLedger(dir, entry.runId, appendLine)) return { appended: true, result: null, refusal: null };
+    appendFileSync(live, appendLine, 'utf8');
     return { appended: true, result: null, refusal: null };
   });
 }
@@ -925,6 +1075,7 @@ function parseRunLedgerEntry(line: string, lineNumber: number, expectedRunId: st
   }
   const entry = parsed as Partial<RunLedgerEntry>;
   if ((entry.timestamp !== undefined && typeof entry.timestamp !== 'string') || typeof entry.runId !== 'string' || typeof entry.event !== 'string'
+    || (entry.seq !== undefined && (!Number.isSafeInteger(entry.seq) || entry.seq < 1))
     || !entry.data || typeof entry.data !== 'object' || Array.isArray(entry.data)
     || (entry.goalId !== undefined && typeof entry.goalId !== 'string')
     || (entry.orchestrationId !== undefined && typeof entry.orchestrationId !== 'string')