elanous 0.2.40 → 0.2.42

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,119 @@
+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) => Boolean(e.data.handoff)
+    && !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, 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,4 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { refuseProductionLedgerWriteInTest } from '../harness/ledger-write-guard.js';
@@ -17,6 +17,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 +32,89 @@ export interface RunLedgerEntry {
   shardIdentityReadFailure?: RunShardIdentityReadFailure;
 }
 
+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',
+]);
+
+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 {
@@ -414,12 +499,20 @@ export function runGraphVariantPath(runId: string, dir = runLedgerDir()): string
   return `${runLedgerPath(runId, dir)}.graph.yaml`;
 }
 
+/** 원장에 실린 unit 선언 근거 한 줄 — 경로와 내용 해시뿐이고 본문은 원장에 없다. */
+export interface RunGraphVariantUnitDeclaration {
+  readonly path: string;
+  readonly contentHash: string;
+}
+
 /** 최초 graph variant 선택의 원장 옆 재조회 계약 — 같은 runId·파일이면 같은 id·선택 이유가 돌아온다. */
 export interface RunGraphVariantSelection {
   /** createGraphVariant 가 골 종류·대상 경로 수에서 유도한 최초 variant id. */
   readonly variantId: string;
   /** 그 variant가 최초로 선택된 근거(종류·경로 수 기반) — 저장·재조회가 같은 문자열. */
   readonly reason: string;
+  /** 이 런이 읽은 unit 선언의 경로·내용 해시 — 옛 원장에는 키가 없어 값도 없다(추가 키). */
+  readonly unitDeclarations?: readonly RunGraphVariantUnitDeclaration[];
 }
 
 /** 런 원장 옆 .graph.yaml 을 처음 한 번 쓰고 저장 경로를 돌려준다 — 이미 있으면 덮쓰지 않는다(flag wx). */
@@ -447,9 +540,24 @@ export function loadRunGraphVariant(runId: string, dir = runLedgerDir()): RunGra
     throw new Error(`invalid run graph variant YAML at ${path}: ${error instanceof Error ? error.message : String(error)}`);
   }
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
-  const record = parsed as { variant_id?: unknown; reason?: unknown };
+  const record = parsed as { variant_id?: unknown; reason?: unknown; unit_declarations?: unknown };
   if (typeof record.variant_id !== 'string' || typeof record.reason !== 'string') return null;
-  return { variantId: record.variant_id, reason: record.reason };
+  const unitDeclarations = parseRunGraphVariantUnitDeclarations(record.unit_declarations);
+  return { variantId: record.variant_id, reason: record.reason,
+    ...(unitDeclarations === undefined ? {} : { unitDeclarations }) };
+}
+
+/** `unit_declarations: [{ path, content_hash }]` 추가 키의 재읽기 — 키가 없거나 비면 근거도 없다. */
+function parseRunGraphVariantUnitDeclarations(value: unknown): RunGraphVariantUnitDeclaration[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const declarations: RunGraphVariantUnitDeclaration[] = [];
+  for (const entry of value) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+    const record = entry as { path?: unknown; content_hash?: unknown };
+    if (typeof record.path !== 'string' || typeof record.content_hash !== 'string') continue;
+    declarations.push({ path: record.path, contentHash: record.content_hash });
+  }
+  return declarations.length === 0 ? undefined : declarations;
 }
 
 /**
@@ -689,12 +797,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);
@@ -767,7 +884,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) {
@@ -775,11 +893,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 };
   });
 }
@@ -902,6 +1025,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')
@@ -1811,6 +1935,8 @@ export interface UnfinishedRunLedgerQuery {
    * 엉킨 visit 을 셀 수 있게 하는 값이다.
    */
   orphanUnitVisitCount?: number;
+  /** True when a caller deadline stopped the scan before every ledger was visited. */
+  timedOut?: boolean;
   scope: 'self-implement-run-ledger';
   note: string;
 }
@@ -1824,6 +1950,8 @@ export interface UnfinishedRunLedgerQueryOptions {
   noCache?: boolean;
   /** ⛔ 「도는 중」으로 볼 마지막 활동 나이(ms). 호출자가 준다 — 이 모듈이 새 수를 정하지 않는다. */
   liveWindowMs?: number;
+  /** Absolute wall-clock deadline; when reached, return the rows scanned so far as partial evidence. */
+  deadlineAtMs?: number;
 }
 
 const UNFINISHED_RUN_LEDGER_NOTE = 'Read-only scan of the specified run-ledger directory. A terminal-status-missing ledger is not the same as an unreadable ledger; planned paths are extracted only from a goal document matched by the final hyphen-separated branch segment.';
