elanous 0.2.20 → 0.2.21

package/src/nexus/api/draft-metrics.ts

@@ -0,0 +1,114 @@
+import { join } from 'node:path';
+import { debug } from '../../debug/log.js';
+import type { DraftMetrics } from '../../self-dev/draft-sweep.js';
+
+/**
+ * DRAFT-METRIC — CEO view source. Opening the page must never trigger a GitHub read:
+ * `read()` answers from memory and at most one background collection runs at a time,
+ * no more often than the TTL (or the failure back-off). The collection itself is
+ * `elanous harness drafts metrics --json` in a child process, which reads PR evidence
+ * through the batched GraphQL path (#24918) — one call per 40 drafts, no per-draft comments call.
+ */
+export type DraftMetricsState = 'measuring' | 'ready' | 'unavailable';
+
+export interface DraftMetricsSnapshot {
+  /** measuring = no value yet and a collection is running · unavailable = no value and the last collection failed. */
+  readonly state: DraftMetricsState;
+  readonly metrics: DraftMetrics | null;
+  /** When the served value was collected (ISO). null without a value. */
+  readonly measuredAt: string | null;
+  /** A background collection is in flight. */
+  readonly refreshing: boolean;
+  /** Last collection failure; with a value it means the value is older than intended. */
+  readonly reason: string | null;
+}
+
+export interface DraftMetricsSourceOptions {
+  readonly collect?: () => Promise<DraftMetrics>;
+  readonly ttlMs?: number;
+  readonly failureRetryMs?: number;
+  readonly now?: () => number;
+}
+
+export const DRAFT_METRICS_TTL_MS = 10 * 60_000;
+export const DRAFT_METRICS_FAILURE_RETRY_MS = 2 * 60_000;
+const COLLECT_TIMEOUT_MS = 5 * 60_000;
+
+function isMetrics(value: unknown): value is DraftMetrics {
+  if (!value || typeof value !== 'object') return false;
+  const row = value as Record<string, unknown>;
+  const count = (key: string) => Number.isInteger(row[key]) && (row[key] as number) >= 0;
+  const nullableNumber = (key: string) => row[key] === null || (typeof row[key] === 'number' && Number.isFinite(row[key]));
+  return count('inventory') && count('needsOwner') && count('converted48h') && count('cohort48h')
+    && nullableNumber('oldestAgeHours') && nullableNumber('conversion48h');
+}
+
+/** Parses the CLI's single JSON line; anything else is a failed collection, never a zero. */
+export function parseDraftMetricsOutput(stdout: string): DraftMetrics {
+  const line = stdout.trim().split('\n').reverse().find((text) => text.trim().startsWith('{'));
+  if (!line) throw new Error('draft metrics: no JSON output');
+  const parsed: unknown = JSON.parse(line);
+  if (!isMetrics(parsed)) throw new Error('draft metrics: malformed output');
+  const { inventory, oldestAgeHours, needsOwner, converted48h, cohort48h, conversion48h } = parsed;
+  return { inventory, oldestAgeHours, needsOwner, converted48h, cohort48h, conversion48h };
+}
+
+async function collectViaCli(): Promise<DraftMetrics> {
+  const root = join(import.meta.dir, '../../..');
+  const proc = Bun.spawn(['bun', join(root, 'bin/elanous.mjs'), 'harness', 'drafts', 'metrics', '--json'], {
+    cwd: root, stdout: 'pipe', stderr: 'pipe',
+  });
+  const timer = setTimeout(() => proc.kill(), COLLECT_TIMEOUT_MS);
+  try {
+    const [stdout, stderr, exitCode] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited]);
+    if (exitCode !== 0) throw new Error(stderr.trim().split('\n').at(-1) || `draft metrics exited ${exitCode}`);
+    return parseDraftMetricsOutput(stdout);
+  } finally { clearTimeout(timer); }
+}
+
+export interface DraftMetricsSource {
+  read(): DraftMetricsSnapshot;
+}
+
+export function createDraftMetricsSource(options: DraftMetricsSourceOptions = {}): DraftMetricsSource {
+  const collect = options.collect ?? collectViaCli;
+  const ttl = options.ttlMs ?? DRAFT_METRICS_TTL_MS;
+  const retry = options.failureRetryMs ?? DRAFT_METRICS_FAILURE_RETRY_MS;
+  const now = options.now ?? Date.now;
+  let value: { metrics: DraftMetrics; at: number } | null = null;
+  let failure: { reason: string; at: number } | null = null;
+  let inFlight: Promise<void> | null = null;
+
+  const refresh = (): void => {
+    if (inFlight) return;
+    const started = now();
+    inFlight = (async () => {
+      try {
+        const metrics = await collect();
+        value = { metrics, at: now() };
+        failure = null;
+        try { debug.log('nexus.draft-metrics', 'collected', { ms: now() - started, inventory: metrics.inventory }); } catch { /* fail-soft */ }
+      } catch (error) {
+        failure = { reason: error instanceof Error ? error.message : String(error), at: now() };
+        try { debug.log('nexus.draft-metrics', 'failed', { ms: now() - started, reason: failure.reason }); } catch { /* fail-soft */ }
+      } finally { inFlight = null; }
+    })();
+  };
+
+  return {
+    read() {
+      const clock = now();
+      const due = failure && (!value || failure.at >= value.at)
+        ? clock - failure.at >= retry
+        : !value || clock - value.at >= ttl;
+      if (due) refresh();
+      return {
+        state: value ? 'ready' : failure && !inFlight ? 'unavailable' : 'measuring',
+        metrics: value?.metrics ?? null,
+        measuredAt: value ? new Date(value.at).toISOString() : null,
+        refreshing: inFlight !== null,
+        reason: failure?.reason ?? null,
+      };
+    },
+  };
+}

