elanous 0.2.19 → 0.2.21

package/src/nexus/api/graphs-api.ts

@@ -1,15 +1,33 @@
-import { mkdtempSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { elanousStateRoot } from '../../autopilot/state-paths.js';
+import { debug } from '../../debug/log.js';
 import { defaultGraphsDir, loadGraphTemplatesFrom } from '../../self-implement/graph-templates.js';
 import { loadGraphTemplates } from '../../self-implement/graph-yaml.js';
+import { validateGraphYaml } from './graph-kinds.js';
+import { parseWizardSteps, readWizardSteps, withWizardSteps } from '../../graph-wizard/saved-steps.js';
+import type { WizardNodeStep } from '../../graph-wizard/steps.js';
 import { jsonResponse } from './json-response.js';
 
 /** Declared graph ids only. A user string is never joined onto a filesystem path. */
 const GRAPH_ID = /^[a-z0-9-]+$/;
 
+/**
+ * Sidecar names a graph directory loads specially. `recipes.yaml` next to a graph is what
+ * the graph runner executes (`cmd:` recipes), so an HTTP write to `<mine>/recipes.yaml`
+ * would be a remote command path. These ids are never created, saved or reverted, and
+ * these files are never indexed as graphs.
+ */
+export const RESERVED_GRAPH_IDS: ReadonlySet<string> = new Set(['recipes', 'overlay', 'overlays']);
+
+function reserved(id: string): Response | null {
+  if (!RESERVED_GRAPH_IDS.has(id)) return null;
+  debug.log('nexus.graphs', 'rejected-reserved', { id });
+  return jsonResponse({ error: 'reserved-id', id }, 400);
+}
+
 export interface GraphCatalogEntry {
   id: string;
   source: 'core' | 'mine';
@@ -45,6 +63,7 @@ function readDirYaml(dir: string): string[] {
 function indexByDeclaredId(dir: string): Map<string, { file: string; text: string }> {
   const found = new Map<string, { file: string; text: string }>();
   for (const file of readDirYaml(dir)) {
+    if (RESERVED_GRAPH_IDS.has(file.replace(/\.ya?ml$/, ''))) continue;
     let text: string;
     try { text = readFileSync(join(dir, file), 'utf8'); }
     catch { continue; }
@@ -92,7 +111,12 @@ function detailOf(id: string, source: 'core' | 'mine', editable: boolean, dir: s
     editable,
     entry_node: template.entryNode,
     terminal_nodes: template.terminalNodes,
-    nodes: template.nodes.map(({ nodeId, kind, recipe, maxVisits }) => ({ node_id: nodeId, kind, recipe, max_visits: maxVisits })),
+    // GRAPH-GROUPS — a node's `group:` tag (when the loader carries it) rides along so the PWA can box/fold units.
+    nodes: template.nodes.map((node) => {
+      const { nodeId, kind, recipe, maxVisits } = node;
+      const group = (node as { group?: unknown }).group;
+      return { node_id: nodeId, kind, recipe, max_visits: maxVisits, ...(typeof group === 'string' && group.trim() ? { group: group.trim() } : {}) };
+    }),
     edges: spec.edges.map(({ from, to, on, map }) => ({
       from,
       ...(to === undefined ? {} : { to }),
@@ -125,6 +149,21 @@ function validateInTemp(text: string, expectedId: string): { ok: true } | { ok:
   }
 }
 
+/** Same validator as POST /v1/graphs/validate. Invalid → 422; declared graph_id ≠ id → 400. Null = ok. */
+function rejectGraphYaml(text: string, id: string, version?: string): Response | null {
+  const checked = validateGraphYaml('harness', text);
+  if (!checked.ok) {
+    debug.log('nexus.graphs', 'rejected-invalid', { id, ...(version ? { version } : {}), issues: checked.errors });
+    return jsonResponse({ error: 'invalid-graph', errors: checked.errors, ignoredKeys: checked.ignoredKeys }, 422);
+  }
+  if (checked.graphId !== id) {
+    const errors = [{ path: `${id}/graph_id`, message: 'graph_id 가 요청 id 와 다르다' }];
+    debug.log('nexus.graphs', 'rejected-invalid', { id, issues: errors });
+    return jsonResponse({ error: 'graph-id-mismatch', errors }, 400);
+  }
+  return null;
+}
+
 /** Core graphs are read from the same YAML loader as the harness, never rewritten by this API. */
 export function handleGraphsGet(pathname: string, dir = defaultGraphsDir(), deps: GraphsApiDeps = {}): Response {
   const coreDir = deps.coreDir ?? dir;
@@ -146,7 +185,8 @@ export function handleGraphsGet(pathname: string, dir = defaultGraphsDir(), deps
     const coreHit = core.ok ? indexByDeclaredId(coreDir).get(id) : undefined;
     const hit = mineHit ?? coreHit;
     if (!hit) return jsonResponse({ error: 'not-found', id }, 404);
-    return jsonResponse({ id, source: mineHit ? 'mine' : 'core', editable: Boolean(mineHit), yaml: hit.text });
+    const steps = mineHit ? readWizardSteps(mineDir, id, hit.text) : null;
+    return jsonResponse({ id, source: mineHit ? 'mine' : 'core', editable: Boolean(mineHit), yaml: hit.text, ...(steps ? { steps } : {}) });
   }
 
   const match = /^\/v1\/graphs\/([^/]+)$/.exec(pathname);
@@ -168,6 +208,8 @@ export async function handleGraphsPut(pathname: string, req: Request, deps: Grap
   if (!match) return jsonResponse({ error: 'not-found' }, 404);
   const id = resolveId(match[1]!);
   if (!id) return jsonResponse({ error: 'bad_request', reason: 'invalid graph id' }, 400);
+  const reservedId = reserved(id);
+  if (reservedId) return reservedId;
   const coreDir = deps.coreDir ?? defaultGraphsDir();
   const mineDir = deps.mineDir ?? mineGraphsDir();
   const core = coreCatalog(coreDir);
@@ -175,15 +217,179 @@ export async function handleGraphsPut(pathname: string, req: Request, deps: Grap
   const mineOwns = indexByDeclaredId(mineDir).has(id);
   if (coreOwns && !mineOwns) return jsonResponse({ error: 'core-read-only', id }, 403);
   if (!mineOwns) return jsonResponse({ error: 'not-found', id }, 404);
-  let body: { yaml?: unknown };
-  try { body = await req.json() as { yaml?: unknown }; }
+  let body: { yaml?: unknown; steps?: unknown };
+  try { body = await req.json() as { yaml?: unknown; steps?: unknown }; }
   catch { return jsonResponse({ error: 'bad_request', reason: 'json body required' }, 400); }
-  if (typeof body.yaml !== 'string') return jsonResponse({ error: 'bad_request', reason: 'yaml string required' }, 400);
-  const checked = validateInTemp(body.yaml, id);
-  if (!checked.ok) return jsonResponse({ error: 'invalid-graph', errors: checked.errors }, 400);
+  if (typeof body?.yaml !== 'string') return jsonResponse({ error: 'bad_request', reason: 'yaml string required' }, 400);
+  const rejected = rejectGraphYaml(body.yaml, id);
+  if (rejected) return rejected;
+  const steps = stepsOf(body.steps, body.yaml);
+  if (steps instanceof Response) return steps;
   const existing = indexByDeclaredId(mineDir).get(id)!;
-  writeFileSync(join(mineDir, existing.file), body.yaml);
-  return jsonResponse({ id, source: 'mine', editable: true, saved: true });
+  // Writes go only to <mine>/<id>.yaml; a hand-placed file under another name is not edited over HTTP.
+  if (existing.file !== `${id}.yaml`) return jsonResponse({ error: 'file-name-mismatch', id, file: existing.file }, 409);
+  let written: { version: string; previous: string };
+  try { written = withWizardSteps(mineDir, id, steps, () => writeWithVersion(mineDir, id, existing, body.yaml as string)); }
+  catch (error) { return saveFailed(id, error); }
+  const { version, previous } = written;
+  debug.log('nexus.graphs', 'saved', { id, version, previous, steps: steps ? Object.keys(steps).length : 0 });
+  return jsonResponse({ id, source: 'mine', editable: true, saved: true, version, previous });
+}
+
+const VERSION_ID = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z(?:-\d{4})?$/;
+export const GRAPH_VERSION_CAP = 20;
+
+function versionsDir(mineDir: string, id: string): string {
+  return join(mineDir, '.versions', id);
+}
+
+/** Version ids are ISO timestamps (`:`/`.` → `-`), so name order is save order. */
+export function listGraphVersions(mineDir: string, id: string): Array<{ version: string; savedAt: string; bytes: number }> {
+  const dir = versionsDir(mineDir, id);
+  // Only `.yaml` is ever written, read and reverted — a stray `.yml` is not a version.
+  return readDirYaml(dir)
+    .filter((file) => file.endsWith('.yaml'))
+    .map((file) => file.replace(/\.yaml$/, ''))
+    .filter((version) => VERSION_ID.test(version))
+    .sort()
+    .map((version) => {
+      const iso = /^(\d{4}-\d{2}-\d{2})T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z/.exec(version);
+      let bytes = 0;
+      try { bytes = statSync(join(dir, `${version}.yaml`)).size; } catch { /* listed above; raced away */ }
+      return { version, savedAt: iso ? `${iso[1]}T${iso[2]}:${iso[3]}:${iso[4]}.${iso[5]}Z` : version, bytes };
+    });
+}
+
+function recordVersion(mineDir: string, id: string, text: string): string {
+  const dir = versionsDir(mineDir, id);
+  mkdirSync(dir, { recursive: true });
+  const base = new Date().toISOString().replace(/[:.]/g, '-');
+  let version = base;
+  for (let n = 1; existsSync(join(dir, `${version}.yaml`)); n += 1) version = `${base}-${String(n).padStart(4, '0')}`;
+  writeFileSync(join(dir, `${version}.yaml`), text);
+  const all = listGraphVersions(mineDir, id);
+  for (const old of all.slice(0, Math.max(0, all.length - GRAPH_VERSION_CAP))) {
+    rmSync(join(dir, `${old.version}.yaml`), { force: true });
+  }
+  return version;
+}
+
+/**
+ * Every saved state is a version. A graph with no history yet (e.g. a fresh clone)
+ * first records its current bytes, so `previous` always points at restorable bytes.
+ */
+function writeWithVersion(mineDir: string, id: string, existing: { file: string; text: string }, text: string): { version: string; previous: string } {
+  const history = listGraphVersions(mineDir, id);
+  const previous = history.at(-1)?.version ?? recordVersion(mineDir, id, existing.text);
+  // Version first, then an atomic replace of the current file: a crash in between leaves
+  // the old current bytes intact (they are `previous`), never bytes that no version holds.
+  const version = recordVersion(mineDir, id, text);
+  const target = join(mineDir, `${id}.yaml`);
+  const temp = join(mineDir, `.${id}.yaml.${process.pid}.tmp`);
+  writeFileSync(temp, text);
+  renameSync(temp, target);
+  return { version, previous };
+}
+
+function mineOwnership(id: string, deps: GraphsApiDeps): { mineDir: string; existing: { file: string; text: string } } | Response {
+  const reservedId = reserved(id);
+  if (reservedId) return reservedId;
+  const coreDir = deps.coreDir ?? defaultGraphsDir();
+  const mineDir = deps.mineDir ?? mineGraphsDir();
+  const existing = indexByDeclaredId(mineDir).get(id);
+  if (!existing) {
+    const core = coreCatalog(coreDir);
+    if (core.ok && indexByDeclaredId(coreDir).has(id)) return jsonResponse({ error: 'core-read-only', id }, 403);
+    return jsonResponse({ error: 'not-found', id }, 404);
+  }
+  return { mineDir, existing };
+}
+
+/** GET /v1/graphs/<id>/versions — only «mine» graphs have history. */
+export function handleGraphVersionsGet(pathname: string, deps: GraphsApiDeps = {}): Response {
+  const match = /^\/v1\/graphs\/([^/]+)\/versions$/.exec(pathname);
+  if (!match) return jsonResponse({ error: 'not-found' }, 404);
+  const id = resolveId(match[1]!);
+  if (!id) return jsonResponse({ error: 'bad_request', reason: 'invalid graph id' }, 400);
+  const owned = mineOwnership(id, deps);
+  if (owned instanceof Response) return owned;
+  return jsonResponse({ id, versions: listGraphVersions(owned.mineDir, id) });
+}
+
+/** POST /v1/graphs/<id>/revert {version} — restores that version; the restore is itself a new version. */
+export async function handleGraphsRevert(pathname: string, req: Request, deps: GraphsApiDeps = {}): Promise<Response> {
+  const match = /^\/v1\/graphs\/([^/]+)\/revert$/.exec(pathname);
+  if (!match) return jsonResponse({ error: 'not-found' }, 404);
+  const id = resolveId(match[1]!);
+  if (!id) return jsonResponse({ error: 'bad_request', reason: 'invalid graph id' }, 400);
+  const owned = mineOwnership(id, deps);
+  if (owned instanceof Response) return owned;
+  if (owned.existing.file !== `${id}.yaml`) return jsonResponse({ error: 'file-name-mismatch', id, file: owned.existing.file }, 409);
+  let body: { version?: unknown };
+  try { body = await req.json() as { version?: unknown }; }
+  catch { return jsonResponse({ error: 'bad_request', reason: 'json body required' }, 400); }
+  if (typeof body?.version !== 'string' || !VERSION_ID.test(body.version)) {
+    return jsonResponse({ error: 'bad_request', reason: 'version string required' }, 400);
+  }
+  const target = body.version;
+  // Only a listed version id is ever joined onto a path.
+  if (!listGraphVersions(owned.mineDir, id).some((entry) => entry.version === target)) {
+    return jsonResponse({ error: 'version-not-found', id, version: target }, 404);
+  }
+  const text = readFileSync(join(versionsDir(owned.mineDir, id), `${target}.yaml`), 'utf8');
+  const rejected = rejectGraphYaml(text, id, target);
+  if (rejected) return rejected;
+  const { version, previous } = writeWithVersion(owned.mineDir, id, owned.existing, text);
+  debug.log('nexus.graphs', 'reverted', { id, version, previous, restoredFrom: target });
+  return jsonResponse({ id, source: 'mine', editable: true, reverted: true, version, previous, restoredFrom: target });
+}
+
+/** GRAPH-WIZARD-SAVE-RECIPES — optional `steps` on save (the wizard's node → library step map). Absent = keep
+ *  whatever sidecar the graph has; present = validated against the step library and stored as a sidecar. The
+ *  run builds commands from it server-side (src/graph-wizard/saved-steps.ts) — no client command text is kept. */
+function stepsOf(raw: unknown, yaml: string): Record<string, WizardNodeStep> | null | Response {
+  // Only an absent field means «keep what is there»; an explicit null or any other non-object is a bad request.
+  if (raw === undefined) return null;
+  const parsed = parseWizardSteps(raw, yaml);
+  if (!parsed.ok) return jsonResponse({ error: 'bad_request', reason: parsed.reason }, 400);
+  return parsed.steps;
+}
+
+function saveFailed(id: string, error: unknown): Response {
+  const reason = error instanceof Error ? error.message.slice(0, 200) : String(error);
+  debug.log('nexus.graphs', 'save-failed', { id, reason }, { level: 'warn' });
+  return jsonResponse({ error: 'save-failed', id, reason }, 500);
+}
+
+/** POST /v1/graphs {id, yaml} — a brand-new «mine» graph (blank canvas → save). Records version v1. */
+export async function handleGraphsCreate(req: Request, deps: GraphsApiDeps = {}): Promise<Response> {
+  let body: { id?: unknown; yaml?: unknown; steps?: unknown };
+  try { body = await req.json() as { id?: unknown; yaml?: unknown; steps?: unknown }; }
+  catch { return jsonResponse({ error: 'bad_request', reason: 'json body required' }, 400); }
+  const id = typeof body?.id === 'string' ? resolveId(body.id) : null;
+  if (!id) return jsonResponse({ error: 'bad_request', reason: 'id must match [a-z0-9-]' }, 400);
+  const reservedId = reserved(id);
+  if (reservedId) return reservedId;
+  if (typeof body.yaml !== 'string') return jsonResponse({ error: 'bad_request', reason: 'yaml string required' }, 400);
+  const coreDir = deps.coreDir ?? defaultGraphsDir();
+  const mineDir = deps.mineDir ?? mineGraphsDir();
+  if (indexByDeclaredId(coreDir).has(id)) return jsonResponse({ error: 'core-read-only', id }, 403);
+  if (indexByDeclaredId(mineDir).has(id) || existsSync(join(mineDir, `${id}.yaml`))) return jsonResponse({ error: 'exists', id }, 409);
+  const rejected = rejectGraphYaml(body.yaml, id);
+  if (rejected) return rejected;
+  const steps = stepsOf(body.steps, body.yaml);
+  if (steps instanceof Response) return steps;
+  let version: string;
+  try {
+    version = withWizardSteps(mineDir, id, steps, () => {
+      mkdirSync(mineDir, { recursive: true });
+      writeFileSync(join(mineDir, `${id}.yaml`), body.yaml as string, { flag: 'wx' });
+      try { return recordVersion(mineDir, id, body.yaml as string); }
+      catch (error) { rmSync(join(mineDir, `${id}.yaml`), { force: true }); throw error; }
+    });
+  } catch (error) { return saveFailed(id, error); }
+  debug.log('nexus.graphs', 'saved', { id, version, created: true, steps: steps ? Object.keys(steps).length : 0 });
+  return jsonResponse({ id, source: 'mine', editable: true, saved: true, version, previous: null }, 201);
 }
 
 /** Copy core bytes into «my graphs», changing only the declared graph_id. */
@@ -198,6 +404,8 @@ export async function handleGraphsClone(pathname: string, req: Request, deps: Gr
   if (typeof body.newId !== 'string' || !GRAPH_ID.test(body.newId) || body.newId === id) {
     return jsonResponse({ error: 'bad_request', reason: 'newId must match [a-z0-9-]' }, 400);
   }
+  const reservedId = reserved(body.newId);
+  if (reservedId) return reservedId;
   const coreDir = deps.coreDir ?? defaultGraphsDir();
   const mineDir = deps.mineDir ?? mineGraphsDir();
   const source = indexByDeclaredId(coreDir).get(id) ?? indexByDeclaredId(mineDir).get(id);
@@ -215,7 +423,9 @@ export async function handleGraphsClone(pathname: string, req: Request, deps: Gr
 }
 
 export async function handleGraphsMutation(pathname: string, req: Request, deps: GraphsApiDeps = {}): Promise<Response | null> {
+  if (req.method === 'POST' && pathname === '/v1/graphs') return handleGraphsCreate(req, deps);
   if (req.method === 'PUT' && /^\/v1\/graphs\/[^/]+\/yaml$/.test(pathname)) return handleGraphsPut(pathname, req, deps);
   if (req.method === 'POST' && /^\/v1\/graphs\/[^/]+\/clone$/.test(pathname)) return handleGraphsClone(pathname, req, deps);
+  if (req.method === 'POST' && /^\/v1\/graphs\/[^/]+\/revert$/.test(pathname)) return handleGraphsRevert(pathname, req, deps);
   return null;
 }

package/src/nexus/api/harness-traversal.ts

@@ -0,0 +1,205 @@
+// HARNESS-RUN-LIVE-GRAPH (0.2.21) — one harness run's «which node, which outcome, when» for the PWA
+// live/replay graph page (`/live-run/?run=<runId>`).
+//
+// Canonical source = the run's own ledger `~/.elanous/run-ledger/<runId>.jsonl` (federated: pod ledgers synced
+// home are found through the same directories as the running-runs query):
+//   · `pipeline-node-entry` — one per node visit (node · round · graphId)
+//   · `graph-visit-budget`  — the visit count the runtime itself counted
+//   · per-node outcome events — implemented · gated · reviewed(+review-reflect) · rework-budget · pre-pr-sync ·
+//     gate.postsync · pr-opened · merge-decision
+//   · `run-status` — terminal status of the whole run
+// Durations are derived (gap to the next node entry, or to the terminal status); nothing writes a node «end».
+//
+// Node ids are never hardcoded for routing: any node the graph declares and the runtime enters (including the journey
+// nodes HARNESS-FULL-GRAPH adds — entrance, queue, author, dispatch, landing, failure side) shows up as a step. A
+// generic `pipeline-node-exit {node, outcome, detail?}` wins over the per-node heuristics below when present.
+//
+// ⛔ No goal body: the title is the first line of `start.feature`, cut to 80 chars. No artifact paths, no tokens.
+
+import { loadFederatedRunLedger, loadRunLedger, runLedgerDir, type RunLedgerEntry } from '../../self-implement/run-ledger.js';
+import { redactSecretText } from '../../debug/log.js';
+
+export interface TraversalStepWire {
+  node: string;
+  round: number | null;
+  /** `pass` · `fail` · null (still running). */
+  outcome: string | null;
+  at: string;
+  durationMs: number | null;
+  visit: number;
+  maxVisits: number | null;
+  detail: string | null;
+}
+
+export interface RunTraversalWire {
+  runId: string;
+  graphId: string | null;
+  title: string | null;
+  /** `running` until the ledger carries a terminal `run-status`. */
+  status: string;
+  stage: string | null;
+  startedAt: string | null;
+  endedAt: string | null;
+  prNumber: number | null;
+  substrate: string | null;
+  steps: TraversalStepWire[];
+  ledgerEvents: number;
+}
+
+const str = (value: unknown): string | null => typeof value === 'string' && value.trim() ? value : null;
+const num = (value: unknown): number | null => typeof value === 'number' && Number.isFinite(value) ? value : null;
+const ms = (iso: string | undefined | null): number => iso ? Date.parse(iso) : Number.NaN;
+
+const TERMINAL_FAIL = new Set(['failed', 'abandoned', 'cancelled', 'error', 'aborted', 'stopped']);
+
+/** A display title from a goal's first line: path-like tokens shrink to their basename (`a/b/c.tsx` → `c.tsx`),
+ *  then the line is redacted and cut to 80 chars. Shared with the PWA picker (`apps/pwa/src/lib/live-run-view.ts`). */
+export function displayTitle(text: string | null | undefined, max = 80): string | null {
+  const line = text?.split('\n').map((part) => part.trim()).find(Boolean) ?? '';
+  const shrunk = line.replace(/\s*\[truncated[^\]]*\]\s*$/, '').replace(/(?:~|\.{0,2})?\/?(?:[\w.@-]+\/)+([\w.@-]+)/g, '$1');
+  const cut = shrunk.length > max ? `${shrunk.slice(0, max - 1)}…` : shrunk;
+  return cut ? redactSecretText(cut) : null;
+}
+
+function titleOf(entries: readonly RunLedgerEntry[]): string | null {
+  return displayTitle(str(entries.find((entry) => entry.event === 'start')?.data.feature));
+}
+
+/** Outcome + one-line detail of a node visit, read from the events between its entry and the next entry. */
+function judgeVisit(node: string, window: readonly RunLedgerEntry[], lookback: readonly RunLedgerEntry[] = []): { outcome: 'pass' | 'fail' | null; detail: string | null } {
+  const last = (event: string) => [...window].reverse().find((entry) => entry.event === event)?.data;
+  // Some decisions are written just before the node they belong to is entered (merge-decision lands in the regate
+  // window, right before open-pr) — look back to the previous node entry for those.
+  const near = (event: string) => last(event) ?? [...lookback].reverse().find((entry) => entry.event === event)?.data;
+  const exit = [...window].reverse().find((entry) => entry.event === 'pipeline-node-exit' && entry.data.node === node)?.data;
+  const exitOutcome = str(exit?.outcome);
+  if (exitOutcome) {
+    const failed = TERMINAL_FAIL.has(exitOutcome) || exitOutcome === 'fail';
+    const exitDetail = str(exit?.detail)?.replace(/\s+/g, ' ').trim();
+    return { outcome: failed ? 'fail' : 'pass', detail: exitDetail ? redactSecretText(exitDetail.slice(0, 120)) : exitOutcome };
+  }
+  switch (node) {
+    case 'implement': {
+      const done = last('implemented');
+      if (!done) return { outcome: null, detail: null };
+      const evidence = last('off-diff-evidence');
+      const covered = num(evidence?.coveredEvidence); const required = num(evidence?.requiredEvidence);
+      const proof = covered !== null && required !== null ? ` · 증거 ${covered}/${required}` : '';
+      return done.ok === false ? { outcome: 'fail', detail: '구현 실패' } : { outcome: 'pass', detail: `구현 완료${proof}` };
+    }
+    case 'gate': {
+      const gated = last('gated');
+      if (!gated) return { outcome: null, detail: null };
+      return gated.passed === true ? { outcome: 'pass', detail: '게이트 통과' } : { outcome: 'fail', detail: '게이트 실패' };
+    }
+    case 'regate': {
+      const gated = last('gate.postsync');
+      if (!gated) return { outcome: null, detail: null };
+      return gated.passed === true ? { outcome: 'pass', detail: 'main 동기화 뒤 재게이트 통과' } : { outcome: 'fail', detail: '재게이트 실패' };
+    }
+    case 'review': {
+      const review = last('reviewed');
+      if (!review) return { outcome: null, detail: null };
+      const verdict = str(review.verdict) ?? '?';
+      const mustFix = num(review.mustFix);
+      const converged = window.some((entry) => entry.event === 'review-reflect' && entry.data.converged === true);
+      const base = `리뷰 ${verdict}${mustFix !== null ? ` · 꼭 고칠 것 ${mustFix}` : ''}`;
+      if (converged) return { outcome: 'pass', detail: `${base} · 반박 수렴` };
+      return { outcome: verdict === 'fail' ? 'fail' : 'pass', detail: base };
+    }
+    case 'rework': {
+      const budget = last('rework-budget');
+      const verdict = str(budget?.verdict);
+      return { outcome: 'pass', detail: verdict ? `재작업 예산 ${verdict}` : '재작업' };
+    }
+    case 'main-sync': {
+      const sync = last('pre-pr-sync');
+      if (!sync) return { outcome: null, detail: null };
+      const status = str(sync.status) ?? '?';
+      return { outcome: status === 'merged' || status === 'up-to-date' ? 'pass' : 'fail', detail: `main 동기화 ${status}` };
+    }
+    case 'open-pr': {
+      const opened = last('pr-opened');
+      const decision = str(near('merge-decision')?.decision);
+      if (!opened) return { outcome: null, detail: decision ? `병합 결정 ${decision}` : null };
+      const number = num(opened.number);
+      return { outcome: 'pass', detail: `PR${number !== null ? ` #${number}` : ''} 열림${decision ? ` · 병합 결정 ${decision}` : ''}` };
+    }
+    default:
+      return { outcome: null, detail: null };
+  }
+}
+
+export function buildRunTraversal(runId: string, entries: readonly RunLedgerEntry[]): RunTraversalWire {
+  const sorted = [...entries].map((entry, index) => ({ entry, index }))
+    .sort((a, b) => (ms(a.entry.timestamp) - ms(b.entry.timestamp)) || a.index - b.index).map(({ entry }) => entry);
+  const terminal = [...sorted].reverse().find((entry) => entry.event === 'run-status' && str(entry.data.runStatus));
+  const status = terminal ? str(terminal.data.runStatus)! : 'running';
+  const entryIndexes = sorted.map((entry, index) => entry.event === 'pipeline-node-entry' && str(entry.data.node) ? index : -1).filter((index) => index >= 0);
+  const visits = new Map<string, number>();
+  const steps: TraversalStepWire[] = entryIndexes.map((at, position) => {
+    const entry = sorted[at]!;
+    const node = str(entry.data.node)!;
+    const nextAt = entryIndexes[position + 1];
+    const window = sorted.slice(at + 1, nextAt ?? sorted.length);
+    const budget = [...sorted.slice(Math.max(0, at - 3), at)].reverse()
+      .find((candidate) => candidate.event === 'graph-visit-budget' && candidate.data.node === node);
+    const visit = num(budget?.data.visits) ?? (visits.get(node) ?? 0) + 1;
+    visits.set(node, visit);
+    const prevAt = position > 0 ? entryIndexes[position - 1]! : -1;
+    let { outcome, detail } = judgeVisit(node, window, sorted.slice(prevAt + 1, at));
+    const isLast = nextAt === undefined;
+    if (!isLast && outcome === null) outcome = 'pass';
+    if (isLast && terminal) outcome = TERMINAL_FAIL.has(status) ? 'fail' : (outcome ?? 'pass');
+    const endIso = nextAt !== undefined ? sorted[nextAt]!.timestamp : terminal?.timestamp;
+    const duration = ms(endIso) - ms(entry.timestamp);
+    return {
+      node,
+      round: num(entry.data.round),
+      outcome,
+      at: entry.timestamp ?? '',
+      durationMs: Number.isFinite(duration) && duration >= 0 ? duration : null,
+      visit,
+      maxVisits: num(budget?.data.maxVisits),
+      detail,
+    };
+  });
+
+  const contract = sorted.find((entry) => entry.event === 'graph-run-contract-resolved')?.data;
+  const pr = [...sorted].reverse().find((entry) => entry.event === 'pr-opened')?.data;
+  return {
+    runId,
+    graphId: str(contract?.graphId) ?? str(sorted.find((entry) => entry.event === 'pipeline-node-entry')?.data.graphId),
+    title: titleOf(sorted),
+    status,
+    stage: terminal ? str(terminal.data.stage) : null,
+    startedAt: sorted[0]?.timestamp ?? null,
+    endedAt: terminal?.timestamp ?? null,
+    prNumber: num(pr?.number),
+    substrate: str(contract?.actualSubstrate),
+    steps,
+    ledgerEvents: sorted.length,
+  };
+}
+
+export interface TraversalDeps {
+  loadLedger?: (runId: string) => RunLedgerEntry[] | null;
+}
+
+const USAGE = 'usage: GET /v1/harness/run-traversal?runId=<runId>';
+
+/** GET /v1/harness/run-traversal?runId= — ordered node steps of one harness run. */
+export function handleHarnessRunTraversalGet(req: Request, deps: TraversalDeps = {}): Response {
+  const runId = new URL(req.url).searchParams.get('runId')?.trim() ?? '';
+  if (!runId || /[\\/]|\.\./.test(runId)) return Response.json({ error: USAGE }, { status: 400 });
+  let entries: RunLedgerEntry[] | null;
+  try {
+    entries = deps.loadLedger
+      ? deps.loadLedger(runId)
+      : loadRunLedger(runId, runLedgerDir()) ?? loadFederatedRunLedger(runId);
+  } catch (error) {
+    return Response.json({ error: 'ledger-unreadable', reason: error instanceof Error ? error.message.slice(0, 200) : 'unknown' }, { status: 422 });
+  }
+  if (!entries) return Response.json({ error: 'run-not-found', runId }, { status: 404 });
+  return Response.json(buildRunTraversal(runId, entries));
+}