@@ -2470,7 +2598,12 @@ export function queryUnfinishedRunLedgers(options: UnfinishedRunLedgerQueryOptio
   let callerCwdCount = 0;
   // ⭐ 터미널 원장도 «세기만» 한다 — entries 로 되살리지 않는다(부활 금지).
   let orphanUnitVisitCount = 0;
+  let timedOut = false;
   for (const fileName of fileNames) {
+    if (options.deadlineAtMs !== undefined && Date.now() >= options.deadlineAtMs) {
+      timedOut = true;
+      break;
+    }
     const runId = runIdFromCanonicalLedgerFile(fileName);
     if (!runId) continue;
     scanned += 1;
@@ -2555,9 +2688,10 @@ export function queryUnfinishedRunLedgers(options: UnfinishedRunLedgerQueryOptio
     indexOrigin,
     indexHits,
     ms: Date.now() - startedAt,
+    ...(timedOut ? { timedOut: true, stopReason: 'deadline-exceeded' } : {}),
   });
   if (options.path === undefined) {
-    return { entries, ledgerDirectory: dir, goalsDirectory: goalsDir, unreadableLedgerCount, orphanUnitVisitCount, ledgerDirectoryMissing: false, terminalByTrailingRunStatus, cacheHits, cacheMisses, indexHits, indexOrigin, scope: 'self-implement-run-ledger', note: UNFINISHED_RUN_LEDGER_NOTE };
+    return { entries, ledgerDirectory: dir, goalsDirectory: goalsDir, unreadableLedgerCount, orphanUnitVisitCount, ledgerDirectoryMissing: false, terminalByTrailingRunStatus, cacheHits, cacheMisses, indexHits, indexOrigin, ...(timedOut ? { timedOut: true } : {}), scope: 'self-implement-run-ledger', note: UNFINISHED_RUN_LEDGER_NOTE };
   }
   const pathFilter = options.path;
   const unknownPathStatus = (entry: UnfinishedRunLedgerEntry): boolean => entry.plannedPathStatus !== 'found-ledger-goal-file'
@@ -2583,6 +2717,7 @@ export function queryUnfinishedRunLedgers(options: UnfinishedRunLedgerQueryOptio
     pathFilter,
     matchingPathCount: matchingEntries.length,
     unknownPathCount: unknownEntries.length,
+    ...(timedOut ? { timedOut: true } : {}),
     scope: 'self-implement-run-ledger',
     note: UNFINISHED_RUN_LEDGER_NOTE,
   };
@@ -2619,6 +2754,8 @@ export interface FederatedUnfinishedRunLedgerQuery {
   cacheMisses?: number;
   /** Hits served by the persisted cross-process scan index (subset of cacheHits). */
   indexHits?: number;
+  timedOut?: boolean;
+  stalledStage?: 'ledger-scan' | 'cross-directory-reconciliation';
   pathFilter?: string;
   matchingPathCount?: number;
   unknownPathCount?: number;
@@ -2640,6 +2777,7 @@ export interface FederatedUnfinishedRunLedgerQueryOptions {
    * canonical *.jsonl plus the cross-directory unfinished-runId reconciliation.
    */
   runIds?: readonly string[];
+  deadlineAtMs?: number;
 }
 
 const FEDERATED_UNFINISHED_RUN_LEDGER_NOTE = 'Read-only union of run-ledger directories selected by the same --all/--include-test target policy as elanous logs. Each row carries its physical ledger directory because instance names can identify multiple state roots.';
@@ -2659,12 +2797,19 @@ export function queryFederatedUnfinishedRunLedgers(options: FederatedUnfinishedR
   let cacheHits = 0;
   let cacheMisses = 0;
   let indexHits = 0;
+  let timedOut = false;
+  let stalledStage: FederatedUnfinishedRunLedgerQuery['stalledStage'];
   const recordDirectoryFailure = (kind: FederatedLedgerDirectoryFailureKind): void => {
     if (kind === 'missing') missingLedgerDirectoryCount += 1;
     else if (kind === 'unreadable') unreadableLedgerDirectoryAccessCount += 1;
     else indeterminateLedgerDirectoryCount += 1;
   };
   for (const ledgerDirectory of candidateLedgerDirectories) {
+    if (options.deadlineAtMs !== undefined && Date.now() >= options.deadlineAtMs) {
+      timedOut = true;
+      stalledStage = 'ledger-scan';
+      break;
+    }
     try {
       const listDirectory = options.list ?? readdirSync;
       const list = requestedRunIds === undefined
@@ -2673,7 +2818,7 @@ export function queryFederatedUnfinishedRunLedgers(options: FederatedUnfinishedR
           const runId = runIdFromCanonicalLedgerFile(fileName);
           return runId !== null && requestedRunIds.has(runId);
         });
-      const result = queryUnfinishedRunLedgers({ dir: ledgerDirectory, goalsDir: goalsDirectory, ...(options.path === undefined ? {} : { path: options.path }), ...(list === undefined ? {} : { list }), noCache: options.noCache });
+      const result = queryUnfinishedRunLedgers({ dir: ledgerDirectory, goalsDir: goalsDirectory, ...(options.path === undefined ? {} : { path: options.path }), ...(list === undefined ? {} : { list }), noCache: options.noCache, deadlineAtMs: options.deadlineAtMs });
       if (result.ledgerDirectoryMissing) {
         recordDirectoryFailure('missing');
         continue;
@@ -2685,10 +2830,15 @@ export function queryFederatedUnfinishedRunLedgers(options: FederatedUnfinishedR
       cacheHits += result.cacheHits ?? 0;
       cacheMisses += result.cacheMisses ?? 0;
       indexHits += result.indexHits ?? 0;
+      if (result.timedOut) {
+        timedOut = true;
+        stalledStage = 'ledger-scan';
+      }
       entries.push(...result.entries.map((entry) => ({ ...entry, ledgerDirectory })));
     } catch (error) {
       recordDirectoryFailure(classifyFederatedLedgerDirectoryReadFailure(error));
     }
+    if (timedOut) break;
   }
   const unreadableLedgerDirectoryCount = missingLedgerDirectoryCount + unreadableLedgerDirectoryAccessCount + indeterminateLedgerDirectoryCount;
   // ⛔⭐⭐ 가로 대조 — 원장 «하나»만 보고 「미완」이라 말하지 않는다 (2026-08-11 · 🅣 71차 실측).
@@ -2698,20 +2848,28 @@ export function queryFederatedUnfinishedRunLedgers(options: FederatedUnfinishedR
   //   📏 실측(2026-08-11): 미완 57 중 ***7*** 이 다른 원장에 종결을 갖고 있었다.
   // ⛔ 판정 술어는 스캐너와 «같은 것»을 쓴다(`run-status` 또는 `terminal`) — 어휘를 새로 만들지 않는다.
   const terminatedElsewhere = new Set<string>();
+  const reconciledRunIds = new Set<string>();
   // Runs carrying a non-blocking request record never drop out of the union: their requestId
   // reason·next must survive restarts and cross-directory reconciliation alike.
   const unfinishedRunIds = requestedRunIds === undefined
     ? new Set(entries.filter((entry) => !entry.nonBlocking).map((entry) => entry.runId))
     : new Set([...requestedRunIds].filter((runId) => entries.some((entry) => entry.runId === runId && !entry.nonBlocking)));
-  for (const runId of unfinishedRunIds) {
+  for (const runId of timedOut ? [] : unfinishedRunIds) {
+    if (options.deadlineAtMs !== undefined && Date.now() >= options.deadlineAtMs) {
+      timedOut = true;
+      stalledStage = 'cross-directory-reconciliation';
+      break;
+    }
     for (const ledgerDirectory of ledgerDirectories) {
       try {
         const reconciliationIndex = options.noCache ? undefined : loadRunLedgerScanIndex(ledgerDirectory);
         if (readUnfinishedLedgerFacts(runId, ledgerDirectory, undefined, options.noCache, reconciliationIndex).facts.terminal) { terminatedElsewhere.add(runId); break; }
       } catch { /* An absent or unreadable sibling cannot establish termination. */ }
     }
+    reconciledRunIds.add(runId);
   }
-  const reconciledEntries = entries.filter((entry) => !terminatedElsewhere.has(entry.runId));
+  const reconciledEntries = entries.filter((entry) => !terminatedElsewhere.has(entry.runId)
+    && (stalledStage !== 'cross-directory-reconciliation' || reconciledRunIds.has(entry.runId)));
   const reconciledTerminatedElsewhereCount = entries.length - reconciledEntries.length;
   entries.length = 0;
   entries.push(...reconciledEntries);
@@ -2729,6 +2887,7 @@ export function queryFederatedUnfinishedRunLedgers(options: FederatedUnfinishedR
     cacheHits,
     cacheMisses,
     indexHits,
+    ...(timedOut ? { timedOut: true, stalledStage } : {}),
     ...(options.path === undefined ? {} : { pathFilter: options.path, matchingPathCount, unknownPathCount }),
     scope: 'self-implement-run-ledger-federated',
     note: FEDERATED_UNFINISHED_RUN_LEDGER_NOTE,