package/src/nexus/api/graph-wizard-api.ts

@@ -0,0 +1,53 @@
+import { debug } from '../../debug/log.js';
+import { GraphWizardInputError, generateGraphFromPrompt, type GraphWizardDeps, type GraphWizardTurn } from '../../graph-wizard/generate.js';
+import { jsonResponse } from './json-response.js';
+
+const MAX_PROMPT = 4000;
+const MAX_YAML = 200_000;
+
+/**
+ * POST /v1/graphs/wizard {prompt, kind?, currentYaml?, history?}
+ * → 200 {ok:true, id, yaml, base, baseReason, issues:[], attempts, summary, labels, steps, recipes, dryRun} · 422 {ok:false, …} · 400 빈 prompt.
+ * (labels·steps·recipes·dryRun·baseReason 는 v2 추가 필드 — 기존 필드는 그대로.)
+ * currentYaml 이 빈 문자열이면 «빈 캔버스»로 보고 새 그래프를 짓는다(의도) · 내용이 있는데 id 가 없거나 형식 밖이면 400.
+ * 저장하지 않는다 — 저장은 POST /v1/graphs(새 그래프) 또는 PUT /v1/graphs/<id>/yaml(내 그래프).
+ */
+export async function handleGraphWizardPost(req: Request, deps: GraphWizardDeps = {}): Promise<Response> {
+  let body: Record<string, unknown>;
+  try {
+    const parsed: unknown = await req.json();
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('object');
+    body = parsed as Record<string, unknown>;
+  } catch { return jsonResponse({ error: 'bad_request', reason: 'json body required' }, 400); }
+  const prompt = typeof body.prompt === 'string' ? body.prompt.trim() : '';
+  if (!prompt) return jsonResponse({ error: 'bad_request', reason: 'prompt required' }, 400);
+  if (prompt.length > MAX_PROMPT) return jsonResponse({ error: 'bad_request', reason: `prompt longer than ${MAX_PROMPT}` }, 400);
+  if (body.kind !== undefined && body.kind !== 'harness' && body.kind !== 'workflow') {
+    return jsonResponse({ error: 'bad_request', reason: 'kind must be harness or workflow' }, 400);
+  }
+  if (body.currentYaml !== undefined && (typeof body.currentYaml !== 'string' || body.currentYaml.length > MAX_YAML)) {
+    return jsonResponse({ error: 'bad_request', reason: 'currentYaml must be a string' }, 400);
+  }
+  let history: GraphWizardTurn[] | undefined;
+  if (body.history !== undefined) {
+    if (!Array.isArray(body.history) || !body.history.every((t) => t && typeof t === 'object' &&
+      ((t as GraphWizardTurn).role === 'user' || (t as GraphWizardTurn).role === 'assistant') && typeof (t as GraphWizardTurn).text === 'string')) {
+      return jsonResponse({ error: 'bad_request', reason: 'history must be [{role, text}]' }, 400);
+    }
+    history = body.history as GraphWizardTurn[];
+  }
+  try {
+    const result = await generateGraphFromPrompt({
+      prompt,
+      ...(body.kind ? { kind: body.kind as 'harness' | 'workflow' } : {}),
+      ...(typeof body.currentYaml === 'string' && body.currentYaml.trim() ? { currentYaml: body.currentYaml } : {}),
+      ...(history ? { history } : {}),
+    }, deps);
+    return jsonResponse({ ...result, base: result.base ?? null }, result.ok ? 200 : 422);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (error instanceof GraphWizardInputError) return jsonResponse({ error: 'bad_request', reason: message }, 400);
+    debug.log('graph.wizard', 'error', { message });
+    return jsonResponse({ error: 'wizard-failed', reason: message }, 502);
+  }
+}

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

