elanous 0.2.20 → 0.2.22

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

@@ -1,13 +1,17 @@
 import { existsSync, mkdtempSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { createHash, randomUUID, timingSafeEqual } from 'node:crypto';
 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';
+import { clearPeerEdit, peerEditRefusalBody, peerEditRunGate, readPeerEdit, writePeerEdit } from './graph-peer-edit.js';
 
 /** Declared graph ids only. A user string is never joined onto a filesystem path. */
 const GRAPH_ID = /^[a-z0-9-]+$/;
@@ -42,6 +46,93 @@ function mineGraphsDir(): string {
   return join(elanousStateRoot(), 'graphs');
 }
 
+export type GraphPermission = 'view' | 'edit';
+type GraphGrant = { recipient: string; permission: GraphPermission };
+const TOKEN_PATTERN = /^eg_[A-Za-z0-9_-]{32,}$/;
+
+function accessFile(dir: string, id: string): string {
+  return join(dir, '.access', `${id}.json`);
+}
+function tokenHash(token: string): string {
+  return createHash('sha256').update(token).digest('hex');
+}
+function accessGrants(dir: string, id: string): GraphGrant[] {
+  let text: string;
+  try { text = readFileSync(accessFile(dir, id), 'utf8'); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+  const parsed: unknown = JSON.parse(text);
+  if (!Array.isArray(parsed) || !parsed.every((entry): entry is GraphGrant => entry !== null && typeof entry === 'object'
+    && typeof entry.recipient === 'string' && /^[a-f0-9]{64}$/.test(entry.recipient)
+    && (entry.permission === 'view' || entry.permission === 'edit'))) throw new Error('invalid graph access store');
+  return parsed;
+}
+
+/** Only a hash is persisted; no owner bearer or raw recipient credential goes into a graph/YAML. */
+export function handleGraphAccess(pathname: string, req: Request, deps: GraphsApiDeps = {}): Response {
+  const match = /^\/v1\/graphs\/([^/]+)\/access$/.exec(pathname);
+  const id = match ? resolveId(match[1]!) : null;
+  if (!id) return jsonResponse({ error: 'bad_request' }, 400);
+  const owned = mineOwnership(id, deps);
+  if (owned instanceof Response) return owned;
+  if (req.method !== 'GET') return jsonResponse({ error: 'method-not-allowed' }, 405);
+  try { return jsonResponse({ grants: accessGrants(owned.mineDir, id) }); }
+  catch (error) { return saveFailed(id, error); }
+}
+
+export async function handleGraphAccessPut(pathname: string, req: Request, deps: GraphsApiDeps = {}): Promise<Response> {
+  const match = /^\/v1\/graphs\/([^/]+)\/access$/.exec(pathname);
+  const id = match ? resolveId(match[1]!) : null;
+  if (!id) return jsonResponse({ error: 'bad_request' }, 400);
+  const owned = mineOwnership(id, deps);
+  if (owned instanceof Response) return owned;
+  // Detail GET resolves a core id first; do not grant a token for a shadowed mine id.
+  if (indexByDeclaredId(deps.coreDir ?? defaultGraphsDir()).has(id)) return jsonResponse({ error: 'core-id-conflict', id }, 409);
+  let body: { recipient?: unknown; permission?: unknown };
+  try { body = await req.json() as typeof body; }
+  catch { return jsonResponse({ error: 'bad_request' }, 400); }
+  if (!body || typeof body.recipient !== 'string' || !TOKEN_PATTERN.test(body.recipient)
+    || (body.permission !== 'view' && body.permission !== 'edit')) {
+    return jsonResponse({ error: 'bad_request', reason: 'recipient access token and view/edit permission required' }, 400);
+  }
+  const recipient = tokenHash(body.recipient);
+  const dir = join(owned.mineDir, '.access');
+  try {
+    const grants = accessGrants(owned.mineDir, id).filter((grant) => grant.recipient !== recipient);
+    grants.push({ recipient, permission: body.permission });
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const target = accessFile(owned.mineDir, id);
+    const temp = `${target}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+      writeFileSync(temp, JSON.stringify(grants), { mode: 0o600 });
+      renameSync(temp, target);
+    } finally { rmSync(temp, { force: true }); }
+  } catch (error) { return saveFailed(id, error); }
+  return jsonResponse({ recipient, permission: body.permission });
+}
+
+/** The peer token works only on this graph and the requested read/edit operation. */
+export function graphAccessForRequest(pathname: string, method: string, token: string | null, deps: GraphsApiDeps = {}): boolean {
+  const match = /^\/v1\/graphs\/([^/]+)(?:\/(yaml))?$/.exec(pathname);
+  const id = match ? resolveId(match[1]!) : null;
+  if (!id || !token || !TOKEN_PATTERN.test(token)) return false;
+  if (method !== 'GET' && !(method === 'PUT' && match?.[2] === 'yaml')) return false;
+  try {
+    if (!indexByDeclaredId(deps.mineDir ?? mineGraphsDir()).has(id)) return false;
+    if (indexByDeclaredId(deps.coreDir ?? defaultGraphsDir()).has(id)) return false;
+    const wanted = tokenHash(token);
+    return accessGrants(deps.mineDir ?? mineGraphsDir(), id).some((grant) => {
+      const stored = Buffer.from(grant.recipient, 'hex');
+      return timingSafeEqual(stored, Buffer.from(wanted, 'hex')) && (method === 'GET' || grant.permission === 'edit');
+    });
+  } catch (error) {
+    debug.log('nexus.graphs', 'access-read-failed', { id, reason: String(error) }, { level: 'warn' });
+    return false;
+  }
+}
+
 function resolveId(raw: string): string | null {
   let id: string;
   try { id = decodeURIComponent(raw); }
@@ -109,7 +200,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 }),
@@ -178,7 +274,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);
@@ -195,7 +292,10 @@ export function handleGraphsGet(pathname: string, dir = defaultGraphsDir(), deps
 }
 
 /** PUT writes only under the state-root graphs directory. Core YAML is never opened for write. */
-export async function handleGraphsPut(pathname: string, req: Request, deps: GraphsApiDeps = {}): Promise<Response> {
+/** Who authorized a save: the owner, or a peer token holding an «edit» grant (raw token; only a hash prefix is kept). */
+export type GraphSaveActor = { peerToken: string } | null;
+
+export async function handleGraphsPut(pathname: string, req: Request, deps: GraphsApiDeps = {}, actor: GraphSaveActor = null): Promise<Response> {
   const match = /^\/v1\/graphs\/([^/]+)\/yaml$/.exec(pathname);
   if (!match) return jsonResponse({ error: 'not-found' }, 404);
   const id = resolveId(match[1]!);
@@ -209,18 +309,33 @@ 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 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)!;
   // 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);
-  const { version, previous } = writeWithVersion(mineDir, id, existing, body.yaml);
-  debug.log('nexus.graphs', 'saved', { id, version, previous });
-  return jsonResponse({ id, source: 'mine', editable: true, saved: true, version, previous });
+  let written: { version: string; previous: string };
+  const editedBy = actor ? `peer:${tokenHash(actor.peerToken).slice(0, 8)}` : null;
+  try {
+    written = withWizardSteps(mineDir, id, steps, () => {
+      // Peer save: the marker goes down «before» the bytes, so a crash in between still refuses the run.
+      if (editedBy) writePeerEdit(mineDir, id, { editedBy, version: 'pending', at: new Date().toISOString() });
+      const result = writeWithVersion(mineDir, id, existing, body.yaml as string);
+      if (editedBy) writePeerEdit(mineDir, id, { editedBy, version: result.version, at: new Date().toISOString() });
+      else clearPeerEdit(mineDir, id);
+      return result;
+    });
+  }
+  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, ...(editedBy ? { editedBy } : {}) });
+  return jsonResponse({ id, source: 'mine', editable: true, saved: true, version, previous, ...(editedBy ? { editedBy } : {}) });
 }
 
 const VERSION_ID = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z(?:-\d{4})?$/;
@@ -331,10 +446,27 @@ export async function handleGraphsRevert(pathname: string, req: Request, deps: G
   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 };
-  try { body = await req.json() as { id?: unknown; yaml?: unknown }; }
+  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);
@@ -347,10 +479,18 @@ export async function handleGraphsCreate(req: Request, deps: GraphsApiDeps = {})
   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;
-  mkdirSync(mineDir, { recursive: true });
-  writeFileSync(join(mineDir, `${id}.yaml`), body.yaml, { flag: 'wx' });
-  const version = recordVersion(mineDir, id, body.yaml);
-  debug.log('nexus.graphs', 'saved', { id, version, created: true });
+  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);
 }
 
@@ -370,8 +510,14 @@ export async function handleGraphsClone(pathname: string, req: Request, deps: Gr
   if (reservedId) return reservedId;
   const coreDir = deps.coreDir ?? defaultGraphsDir();
   const mineDir = deps.mineDir ?? mineGraphsDir();
-  const source = indexByDeclaredId(coreDir).get(id) ?? indexByDeclaredId(mineDir).get(id);
+  const fromCore = indexByDeclaredId(coreDir).get(id);
+  const source = fromCore ?? indexByDeclaredId(mineDir).get(id);
   if (!source) return jsonResponse({ error: 'not-found', id }, 404);
+  // A clone would carry a peer's unapproved change into a graph with no marker — approve first.
+  if (!fromCore) {
+    const gate = peerEditRunGate(mineDir, id);
+    if (!gate.ok) return jsonResponse(peerEditRefusalBody(id, gate), 409);
+  }
   if (indexByDeclaredId(mineDir).has(body.newId) || indexByDeclaredId(coreDir).has(body.newId)) {
     return jsonResponse({ error: 'conflict', id: body.newId }, 409);
   }
@@ -384,9 +530,39 @@ export async function handleGraphsClone(pathname: string, req: Request, deps: Gr
   return jsonResponse({ id: body.newId, source: 'mine', editable: true, clonedFrom: id }, 201);
 }
 
-export async function handleGraphsMutation(pathname: string, req: Request, deps: GraphsApiDeps = {}): Promise<Response | null> {
+/** POST /v1/graphs/<id>/approve {version} — owner only (the route never accepts a peer token). Approves the
+ *  exact peer version the run refusal named; a newer peer save is a new version and needs a new approval. */
+export async function handleGraphsApprove(pathname: string, req: Request, deps: GraphsApiDeps = {}): Promise<Response> {
+  const match = /^\/v1\/graphs\/([^/]+)\/approve$/.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;
+  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' || !body.version) return jsonResponse({ error: 'bad_request', reason: 'version string required' }, 400);
+  let record;
+  try { record = readPeerEdit(owned.mineDir, id); }
+  catch (error) { return saveFailed(id, error); }
+  if (!record) return jsonResponse({ id, approved: true, version: body.version, pending: false });
+  if (record.version !== body.version) {
+    return jsonResponse({ error: 'version-mismatch', id, version: record.version, reason: '승인하려는 판이 최신 상대 변경과 다르다 — 다시 확인하라' }, 409);
+  }
+  const approved = { version: record.version, at: new Date().toISOString() };
+  try { writePeerEdit(owned.mineDir, id, { ...record, approved }); }
+  catch (error) { return saveFailed(id, error); }
+  debug.log('nexus.graphs', 'peer-edit-approved', { id, version: record.version, editedBy: record.editedBy });
+  return jsonResponse({ id, approved: true, version: record.version, editedBy: record.editedBy });
+}
+
+export async function handleGraphsMutation(pathname: string, req: Request, deps: GraphsApiDeps = {}, actor: GraphSaveActor = null): Promise<Response | null> {
+  // Only PUT …/yaml is open to a peer token; every other mutation is the owner's alone.
+  if (actor && !(req.method === 'PUT' && /^\/v1\/graphs\/[^/]+\/yaml$/.test(pathname))) return jsonResponse({ error: 'unauthorized' }, 401);
   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 === 'PUT' && /^\/v1\/graphs\/[^/]+\/yaml$/.test(pathname)) return handleGraphsPut(pathname, req, deps, actor);
+  if (req.method === 'POST' && /^\/v1\/graphs\/[^/]+\/approve$/.test(pathname)) return handleGraphsApprove(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));
+}