@worca/app 1.0.0 → 1.1.1

package/src/shared/graph/geometry.mjs

@@ -0,0 +1,157 @@
+// src/shared/graph/geometry.mjs
+// THE geometry: card sizing, port anchors and model-driven card/port hit tests.
+// Wire SHAPE lives in route.mjs (the orthogonal router), which imports
+// WIRE_HIT_TOL from here. Framework-free and DOM-free so the whole render path
+// derives from the
+// model's x/y — zero getBoundingClientRect on the pointer path, and every claim
+// is unit-testable without jsdom. style.css consumes these numbers ONLY through
+// the --gv-* custom properties injectGeometry writes, so the CSS box model can
+// never drift from nodeSize.
+export const NODE_W = 220;
+export const HEAD_H = 34;
+export const ROW_H = 24;
+export const SEP_H = 9;
+export const PAD_T = 8.5;
+export const PAD_B = 8;
+export const BORDER = 1.5;
+export const DOT = 10;
+export const FOOT_H = 26;
+export const EXEC_ROW_H = 22;
+/** Sub-agent fan squares per wrapped line. The squares are 7px + 3px gap, so a
+ *  full line is 16·10 − 3 = 157px (--gv-fan-w), leaving the ×N tail its column. */
+export const FAN_PER_ROW = 16;
+export const FAN_ROW_W = FAN_PER_ROW * 10 - 3;
+export const SNAP = 11;
+export const PORT_HIT_R = 14;
+export const WIRE_HIT_TOL = 6;
+export const ZOOM_MIN = 0.4;
+export const ZOOM_MAX = 1.6;
+export const ZOOM_K = 0.002;
+/** First row centre from the top of the card: 1.5 + 34 + 8.5 + 12. */
+export const ROW0 = BORDER + HEAD_H + PAD_T + ROW_H / 2;
+
+/** Every CSS-visible number, as the custom properties style.css reads. */
+export const GEOMETRY_CSS_VARS = Object.freeze({
+  '--gv-node-w': `${NODE_W}px`, '--gv-head-h': `${HEAD_H}px`, '--gv-row-h': `${ROW_H}px`,
+  '--gv-sep-h': `${SEP_H}px`, '--gv-pad-t': `${PAD_T}px`, '--gv-pad-b': `${PAD_B}px`,
+  '--gv-border': `${BORDER}px`, '--gv-dot': `${DOT}px`, '--gv-foot-h': `${FOOT_H}px`,
+  '--gv-exec-row-h': `${EXEC_ROW_H}px`, '--gv-fan-w': `${FAN_ROW_W}px`,
+});
+
+/** Write the variables onto a host element at mount. Guarded: jsdom hosts and a
+ *  missing element are both fine (the caller is a renderer, not a validator). */
+export function injectGeometry(el) {
+  if (!el || !el.style || typeof el.style.setProperty !== 'function') return;
+  for (const [name, value] of Object.entries(GEOMETRY_CSS_VARS)) el.style.setProperty(name, value);
+}
+
+const CAPTION_SET = new Set(['task', 'end', 'or']);
+const metaInputs = (ports) => (Array.isArray(ports?.inputs) ? ports.inputs : []).filter((p) => !p?.synthetic);
+const hasAwaitRow = (ports) => (Array.isArray(ports?.inputs) ? ports.inputs : []).some((p) => p?.synthetic);
+const outs = (ports) => (Array.isArray(ports?.outputs) ? ports.outputs : []);
+
+/** Zones top to bottom: inputs -> outputs -> await gate (agents) -> caption
+ *  (task/end/or). A zone is emitted only when NON-EMPTY and a separator sits
+ *  only BETWEEN emitted zones — that is what reproduces the closed forms and
+ *  degrades sanely on a 0-input card. */
+function zones(node, ports) {
+  const z = [];
+  const ins = metaInputs(ports).length;
+  if (ins) z.push({ kind: 'in', n: ins });
+  if (outs(ports).length) z.push({ kind: 'out', n: outs(ports).length });
+  if (hasAwaitRow(ports)) z.push({ kind: 'await', n: 1 });
+  if (CAPTION_SET.has(node?.kind)) z.push({ kind: 'cap', n: 1 });
+  return z;
+}
+
+/** y offset of a zone's FIRST row centre, or null when the zone is not emitted. */
+function zoneTop(node, ports, kind) {
+  let y = ROW0;
+  for (const z of zones(node, ports)) {
+    if (z.kind === kind) return y;
+    y += z.n * ROW_H + SEP_H;
+  }
+  return null;
+}
+
+/** Wrapped lines a fan of `n` squares occupies (the leds are pre-capped upstream). */
+export function fanLines(n) {
+  return Math.max(1, Math.ceil((Number(n) || 0) / FAN_PER_ROW));
+}
+
+/**
+ * @param {{kind:string}} node
+ * @param {{inputs:Array, outputs:Array}} ports  RESOLVED ports (await included for agents)
+ * @param {{footerRows?:number}} [opts]  footer LINES: 0 none · 1 collapsed executions
+ *   strip · more for extra lines (a wrapped fan line, a stacked exec row's extra
+ *   lines). The first line is FOOT_H tall, every further one EXEC_ROW_H.
+ */
+export function nodeSize(node, ports, { footerRows = 0 } = {}) {
+  const zs = zones(node, ports);
+  const rows = zs.reduce((s, z) => s + z.n, 0);
+  const seps = Math.max(0, zs.length - 1);
+  const footer = footerRows ? FOOT_H + (footerRows - 1) * EXEC_ROW_H : 0;
+  return { w: NODE_W, h: 2 * BORDER + HEAD_H + PAD_T + rows * ROW_H + seps * SEP_H + PAD_B + footer };
+}
+
+/** Inputs and the await gate anchor on the LEFT edge, outputs on the RIGHT.
+ *  The footer is the bottom-most box, so no anchor depends on it. */
+export function portAnchor(node, ports, portId, dir) {
+  if (dir === 'in' && portId === 'await' && hasAwaitRow(ports)) {
+    return { x: node.x, y: node.y + zoneTop(node, ports, 'await') };
+  }
+  if (dir === 'in') {
+    const i = metaInputs(ports).findIndex((p) => p?.id === portId);
+    const top = zoneTop(node, ports, 'in');
+    return i < 0 || top === null ? null : { x: node.x, y: node.y + top + ROW_H * i };
+  }
+  const j = outs(ports).findIndex((p) => p?.id === portId);
+  const top = zoneTop(node, ports, 'out');
+  return j < 0 || top === null ? null : { x: node.x + NODE_W, y: node.y + top + ROW_H * j };
+}
+
+const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+
+/** Snap to the 11px half-grid (the 22px dot grid's half step). DRAG only —
+ *  loaded templates render at their authored positions, unsnapped. */
+export function snap(value, grid = SNAP) {
+  return Math.round(value / grid) * grid;
+}
+
+export function hitNode(node, size, pt) {
+  return pt.x >= node.x && pt.x <= node.x + size.w && pt.y >= node.y && pt.y <= node.y + size.h;
+}
+
+export function hitPort(anchor, pt, r = PORT_HIT_R) {
+  return Math.hypot(pt.x - anchor.x, pt.y - anchor.y) <= r;
+}
+
+/** The union of the card boxes, optionally padded. `footerRowsOf(node)` lets the
+ *  run monitor fit an expanded executions footer. null when there is nothing. */
+export function graphBounds(tpl, portsFn, { pad = 0, footerRowsOf } = {}) {
+  // OBJECTS only: `filter(Boolean)` kept a truthy non-object (`7`), sized it as a
+  // card at the origin and stretched the bounds of every fit built from it.
+  const nodes = (Array.isArray(tpl?.nodes) ? tpl.nodes : [])
+    .filter((n) => Boolean(n) && typeof n === 'object' && !Array.isArray(n));
+  if (!nodes.length) return null;
+  let minX = Infinity; let minY = Infinity; let maxX = -Infinity; let maxY = -Infinity;
+  for (const node of nodes) {
+    const ports = (typeof portsFn === 'function' ? portsFn(node) : null) || { inputs: [], outputs: [] };
+    const size = nodeSize(node, ports, { footerRows: footerRowsOf ? footerRowsOf(node) : 0 });
+    const x = Number(node.x) || 0;
+    const y = Number(node.y) || 0;
+    minX = Math.min(minX, x); minY = Math.min(minY, y);
+    maxX = Math.max(maxX, x + size.w); maxY = Math.max(maxY, y + size.h);
+  }
+  return { x: minX - pad, y: minY - pad, w: maxX - minX + 2 * pad, h: maxY - minY + 2 * pad };
+}
+
+/** Fit `bounds` into a viewport: `screen = world·z + t`. zoomMax defaults to 1 —
+ *  auto-fit NEVER magnifies past 1x (spec §7.6). */
+export function fitBounds(bounds, viewport, { zoomMin = ZOOM_MIN, zoomMax = 1 } = {}) {
+  const width = Number(viewport?.width) || 0;
+  const height = Number(viewport?.height) || 0;
+  if (!bounds || !(bounds.w > 0) || !(bounds.h > 0) || width <= 0 || height <= 0) return { z: 1, tx: 0, ty: 0 };
+  const z = clamp(Math.min(width / bounds.w, height / bounds.h), zoomMin, zoomMax);
+  return { z, tx: (width - bounds.w * z) / 2 - bounds.x * z, ty: (height - bounds.h * z) / 2 - bounds.y * z };
+}