@@ -7,6 +7,8 @@ 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. */
@@ -109,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 }),
@@ -178,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);
@@ -209,17 +217,22 @@ 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 });
+  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 });
 }
 
@@ -331,10 +344,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 +377,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);
 }
 

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));
+}

package/src/nexus/api/http-server.ts

@@ -23,6 +23,7 @@ import { isAbsolute } from 'node:path';
 import { createProject, listProjects } from '../../project/project-store.js';
 import { handleOutputsGet, type OutputsDeps } from './outputs-route.js';
 import { buildGridData, type GridDeps } from './grid.js';
+import { createDraftMetricsSource, type DraftMetricsSource } from './draft-metrics.js';
 import { DECISIONS_PATH, handleDecisions, type DecisionsRouteDeps } from './decisions-route.js';
 import { OPS_BOARD_PATH, handleOpsBoard, type OpsBoardDeps } from './ops-board-route.js';
 import { CARD_FOLLOWUP_PATH, createCardFollowupJobs, type CardFollowupJobs } from './card-followup-route.js';
@@ -31,6 +32,7 @@ import { compareTokenConstTime } from '../../acp/transport/auth.js';
 import { ensureAuthToken } from '../../auth/acp-token.js';
 import type { NexusState } from '../state/state.js';
 import { DEFAULT_NEXUS_HTTP_PORT } from '../default-port.js';
+
 export { DEFAULT_NEXUS_HTTP_PORT } from '../default-port.js';
 import type { TabRegistry } from '../state/tab-registry.js';
 import type { FeedbackEnvelope } from '../../feedback/envelope.js';
@@ -164,6 +166,7 @@ import {
 } from './vault-api.js';
 import { handleBuildsGet, parseBuildsPath } from './builds-api.js';
 import { handleHarnessAskPost, handleHarnessAskStatusGet, handleHarnessRunEventsGet, handleHarnessRunScreenGet, handleHarnessRunsGet, handleHarnessStopPost } from './harness-api.js';
+import { handleHarnessRunTraversalGet } from './harness-traversal.js';
 import { handleLoopEdgesGet } from './loop-edges.js';
 import { handleFabricPlans, type FabricPlansRouteOpts } from './fabric-plans.js';
 import { dispatchPersonaRoute } from './personas.js';
@@ -367,6 +370,7 @@ import { handleTriggersSnapshot } from './triggers.js';
 import { handleWorkflowTemplatesList } from './workflow-templates.js';
 import { handleGraphVersionsGet, handleGraphsGet, handleGraphsMutation } from './graphs-api.js';
 import { handleGraphKindsGet, handleGraphsValidatePost } from './graph-kinds.js';
+import { handleGraphWizardPost } from './graph-wizard-api.js';
 import { syncInstalledPluginNodes } from '../../graph-kinds/installed-plugin-nodes.js';
 import { elanousStateRoot } from '../../autopilot/state-paths.js';
 import { handlePluginsIndexGet, handlePluginsGet, handlePluginsMarketRefresh, handlePluginsInstall, handlePluginsRemove } from './plugins-market.js';