package/src/shared/graph/layout.mjs

@@ -0,0 +1,134 @@
+// src/shared/graph/layout.mjs
+// Auto-layout for the composer's header button: longest-path ranks with LOOP
+// WIRES EXCLUDED, columns at x = 60 + rank*320, barycenter ordering inside each
+// column, y stacked so no two cards touch and snapped to the 11px grid.
+// Deterministic by construction — same template in, same positions out, and
+// re-running over an already laid-out template reproduces it exactly.
+import { classifyLoops } from './loops.mjs';
+import { nodeSize, snap } from './geometry.mjs';
+
+export const RANK_X0 = 60;
+export const RANK_DX = 320;                // 100px column gap: two 24px clearance bands + laned verticals
+export const RANK_Y0 = 60;
+export const ROW_GAP = 64;                 // > 2×ROUTE_CLEARANCE so a wire corridor survives between stacked cards
+const SWEEPS = 2;
+
+/** A layoutable node: an object with a string id. `filter(Boolean)` let a truthy
+ *  non-object through and indexed an id-less node under `undefined`, so a wire
+ *  with a missing endpoint resolved through it and threw. */
+const isNode = (n) => Boolean(n) && typeof n === 'object' && !Array.isArray(n) && typeof n.id === 'string';
+
+/** @param {object} tpl @param {{loopWireIds:Set<string>}} loops classifyLoops() output */
+export function rankNodes(tpl, loops) {
+  const nodes = (Array.isArray(tpl?.nodes) ? tpl.nodes : []).filter(isNode);
+  const ids = new Set(nodes.map((n) => n.id));
+  const edges = nonLoopEdges(tpl, loops, ids);
+
+  const rank = {};
+  const indegree = {};
+  for (const id of ids) { rank[id] = 0; indegree[id] = 0; }
+  const out = new Map();
+  for (const e of edges) {
+    if (!out.has(e.from)) out.set(e.from, []);
+    out.get(e.from).push(e.to);
+    indegree[e.to] += 1;
+  }
+  // Kahn with a SORTED frontier: ties break by node id, so the walk order — and
+  // therefore the result — never depends on declaration order.
+  const ready = [...ids].filter((id) => indegree[id] === 0).sort();
+  const settled = new Set();
+  while (ready.length) {
+    const id = ready.shift();
+    settled.add(id);
+    for (const next of out.get(id) || []) {
+      rank[next] = Math.max(rank[next], rank[id] + 1);
+      indegree[next] -= 1;
+      if (indegree[next] === 0) insertSorted(ready, next);
+    }
+  }
+  // A residual cycle survives only when no loop wire cuts it (V10 blocks SAVING
+  // such a graph, but the editor still has to draw it). Rank the leftovers from
+  // whatever settled feeds them, in id order — bounded, never a hang.
+  for (const id of [...ids].filter((n) => !settled.has(n)).sort()) {
+    rank[id] = edges.filter((e) => e.to === id && settled.has(e.from))
+      .reduce((best, e) => Math.max(best, rank[e.from] + 1), 0);
+    settled.add(id);
+  }
+  return rank;
+}
+
+/** @returns {{[nodeId:string]: {x:number, y:number}}} — the caller applies them. */
+export function autoLayout(tpl, portsFn, { x0 = RANK_X0, dx = RANK_DX, y0 = RANK_Y0, gap = ROW_GAP } = {}) {
+  const nodes = (Array.isArray(tpl?.nodes) ? tpl.nodes : []).filter(isNode);
+  const loops = classifyLoops(tpl, portsFn);
+  const rank = rankNodes(tpl, loops);
+  const ids = new Set(nodes.map((n) => n.id));
+  const edges = nonLoopEdges(tpl, loops, ids);
+
+  const columns = new Map();
+  for (const n of nodes) {
+    if (!columns.has(rank[n.id])) columns.set(rank[n.id], []);
+    columns.get(rank[n.id]).push(n.id);
+  }
+  const ranksAscending = [...columns.keys()].sort((a, b) => a - b);
+
+  // Barycenter: sweep left to right, ordering each column by the mean row index
+  // of its predecessors. A node with no ranked predecessor keeps its index, so
+  // the pass is stable.
+  const preds = new Map();
+  for (const e of edges) {
+    if (!preds.has(e.to)) preds.set(e.to, []);
+    preds.get(e.to).push(e.from);
+  }
+  for (let sweep = 0; sweep < SWEEPS; sweep += 1) {
+    for (const r of ranksAscending) {
+      const rowOf = new Map();
+      for (const prevRank of ranksAscending) {
+        if (prevRank >= r) break;
+        columns.get(prevRank).forEach((id, i) => rowOf.set(id, i));
+      }
+      const keyed = columns.get(r).map((id, i) => ({ id, i, bary: barycenter(preds.get(id), rowOf, i) }));
+      keyed.sort((a, b) => a.bary - b.bary || a.i - b.i);
+      columns.set(r, keyed.map((k) => k.id));
+    }
+  }
+
+  const byId = new Map(nodes.map((n) => [n.id, n]));
+  const positions = {};
+  for (const r of ranksAscending) {
+    let cursor = y0;
+    for (const id of columns.get(r)) {
+      const node = byId.get(id);
+      const ports = (typeof portsFn === 'function' ? portsFn(node) : null) || { inputs: [], outputs: [] };
+      const { h } = nodeSize(node, ports);
+      const y = snap(cursor);
+      positions[id] = { x: x0 + r * dx, y };
+      cursor = y + h + gap;                 // stack from the SNAPPED row: idempotent
+    }
+  }
+  return positions;
+}
+
+function nonLoopEdges(tpl, loops, ids) {
+  const loopWireIds = loops?.loopWireIds instanceof Set ? loops.loopWireIds : new Set();
+  return (Array.isArray(tpl?.wires) ? tpl.wires : [])
+    .filter((w) => ids.has(w?.from?.node) && ids.has(w?.to?.node)
+      && w.from.node !== w.to.node && !loopWireIds.has(w.id))
+    .map((w) => ({ from: w.from.node, to: w.to.node }));
+}
+
+function barycenter(predecessors, rowOf, fallback) {
+  const rows = (predecessors || []).map((id) => rowOf.get(id)).filter((row) => row !== undefined);
+  if (!rows.length) return fallback;
+  return rows.reduce((sum, row) => sum + row, 0) / rows.length;
+}
+
+function insertSorted(list, id) {
+  let lo = 0;
+  let hi = list.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (list[mid] < id) lo = mid + 1; else hi = mid;
+  }
+  list.splice(lo, 0, id);
+}

package/src/shared/graph/loops.mjs

@@ -0,0 +1,130 @@
+// src/shared/graph/loops.mjs
+// Loop classification and launch order. Two orthogonal concepts (base spec §2):
+//   loop WIRE  (budget + amber styling) = both endpoints in ONE nontrivial SCC
+//              (or a self-wire) AND the source output is `when:'blocking'`.
+//   loop INPUT (firing semantics)       = an input declared `loop:true` in meta;
+//              wiring-independent, so an unwired one is still in the set.
+// Pure and crash-free: dangling endpoints and unknown agent keys are the
+// validator's errors (V5/V4), so they are filtered, never thrown on.
+import { portsOf, findPort } from './ports.mjs';
+
+/**
+ * Iterative Tarjan (an explicit stack — recursion depth is not a property worth
+ * depending on). Roots are visited in sorted id order and every component is
+ * returned sorted, so the result is reproducible run to run.
+ * @param {string[]} ids
+ * @param {Array<{from:string, to:string}>} edges
+ * @returns {string[][]}
+ */
+export function tarjanSccs(ids, edges) {
+  const adj = new Map((Array.isArray(ids) ? ids : []).map((id) => [id, []]));
+  for (const e of Array.isArray(edges) ? edges : []) {
+    if (adj.has(e?.from) && adj.has(e?.to)) adj.get(e.from).push(e.to);
+  }
+  for (const tos of adj.values()) tos.sort();
+  const index = new Map(); const low = new Map(); const onStack = new Set();
+  const stack = []; const sccs = []; let counter = 0;
+  for (const root of [...adj.keys()].sort()) {
+    if (index.has(root)) continue;
+    index.set(root, counter); low.set(root, counter); counter += 1;
+    stack.push(root); onStack.add(root);
+    const work = [{ id: root, edges: adj.get(root) || [], at: 0 }];
+    while (work.length) {
+      const frame = work[work.length - 1];
+      if (frame.at < frame.edges.length) {
+        const next = frame.edges[frame.at];
+        frame.at += 1;
+        if (!index.has(next)) {
+          index.set(next, counter); low.set(next, counter); counter += 1;
+          stack.push(next); onStack.add(next);
+          work.push({ id: next, edges: adj.get(next) || [], at: 0 });
+        } else if (onStack.has(next)) {
+          low.set(frame.id, Math.min(low.get(frame.id), index.get(next)));
+        }
+        continue;
+      }
+      work.pop();
+      if (work.length) {
+        const parent = work[work.length - 1].id;
+        low.set(parent, Math.min(low.get(parent), low.get(frame.id)));
+      }
+      if (low.get(frame.id) === index.get(frame.id)) {
+        const scc = [];
+        for (;;) { const id = stack.pop(); onStack.delete(id); scc.push(id); if (id === frame.id) break; }
+        sccs.push(scc.sort());
+      }
+    }
+  }
+  return sccs;
+}
+
+/**
+ * @param {object} tpl v2 template { nodes, wires }
+ * @param {(node:object) => object|undefined} portsFn
+ * @returns {{loopWireIds:Set<string>, loopInputs:Set<string>, sccOf:Map<string,number>, launchOrder:string[]}}
+ *          `loopInputs` is graph-global (`'<nodeId>.<port>'`).
+ */
+export function classifyLoops(tpl, portsFn) {
+  const nodes = (Array.isArray(tpl?.nodes) ? tpl.nodes : [])
+    .filter((n) => Boolean(n) && typeof n === 'object' && !Array.isArray(n));
+  const byId = new Map();
+  // STRING ids only — an id-less node indexed under `undefined` would make the
+  // wire filter below accept a wire with a missing `from`/`to`, and the map on
+  // the next line would throw on it (V2/V5 are the validator's to report).
+  for (const n of nodes) if (typeof n.id === 'string' && !byId.has(n.id)) byId.set(n.id, n);
+  const wires = (Array.isArray(tpl?.wires) ? tpl.wires : [])
+    .filter((w) => byId.has(w?.from?.node) && byId.has(w?.to?.node));
+
+  const ids = [...byId.keys()];
+  const sccs = tarjanSccs(ids, wires.map((w) => ({ from: w.from.node, to: w.to.node })));
+  const sccOf = new Map();
+  sccs.forEach((scc, i) => scc.forEach((id) => sccOf.set(id, i)));
+  const nontrivial = new Set(sccs.map((scc, i) => (scc.length > 1 ? i : -1)).filter((i) => i >= 0));
+  const selfWired = new Set(wires.filter((w) => w.from.node === w.to.node).map((w) => w.from.node));
+
+  const loopWireIds = new Set();
+  for (const w of wires) {
+    const a = sccOf.get(w.from.node);
+    if (a === undefined || a !== sccOf.get(w.to.node)) continue;
+    if (!nontrivial.has(a) && !selfWired.has(w.from.node)) continue;
+    const out = findPort(portsOf(portsFn, byId.get(w.from.node)), w.from.port, 'out');
+    if (out && out.when === 'blocking') loopWireIds.add(w.id);
+  }
+
+  const loopInputs = new Set();
+  for (const n of nodes) {
+    for (const inp of portsOf(portsFn, n).inputs) {
+      if (inp?.loop) loopInputs.add(`${n.id}.${inp.id}`);
+    }
+  }
+
+  return { loopWireIds, loopInputs, sccOf, launchOrder: condensationTopo(sccs, wires) };
+}
+
+/** Kahn over the condensation: ties break by the component's minimum node id
+ *  (members are sorted), which is what makes the launch order reproducible.
+ *  Parallel wires collapse to one condensation edge so in-degrees stay balanced. */
+function condensationTopo(sccs, wires) {
+  const sccOf = new Map();
+  sccs.forEach((scc, i) => scc.forEach((id) => sccOf.set(id, i)));
+  const succ = sccs.map(() => new Set());
+  const indegree = sccs.map(() => 0);
+  for (const w of wires) {
+    const a = sccOf.get(w.from.node);
+    const b = sccOf.get(w.to.node);
+    if (a === undefined || b === undefined || a === b || succ[a].has(b)) continue;
+    succ[a].add(b);
+    indegree[b] += 1;
+  }
+  const remaining = new Set(sccs.map((_, i) => i));
+  const order = [];
+  while (remaining.size) {
+    let pick = -1;
+    for (const i of remaining) if (indegree[i] === 0 && (pick < 0 || sccs[i][0] < sccs[pick][0])) pick = i;
+    if (pick < 0) break;                                   // acyclic by construction — defensive only
+    remaining.delete(pick);
+    order.push(...sccs[pick]);
+    for (const b of succ[pick]) indegree[b] -= 1;
+  }
+  return order;
+}