@@ -426,6 +430,9 @@ import {
   parseShowroomLayoutPath,
 } from './showroom-layouts.js';
 
+/** Process-wide DRAFT-METRIC cache (one background collection per TTL, shared by every page load). */
+let sharedDraftMetrics: DraftMetricsSource | undefined;
+
 export const NEXUS_HTTP_PORT_RANGE = 16;     // try 31415..31430
 /** Short timeout for the pre-bind localhost occupancy probe. */
 export const NEXUS_PORT_PROBE_TIMEOUT_MS = 400;
@@ -480,11 +487,15 @@ export type NexusWsBridgeInit = Omit<WsBridgeOpts, 'hostname' | 'port'>;
 export interface NexusHttpServerOpts {
   /** Optional fabric-plan ledger and decomposition seam; production uses the instance root and existing fabric decomposer. */
   fabricPlans?: FabricPlansRouteOpts;
+  /** GRAPH-WIZARD 시험 주입(LLM·템플릿 뿌리). 운영은 비워 둔다. */
+  graphWizard?: import('../../graph-wizard/generate.js').GraphWizardDeps;
   /** Optional installer state root for isolated API consumers and tests. */
   pluginStateRoot?: string;
   outputs?: OutputsDeps;
   /** Read-only grid measurement seam; omitted in production for live HQ and Pod pool reads. */
   grid?: GridDeps;
+  /** DRAFT-METRIC cached source seam; omitted in production for the process-wide TTL cache. */
+  draftMetrics?: DraftMetricsSource;
   decisions?: Pick<DecisionsRouteDeps, 'ledger'>;
   opsBoard?: Pick<OpsBoardDeps, 'openStore'>;
   cardFollowup?: CardFollowupJobs;
@@ -1360,6 +1371,13 @@ export async function routeRequest(
     return handleHarnessRunEventsGet(req, opts.metaApi);
   }
 
+  // HARNESS-RUN-LIVE-GRAPH — one run's ordered node steps ⊕ journey band (PWA /live-run).
+  if (pathname === '/v1/harness/run-traversal' && method === 'GET') {
+    if (!opts.metaApi) return jsonResponse({ error: 'meta-api-runtime-not-wired' }, 503);
+    if (!checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
+    return handleHarnessRunTraversalGet(req);
+  }
+
   // Design direction is a write: check owner auth before the handler reads the body.
   // Keep this POST ahead of the mutation fallback, and never make it a public route.
   if (method === 'POST' && pathname === DESIGN_DIRECTION_PATH) {
@@ -1389,6 +1407,13 @@ export async function routeRequest(
     return handleGraphsValidatePost(req, opts.metaApi);
   }
 
+  // GRAPH-WIZARD — 말 → 그래프 YAML(저장 안 함). 다른 /v1/graphs 쓰기와 같은 인증.
+  if (method === 'POST' && pathname === '/v1/graphs/wizard') {
+    if (!opts.metaApi) return jsonResponse({ error: 'meta-api-not-wired' }, 503);
+    if (!checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
+    return handleGraphWizardPost(req, opts.graphWizard);
+  }
+
   if (pathname === '/v1/fabric/decompose' || pathname.startsWith('/v1/fabric/plans/')) {
     if (!opts.metaApi || !checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
     return handleFabricPlans(req, opts.fabricPlans);
@@ -1437,6 +1462,12 @@ export async function routeRequest(
     if (method !== 'GET') return jsonResponse({ error: 'method-not-allowed', method }, 405);
     return jsonResponse(buildGridData(opts.grid));
   }
+  // DRAFT-METRIC: answers from memory; a stale/cold cache starts one background collection (never per request).
+  if (pathname === '/v1/drafts/metrics') {
+    if (!opts.metaApi || !checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
+    if (method !== 'GET') return jsonResponse({ error: 'method-not-allowed', method }, 405);
+    return jsonResponse((opts.draftMetrics ?? (sharedDraftMetrics ??= createDraftMetricsSource())).read());
+  }
   if (method === 'GET' && pathname === '/v1/outputs') {
     if (!opts.metaApi || !checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
     return handleOutputsGet(req, opts.outputs);