package/src/shared/graph/manifest.mjs

@@ -0,0 +1,257 @@
+// src/shared/graph/manifest.mjs
+// The run-start snapshot persisted as pipelines.stepper. SELF-SUFFICIENT by
+// design: History renders it when the registry is gone or edited, so nothing
+// here may be re-resolved later. Built once per run (and by resume()), NEVER
+// rewritten mid-run — fan-out lives in the execution ledger, not the manifest.
+//
+// It also carries DERIVED `steps` cells and `feedbacks` in the shape the v1
+// buildStepperManifest used to produce. P1's handoff said P8 would delete them;
+// it does NOT, and deliberately: they have LIVE v2 readers (findManifestNode,
+// cycleAwareLabel, nodeLabelLookup, manifestStepsForWires, loopCounts), so they
+// are a real part of the v2 manifest now, not a shim. What made them safe is
+// manifestFor() returning an EMPTY manifest instead of the v1 default seven.
+// UI_PHASE survives for the same reason: `:116` stamps `uiPhase` on every v2
+// agent cell, and the sub_agents.ui_phase attribution column still needs it. The
+// workflows.mjs copy is gone (the v1 topology helpers went with the v1 engine),
+// so THIS is the only copy — shared code may not import workflows.mjs.
+import { TEMPLATE_VERSION, AWAIT_PORT, DEFAULT_MAX_CYCLES, FLOW_LABEL } from './constants.mjs';
+import { portsFnFor, portsOf, resolveOrOutType } from './ports.mjs';
+import { classifyLoops } from './loops.mjs';
+import { rankNodes } from './layout.mjs';
+
+/** Agent key -> the UI stepper bucket. The only copy: the v1 original left
+ *  workflows.mjs with the topology helpers. */
+export const UI_PHASE = Object.freeze({
+  clarify: 'clarify',
+  planner: 'plan', refiner: 'refine', decomposer: 'decompose', implementer: 'implement', reviewer: 'review',
+  manualTestsChecklist: 'manual-checklist', manualWebUiTesting: 'manual-web', planReviewer: 'plan-review',
+  workspaceReviewer: 'review',
+});
+
+const ICON_MAX = 2048;
+/** The icon is an ALLOWLIST, not a denylist: a sidecar can be user- or
+ *  plugin-authored (exactly what v1's UI refuses to inline — `safeAgentIcon`),
+ *  the markup rides the manifest into innerHTML, and the manifest is persisted,
+ *  so it outlives any renderer-side fix. A denylist of `on…=` handlers misses
+ *  `/`, `"` and `'` as attribute separators and every entity encoding; these
+ *  three tables cover the whole shipped icon vocabulary instead. */
+const ICON_TAGS = new Set(['path', 'circle', 'ellipse', 'rect', 'line', 'polyline', 'polygon', 'g']);
+const ICON_ATTRS = new Set(['d', 'cx', 'cy', 'r', 'rx', 'ry', 'x', 'y', 'x1', 'y1', 'x2', 'y2',
+  'width', 'height', 'points', 'transform', 'opacity', 'fill', 'fill-rule', 'fill-opacity',
+  'stroke', 'stroke-width', 'stroke-opacity', 'stroke-linecap', 'stroke-linejoin', 'stroke-dasharray',
+  'stroke-dashoffset', 'stroke-miterlimit', 'vector-effect', 'clip-rule']);
+// Both alternations are UNAMBIGUOUS at every position (the bare class excludes
+// the quotes), so neither can backtrack quadratically on a malformed icon.
+const ICON_TAG_RE = /<\s*(\/?)\s*([a-zA-Z][a-zA-Z0-9-]*)((?:[^<>"']|"[^"]*"|'[^']*')*)>/g;
+const ICON_ATTR_RE = /([a-zA-Z][a-zA-Z0-9:-]*)\s*=\s*("[^"]*"|'[^']*')/g;
+
+/** Inline SVG markup rides the manifest into innerHTML, so anything outside the
+ *  allowlist is dropped WHOLE (never truncated — a half tag is worse).
+ *  EXPORTED (C-2): the composer's canvas reaches the SAME untrusted field through
+ *  GET /api/agents rather than through a manifest, and it had only an
+ *  `origin === 'user'` denylist — so a plugin sidecar's icon went to innerHTML
+ *  verbatim. One allowlist, both paths. Idempotent: a string that passes is
+ *  returned unchanged, so sanitizing an already-sanitized icon is a no-op. */
+export function sanitizeIcon(raw) {
+  const s = typeof raw === 'string' ? raw.trim() : '';
+  if (!s || s.length > ICON_MAX) return '';
+  let cursor = 0;
+  ICON_TAG_RE.lastIndex = 0;
+  for (let m; (m = ICON_TAG_RE.exec(s));) {
+    if (s.slice(cursor, m.index).trim()) return '';           // a text node between tags
+    cursor = m.index + m[0].length;
+    if (!ICON_TAGS.has(m[2].toLowerCase())) return '';
+    if (m[1]) { if (m[3].trim()) return ''; continue; }        // a closing tag carries nothing
+    if (!iconAttrsOk(m[3])) return '';
+  }
+  return cursor === s.length ? s : '';                        // trailing text or an unclosed tag
+}
+
+/** Every attribute quoted, named in ICON_ATTRS, and free of `<`/`&` — an
+ *  entity-encoded `javascript:` decodes only AFTER the filter would have run. */
+function iconAttrsOk(rawAttrs) {
+  const attrs = rawAttrs.replace(/\/\s*$/, '');               // the self-closing slash
+  let cursor = 0;
+  ICON_ATTR_RE.lastIndex = 0;
+  for (let m; (m = ICON_ATTR_RE.exec(attrs));) {
+    if (attrs.slice(cursor, m.index).trim()) return false;    // a bare or unquoted attribute
+    cursor = m.index + m[0].length;
+    if (!ICON_ATTRS.has(m[1].toLowerCase())) return false;
+    if (/[<&]/.test(m[2])) return false;
+  }
+  return !attrs.slice(cursor).trim();
+}
+
+const isNode = (n) => Boolean(n) && typeof n === 'object' && !Array.isArray(n) && typeof n.id === 'string';
+const isWire = (w) => Boolean(w) && typeof w === 'object' && !Array.isArray(w)
+  && typeof w?.from?.node === 'string' && typeof w?.to?.node === 'string';
+
+/**
+ * @param {object} tpl resolved v2 template
+ * @param {Record<string,object>} agentsByKey merged registry metas
+ * @param {{overlays?:{nodes?:object, wires?:object}}} [opts] effective per-node config + per-wire budgets
+ */
+export function buildGraphManifest(tpl, agentsByKey, opts = {}) {
+  const overlays = opts.overlays || {};
+  const nodeOverlays = overlays.nodes || {};
+  const wireOverlays = overlays.wires || {};
+  const portsFn = portsFnFor(agentsByKey);
+  // Objects with real endpoints only. `filter(Boolean)` kept a truthy non-object
+  // node and an endpoint-less wire, and `w.from.node` threw one map later — the
+  // manifest is built from an ALREADY validated template, but it is also built
+  // by resume() from a persisted one, so it degrades instead of crashing.
+  const nodes = (Array.isArray(tpl?.nodes) ? tpl.nodes : []).filter(isNode);
+  const wires = (Array.isArray(tpl?.wires) ? tpl.wires : []).filter(isWire);
+  const loops = classifyLoops(tpl, portsFn);
+  const ranks = rankNodes(tpl, loops);
+  const launchIndex = new Map(loops.launchOrder.map((id, i) => [id, i]));
+  const isWired = new Set(wires.map((w) => `${w?.to?.node}.${w?.to?.port}`));
+
+  const manifestNodes = nodes.map((node) => {
+    const resolved = portsOf(portsFn, node);
+    const meta = node.kind === 'agent' ? (agentsByKey?.[node.key] || null) : null;
+    const over = nodeOverlays[node.id] || {};
+    const cfg = node.config || {};
+    const outType = (port) => (node.kind === 'or' && (!port.type || port.type === 'any')
+      ? (resolveOrOutType(tpl, portsFn, node.id) || 'any') : port.type);
+    const cell = {
+      id: node.id,
+      kind: node.kind,
+      key: node.kind === 'agent' ? node.key : null,
+      x: Number(node.x) || 0,
+      y: Number(node.y) || 0,
+      label: node.kind === 'agent' ? (meta?.displayName || node.key) : (FLOW_LABEL[node.kind] || node.kind),
+      // The v1 stepper bucket. UI_PHASE knows the 11 builtins; a custom agent
+      // buckets under its own key (the sidecar's `uiPhase` died with the v1
+      // vocabulary). The whole field goes with the phase shim in Task 16.
+      uiPhase: node.kind === 'agent' ? (UI_PHASE[node.key] || node.key) : node.kind,
+      // The AUTHORED config, verbatim and complete (unknown keys included —
+      // V17's "preserved and ignored" promise). The manifest is the ONLY
+      // persisted copy of the topology: P4 rebuilds the template from it on a
+      // resume and never re-reads the workflow row, so anything dropped here
+      // (`planStoreSeed`, a future tunable) is lost for the rest of the run.
+      config: { ...(node.config || {}) },
+      ports: {
+        inputs: resolved.inputs.filter((p) => !p.synthetic).map((p) => ({
+          id: p.id, type: p.type, required: p.required !== false, loop: !!p.loop, expands: !!p.expands })),
+        outputs: resolved.outputs.map((p) => ({ id: p.id, type: outType(p), when: p.when || 'always' })),
+        await: resolved.inputs.some((p) => p.synthetic),
+      },
+    };
+    if (node.kind === 'agent') {
+      cell.color = meta?.color || '';
+      cell.icon = sanitizeIcon(meta?.icon);
+      cell.model = over.model ?? cfg.model ?? '';
+      cell.effort = over.effort ?? cfg.effort ?? '';
+      cell.askQuestions = !!(over.askQuestions ?? cfg.askQuestions ?? meta?.questionsDefault ?? false);
+      cell.awaitAll = !!(over.awaitAll ?? cfg.awaitAll ?? false);
+      cell.fanOut = !!(over.fanOut ?? cfg.fanOut ?? meta?.fanOut ?? false);
+      // Sub-agent model policy ('' = inherit). Recorded like model/effort so a
+      // RESUMED run rebuilds the same child-model behavior from the manifest
+      // alone — the workflow row is never re-read after the run starts.
+      cell.subagentModel = over.subagentModel ?? cfg.subagentModel ?? '';
+    }
+    if (node.kind === 'and' || node.kind === 'or' || node.kind === 'combine') {
+      cell.arity = Number.isInteger(cfg.arity) ? cfg.arity : 2;
+    }
+    return cell;
+  });
+
+  const manifestWires = wires.map((w) => {
+    const loop = loops.loopWireIds.has(w.id);
+    const cell = { id: w.id, from: { node: w.from.node, port: w.from.port },
+      to: { node: w.to.node, port: w.to.port }, loop };
+    // maxCycles rides LOOP wires only: overlay > authored > default.
+    if (loop) cell.maxCycles = coerceCycles(wireOverlays[w.id]?.maxCycles ?? w.config?.maxCycles);
+    return cell;
+  });
+
+  // ── the v1 shim (P4-P7; deleted in P8) ─────────────────────────────────────
+  const byRank = new Map();
+  for (const node of manifestNodes) {
+    const r = ranks[node.id] ?? 0;
+    if (!byRank.has(r)) byRank.set(r, []);
+    byRank.get(r).push(node);
+  }
+  const agentCells = [...byRank.keys()].sort((a, b) => a - b).map((r) => ({
+    kind: 'agents',
+    nodes: byRank.get(r)
+      .sort((a, b) => (launchIndex.get(a.id) ?? 0) - (launchIndex.get(b.id) ?? 0))
+      .map((n) => ({
+        id: n.id,
+        key: n.key,
+        uiPhase: n.uiPhase,
+        label: n.label,
+        color: n.color || '',
+        sub: (n.key && agentsByKey?.[n.key]?.description) || '',
+        cycles: n.ports.inputs.some((p) => p.loop && isWired.has(`${n.id}.${p.id}`)),
+        model: n.model || '',
+        effort: n.effort || '',
+      })),
+  }));
+
+  return {
+    version: 2,
+    template: { id: tpl?.id ?? '', name: tpl?.name ?? '' },
+    graph: { nodes: manifestNodes, wires: manifestWires },
+    bookends: { preflight: true, done: true },
+    steps: [
+      { kind: 'preflight', nodes: [{ id: 'preflight', label: 'Preflight', sub: 'checks' }] },
+      ...agentCells,
+      { kind: 'done', nodes: [{ id: 'done', label: 'Done', sub: 'complete' }] },
+    ],
+    feedbacks: manifestWires.filter((w) => w.loop)
+      .map((w) => ({ id: w.id, from: w.from.node, to: w.to.node, maxCycles: w.maxCycles })),
+  };
+}
+
+function coerceCycles(value) {
+  const n = Math.floor(Number(value));
+  return Number.isFinite(n) && n >= 1 ? n : DEFAULT_MAX_CYCLES;
+}
+
+/** A portsFn over a MANIFEST — the run monitor never touches the live registry.
+ *  The await port is re-synthesized from the boolean so geometry, validation and
+ *  hit-testing behave exactly as they do in the composer. */
+export function manifestPortsFn(manifest) {
+  const byId = new Map((manifest?.graph?.nodes || []).map((n) => [n.id, n]));
+  return (node) => {
+    const cell = byId.get(node?.id);
+    if (!cell) return undefined;
+    return {
+      known: true,
+      ported: true,
+      inputs: cell.ports.await ? [...cell.ports.inputs, AWAIT_PORT] : [...cell.ports.inputs],
+      outputs: [...cell.ports.outputs],
+      displayName: cell.label,
+      color: cell.color,
+      icon: cell.icon,
+      // A verdict-bearing node is one with a conditional output — enough for V13
+      // and firedOutputs; the filename itself never leaves the engine.
+      verdict: cell.ports.outputs.some((p) => p.when && p.when !== 'always') ? { filename: '' } : undefined,
+    };
+  };
+}
+
+/** The renderable template inside a manifest (id/kind/x/y/config + wires). */
+export function manifestTemplate(manifest) {
+  return {
+    id: manifest?.template?.id ?? '',
+    name: manifest?.template?.name ?? '',
+    version: TEMPLATE_VERSION,
+    domain: '',
+    nodes: (manifest?.graph?.nodes || []).map((n) => {
+      // `config` is restored VERBATIM from the cell — no per-key rebuild. The
+      // old `{arity, awaitAll}` reconstruction silently dropped everything else
+      // (`planStoreSeed` on the Task card of `wf_provided-plan`, for one).
+      const node = { id: n.id, kind: n.kind, x: n.x, y: n.y, config: { ...(n.config || {}) } };
+      if (n.kind === 'agent') node.key = n.key;
+      return node;
+    }),
+    wires: (manifest?.graph?.wires || []).map((w) => {
+      const wire = { id: w.id, from: { ...w.from }, to: { ...w.to } };
+      if (w.loop && w.maxCycles !== undefined) wire.config = { maxCycles: w.maxCycles };
+      return wire;
+    }),
+  };
+}