From 3e86d54c26e6a40bb8cc644d6494e058afddf170 Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 04:07:12 +0000
Subject: [PATCH 01/25] feat(task T01): implement via codex

---
 dashboard/src/v2/lib/nodes-agent-surface.ts   |   5 +-
 dashboard/src/v2/lib/nodes-canvas-state.ts    | 121 +++++++++++--
 docs-web/architecture/node-flow-foundation.md |   7 +
 docs-web/architecture/node-flows.md           |  16 ++
 .../architecture-node-flow-foundation.mdx     |   7 +
 .../content/docs/architecture-node-flows.mdx  |  16 ++
 docs-web/content/docs/registry.ts             |  18 ++
 .../docs/user-dashboard-node-flows.mdx        |   4 +
 .../docs/user-dashboard-nodes-canvas.mdx      |   4 +
 ...architecture-node-flow-foundation.lazy.tsx |  11 ++
 .../docs.architecture-node-flows.lazy.tsx     |  11 ++
 docs-web/user/dashboard/node-flows.md         |   4 +
 docs-web/user/dashboard/nodes-canvas.md       |   4 +
 docs/architecture/node-flow-foundation.md     |   8 +
 docs/architecture/node-flows.md               |   8 +
 docs/dashboard/node-flows.md                  |   4 +
 docs/dashboard/nodes-canvas.md                |   4 +
 src/contracts/node-definition-types.ts        |  46 +++++
 src/contracts/node-flow-types.ts              |  70 ++++++++
 .../node-flows/node-definition-registry.ts    |  91 ++++++++++
 src/domain/node-flows/node-flow-migrators.ts  | 110 ++++++++++++
 src/domain/node-flows/node-flow-validation.ts | 162 +++++++++++++++++-
 src/repositories/db/app-db-migrations.ts      |  46 +++++
 src/repositories/node-flow-repository.ts      |   2 +
 src/services/node-flow-runtime-service.ts     |  11 +-
 .../node-definition-registry.test.ts          |  17 ++
 .../node-flows/node-flow-migrators.test.ts    |  31 ++++
 .../node-flows/node-flow-validation.test.ts   |  37 +++-
 .../repositories/node-flow-repository.test.ts |  18 ++
 .../services/node-flow-service.test.ts        |   2 +-
 .../dashboard/lib/nodes-canvas-state.test.ts  |  15 ++
 31 files changed, 880 insertions(+), 30 deletions(-)
 create mode 100644 docs-web/architecture/node-flow-foundation.md
 create mode 100644 docs-web/architecture/node-flows.md
 create mode 100644 docs-web/content/docs/architecture-node-flow-foundation.mdx
 create mode 100644 docs-web/content/docs/architecture-node-flows.mdx
 create mode 100644 docs-web/routes/docs.architecture-node-flow-foundation.lazy.tsx
 create mode 100644 docs-web/routes/docs.architecture-node-flows.lazy.tsx
 create mode 100644 src/contracts/node-definition-types.ts
 create mode 100644 src/domain/node-flows/node-definition-registry.ts
 create mode 100644 src/domain/node-flows/node-flow-migrators.ts
 create mode 100644 tests/backend/domain/node-flows/node-definition-registry.test.ts
 create mode 100644 tests/backend/domain/node-flows/node-flow-migrators.test.ts

diff --git a/dashboard/src/v2/lib/nodes-agent-surface.ts b/dashboard/src/v2/lib/nodes-agent-surface.ts
index dcf3b0808f..8326f5004c 100644
--- a/dashboard/src/v2/lib/nodes-agent-surface.ts
+++ b/dashboard/src/v2/lib/nodes-agent-surface.ts
@@ -12,6 +12,7 @@ import type {
   NodeCanvasValidationIssue,
 } from "./nodes-canvas-state.js";
 import {
+  deserializeNodeCanvasGraphWithMigration,
   nodesCanvasReducer,
   normalizeNodeCanvasGraph,
   validateNodeCanvasGraph,
@@ -278,8 +279,8 @@ const applyParsedCommand = (
       return nextGraph;
     }
     case "replace_graph": {
-      const parsed = JSON.parse(command.serializedGraph) as unknown;
-      return nodesCanvasReducer(graph, { type: "replace_graph", graph: normalizeNodeCanvasGraph(parsed) });
+      const migration = deserializeNodeCanvasGraphWithMigration(command.serializedGraph);
+      return nodesCanvasReducer(graph, { type: "replace_graph", graph: migration.graph });
     }
   }
 };
diff --git a/dashboard/src/v2/lib/nodes-canvas-state.ts b/dashboard/src/v2/lib/nodes-canvas-state.ts
index 2a35928413..0b363bd42f 100644
--- a/dashboard/src/v2/lib/nodes-canvas-state.ts
+++ b/dashboard/src/v2/lib/nodes-canvas-state.ts
@@ -1,3 +1,5 @@
+import type { NodeFlowGraph, NodeFlowJsonObject, NodeFlowJsonValue, NodeFlowPort } from "../../../../src/contracts/node-flow-types.js";
+
 export type NodeCanvasNodeKind = "trigger" | "agent" | "task" | "condition" | "output";
 export type NodeCanvasPortDirection = "input" | "output";
 export type NodeCanvasPortType = "control" | "agent" | "task" | "condition" | "result" | "data";
@@ -66,11 +68,18 @@ export interface NodeCanvasSelectionState {
 }
 
 export interface NodeCanvasGraph {
+  schemaVersion?: 2;
   nodes: NodeCanvasNode[];
   edges: NodeCanvasEdge[];
   selection: NodeCanvasSelectionState;
 }
 
+export interface NodeCanvasGraphMigrationResult {
+  graph: NodeCanvasGraph;
+  migrated: boolean;
+  legacySnapshot: unknown | null;
+}
+
 export type NodeCanvasValidationIssueCode =
   | "duplicate_node_id"
   | "missing_edge_source_node"
@@ -201,6 +210,7 @@ export const createInitialNodeCanvasGraph = (): NodeCanvasGraph => {
   ];
 
   return normalizeNodeCanvasGraph({
+    schemaVersion: 2,
     nodes,
     edges: [
       createNodeCanvasEdge("edge-trigger-1-event-agent-1-in", "trigger-1", "event", "agent-1", "in"),
@@ -487,18 +497,73 @@ export const validateNodeCanvasGraph = (graph: NodeCanvasGraph): NodeCanvasValid
 };
 
 export const serializeNodeCanvasGraph = (graph: NodeCanvasGraph): string => (
-  JSON.stringify(toStableJson(normalizeNodeCanvasGraph(graph)), null, 2)
+  JSON.stringify(toStableJson(toCanonicalNodeFlowGraph(graph)), null, 2)
 );
 
+export const toCanonicalNodeFlowGraph = (graph: NodeCanvasGraph): NodeFlowGraph => {
+  const normalized = normalizeNodeCanvasGraph(graph);
+  return {
+    schemaVersion: 2,
+    nodes: normalized.nodes.map((node) => ({
+      id: node.id,
+      type: node.kind,
+      title: node.label,
+      description: node.description,
+      position: node.position,
+      definition: { type: node.kind, version: 1 },
+      ports: [...node.inputPorts, ...node.outputPorts].map(toCanonicalPort),
+      credentialBindings: [],
+      policy: {},
+      capabilities: [],
+      sideEffect: "none",
+      disabled: false,
+      data: {
+        canvas: {
+          config: node.config as unknown as NodeFlowJsonValue,
+          metadata: node.metadata as unknown as NodeFlowJsonValue,
+        },
+      },
+    })),
+    edges: normalized.edges.map((edge) => ({
+      id: edge.id,
+      fromNodeId: edge.source.nodeId,
+      toNodeId: edge.target.nodeId,
+      fromHandle: edge.source.portId,
+      toHandle: edge.target.portId,
+    })),
+    metadata: { canvasSelection: normalized.selection as unknown as NodeFlowJsonObject },
+  };
+};
+
+const toCanonicalPort = (port: NodeCanvasPort): NodeFlowPort => ({
+  id: port.id,
+  direction: port.direction,
+  schema: { type: "object", description: port.type },
+  required: port.required,
+});
+
 export const deserializeNodeCanvasGraph = (serialized: string): NodeCanvasGraph => {
+  return deserializeNodeCanvasGraphWithMigration(serialized).graph;
+};
+
+export const deserializeNodeCanvasGraphWithMigration = (serialized: string): NodeCanvasGraphMigrationResult => {
   try {
     const parsed: unknown = JSON.parse(serialized);
-    return normalizeNodeCanvasGraph(parsed);
+    return migrateNodeCanvasGraph(parsed);
   } catch {
-    return createInitialNodeCanvasGraph();
+    return { graph: createInitialNodeCanvasGraph(), migrated: false, legacySnapshot: null };
   }
 };
 
+export const migrateNodeCanvasGraph = (input: unknown): NodeCanvasGraphMigrationResult => {
+  const migrated = !isRecord(input) || input.schemaVersion !== 2;
+  return {
+    graph: normalizeNodeCanvasGraph(input),
+    migrated,
+    legacySnapshot: migrated ? cloneStableValue(input) : null,
+  };
+};
+
 export const normalizeNodeCanvasGraph = (input: unknown): NodeCanvasGraph => {
   if (!isRecord(input)) {
     return createInitialNodeCanvasGraph();
@@ -517,15 +582,19 @@ export const normalizeNodeCanvasGraph = (input: unknown): NodeCanvasGraph => {
     : [];
 
   const validNodeIds = new Set(parsedNodes.map((node) => node.id));
-  const parsedSelection = parseSelection(input.selection, validNodeIds, new Set(parsedEdges.map((edge) => edge.id)));
+  const canvasSelection = isRecord(input.metadata) ? input.metadata.canvasSelection : undefined;
+  const parsedSelection = parseSelection(input.selection ?? canvasSelection, validNodeIds, new Set(parsedEdges.map((edge) => edge.id)));
 
   return {
+    schemaVersion: 2,
     nodes: parsedNodes.sort(compareById),
     edges: parsedEdges.sort(compareById),
     selection: parsedSelection,
   };
 };
 
+const cloneStableValue = (value: unknown): unknown => structuredClone(value);
+
 const createNodeCanvasEdge = (
   id: string,
   sourceNodeId: string,
@@ -619,10 +688,11 @@ const normalizeMetadata = (metadata: NodeCanvasNodeMetadata): NodeCanvasNodeMeta
 });
 
 const parseNode = (value: unknown): NodeCanvasNode | null => {
-  if (!isRecord(value) || !isString(value.id) || !isNodeKind(value.kind)) {
+  const kindValue = isRecord(value) ? value.kind ?? value.type : undefined;
+  if (!isRecord(value) || !isString(value.id) || !isNodeKind(kindValue)) {
     return null;
   }
-  const template = createNodeCanvasNode(value.kind, { id: value.id });
+  const template = createNodeCanvasNode(kindValue, { id: value.id });
   const position = isRecord(value.position)
     ? {
         x: finiteOrDefault(typeof value.position.x === "number" ? value.position.x : undefined, template.position.x),
@@ -630,18 +700,25 @@ const parseNode = (value: unknown): NodeCanvasNode | null => {
       }
     : template.position;
 
+  const canvasData = readCanonicalCanvasData(value.data);
+  const canonicalPorts = Array.isArray(value.ports) ? value.ports : undefined;
   return {
     ...template,
-    label: isString(value.label) ? value.label : template.label,
+    label: isString(value.label) ? value.label : isString(value.title) ? value.title : template.label,
     description: isString(value.description) ? value.description : template.description,
     position,
-    inputPorts: parsePorts(value.inputPorts, "input", template.inputPorts),
-    outputPorts: parsePorts(value.outputPorts, "output", template.outputPorts),
-    config: parseConfig(value.config, template.config),
-    metadata: parseMetadata(value.metadata),
+    inputPorts: parsePorts(value.inputPorts ?? canonicalPorts?.filter((port) => isRecord(port) && port.direction === "input"), "input", template.inputPorts),
+    outputPorts: parsePorts(value.outputPorts ?? canonicalPorts?.filter((port) => isRecord(port) && port.direction === "output"), "output", template.outputPorts),
+    config: parseConfig(value.config ?? canvasData?.config, template.config),
+    metadata: parseMetadata(value.metadata ?? canvasData?.metadata),
   };
 };
 
+const readCanonicalCanvasData = (value: unknown): Record<string, unknown> | null => {
+  if (!isRecord(value) || !isRecord(value.canvas)) return null;
+  return value.canvas;
+};
+
 const parsePorts = <TDirection extends NodeCanvasPortDirection>(
   value: unknown,
   expectedDirection: TDirection,
@@ -660,17 +737,19 @@ const parsePort = <TDirection extends NodeCanvasPortDirection>(
   value: unknown,
   expectedDirection: TDirection,
 ): (NodeCanvasPort & { direction: TDirection }) | null => {
-  if (!isRecord(value) || !isString(value.id) || !isString(value.label) || !isString(value.type)) {
+  if (!isRecord(value) || !isString(value.id)) {
     return null;
   }
-  if (!["control", "agent", "task", "condition", "result", "data"].includes(value.type)) {
+  const canonicalDescription = isRecord(value.schema) && isString(value.schema.description) ? value.schema.description : undefined;
+  const portType = isString(value.type) ? value.type : canonicalDescription ?? "data";
+  if (!["control", "agent", "task", "condition", "result", "data"].includes(portType)) {
     return null;
   }
   return {
     id: value.id,
-    label: value.label,
+    label: isString(value.label) ? value.label : value.id,
     direction: expectedDirection,
-    type: value.type as NodeCanvasPortType,
+    type: portType as NodeCanvasPortType,
     ...(typeof value.required === "boolean" ? { required: value.required } : {}),
   };
 };
@@ -724,16 +803,20 @@ const parseMetadata = (value: unknown): NodeCanvasNodeMetadata => {
 };
 
 const parseEdge = (value: unknown): NodeCanvasEdge | null => {
-  if (!isRecord(value) || !isString(value.id) || !isRecord(value.source) || !isRecord(value.target)) {
+  if (!isRecord(value) || !isString(value.id)) {
     return null;
   }
-  if (!isString(value.source.nodeId) || !isString(value.source.portId) || !isString(value.target.nodeId) || !isString(value.target.portId)) {
+  const sourceNodeId = isRecord(value.source) ? value.source.nodeId : value.fromNodeId;
+  const sourcePortId = isRecord(value.source) ? value.source.portId : value.fromHandle;
+  const targetNodeId = isRecord(value.target) ? value.target.nodeId : value.toNodeId;
+  const targetPortId = isRecord(value.target) ? value.target.portId : value.toHandle;
+  if (!isString(sourceNodeId) || !isString(sourcePortId) || !isString(targetNodeId) || !isString(targetPortId)) {
     return null;
   }
   return {
     id: value.id,
-    source: { nodeId: value.source.nodeId, portId: value.source.portId },
-    target: { nodeId: value.target.nodeId, portId: value.target.portId },
+    source: { nodeId: sourceNodeId, portId: sourcePortId },
+    target: { nodeId: targetNodeId, portId: targetPortId },
     ...(isString(value.label) ? { label: value.label } : {}),
   };
 };
diff --git a/docs-web/architecture/node-flow-foundation.md b/docs-web/architecture/node-flow-foundation.md
new file mode 100644
index 0000000000..acd3237449
--- /dev/null
+++ b/docs-web/architecture/node-flow-foundation.md
@@ -0,0 +1,7 @@
+# Node Flow Foundation
+
+Code UX uses one canonical Graph v2 contract across backend, MCP, runtime, and dashboard. Graphs carry `schemaVersion: 2`, versioned definitions, typed ports, credential-id bindings, bounded policies, capabilities, side effects, disabled state, flow schemas, and optional immutable publication metadata.
+
+Validation resolves definitions, checks configuration, ports, policies, graph limits, and cycles, and rejects plaintext secrets and custom source. Only `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output` are executable.
+
+Persisted Graph v1 records retain their original immutable version and append deterministic Graph v2. Browser migration retains its original snapshot outside executable graph JSON.
diff --git a/docs-web/architecture/node-flows.md b/docs-web/architecture/node-flows.md
new file mode 100644
index 0000000000..493c84b123
--- /dev/null
+++ b/docs-web/architecture/node-flows.md
@@ -0,0 +1,16 @@
+# Node Flows
+
+Node flows are project-owned, versioned Graph v2 workflows.
+
+## Implemented runtime nodes
+
+| Type | Execution |
+| --- | --- |
+| `input` | Emits run input. |
+| `set_fields` | Transforms object fields. |
+| `template` | Renders text templates. |
+| `provider_prompt` | Invokes a configured CLI provider. |
+| `http_request` | Performs a bounded HTTP/HTTPS request. |
+| `output` | Selects the result. |
+
+These are the only executable definitions. Trigger, agent-router, task, condition, notification, and other palette concepts are planned entries without runtime handlers. Graph v1 migration preserves the legacy snapshot and appends deterministic v2.
diff --git a/docs-web/content/docs/architecture-node-flow-foundation.mdx b/docs-web/content/docs/architecture-node-flow-foundation.mdx
new file mode 100644
index 0000000000..acd3237449
--- /dev/null
+++ b/docs-web/content/docs/architecture-node-flow-foundation.mdx
@@ -0,0 +1,7 @@
+# Node Flow Foundation
+
+Code UX uses one canonical Graph v2 contract across backend, MCP, runtime, and dashboard. Graphs carry `schemaVersion: 2`, versioned definitions, typed ports, credential-id bindings, bounded policies, capabilities, side effects, disabled state, flow schemas, and optional immutable publication metadata.
+
+Validation resolves definitions, checks configuration, ports, policies, graph limits, and cycles, and rejects plaintext secrets and custom source. Only `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output` are executable.
+
+Persisted Graph v1 records retain their original immutable version and append deterministic Graph v2. Browser migration retains its original snapshot outside executable graph JSON.
diff --git a/docs-web/content/docs/architecture-node-flows.mdx b/docs-web/content/docs/architecture-node-flows.mdx
new file mode 100644
index 0000000000..493c84b123
--- /dev/null
+++ b/docs-web/content/docs/architecture-node-flows.mdx
@@ -0,0 +1,16 @@
+# Node Flows
+
+Node flows are project-owned, versioned Graph v2 workflows.
+
+## Implemented runtime nodes
+
+| Type | Execution |
+| --- | --- |
+| `input` | Emits run input. |
+| `set_fields` | Transforms object fields. |
+| `template` | Renders text templates. |
+| `provider_prompt` | Invokes a configured CLI provider. |
+| `http_request` | Performs a bounded HTTP/HTTPS request. |
+| `output` | Selects the result. |
+
+These are the only executable definitions. Trigger, agent-router, task, condition, notification, and other palette concepts are planned entries without runtime handlers. Graph v1 migration preserves the legacy snapshot and appends deterministic v2.
diff --git a/docs-web/content/docs/registry.ts b/docs-web/content/docs/registry.ts
index 6e1bf494dc..0b0792112c 100644
--- a/docs-web/content/docs/registry.ts
+++ b/docs-web/content/docs/registry.ts
@@ -107,6 +107,8 @@ export type DocsSlug =
   | 'user-dashboard-custom-dashboards'
   | 'architecture-custom-dashboard-foundation'
   | 'architecture-managed-container-runtime'
+  | 'architecture-node-flow-foundation'
+  | 'architecture-node-flows'
   | 'architecture-speech-input'
   | 'architecture-speech-output'
   | 'architecture-worker-clarification-contract'
@@ -848,6 +850,20 @@ export const docsRegistry: Record<DocsSlug, DocsRegistryEntry> = {
     title: "Managed Container Runtime",
     description: "The managed container runtime removes first-invocation Docker builds while keeping provider binaries local to each user's Docker host.",
   },
+  'architecture-node-flow-foundation': {
+    id: 'architecture-node-flow-foundation',
+    path: '/docs/architecture-node-flow-foundation',
+    section: 'Architecture',
+    title: "Node Flow Foundation",
+    description: "Code UX uses one canonical Graph v2 contract across backend, MCP, runtime, and dashboard. Graphs carry schemaVersion: 2, versioned definitions, typed ports, credential-id bindings, bounded policies, capabilities, side...",
+  },
+  'architecture-node-flows': {
+    id: 'architecture-node-flows',
+    path: '/docs/architecture-node-flows',
+    section: 'Architecture',
+    title: "Node Flows",
+    description: "Node flows are project-owned, versioned Graph v2 workflows.",
+  },
   'architecture-speech-input': {
     id: 'architecture-speech-input',
     path: '/docs/architecture-speech-input',
@@ -976,6 +992,8 @@ export const orderedDocs: DocsRegistryEntry[] = [
   docsRegistry['user-dashboard-custom-dashboards'],
   docsRegistry['architecture-custom-dashboard-foundation'],
   docsRegistry['architecture-managed-container-runtime'],
+  docsRegistry['architecture-node-flow-foundation'],
+  docsRegistry['architecture-node-flows'],
   docsRegistry['architecture-speech-input'],
   docsRegistry['architecture-speech-output'],
   docsRegistry['architecture-worker-clarification-contract'],
diff --git a/docs-web/content/docs/user-dashboard-node-flows.mdx b/docs-web/content/docs/user-dashboard-node-flows.mdx
index 2edb85fe58..949de5d5ed 100644
--- a/docs-web/content/docs/user-dashboard-node-flows.mdx
+++ b/docs-web/content/docs/user-dashboard-node-flows.mdx
@@ -39,3 +39,7 @@ A flow can be attached to a project agent preset as a repeatable skill with a na
 ## Scheduling
 
 Use the [Scheduler](/docs/user-dashboard-scheduler) page to run a saved node flow once or on a recurrence. Scheduled node-flow entries select a project-owned flow and may include optional JSON object input. Pause, resume, failure handling, and due-run behavior match the normal scheduler model.
+
+## Graph v2 boundary
+
+The dashboard edits the shared Graph v2 contract. The executable registry is limited to `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output`; planned palette concepts are not runtime handlers.
diff --git a/docs-web/content/docs/user-dashboard-nodes-canvas.mdx b/docs-web/content/docs/user-dashboard-nodes-canvas.mdx
index f668ef9733..2c7a5bc4b7 100644
--- a/docs-web/content/docs/user-dashboard-nodes-canvas.mdx
+++ b/docs-web/content/docs/user-dashboard-nodes-canvas.mdx
@@ -41,3 +41,7 @@ The page displays a deterministic graph summary for command workflows, including
 ## Empty and reset states
 
 `Clear` empties the canvas while keeping the palette available. `Reset` restores the starter trigger -> agent -> task -> condition -> output graph. The layout collapses to a single column at smaller widths so controls remain reachable without overlapping.
+
+## Graph v2 migration
+
+Serialization writes `schemaVersion: 2`. Legacy browser v1 values migrate deterministically with their untouched snapshot retained separately. Trigger, agent, task, condition, and output are planning concepts; executable definitions are limited to `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output`.
diff --git a/docs-web/routes/docs.architecture-node-flow-foundation.lazy.tsx b/docs-web/routes/docs.architecture-node-flow-foundation.lazy.tsx
new file mode 100644
index 0000000000..d4eebd0943
--- /dev/null
+++ b/docs-web/routes/docs.architecture-node-flow-foundation.lazy.tsx
@@ -0,0 +1,11 @@
+import { createLazyFileRoute } from '@tanstack/react-router'
+import ArchitectureNodeFlowFoundationContent from '../content/docs/architecture-node-flow-foundation.mdx'
+import { DocsPage } from '../components/docs/DocsPage'
+
+export const Route = createLazyFileRoute('/docs/architecture-node-flow-foundation')({
+  component: () => (
+    <DocsPage id="architecture-node-flow-foundation">
+      <ArchitectureNodeFlowFoundationContent />
+    </DocsPage>
+  )
+})
diff --git a/docs-web/routes/docs.architecture-node-flows.lazy.tsx b/docs-web/routes/docs.architecture-node-flows.lazy.tsx
new file mode 100644
index 0000000000..8f7e769eab
--- /dev/null
+++ b/docs-web/routes/docs.architecture-node-flows.lazy.tsx
@@ -0,0 +1,11 @@
+import { createLazyFileRoute } from '@tanstack/react-router'
+import ArchitectureNodeFlowsContent from '../content/docs/architecture-node-flows.mdx'
+import { DocsPage } from '../components/docs/DocsPage'
+
+export const Route = createLazyFileRoute('/docs/architecture-node-flows')({
+  component: () => (
+    <DocsPage id="architecture-node-flows">
+      <ArchitectureNodeFlowsContent />
+    </DocsPage>
+  )
+})
diff --git a/docs-web/user/dashboard/node-flows.md b/docs-web/user/dashboard/node-flows.md
index 32db788798..d532ef1050 100644
--- a/docs-web/user/dashboard/node-flows.md
+++ b/docs-web/user/dashboard/node-flows.md
@@ -39,3 +39,7 @@ A flow can be attached to a project agent preset as a repeatable skill with a na
 ## Scheduling
 
 Use the [Scheduler](./scheduler.md) page to run a saved node flow once or on a recurrence. Scheduled node-flow entries select a project-owned flow and may include optional JSON object input. Pause, resume, failure handling, and due-run behavior match the normal scheduler model.
+
+## Graph v2 boundary
+
+The dashboard edits the shared Graph v2 contract. The executable registry is limited to `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output`; planned palette concepts are not runtime handlers.
diff --git a/docs-web/user/dashboard/nodes-canvas.md b/docs-web/user/dashboard/nodes-canvas.md
index f668ef9733..2c7a5bc4b7 100644
--- a/docs-web/user/dashboard/nodes-canvas.md
+++ b/docs-web/user/dashboard/nodes-canvas.md
@@ -41,3 +41,7 @@ The page displays a deterministic graph summary for command workflows, including
 ## Empty and reset states
 
 `Clear` empties the canvas while keeping the palette available. `Reset` restores the starter trigger -> agent -> task -> condition -> output graph. The layout collapses to a single column at smaller widths so controls remain reachable without overlapping.
+
+## Graph v2 migration
+
+Serialization writes `schemaVersion: 2`. Legacy browser v1 values migrate deterministically with their untouched snapshot retained separately. Trigger, agent, task, condition, and output are planning concepts; executable definitions are limited to `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output`.
diff --git a/docs/architecture/node-flow-foundation.md b/docs/architecture/node-flow-foundation.md
index 6bb2573ceb..7a854f6f65 100644
--- a/docs/architecture/node-flow-foundation.md
+++ b/docs/architecture/node-flow-foundation.md
@@ -77,3 +77,11 @@ Dashboard routes are registered through `registerNodeFlowRoutes`:
 - `GET /api/node-flow-runs/:runId/node-runs`
 
 Handlers stay thin and delegate behavior to `NodeFlowService`.
+
+## Canonical Graph v2
+
+Normalized graphs carry `schemaVersion: 2`. Nodes reference a stable definition type and version and carry typed ports, credential-id bindings, bounded retry/timeout policies, capabilities, side-effect classification, and disabled state. Graphs may declare typed input/output schemas and immutable publication metadata.
+
+The typed registry includes configuration and UI schemas, ports, credential slots, capabilities, side effects, default policies, documentation, deprecation, and execution kind. Only `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output` are executable. Other palette ideas are planned concepts without runtime handlers.
+
+Validation resolves definitions and checks configuration, handles, policies, graph limits, and cycles with field-level issues. Graph JSON rejects secret-shaped fields and generated/custom source fields. Persisted Graph v1 rows keep their original immutable snapshot and append deterministic Graph v2 as a new current version.
diff --git a/docs/architecture/node-flows.md b/docs/architecture/node-flows.md
index 42914ddc4f..6268a53066 100644
--- a/docs/architecture/node-flows.md
+++ b/docs/architecture/node-flows.md
@@ -98,3 +98,11 @@ Use these rules:
 - Validate every node field before saving: required prompt/template/url fields, finite numeric limits, supported HTTP method, JSON object input, and select defaults that match options.
 - Keep flows deterministic and rerunnable. Avoid hidden dependence on local time, ambient chat state, or one-off sprint context unless it is explicitly passed as JSON input.
 - Preserve inspection value. Name nodes for the operation they perform, keep edges acyclic, and make the output node return the artifact another operator or agent will actually consume.
+
+## Graph v2 contract and migration
+
+Graph v2 is the single workflow model used by backend, MCP, runtime, and dashboard. It adds `schemaVersion: 2`, stable definition references, typed ports and flow schemas, credential-id bindings, retry and timeout policies, capability and side-effect metadata, disabled state, and optional immutable publication metadata. Plaintext credentials, secret-shaped fields, generated source, and custom code are not valid graph data.
+
+The executable registry is exactly `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output`. Planned trigger, agent-router, task, condition, notification, and integration entries are not executable until handlers exist.
+
+Backend Graph v1 migration retains the exact prior version and appends deterministic v2. Browser canvas v1 migration returns the untouched legacy snapshot separately from the normalized graph.
diff --git a/docs/dashboard/node-flows.md b/docs/dashboard/node-flows.md
index 87ff413060..3c78d9d122 100644
--- a/docs/dashboard/node-flows.md
+++ b/docs/dashboard/node-flows.md
@@ -91,3 +91,7 @@ Nodes must stay usable on desktop and mobile:
 - validation and run errors must be text, not color-only
 - focus order should follow library -> canvas -> inspector -> run/attachment panels
 - JSON editors and textareas should preserve visible labels and error messages on small screens
+
+## Graph v2 boundary
+
+The dashboard edits the shared Graph v2 contract rather than owning a second execution model. A graph is executable only when every node resolves to `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, or `output`. Planning palette concepts are not runtime handlers.
diff --git a/docs/dashboard/nodes-canvas.md b/docs/dashboard/nodes-canvas.md
index 2bd32be0a2..7d44194533 100644
--- a/docs/dashboard/nodes-canvas.md
+++ b/docs/dashboard/nodes-canvas.md
@@ -73,3 +73,7 @@ The page displays the deterministic `buildNodeCanvasAgentSummary` output so agen
 `Clear` replaces the graph with an empty canvas. The canvas and inspector show empty/no-selection states, while the palette remains available for recovery. `Reset` restores the starter trigger -> agent -> task -> condition -> output graph and refreshes the exchange JSON.
 
 The page uses responsive grid columns that collapse into a single column at smaller widths so the palette, canvas, inspector, validation panel, and JSON exchange controls remain reachable without overlapping.
+
+## Graph v2 migration
+
+Serialization writes `schemaVersion: 2`. Importing a legacy browser v1 value deterministically normalizes it and retains the untouched snapshot separately. Trigger, agent, task, condition, and output palette entries are planning concepts; executable definitions are limited to `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output`.
diff --git a/src/contracts/node-definition-types.ts b/src/contracts/node-definition-types.ts
new file mode 100644
index 0000000000..6e49a1fca6
--- /dev/null
+++ b/src/contracts/node-definition-types.ts
@@ -0,0 +1,46 @@
+import type {
+  NodeFlowExecutionPolicy,
+  NodeFlowPort,
+  NodeFlowSideEffect,
+  NodeFlowValueSchema,
+  NodeWidgetSchema,
+} from "./node-flow-types.js";
+
+export type NodeDefinitionExecutionKind = "local" | "provider" | "http" | "unavailable";
+
+export interface NodeDefinitionCredentialRequirement {
+  slot: string;
+  label: string;
+  required: boolean;
+  allowedKinds: string[];
+}
+
+export interface NodeDefinitionUiManifest {
+  label: string;
+  description: string;
+  category: string;
+  icon?: string;
+  widgetSchema: NodeWidgetSchema;
+}
+
+export interface NodeDefinitionDeprecation {
+  deprecated: boolean;
+  message?: string;
+  replacementType?: string;
+}
+
+export interface NodeDefinitionManifest {
+  type: string;
+  version: number;
+  executable: boolean;
+  executionKind: NodeDefinitionExecutionKind;
+  configurationSchema: NodeFlowValueSchema;
+  ui: NodeDefinitionUiManifest;
+  ports: NodeFlowPort[];
+  credentials: NodeDefinitionCredentialRequirement[];
+  capabilities: string[];
+  sideEffect: NodeFlowSideEffect;
+  defaultPolicy: NodeFlowExecutionPolicy;
+  documentation: string;
+  deprecation: NodeDefinitionDeprecation;
+}
diff --git a/src/contracts/node-flow-types.ts b/src/contracts/node-flow-types.ts
index 1921310dd9..8e19d7ab7a 100644
--- a/src/contracts/node-flow-types.ts
+++ b/src/contracts/node-flow-types.ts
@@ -15,6 +15,66 @@ export type NodeFlowJsonValue =
   | { [key: string]: NodeFlowJsonValue };
 export type NodeFlowJsonObject = { [key: string]: NodeFlowJsonValue };
 
+export const NODE_FLOW_SCHEMA_VERSION = 2 as const;
+export type NodeFlowSchemaVersion = typeof NODE_FLOW_SCHEMA_VERSION;
+
+export type NodeFlowPortDirection = "input" | "output";
+export type NodeFlowPortCardinality = "one" | "many";
+export type NodeFlowSideEffect = "none" | "read" | "write" | "external";
+
+export interface NodeFlowValueSchema {
+  type: "any" | "object" | "array" | "string" | "number" | "boolean" | "null";
+  description?: string;
+  required?: string[];
+  properties?: Record<string, NodeFlowValueSchema>;
+  items?: NodeFlowValueSchema;
+}
+
+export interface NodeFlowDefinitionReference {
+  type: string;
+  version: number;
+}
+
+export interface NodeFlowPort {
+  id: string;
+  direction: NodeFlowPortDirection;
+  schema: NodeFlowValueSchema;
+  required?: boolean;
+  cardinality?: NodeFlowPortCardinality;
+}
+
+export interface NodeFlowCredentialBinding {
+  slot: string;
+  credentialId: string;
+}
+
+export interface NodeFlowRetryPolicy {
+  maxAttempts: number;
+  backoffMs: number;
+  maxBackoffMs?: number;
+}
+
+export interface NodeFlowTimeoutPolicy {
+  timeoutMs: number;
+}
+
+export interface NodeFlowExecutionPolicy {
+  retry?: NodeFlowRetryPolicy;
+  timeout?: NodeFlowTimeoutPolicy;
+}
+
+export interface NodeFlowPublicationMetadata {
+  publicationId: string;
+  publishedAt: string;
+  publishedBy: string;
+  sourceVersion: number;
+}
+
+export interface NodeFlowSchemas {
+  input?: NodeFlowValueSchema;
+  output?: NodeFlowValueSchema;
+}
+
 export interface NodeWidgetSelectOption {
   label: string;
   value: string | number | boolean;
@@ -51,6 +111,13 @@ export interface NodeFlowNode {
   widgetSchema?: NodeWidgetSchema;
   position?: NodeFlowNodePosition;
   data?: NodeFlowJsonObject;
+  definition?: NodeFlowDefinitionReference;
+  ports?: NodeFlowPort[];
+  credentialBindings?: NodeFlowCredentialBinding[];
+  policy?: NodeFlowExecutionPolicy;
+  capabilities?: string[];
+  sideEffect?: NodeFlowSideEffect;
+  disabled?: boolean;
 }
 
 export interface NodeFlowEdge {
@@ -62,10 +129,13 @@ export interface NodeFlowEdge {
 }
 
 export interface NodeFlowGraph {
+  schemaVersion?: NodeFlowSchemaVersion;
   nodes: NodeFlowNode[];
   edges: NodeFlowEdge[];
   inputSchema?: NodeWidgetSchema;
+  schemas?: NodeFlowSchemas;
   metadata?: NodeFlowJsonObject;
+  publication?: Readonly<NodeFlowPublicationMetadata>;
 }
 
 export interface NodeFlowRecord {
diff --git a/src/domain/node-flows/node-definition-registry.ts b/src/domain/node-flows/node-definition-registry.ts
new file mode 100644
index 0000000000..498c0fc1d4
--- /dev/null
+++ b/src/domain/node-flows/node-definition-registry.ts
@@ -0,0 +1,91 @@
+import type { NodeDefinitionManifest } from "../../contracts/node-definition-types.js";
+import type { NodeFlowPort, NodeFlowValueSchema, NodeWidgetField } from "../../contracts/node-flow-types.js";
+
+const objectSchema = (required: string[] = [], properties: Record<string, NodeFlowValueSchema> = {}) => ({
+  type: "object" as const,
+  ...(required.length > 0 ? { required } : {}),
+  ...(Object.keys(properties).length > 0 ? { properties } : {}),
+});
+
+const dataPort = (id: string, direction: "input" | "output", required = false): NodeFlowPort => ({
+  id,
+  direction,
+  schema: { type: "object" },
+  required,
+  cardinality: direction === "input" ? "many" : "one",
+});
+
+const field = (
+  id: string,
+  label: string,
+  type: NodeWidgetField["type"],
+  required = false,
+): NodeWidgetField => ({ id, label, type, required });
+
+const manifests: NodeDefinitionManifest[] = [
+  {
+    type: "input", version: 1, executable: true, executionKind: "local",
+    configurationSchema: objectSchema(),
+    ui: { label: "Input", description: "Emits the flow input.", category: "control", widgetSchema: { fields: [] } },
+    ports: [dataPort("output", "output")], credentials: [], capabilities: [], sideEffect: "none",
+    defaultPolicy: { retry: { maxAttempts: 1, backoffMs: 0 } }, documentation: "docs/architecture/node-flows.md#runtime",
+    deprecation: { deprecated: false },
+  },
+  {
+    type: "set_fields", version: 1, executable: true, executionKind: "local",
+    configurationSchema: objectSchema([], { fields: { type: "object" }, values: { type: "object" }, replace: { type: "boolean" } }),
+    ui: { label: "Set fields", description: "Adds or replaces object fields.", category: "transform", widgetSchema: { fields: [field("fields", "Fields", "json")] } },
+    ports: [dataPort("input", "input"), dataPort("output", "output")], credentials: [], capabilities: [], sideEffect: "none",
+    defaultPolicy: { retry: { maxAttempts: 1, backoffMs: 0 } }, documentation: "docs/architecture/node-flows.md#runtime",
+    deprecation: { deprecated: false },
+  },
+  {
+    type: "template", version: 1, executable: true, executionKind: "local",
+    configurationSchema: objectSchema(["template"], { template: { type: "string" }, prompt: { type: "string" }, outputKey: { type: "string" } }),
+    ui: { label: "Template", description: "Renders a deterministic text template.", category: "transform", widgetSchema: { fields: [field("template", "Template", "textarea", true), field("outputKey", "Output key", "text")] } },
+    ports: [dataPort("input", "input"), dataPort("output", "output")], credentials: [], capabilities: [], sideEffect: "none",
+    defaultPolicy: { retry: { maxAttempts: 1, backoffMs: 0 } }, documentation: "docs/architecture/node-flows.md#runtime",
+    deprecation: { deprecated: false },
+  },
+  {
+    type: "provider_prompt", version: 1, executable: true, executionKind: "provider",
+    configurationSchema: objectSchema(["prompt"], { prompt: { type: "string" }, template: { type: "string" }, provider: { type: "string" } }),
+    ui: { label: "Provider prompt", description: "Runs a prompt through a configured CLI provider.", category: "ai", widgetSchema: { fields: [field("prompt", "Prompt", "textarea", true), field("provider", "Provider", "text")] } },
+    ports: [dataPort("input", "input"), dataPort("output", "output")],
+    credentials: [{ slot: "provider", label: "Provider connection", required: false, allowedKinds: ["provider"] }],
+    capabilities: ["provider.execute"], sideEffect: "external",
+    defaultPolicy: { retry: { maxAttempts: 1, backoffMs: 0 } }, documentation: "docs/architecture/node-flows.md#runtime",
+    deprecation: { deprecated: false },
+  },
+  {
+    type: "http_request", version: 1, executable: true, executionKind: "http",
+    configurationSchema: objectSchema(["url"], { url: { type: "string" }, method: { type: "string" }, timeoutMs: { type: "number" }, headers: { type: "object" } }),
+    ui: { label: "HTTP request", description: "Calls a bounded HTTP or HTTPS endpoint.", category: "integration", widgetSchema: { fields: [field("url", "URL", "text", true), field("method", "Method", "text")] } },
+    ports: [dataPort("input", "input"), dataPort("output", "output")],
+    credentials: [{ slot: "auth", label: "HTTP credential", required: false, allowedKinds: ["http"] }],
+    capabilities: ["network.http"], sideEffect: "external",
+    defaultPolicy: { retry: { maxAttempts: 1, backoffMs: 0 }, timeout: { timeoutMs: 30_000 } }, documentation: "docs/architecture/node-flows.md#runtime",
+    deprecation: { deprecated: false },
+  },
+  {
+    type: "output", version: 1, executable: true, executionKind: "local",
+    configurationSchema: objectSchema(),
+    ui: { label: "Output", description: "Selects the flow result.", category: "control", widgetSchema: { fields: [] } },
+    ports: [dataPort("input", "input")], credentials: [], capabilities: [], sideEffect: "none",
+    defaultPolicy: { retry: { maxAttempts: 1, backoffMs: 0 } }, documentation: "docs/architecture/node-flows.md#runtime",
+    deprecation: { deprecated: false },
+  },
+];
+
+const keyFor = (type: string, version: number): string => `${type}@${version}`;
+const registry = new Map(manifests.map((manifest) => [keyFor(manifest.type, manifest.version), manifest]));
+
+export const listNodeDefinitions = (): readonly NodeDefinitionManifest[] => manifests;
+
+export const resolveNodeDefinition = (type: string, version: number): NodeDefinitionManifest | null => (
+  registry.get(keyFor(type, version)) ?? null
+);
+
+export const resolveLatestNodeDefinition = (type: string): NodeDefinitionManifest | null => (
+  manifests.filter((manifest) => manifest.type === type).sort((left, right) => right.version - left.version)[0] ?? null
+);
diff --git a/src/domain/node-flows/node-flow-migrators.ts b/src/domain/node-flows/node-flow-migrators.ts
new file mode 100644
index 0000000000..527ae746c3
--- /dev/null
+++ b/src/domain/node-flows/node-flow-migrators.ts
@@ -0,0 +1,110 @@
+import {
+  NODE_FLOW_SCHEMA_VERSION,
+  type NodeFlowGraph,
+  type NodeFlowJsonObject,
+  type NodeFlowJsonValue,
+  type NodeFlowNode,
+} from "../../contracts/node-flow-types.js";
+import { resolveLatestNodeDefinition } from "./node-definition-registry.js";
+
+export interface NodeFlowMigrationResult<TLegacy = unknown> {
+  graph: NodeFlowGraph;
+  migrated: boolean;
+  legacySnapshot: TLegacy | null;
+}
+
+const cloneJson = <T>(value: T): T => JSON.parse(JSON.stringify(value)) as T;
+
+export function migrateNodeFlowGraph(graph: unknown): NodeFlowMigrationResult<NodeFlowGraph> {
+  if (isRecord(graph) && graph.schemaVersion === NODE_FLOW_SCHEMA_VERSION) {
+    return { graph: cloneJson(graph as unknown as NodeFlowGraph), migrated: false, legacySnapshot: null };
+  }
+
+  const legacy = isRecord(graph) ? cloneJson(graph as unknown as NodeFlowGraph) : { nodes: [], edges: [] };
+  const nodes = Array.isArray(legacy.nodes) ? legacy.nodes.map(migrateNode) : [];
+  const definitionByNode = new Map(nodes.map((node) => [node.id, resolveLatestNodeDefinition(node.type)]));
+  const edges = Array.isArray(legacy.edges) ? legacy.edges.map((edge) => ({
+    ...edge,
+    ...(edge.fromHandle ? {} : { fromHandle: definitionByNode.get(edge.fromNodeId)?.ports.find((port) => port.direction === "output")?.id }),
+    ...(edge.toHandle ? {} : { toHandle: definitionByNode.get(edge.toNodeId)?.ports.find((port) => port.direction === "input")?.id }),
+  })) : [];
+
+  return {
+    migrated: true,
+    legacySnapshot: legacy,
+    graph: {
+      schemaVersion: NODE_FLOW_SCHEMA_VERSION,
+      nodes,
+      edges,
+      ...(legacy.inputSchema ? { inputSchema: legacy.inputSchema } : {}),
+      ...(legacy.schemas ? { schemas: legacy.schemas } : {}),
+      ...(legacy.metadata ? { metadata: legacy.metadata } : {}),
+      ...(legacy.publication ? { publication: legacy.publication } : {}),
+    },
+  };
+}
+
+function migrateNode(node: NodeFlowNode): NodeFlowNode {
+  const definition = node.definition
+    ? resolveLatestNodeDefinition(node.definition.type)
+    : resolveLatestNodeDefinition(node.type);
+  return {
+    ...node,
+    definition: node.definition ?? { type: node.type, version: definition?.version ?? 1 },
+    ports: node.ports ?? definition?.ports.map((port) => cloneJson(port)) ?? [],
+    credentialBindings: node.credentialBindings ?? [],
+    policy: node.policy ?? (definition ? cloneJson(definition.defaultPolicy) : {}),
+    capabilities: node.capabilities ?? [...(definition?.capabilities ?? [])],
+    sideEffect: node.sideEffect ?? definition?.sideEffect ?? "none",
+    disabled: node.disabled ?? false,
+  };
+}
+
+export function migrateNodeCanvasGraphV1(graph: unknown): NodeFlowMigrationResult<unknown> {
+  if (isRecord(graph) && graph.schemaVersion === NODE_FLOW_SCHEMA_VERSION && Array.isArray(graph.nodes) && graph.nodes.every(isCanonicalNode)) {
+    return migrateNodeFlowGraph(graph);
+  }
+  const legacySnapshot = cloneJson(graph);
+  const legacy = isRecord(graph) ? graph : {};
+  const nodes = Array.isArray(legacy.nodes) ? legacy.nodes.filter(isRecord).map((node): NodeFlowNode => ({
+    id: stringValue(node.id),
+    type: stringValue(node.kind) || stringValue(node.type),
+    title: stringValue(node.label) || stringValue(node.title) || stringValue(node.id),
+    description: stringValue(node.description) || undefined,
+    position: isPosition(node.position) ? { x: node.position.x, y: node.position.y } : undefined,
+    definition: { type: stringValue(node.kind) || stringValue(node.type), version: 1 },
+    ports: [...readPorts(node.inputPorts, "input"), ...readPorts(node.outputPorts, "output")],
+    data: canvasNodeData(node),
+    credentialBindings: [], policy: {}, capabilities: [], sideEffect: "none", disabled: false,
+  })).filter((node) => node.id && node.type) : [];
+  const edges = Array.isArray(legacy.edges) ? legacy.edges.filter(isRecord).map((edge) => ({
+    id: stringValue(edge.id) || undefined,
+    fromNodeId: endpointValue(edge.source, "nodeId"),
+    toNodeId: endpointValue(edge.target, "nodeId"),
+    fromHandle: endpointValue(edge.source, "portId") || undefined,
+    toHandle: endpointValue(edge.target, "portId") || undefined,
+  })).filter((edge) => edge.fromNodeId && edge.toNodeId) : [];
+  return {
+    migrated: true,
+    legacySnapshot,
+    graph: { schemaVersion: NODE_FLOW_SCHEMA_VERSION, nodes, edges, metadata: { canvasSelection: jsonValue(legacy.selection) } },
+  };
+}
+
+function readPorts(value: unknown, direction: "input" | "output") {
+  return Array.isArray(value) ? value.filter(isRecord).map((port) => ({
+    id: stringValue(port.id), direction, schema: { type: "any" as const }, required: port.required === true,
+  })).filter((port) => port.id) : [];
+}
+
+function canvasNodeData(node: Record<string, unknown>): NodeFlowJsonObject {
+  const config = Array.isArray(node.config) ? Object.fromEntries(node.config.filter(isRecord).map((entry) => [stringValue(entry.id), jsonValue(entry.value)]).filter(([id]) => id)) : {};
+  return { config, canvasMetadata: jsonValue(node.metadata) };
+}
+
+const jsonValue = (value: unknown): NodeFlowJsonValue => JSON.parse(JSON.stringify(value ?? null)) as NodeFlowJsonValue;
+const endpointValue = (value: unknown, key: string): string => isRecord(value) ? stringValue(value[key]) : "";
+const stringValue = (value: unknown): string => typeof value === "string" ? value : "";
+const isRecord = (value: unknown): value is Record<string, unknown> => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const isPosition = (value: unknown): value is { x: number; y: number } => isRecord(value) && Number.isFinite(value.x) && Number.isFinite(value.y);
+const isCanonicalNode = (value: unknown): boolean => isRecord(value) && isRecord(value.definition);
diff --git a/src/domain/node-flows/node-flow-validation.ts b/src/domain/node-flows/node-flow-validation.ts
index 0b5d2cbf77..ad98c35254 100644
--- a/src/domain/node-flows/node-flow-validation.ts
+++ b/src/domain/node-flows/node-flow-validation.ts
@@ -2,14 +2,23 @@ import { ValidationError } from "../../repositories/repository-utils.js";
 import type {
   NodeFlowEdge,
   NodeFlowGraph,
+  NodeFlowJsonObject,
   NodeFlowJsonValue,
   NodeFlowNode,
   NodeFlowValidationIssue,
   NodeFlowValidationResponse,
+  NodeFlowValueSchema,
   NodeWidgetField,
   NodeWidgetFieldType,
   NodeWidgetSchema,
 } from "../../contracts/node-flow-types.js";
+import { NODE_FLOW_SCHEMA_VERSION } from "../../contracts/node-flow-types.js";
+import { migrateNodeFlowGraph } from "./node-flow-migrators.js";
+import { resolveNodeDefinition } from "./node-definition-registry.js";
+
+const MAX_GRAPH_NODES = 250;
+const MAX_GRAPH_EDGES = 1_000;
+const FORBIDDEN_GRAPH_KEY = /^(?:sourceCode|generatedSource|code|script|apiKey|authorization|cookie|password|secret|token)$/i;
 
 const WIDGET_FIELD_TYPES = new Set<NodeWidgetFieldType>([
   "text",
@@ -243,6 +252,78 @@ function normalizeWidgetSchema(
   return { fields: normalizedFields };
 }
 
+function containsForbiddenGraphValue(value: NodeFlowJsonValue): boolean {
+  if (Array.isArray(value)) return value.some(containsForbiddenGraphValue);
+  if (!value || typeof value !== "object") return false;
+  return Object.entries(value).some(([key, entry]) => FORBIDDEN_GRAPH_KEY.test(key) || containsForbiddenGraphValue(entry));
+}
+
+function validatePolicy(
+  policy: NodeFlowNode["policy"],
+  path: string,
+  issues: NodeFlowValidationIssue[],
+): void {
+  if (!policy) return;
+  const retry = policy.retry;
+  if (retry && (!Number.isInteger(retry.maxAttempts) || retry.maxAttempts < 1 || retry.maxAttempts > 10)) {
+    issues.push(issue(`${path}.retry.maxAttempts`, "invalid_retry_policy", "Retry maxAttempts must be an integer from 1 to 10."));
+  }
+  if (retry && (!Number.isFinite(retry.backoffMs) || retry.backoffMs < 0 || retry.backoffMs > 300_000)) {
+    issues.push(issue(`${path}.retry.backoffMs`, "invalid_retry_policy", "Retry backoffMs must be between 0 and 300000."));
+  }
+  if (retry?.maxBackoffMs !== undefined && (!Number.isFinite(retry.maxBackoffMs) || retry.maxBackoffMs < retry.backoffMs)) {
+    issues.push(issue(`${path}.retry.maxBackoffMs`, "invalid_retry_policy", "Retry maxBackoffMs must be at least backoffMs."));
+  }
+  if (policy.timeout && (!Number.isInteger(policy.timeout.timeoutMs) || policy.timeout.timeoutMs < 1 || policy.timeout.timeoutMs > 300_000)) {
+    issues.push(issue(`${path}.timeout.timeoutMs`, "invalid_timeout_policy", "Timeout must be an integer from 1 to 300000 milliseconds."));
+  }
+}
+
+function validateCredentialBindings(
+  node: NodeFlowNode,
+  nodePath: string,
+  allowedSlots: string[],
+  issues: NodeFlowValidationIssue[],
+): void {
+  const slots = new Set<string>();
+  (node.credentialBindings ?? []).forEach((binding, index) => {
+    const path = `${nodePath}.credentialBindings[${index}]`;
+    if (!trimmedString(binding.slot)) issues.push(issue(`${path}.slot`, "required", "Credential slot is required."));
+    if (!trimmedString(binding.credentialId)) issues.push(issue(`${path}.credentialId`, "required", "Credential binding must reference a credential id."));
+    if (slots.has(binding.slot)) issues.push(issue(`${path}.slot`, "duplicate_credential_slot", `Duplicate credential slot: ${binding.slot}`));
+    if (!allowedSlots.includes(binding.slot)) issues.push(issue(`${path}.slot`, "unknown_credential_slot", `Definition does not declare credential slot: ${binding.slot}`));
+    slots.add(binding.slot);
+  });
+}
+
+function validateConfiguration(
+  data: NodeFlowJsonObject,
+  schema: NodeFlowValueSchema,
+  nodePath: string,
+  issues: NodeFlowValidationIssue[],
+): void {
+  const values = isPlainJsonObject(data.values) ? data.values : {};
+  for (const key of schema.required ?? []) {
+    const aliases = key === "template" || key === "prompt" ? ["template", "prompt"] : [key];
+    const present = aliases.some((alias) => data[alias] !== undefined || values[alias] !== undefined);
+    if (!present) issues.push(issue(`${nodePath}.data.${key}`, "required_configuration", `Node configuration requires ${key}.`));
+  }
+  for (const [key, propertySchema] of Object.entries(schema.properties ?? {})) {
+    const value = data[key] ?? values[key];
+    if (value !== undefined && !matchesValueSchema(value, propertySchema.type)) {
+      issues.push(issue(`${nodePath}.data.${key}`, "invalid_configuration_type", `Node configuration ${key} must be ${propertySchema.type}.`));
+    }
+  }
+}
+
+function matchesValueSchema(value: NodeFlowJsonValue, type: NodeFlowValueSchema["type"]): boolean {
+  if (type === "any") return true;
+  if (type === "null") return value === null;
+  if (type === "array") return Array.isArray(value);
+  if (type === "object") return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+  return typeof value === type;
+}
+
 function normalizeNode(rawNode: NodeFlowNode, index: number, issues: NodeFlowValidationIssue[]): NodeFlowNode | null {
   const nodePath = `nodes[${index}]`;
   if (!rawNode || typeof rawNode !== "object" || Array.isArray(rawNode)) {
@@ -280,6 +361,36 @@ function normalizeNode(rawNode: NodeFlowNode, index: number, issues: NodeFlowVal
     issues.push(issue(`${nodePath}.data`, "invalid_data", `Node ${id} data must be a JSON object.`));
   }
 
+  const definitionRef = rawNode.definition ?? { type, version: 1 };
+  const definition = resolveNodeDefinition(definitionRef.type, definitionRef.version);
+  if (definitionRef.type !== type) {
+    issues.push(issue(`${nodePath}.definition.type`, "definition_type_mismatch", "Node type must match its definition reference."));
+  }
+  if (!definition) {
+    issues.push(issue(`${nodePath}.definition`, "unknown_node_definition", `Unknown node definition: ${definitionRef.type}@${definitionRef.version}`));
+  }
+  if (definition && rawNode.sideEffect !== undefined && rawNode.sideEffect !== definition.sideEffect) {
+    issues.push(issue(`${nodePath}.sideEffect`, "definition_metadata_mismatch", "Node side effect must match its definition."));
+  }
+  if (definition && rawNode.capabilities !== undefined && [...rawNode.capabilities].sort().join("\0") !== [...definition.capabilities].sort().join("\0")) {
+    issues.push(issue(`${nodePath}.capabilities`, "definition_metadata_mismatch", "Node capabilities must match its definition."));
+  }
+  const ports = rawNode.ports ?? definition?.ports ?? [];
+  const portIds = new Set<string>();
+  ports.forEach((port, portIndex) => {
+    const portPath = `${nodePath}.ports[${portIndex}]`;
+    if (!trimmedString(port.id)) issues.push(issue(`${portPath}.id`, "required", "Port id is required."));
+    if (portIds.has(port.id)) issues.push(issue(`${portPath}.id`, "duplicate_port_id", `Duplicate port id: ${port.id}`));
+    portIds.add(port.id);
+    if (port.direction !== "input" && port.direction !== "output") issues.push(issue(`${portPath}.direction`, "invalid_port_direction", "Port direction must be input or output."));
+  });
+  validatePolicy(rawNode.policy, `${nodePath}.policy`, issues);
+  validateCredentialBindings(rawNode, nodePath, definition?.credentials.map((credential) => credential.slot) ?? [], issues);
+  if (rawNode.data && containsForbiddenGraphValue(rawNode.data)) {
+    issues.push(issue(`${nodePath}.data`, "unsafe_graph_data", "Graph data cannot contain raw secrets or custom source code."));
+  }
+  if (definition) validateConfiguration(isPlainJsonObject(rawNode.data) ? rawNode.data : {}, definition.configurationSchema, nodePath, issues);
+
   return {
     id,
     type,
@@ -288,6 +399,13 @@ function normalizeNode(rawNode: NodeFlowNode, index: number, issues: NodeFlowVal
     ...(widgetSchema ? { widgetSchema } : {}),
     ...(position ? { position } : {}),
     ...(rawNode.data !== undefined && isPlainJsonObject(rawNode.data) ? { data: rawNode.data } : {}),
+    definition: definitionRef,
+    ports,
+    credentialBindings: rawNode.credentialBindings ?? [],
+    policy: rawNode.policy ?? definition?.defaultPolicy ?? {},
+    capabilities: definition?.capabilities ?? rawNode.capabilities ?? [],
+    sideEffect: definition?.sideEffect ?? rawNode.sideEffect ?? "none",
+    disabled: rawNode.disabled ?? false,
   };
 }
 
@@ -329,16 +447,17 @@ function computeExecutionOrder(
     inDegree.set(edge.toNodeId, (inDegree.get(edge.toNodeId) ?? 0) + 1);
   }
 
-  const ready = nodes.filter((node) => inDegree.get(node.id) === 0).map((node) => node.id);
+  const ready = nodes.filter((node) => inDegree.get(node.id) === 0).map((node) => node.id).sort();
   const order: string[] = [];
   while (ready.length > 0) {
     const nodeId = ready.shift()!;
     order.push(nodeId);
-    for (const nextId of outgoing.get(nodeId) ?? []) {
+    for (const nextId of [...(outgoing.get(nodeId) ?? [])].sort()) {
       const nextInDegree = (inDegree.get(nextId) ?? 0) - 1;
       inDegree.set(nextId, nextInDegree);
       if (nextInDegree === 0) {
         ready.push(nextId);
+        ready.sort();
       }
     }
   }
@@ -363,13 +482,20 @@ export function validateNodeFlowGraph(graph: unknown): NodeFlowValidationRespons
     };
   }
 
-  const rawGraph = graph as NodeFlowGraph;
+  const migration = migrateNodeFlowGraph(graph);
+  const rawGraph = migration.graph;
   if (!Array.isArray(rawGraph.nodes)) {
     issues.push(issue("nodes", "required", "Node flow graph requires a nodes array."));
   }
   if (!Array.isArray(rawGraph.edges)) {
     issues.push(issue("edges", "required", "Node flow graph requires an edges array."));
   }
+  if (Array.isArray(rawGraph.nodes) && rawGraph.nodes.length > MAX_GRAPH_NODES) {
+    issues.push(issue("nodes", "graph_limit_exceeded", `Node flow graph supports at most ${MAX_GRAPH_NODES} nodes.`));
+  }
+  if (Array.isArray(rawGraph.edges) && rawGraph.edges.length > MAX_GRAPH_EDGES) {
+    issues.push(issue("edges", "graph_limit_exceeded", `Node flow graph supports at most ${MAX_GRAPH_EDGES} edges.`));
+  }
 
   const nodes = Array.isArray(rawGraph.nodes)
     ? rawGraph.nodes.map((node, index) => normalizeNode(node, index, issues)).filter((node): node is NodeFlowNode => Boolean(node))
@@ -397,18 +523,33 @@ export function validateNodeFlowGraph(graph: unknown): NodeFlowValidationRespons
     if (!nodeIds.has(edge.toNodeId)) {
       issues.push(issue(`edges[${index}].toNodeId`, "invalid_edge_endpoint", `Edge target node does not exist: ${edge.toNodeId}`));
     }
+    const source = nodes.find((node) => node.id === edge.fromNodeId);
+    const target = nodes.find((node) => node.id === edge.toNodeId);
+    if (source && edge.fromHandle && !source.ports?.some((port) => port.id === edge.fromHandle && port.direction === "output")) {
+      issues.push(issue(`edges[${index}].fromHandle`, "invalid_source_port", `Source port does not exist or is not an output: ${edge.fromHandle}`));
+    }
+    if (target && edge.toHandle && !target.ports?.some((port) => port.id === edge.toHandle && port.direction === "input")) {
+      issues.push(issue(`edges[${index}].toHandle`, "invalid_target_port", `Target port does not exist or is not an input: ${edge.toHandle}`));
+    }
   });
 
   const inputSchema = normalizeWidgetSchema(rawGraph.inputSchema, "inputSchema", issues);
   if (rawGraph.metadata !== undefined && !isPlainJsonObject(rawGraph.metadata)) {
     issues.push(issue("metadata", "invalid_metadata", "Node flow graph metadata must be a JSON object."));
   }
+  if (rawGraph.metadata && containsForbiddenGraphValue(rawGraph.metadata)) {
+    issues.push(issue("metadata", "unsafe_graph_metadata", "Graph metadata cannot contain raw secrets or custom source code."));
+  }
+  validatePublication(rawGraph.publication, issues);
 
   const normalizedGraph: NodeFlowGraph = {
+    schemaVersion: NODE_FLOW_SCHEMA_VERSION,
     nodes,
     edges,
     ...(inputSchema ? { inputSchema } : {}),
+    ...(rawGraph.schemas ? { schemas: rawGraph.schemas } : {}),
     ...(rawGraph.metadata !== undefined && isPlainJsonObject(rawGraph.metadata) ? { metadata: rawGraph.metadata } : {}),
+    ...(rawGraph.publication ? { publication: rawGraph.publication } : {}),
   };
   const executionOrder = computeExecutionOrder(nodes, edges, issues);
   const valid = issues.length === 0;
@@ -419,6 +560,21 @@ export function validateNodeFlowGraph(graph: unknown): NodeFlowValidationRespons
   };
 }
 
+function validatePublication(
+  publication: NodeFlowGraph["publication"],
+  issues: NodeFlowValidationIssue[],
+): void {
+  if (!publication) return;
+  if (!trimmedString(publication.publicationId)) issues.push(issue("publication.publicationId", "required", "Publication id is required."));
+  if (!trimmedString(publication.publishedBy)) issues.push(issue("publication.publishedBy", "required", "Publication author is required."));
+  if (!trimmedString(publication.publishedAt) || !Number.isFinite(Date.parse(publication.publishedAt))) {
+    issues.push(issue("publication.publishedAt", "invalid_publication", "Publication timestamp must be ISO-compatible."));
+  }
+  if (!Number.isInteger(publication.sourceVersion) || publication.sourceVersion < 1) {
+    issues.push(issue("publication.sourceVersion", "invalid_publication", "Publication sourceVersion must be a positive integer."));
+  }
+}
+
 export function normalizeNodeFlowGraph(graph: unknown): NormalizedNodeFlowValidation {
   const result = validateNodeFlowGraph(graph);
   if (!result.valid || !result.graph || !result.executionOrder) {
diff --git a/src/repositories/db/app-db-migrations.ts b/src/repositories/db/app-db-migrations.ts
index 5cde8f7975..b874fd2de6 100644
--- a/src/repositories/db/app-db-migrations.ts
+++ b/src/repositories/db/app-db-migrations.ts
@@ -1,4 +1,5 @@
 import { DatabaseAdapter } from "./database-adapter.js";
+import { migrateNodeFlowGraph } from "../../domain/node-flows/node-flow-migrators.js";
 
 export function ensureColumn(db: DatabaseAdapter, tableName: string, columnName: string, columnDefinition: string): void {
   // Using direct sqlite PRAGMA for now, until we abstract schema reflections
@@ -267,6 +268,50 @@ export function ensureNodeFlowTables(db: DatabaseAdapter): void {
   ensureIndex(db, "idx_node_flow_node_runs_run_created", "node_flow_node_runs", "run_id, created_at ASC");
 }
 
+interface LegacyNodeFlowRow {
+  id: string;
+  project_id: string;
+  title: string;
+  description: string | null;
+  graph_json: string;
+  version: number | string;
+  updated_at: string;
+}
+
+export function migratePersistedNodeFlowGraphs(db: DatabaseAdapter): void {
+  const rows = db.prepare("SELECT id, project_id, title, description, graph_json, version, updated_at FROM node_flows ORDER BY id ASC")
+    .all() as unknown as LegacyNodeFlowRow[];
+  for (const row of rows) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(row.graph_json);
+    } catch {
+      continue;
+    }
+    const migration = migrateNodeFlowGraph(parsed);
+    if (!migration.migrated) continue;
+    const currentVersion = Number(row.version);
+    const nextVersion = currentVersion + 1;
+    const migratedJson = JSON.stringify(migration.graph);
+    db.transaction(() => {
+      const originalExists = db.prepare("SELECT id FROM node_flow_versions WHERE flow_id = ? AND version = ?")
+        .get(row.id, currentVersion);
+      if (!originalExists) {
+        db.prepare(`
+          INSERT INTO node_flow_versions (id, flow_id, project_id, version, title, description, graph_json, created_at)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        `).run(`${row.id}:v${currentVersion}:legacy`, row.id, row.project_id, currentVersion, row.title, row.description ?? "", row.graph_json, row.updated_at);
+      }
+      db.prepare(`
+        INSERT INTO node_flow_versions (id, flow_id, project_id, version, title, description, graph_json, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(`${row.id}:v${nextVersion}:schema-v2`, row.id, row.project_id, nextVersion, row.title, row.description ?? "", migratedJson, row.updated_at);
+      db.prepare("UPDATE node_flows SET graph_json = ?, version = ? WHERE id = ?")
+        .run(migratedJson, nextVersion, row.id);
+    });
+  }
+}
+
 export function ensureCustomDashboardTables(db: DatabaseAdapter): void {
   db.exec(`
     CREATE TABLE IF NOT EXISTS custom_dashboards (
@@ -580,6 +625,7 @@ export function runMigrations(db: DatabaseAdapter): void {
   ensureTaskSelfReflectionRatingTables(db);
   ensureConversationDraftTables(db);
   ensureNodeFlowTables(db);
+  migratePersistedNodeFlowGraphs(db);
   ensureCustomDashboardTables(db);
 
   ensureColumn(db, "projects", "initialization_mode", "TEXT NOT NULL DEFAULT 'existing'");
diff --git a/src/repositories/node-flow-repository.ts b/src/repositories/node-flow-repository.ts
index f5df530558..faf2e5ae48 100644
--- a/src/repositories/node-flow-repository.ts
+++ b/src/repositories/node-flow-repository.ts
@@ -20,6 +20,7 @@ import type {
   UpdateNodeFlowInput,
   UpdateNodeFlowRunInput,
 } from "../contracts/node-flow-types.js";
+import { migratePersistedNodeFlowGraphs } from "./db/app-db-migrations.js";
 
 interface NodeFlowRow {
   id: string;
@@ -96,6 +97,7 @@ export class NodeFlowRepository {
     private readonly realtimeNotifier?: DashboardRealtimeMutationNotifier,
   ) {
     this.db = storage.getDatabase();
+    migratePersistedNodeFlowGraphs(this.db);
   }
 
   listFlows(projectId: string): NodeFlowRecord[] {
diff --git a/src/services/node-flow-runtime-service.ts b/src/services/node-flow-runtime-service.ts
index 3ff01dbd70..d99082ef0b 100644
--- a/src/services/node-flow-runtime-service.ts
+++ b/src/services/node-flow-runtime-service.ts
@@ -1,5 +1,6 @@
 import { randomUUID } from "crypto";
 import { normalizeNodeFlowGraph } from "../domain/node-flows/node-flow-validation.js";
+import { resolveNodeDefinition } from "../domain/node-flows/node-definition-registry.js";
 import { ValidationError, EntityNotFoundError } from "../repositories/repository-utils.js";
 import { DEFAULT_DASHBOARD_SETTINGS } from "../repositories/settings-defaults.js";
 import type { NodeFlowRepository } from "../repositories/node-flow-repository.js";
@@ -26,7 +27,6 @@ import type {
   RunNodeFlowOptions,
 } from "../contracts/node-flow-types.js";
 
-const SUPPORTED_NODE_TYPES = new Set(["input", "set_fields", "template", "provider_prompt", "http_request", "output"]);
 const EXTERNALLY_OBSERVABLE_NODE_TYPES = new Set(["provider_prompt", "http_request"]);
 const CLI_PROVIDER_IDS = new Set<ProviderId>(["gemini", "codex", "claude-code", "qwen-code", "opencode", "antigravity", "mockup-cli"]);
 const SECRET_KEY_PATTERN = /(api[_-]?key|authorization|cookie|password|secret|token)/i;
@@ -148,6 +148,10 @@ export class NodeFlowRuntimeService {
         await this.persistSkippedNode(context, node, "skipped", "Skipped because an upstream node failed.");
         continue;
       }
+      if (node.disabled) {
+        await this.persistSkippedNode(context, node, "skipped", "Skipped because the node is disabled.");
+        continue;
+      }
 
       const nodeRun = this.deps.nodeFlowRepository.createNodeRun({
         runId: run.id,
@@ -234,7 +238,10 @@ export class NodeFlowRuntimeService {
   }
 
   private requireSupportedNodes(graph: NodeFlowGraph): void {
-    const unsupported = graph.nodes.filter((node) => !SUPPORTED_NODE_TYPES.has(node.type));
+    const unsupported = graph.nodes.filter((node) => {
+      const reference = node.definition ?? { type: node.type, version: 1 };
+      return resolveNodeDefinition(reference.type, reference.version)?.executable !== true;
+    });
     if (unsupported.length > 0) {
       throw new ValidationError(`Unsupported node flow node type: ${unsupported[0]!.type}.`);
     }
diff --git a/tests/backend/domain/node-flows/node-definition-registry.test.ts b/tests/backend/domain/node-flows/node-definition-registry.test.ts
new file mode 100644
index 0000000000..fd4fdefe02
--- /dev/null
+++ b/tests/backend/domain/node-flows/node-definition-registry.test.ts
@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import { listNodeDefinitions, resolveNodeDefinition } from "../../../../src/domain/node-flows/node-definition-registry.js";
+
+describe("node definition registry", () => {
+  it("registers only the six implemented executable node types", () => {
+    expect(listNodeDefinitions().filter((definition) => definition.executable).map((definition) => definition.type)).toEqual([
+      "input", "set_fields", "template", "provider_prompt", "http_request", "output",
+    ]);
+    expect(resolveNodeDefinition("condition", 1)).toBeNull();
+    expect(resolveNodeDefinition("http_request", 1)).toMatchObject({
+      executionKind: "http",
+      sideEffect: "external",
+      capabilities: ["network.http"],
+      defaultPolicy: { timeout: { timeoutMs: 30_000 } },
+    });
+  });
+});
diff --git a/tests/backend/domain/node-flows/node-flow-migrators.test.ts b/tests/backend/domain/node-flows/node-flow-migrators.test.ts
new file mode 100644
index 0000000000..5ee0b0727a
--- /dev/null
+++ b/tests/backend/domain/node-flows/node-flow-migrators.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import { migrateNodeCanvasGraphV1, migrateNodeFlowGraph } from "../../../../src/domain/node-flows/node-flow-migrators.js";
+
+describe("node flow migrators", () => {
+  it("deterministically migrates backend v1 while retaining an untouched snapshot", () => {
+    const legacy = { nodes: [{ id: "start", type: "input", title: "Start" }], edges: [] };
+    const first = migrateNodeFlowGraph(legacy);
+    const second = migrateNodeFlowGraph(legacy);
+
+    expect(first).toEqual(second);
+    expect(first.legacySnapshot).toEqual(legacy);
+    expect(first.graph).toMatchObject({
+      schemaVersion: 2,
+      nodes: [{ definition: { type: "input", version: 1 }, disabled: false, sideEffect: "none" }],
+    });
+    expect(legacy).toEqual({ nodes: [{ id: "start", type: "input", title: "Start" }], edges: [] });
+  });
+
+  it("migrates a browser v1 canvas into the canonical graph without embedding its snapshot", () => {
+    const legacy = {
+      nodes: [{ id: "trigger-1", kind: "trigger", label: "Trigger", description: "Draft", position: { x: 1, y: 2 }, inputPorts: [], outputPorts: [{ id: "event" }], config: [], metadata: {} }],
+      edges: [], selection: { nodeIds: ["trigger-1"], edgeIds: [] },
+    };
+    const result = migrateNodeCanvasGraphV1(legacy);
+
+    expect(result.legacySnapshot).toEqual(legacy);
+    expect(result.graph.schemaVersion).toBe(2);
+    expect(result.graph.metadata).toEqual({ canvasSelection: legacy.selection });
+    expect(JSON.stringify(result.graph)).not.toContain("legacySnapshot");
+  });
+});
diff --git a/tests/backend/domain/node-flows/node-flow-validation.test.ts b/tests/backend/domain/node-flows/node-flow-validation.test.ts
index c69d912574..2e56cc6bbb 100644
--- a/tests/backend/domain/node-flows/node-flow-validation.test.ts
+++ b/tests/backend/domain/node-flows/node-flow-validation.test.ts
@@ -15,8 +15,8 @@ const validGraph = (): NodeFlowGraph => ({
     ],
   },
   nodes: [
-    { id: "start", type: "prompt", title: "Start" },
-    { id: "finish", type: "agent", title: "Finish" },
+    { id: "start", type: "input", title: "Start" },
+    { id: "finish", type: "output", title: "Finish" },
   ],
   edges: [
     { fromNodeId: "start", toNodeId: "finish" },
@@ -43,7 +43,7 @@ describe("node flow validation", () => {
 
   it("rejects duplicate node ids and invalid edge endpoints", () => {
     const graph = validGraph();
-    graph.nodes.push({ id: "start", type: "agent", title: "Duplicate" });
+    graph.nodes.push({ id: "start", type: "output", title: "Duplicate" });
     graph.edges.push({ fromNodeId: "missing", toNodeId: "finish" });
 
     const result = validateNodeFlowGraph(graph);
@@ -81,4 +81,35 @@ describe("node flow validation", () => {
       "invalid_select_default",
     ]));
   });
+
+  it("rejects unknown definitions, invalid policies, and unsafe graph values with field paths", () => {
+    const graph = validGraph();
+    graph.nodes[0] = {
+      ...graph.nodes[0]!,
+      definition: { type: "planned_only", version: 1 },
+      policy: { retry: { maxAttempts: 0, backoffMs: -1 }, timeout: { timeoutMs: 0 } },
+      data: { generatedSource: "not allowed" },
+    };
+
+    const result = validateNodeFlowGraph(graph);
+
+    expect(result.errors).toEqual(expect.arrayContaining([
+      expect.objectContaining({ field: "nodes[0].definition", code: "unknown_node_definition" }),
+      expect.objectContaining({ field: "nodes[0].policy.retry.maxAttempts", code: "invalid_retry_policy" }),
+      expect.objectContaining({ field: "nodes[0].policy.timeout.timeoutMs", code: "invalid_timeout_policy" }),
+      expect.objectContaining({ field: "nodes[0].data", code: "unsafe_graph_data" }),
+    ]));
+  });
+
+  it("orders independent nodes deterministically by stable id", () => {
+    const graph: NodeFlowGraph = {
+      nodes: [
+        { id: "z", type: "input", title: "Z" },
+        { id: "a", type: "input", title: "A" },
+      ],
+      edges: [],
+    };
+
+    expect(validateNodeFlowGraph(graph).executionOrder).toEqual(["a", "z"]);
+  });
 });
diff --git a/tests/backend/repositories/node-flow-repository.test.ts b/tests/backend/repositories/node-flow-repository.test.ts
index a12202b9b0..af2b020b71 100644
--- a/tests/backend/repositories/node-flow-repository.test.ts
+++ b/tests/backend/repositories/node-flow-repository.test.ts
@@ -42,6 +42,24 @@ afterEach(async () => {
 });
 
 describe("NodeFlowRepository", () => {
+  it("persists a deterministic v2 migration as a new version and preserves v1 history", async () => {
+    const { dir, storage, projectRepository, nodeFlowRepository } = await createRepositories();
+    const project = projectRepository.createProject({ name: "Migration fixture", sourceType: "local", sourceRef: dir });
+    const flow = nodeFlowRepository.createFlow(project.id, { title: "Legacy flow", graph: graph() });
+    const original = JSON.stringify(graph());
+    storage.getDatabase().prepare("UPDATE node_flows SET graph_json = ?, version = 1 WHERE id = ?").run(original, flow.id);
+    storage.getDatabase().prepare("UPDATE node_flow_versions SET graph_json = ? WHERE flow_id = ? AND version = 1").run(original, flow.id);
+
+    const migratedRepository = new NodeFlowRepository(storage);
+    const migrated = migratedRepository.getFlow(flow.id);
+    const versions = migratedRepository.listVersions(flow.id);
+
+    expect(migrated).toMatchObject({ version: 2, graph: { schemaVersion: 2 } });
+    expect(versions.map((version) => version.version)).toEqual([2, 1]);
+    expect(versions[1]?.graph).toEqual(graph());
+    expect(new NodeFlowRepository(storage).getFlow(flow.id)).toEqual(migrated);
+  });
+
   it("creates, updates, versions, lists, and deletes node flows", async () => {
     const { dir, projectRepository, nodeFlowRepository } = await createRepositories();
     const project = projectRepository.createProject({
diff --git a/tests/backend/services/node-flow-service.test.ts b/tests/backend/services/node-flow-service.test.ts
index 1baad7dc66..1560a2d47b 100644
--- a/tests/backend/services/node-flow-service.test.ts
+++ b/tests/backend/services/node-flow-service.test.ts
@@ -28,7 +28,7 @@ async function createService(): Promise<{
 const validGraph = (): NodeFlowGraph => ({
   nodes: [
     { id: "input", type: "input", title: "Input" },
-    { id: "agent", type: "agent", title: "Agent" },
+    { id: "agent", type: "output", title: "Output" },
   ],
   edges: [{ fromNodeId: "input", toNodeId: "agent" }],
 });
diff --git a/tests/dashboard/lib/nodes-canvas-state.test.ts b/tests/dashboard/lib/nodes-canvas-state.test.ts
index 01ae403b9e..be3bb89561 100644
--- a/tests/dashboard/lib/nodes-canvas-state.test.ts
+++ b/tests/dashboard/lib/nodes-canvas-state.test.ts
@@ -4,6 +4,7 @@ import {
   createInitialNodeCanvasGraph,
   deserializeNodeCanvasGraph,
   layoutNodeCanvasGraph,
+  migrateNodeCanvasGraph,
   nodesCanvasReducer,
   serializeNodeCanvasGraph,
   validateNodeCanvasGraph,
@@ -196,6 +197,20 @@ describe("nodes canvas state", () => {
     expect(recovered.selection).toEqual({ nodeIds: ["agent-9"], edgeIds: ["edge-1"] });
   });
 
+  it("migrates legacy canvas snapshots deterministically without embedding the original", () => {
+    const current = createInitialNodeCanvasGraph();
+    const { schemaVersion: _schemaVersion, ...legacy } = current;
+    const first = migrateNodeCanvasGraph(legacy);
+    const second = migrateNodeCanvasGraph(legacy);
+
+    expect(first).toEqual(second);
+    expect(first.migrated).toBe(true);
+    expect(first.graph.schemaVersion).toBe(2);
+    expect(first.legacySnapshot).toEqual(legacy);
+    expect(JSON.stringify(first.graph)).not.toContain("legacySnapshot");
+    expect(migrateNodeCanvasGraph(first.graph)).toMatchObject({ migrated: false, legacySnapshot: null });
+  });
+
   it("lays out graphs deterministically from ids and edges", () => {
     const graph = {
       ...createInitialNodeCanvasGraph(),

From 83fa6f61cc14036e4702223d33bee90ea26815d1 Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 04:27:21 +0000
Subject: [PATCH 02/25] feat(task T02): implement via codex

---
 .../settings/AutomationCredentialManager.tsx  | 21 +++++
 .../AutomationCredentialManager.test.tsx      | 15 ++++
 .../panels/SettingsIntegrationsPanel.tsx      |  2 +
 .../automation-credential-api.test.ts         |  5 ++
 .../src/v2/lib/automation-credential-api.ts   | 15 ++++
 .../docs/operations-credential-security.mdx   | 26 ++++++
 docs-web/content/docs/registry.ts             |  9 ++
 docs-web/operations/credential-security.md    | 26 ++++++
 ...cs.operations-credential-security.lazy.tsx | 11 +++
 docs/SUMMARY.md                               |  1 +
 docs/index.md                                 |  2 +
 docs/operations/credential-security.md        | 30 +++++++
 src/app/dependency-factory/core-factory.ts    | 17 ++++
 .../dependency-factory/dashboard-factory.ts   |  3 +
 src/contracts/automation-credential-types.ts  | 86 ++++++++++++++++++
 src/electron/credential-key-persistence.ts    | 23 +++++
 src/electron/main.ts                          |  9 +-
 .../electron-safe-storage-key-provider.ts     | 43 +++++++++
 .../security/encrypted-sqlite-secret-store.ts | 21 +++++
 .../external-key-provider-adapters.ts         | 22 +++++
 .../security/mounted-key-file-provider.ts     | 38 ++++++++
 .../automation-credential-repository.ts       | 88 +++++++++++++++++++
 src/repositories/db/app-db-migrations.ts      | 84 ++++++++++++++++++
 src/server/automation-credential-routes.ts    | 21 +++++
 src/server/dashboard-route-registration.ts    |  2 +
 src/server/dashboard-server.ts                |  2 +
 src/services/credentials/credential-broker.ts | 88 +++++++++++++++++++
 src/services/credentials/encryption-utils.ts  | 63 +++++++++++++
 .../credentials/key-provider-registry.ts      | 13 +++
 src/services/credentials/key-provider.ts      | 21 +++++
 src/services/credentials/secret-store.ts      | 23 +++++
 src/services/node-flow-runtime-service.ts     | 15 +++-
 .../automation-credential-repository.test.ts  | 20 +++++
 .../automation-credential-routes.test.ts      |  8 ++
 .../services/credential-encryption.test.ts    | 12 +++
 .../node-flow-runtime-service.test.ts         | 11 ++-
 36 files changed, 891 insertions(+), 5 deletions(-)
 create mode 100644 dashboard/src/v2/components/settings/AutomationCredentialManager.tsx
 create mode 100644 dashboard/src/v2/components/settings/__tests__/AutomationCredentialManager.test.tsx
 create mode 100644 dashboard/src/v2/lib/__tests__/automation-credential-api.test.ts
 create mode 100644 dashboard/src/v2/lib/automation-credential-api.ts
 create mode 100644 docs-web/content/docs/operations-credential-security.mdx
 create mode 100644 docs-web/operations/credential-security.md
 create mode 100644 docs-web/routes/docs.operations-credential-security.lazy.tsx
 create mode 100644 docs/operations/credential-security.md
 create mode 100644 src/contracts/automation-credential-types.ts
 create mode 100644 src/electron/credential-key-persistence.ts
 create mode 100644 src/infrastructure/security/electron-safe-storage-key-provider.ts
 create mode 100644 src/infrastructure/security/encrypted-sqlite-secret-store.ts
 create mode 100644 src/infrastructure/security/external-key-provider-adapters.ts
 create mode 100644 src/infrastructure/security/mounted-key-file-provider.ts
 create mode 100644 src/repositories/automation-credential-repository.ts
 create mode 100644 src/server/automation-credential-routes.ts
 create mode 100644 src/services/credentials/credential-broker.ts
 create mode 100644 src/services/credentials/encryption-utils.ts
 create mode 100644 src/services/credentials/key-provider-registry.ts
 create mode 100644 src/services/credentials/key-provider.ts
 create mode 100644 src/services/credentials/secret-store.ts
 create mode 100644 tests/backend/repositories/automation-credential-repository.test.ts
 create mode 100644 tests/backend/server/automation-credential-routes.test.ts
 create mode 100644 tests/backend/services/credential-encryption.test.ts

diff --git a/dashboard/src/v2/components/settings/AutomationCredentialManager.tsx b/dashboard/src/v2/components/settings/AutomationCredentialManager.tsx
new file mode 100644
index 0000000000..607c7c34f9
--- /dev/null
+++ b/dashboard/src/v2/components/settings/AutomationCredentialManager.tsx
@@ -0,0 +1,21 @@
+import type { FunctionComponent } from "preact";
+import { useEffect, useState } from "preact/hooks";
+import { KeyRound, Plus, RefreshCw, ShieldAlert } from "lucide-preact";
+import type { AutomationCredentialMetadata, CredentialBackendHealth } from "../../../../../src/contracts/automation-credential-types.js";
+import { createAutomationCredential, fetchAutomationCredentials, fetchCredentialHealth, revokeAutomationCredential, testAutomationCredential } from "../../lib/automation-credential-api.js";
+
+export const AutomationCredentialManager:FunctionComponent<{projectId:string}> = ({projectId}) => {
+  const [credentials,setCredentials]=useState<AutomationCredentialMetadata[]>([]); const [health,setHealth]=useState<CredentialBackendHealth|null>(null);
+  const [name,setName]=useState(""); const [kind,setKind]=useState(""); const [value,setValue]=useState(""); const [busy,setBusy]=useState(false); const [error,setError]=useState<string|null>(null);
+  const load=async()=>{setError(null);try{const [nextCredentials,nextHealth]=await Promise.all([fetchAutomationCredentials(projectId),fetchCredentialHealth()]);setCredentials(nextCredentials);setHealth(nextHealth);}catch(caught){setError(caught instanceof Error?caught.message:String(caught));}};
+  useEffect(()=>{void load();},[projectId]);
+  const create=async()=>{setBusy(true);setError(null);try{await createAutomationCredential(projectId,{name,kind,value,scope:"project",capabilities:["read"]});setName("");setKind("");setValue("");await load();}catch(caught){setError(caught instanceof Error?caught.message:String(caught));}finally{setBusy(false);}};
+  return <section aria-labelledby="credential-manager-title" className="rounded-[1.25rem] border border-black/[0.06] bg-black/[0.02] p-5 dark:border-white/[0.06] dark:bg-white/[0.03]">
+    <div className="flex items-start justify-between gap-4"><div><h3 id="credential-manager-title" className="flex items-center gap-2 text-sm font-bold text-slate-800 dark:text-slate-100"><KeyRound className="h-4 w-4"/>Automation credentials</h3><p className="mt-1 text-xs text-slate-500 dark:text-slate-400">Values are write-only and encrypted before local persistence.</p></div><button type="button" aria-label="Refresh credentials" onClick={()=>void load()} className="rounded-lg p-2 text-slate-500 focus:outline-none focus-visible:ring-2 focus-visible:ring-signal-500"><RefreshCw className="h-4 w-4"/></button></div>
+    {health&&!health.available?<div role="alert" className="mt-4 flex gap-2 rounded-xl border border-amber-500/30 bg-amber-500/10 p-3 text-xs text-amber-800 dark:text-amber-200"><ShieldAlert className="h-4 w-4 shrink-0"/>{health.reason??"Secure key storage is unavailable. Credential writes are disabled."}</div>:null}
+    {error?<div role="alert" className="mt-3 text-xs font-semibold text-red-600 dark:text-red-300">{error}</div>:null}
+    <div className="mt-4 grid gap-3 md:grid-cols-3"><label className="text-xs font-semibold text-slate-600 dark:text-slate-300">Name<input value={name} onInput={(e)=>setName(e.currentTarget.value)} className="mt-1 w-full rounded-xl border border-black/10 bg-white px-3 py-2 dark:border-white/10 dark:bg-void-900"/></label><label className="text-xs font-semibold text-slate-600 dark:text-slate-300">Kind<input value={kind} onInput={(e)=>setKind(e.currentTarget.value)} placeholder="api-token" className="mt-1 w-full rounded-xl border border-black/10 bg-white px-3 py-2 dark:border-white/10 dark:bg-void-900"/></label><label className="text-xs font-semibold text-slate-600 dark:text-slate-300">Secret value<input type="password" autoComplete="new-password" value={value} onInput={(e)=>setValue(e.currentTarget.value)} className="mt-1 w-full rounded-xl border border-black/10 bg-white px-3 py-2 dark:border-white/10 dark:bg-void-900"/></label></div>
+    <button type="button" disabled={busy||!health?.available||!name||!kind||!value} onClick={()=>void create()} className="mt-3 inline-flex items-center gap-2 rounded-xl bg-signal-600 px-4 py-2 text-xs font-bold text-white disabled:opacity-40 focus:outline-none focus-visible:ring-2 focus-visible:ring-signal-500"><Plus className="h-4 w-4"/>Store credential</button>
+    <ul className="mt-5 space-y-2">{credentials.map((credential)=><li key={credential.id} className="flex flex-wrap items-center justify-between gap-3 rounded-xl border border-black/[0.06] bg-white/70 p-3 dark:border-white/[0.06] dark:bg-void-900/50"><div><div className="text-sm font-bold text-slate-700 dark:text-slate-200">{credential.name}</div><div className="text-[11px] text-slate-500">{credential.kind} · {credential.scope} · {credential.status} · v{credential.version}</div></div><div className="flex gap-2"><button type="button" onClick={()=>void testAutomationCredential(projectId,credential.id).then(load).catch((caught)=>setError(caught instanceof Error?caught.message:String(caught)))} className="rounded-lg border border-black/10 px-3 py-1.5 text-xs font-bold dark:border-white/10">Test</button><button type="button" disabled={credential.status==="revoked"} onClick={()=>void revokeAutomationCredential(projectId,credential.id).then(load).catch((caught)=>setError(caught instanceof Error?caught.message:String(caught)))} className="rounded-lg border border-red-500/30 px-3 py-1.5 text-xs font-bold text-red-600 disabled:opacity-40">Revoke</button></div></li>)}</ul>
+  </section>;
+};
diff --git a/dashboard/src/v2/components/settings/__tests__/AutomationCredentialManager.test.tsx b/dashboard/src/v2/components/settings/__tests__/AutomationCredentialManager.test.tsx
new file mode 100644
index 0000000000..873c537554
--- /dev/null
+++ b/dashboard/src/v2/components/settings/__tests__/AutomationCredentialManager.test.tsx
@@ -0,0 +1,15 @@
+// @vitest-environment jsdom
+import { render,screen,waitFor } from "@testing-library/preact";
+import { beforeEach,describe,expect,it,vi } from "vitest";
+import { AutomationCredentialManager } from "../AutomationCredentialManager.js";
+import { fetchAutomationCredentials,fetchCredentialHealth } from "../../../lib/automation-credential-api.js";
+
+vi.mock("../../../lib/automation-credential-api.js",()=>({
+  fetchAutomationCredentials:vi.fn(), fetchCredentialHealth:vi.fn(), createAutomationCredential:vi.fn(),
+  testAutomationCredential:vi.fn(), revokeAutomationCredential:vi.fn(),
+}));
+
+describe("AutomationCredentialManager",()=>{
+  beforeEach(()=>{vi.clearAllMocks();vi.mocked(fetchAutomationCredentials).mockResolvedValue([{id:"credential-1",name:"Deployment token",kind:"api-token",scope:"project",projectId:"project-1",allowedProjectIds:[],capabilities:["read"],status:"active",configured:true,keyId:"root",keyVersion:1,version:1,lastValidatedAt:null,validationStatus:"untested",createdAt:"now",updatedAt:"now"}]);vi.mocked(fetchCredentialHealth).mockResolvedValue({available:false,secure:false,provider:"electron-safe-storage",keyId:null,keyVersion:null,reason:"OS secure storage is unavailable."});});
+  it("renders metadata and disables secret writes when secure storage is unavailable",async()=>{render(<AutomationCredentialManager projectId="project-1"/>);expect(await screen.findByText("Deployment token")).toBeTruthy();expect(screen.getByRole("alert").textContent).toContain("OS secure storage is unavailable.");await waitFor(()=>expect((screen.getByRole("button",{name:"Store credential"}) as HTMLButtonElement).disabled).toBe(true));expect(document.body.textContent).not.toContain("plain-secret");});
+});
diff --git a/dashboard/src/v2/components/settings/panels/SettingsIntegrationsPanel.tsx b/dashboard/src/v2/components/settings/panels/SettingsIntegrationsPanel.tsx
index fe0ee70660..34d745b166 100644
--- a/dashboard/src/v2/components/settings/panels/SettingsIntegrationsPanel.tsx
+++ b/dashboard/src/v2/components/settings/panels/SettingsIntegrationsPanel.tsx
@@ -49,6 +49,7 @@ import type {
 } from "../../../lib/chat-provider-api.js";
 import { isDeprecatedProvider, providerLifecycle } from "../../../lib/provider-lifecycle.js";
 import { LocalFilePickerField } from "../LocalFilePickerField.js";
+import { AutomationCredentialManager } from "../AutomationCredentialManager.js";
 
 type PublicProviderId = Exclude<ProviderId, "mockup-cli">;
 
@@ -1823,6 +1824,7 @@ export const SettingsIntegrationsPanel: FunctionComponent<{ state: SettingsPageS
 
   return (
     <div className="flex flex-col gap-5">
+      {state.selectedProject?.id ? <AutomationCredentialManager projectId={state.selectedProject.id} /> : null}
       <SectionCard
         title="Integrations"
         watermark="INT"
diff --git a/dashboard/src/v2/lib/__tests__/automation-credential-api.test.ts b/dashboard/src/v2/lib/__tests__/automation-credential-api.test.ts
new file mode 100644
index 0000000000..cbb4410fb2
--- /dev/null
+++ b/dashboard/src/v2/lib/__tests__/automation-credential-api.test.ts
@@ -0,0 +1,5 @@
+import { beforeEach,describe,expect,it,vi } from "vitest";
+import { fetchJson } from "../../../lib/api/fetch-json.js";
+import { createAutomationCredential,rotateAutomationCredential } from "../automation-credential-api.js";
+vi.mock("../../../lib/api/fetch-json.js",()=>({fetchJson:vi.fn()}));
+describe("automation credential api",()=>{beforeEach(()=>vi.clearAllMocks());it("uses write-only create and rotate endpoints",async()=>{vi.mocked(fetchJson).mockResolvedValue({});await createAutomationCredential("project/one",{name:"Token",kind:"api-token",value:"secret"});expect(fetchJson).toHaveBeenCalledWith("/api/projects/project%2Fone/credentials",expect.objectContaining({method:"POST",body:JSON.stringify({name:"Token",kind:"api-token",value:"secret"})}));await rotateAutomationCredential("project/one","credential/one","next");expect(fetchJson).toHaveBeenLastCalledWith("/api/projects/project%2Fone/credentials/credential%2Fone/rotate",expect.objectContaining({method:"POST",body:JSON.stringify({value:"next"})}));});});
diff --git a/dashboard/src/v2/lib/automation-credential-api.ts b/dashboard/src/v2/lib/automation-credential-api.ts
new file mode 100644
index 0000000000..2c5b4d1694
--- /dev/null
+++ b/dashboard/src/v2/lib/automation-credential-api.ts
@@ -0,0 +1,15 @@
+import type { AutomationCredentialBinding, AutomationCredentialMetadata, CreateAutomationCredentialInput, CredentialBackendHealth } from "../../../../src/contracts/automation-credential-types.js";
+import { fetchJson } from "../../lib/api/fetch-json.js";
+
+const json = (method: string, body?: unknown): RequestInit => ({ method, headers: { "Content-Type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body) });
+const base = (projectId: string) => `/api/projects/${encodeURIComponent(projectId)}/credentials`;
+export const fetchCredentialHealth = (): Promise<CredentialBackendHealth> => fetchJson("/api/credentials/health");
+export const fetchAutomationCredentials = (projectId:string):Promise<AutomationCredentialMetadata[]> => fetchJson(base(projectId));
+export const createAutomationCredential = (projectId:string,input:CreateAutomationCredentialInput):Promise<AutomationCredentialMetadata> => fetchJson(base(projectId),json("POST",input));
+export const bindAutomationCredential = (projectId:string,id:string,input:{bindingKey:string;capabilities:string[]}):Promise<AutomationCredentialBinding> => fetchJson(`${base(projectId)}/${encodeURIComponent(id)}/bind`,json("POST",input));
+export const testAutomationCredential = (projectId:string,id:string):Promise<AutomationCredentialMetadata> => fetchJson(`${base(projectId)}/${encodeURIComponent(id)}/test`,json("POST"));
+export const rotateAutomationCredential = (projectId:string,id:string,value:string):Promise<AutomationCredentialMetadata> => fetchJson(`${base(projectId)}/${encodeURIComponent(id)}/rotate`,json("POST",{value}));
+export const replaceAutomationCredential = (projectId:string,id:string,value:string):Promise<AutomationCredentialMetadata> => fetchJson(`${base(projectId)}/${encodeURIComponent(id)}/replace`,json("POST",{value}));
+export const revokeAutomationCredential = (projectId:string,id:string):Promise<AutomationCredentialMetadata> => fetchJson(`${base(projectId)}/${encodeURIComponent(id)}/revoke`,json("POST"));
+export const promoteAutomationCredential = (projectId:string,id:string,allowedProjectIds:string[]):Promise<AutomationCredentialMetadata> => fetchJson(`${base(projectId)}/${encodeURIComponent(id)}/promote`,json("POST",{allowedProjectIds}));
+export const restrictAutomationCredential = (projectId:string,id:string,input:{allowedProjectIds:string[];capabilities:string[]}):Promise<AutomationCredentialMetadata> => fetchJson(`${base(projectId)}/${encodeURIComponent(id)}/restrict`,json("POST",input));
diff --git a/docs-web/content/docs/operations-credential-security.mdx b/docs-web/content/docs/operations-credential-security.mdx
new file mode 100644
index 0000000000..e76d076cfc
--- /dev/null
+++ b/docs-web/content/docs/operations-credential-security.mdx
@@ -0,0 +1,26 @@
+# Automation Credential Security
+
+Code UX resolves canonical node credential IDs and named project binding keys through the credential broker. Stored values are not exposed to nodes, dashboard reads, MCP payloads, agent context, run inspection records, or access audits.
+
+## Scope and policy
+
+- Project credentials are owned by one project.
+- Global credentials require an explicit project allowlist.
+- Both the binding and credential must approve the requested capability.
+- Revoked, unavailable, missing, cross-project, or insufficiently capable credentials fail closed.
+
+Create, rotate, and replace requests are write-only. API responses contain configuration and status metadata but never stored values.
+
+## Encryption and key custody
+
+The SQLite secret store uses AES-256-GCM envelope encryption with a unique data key, payload nonce, and key-wrapping nonce for every write. Credential ownership and workspace context are authenticated. SQLite stores ciphertext, authentication tags, wrapped keys, nonces, and key identifiers/versions—not root keys.
+
+Headless mode requires `CODE_UX_CREDENTIAL_KEY_FILE` to point to a mounted file containing a base64- or hexadecimal-encoded 32-byte key. Electron uses the OS `safeStorage` boundary. Vault and KMS adapters report explicit health states. If secure key material is unavailable, credential operations fail closed; there is no plaintext fallback.
+
+## Recovery and rotation
+
+Back up root keys separately from `app.db`; the database alone cannot recover credentials. Rotation creates a fresh encrypted envelope, increments the credential version, and records metadata about the transition. Revocation prevents subsequent resolution while retaining audit metadata.
+
+## Dashboard API
+
+Credential management uses project-scoped dashboard routes. List, health, and mutation responses return metadata only. Secret values are accepted only by create, rotate, and replace operations.
diff --git a/docs-web/content/docs/registry.ts b/docs-web/content/docs/registry.ts
index 0b0792112c..522ed80858 100644
--- a/docs-web/content/docs/registry.ts
+++ b/docs-web/content/docs/registry.ts
@@ -103,6 +103,7 @@ export type DocsSlug =
   | 'architecture-external-chat-providers'
   | 'architecture-configuration-resolution'
   | 'architecture-security'
+  | 'operations-credential-security'
   | 'settings-google-drive-mount'
   | 'user-dashboard-custom-dashboards'
   | 'architecture-custom-dashboard-foundation'
@@ -822,6 +823,13 @@ export const docsRegistry: Record<DocsSlug, DocsRegistryEntry> = {
     title: "Security model",
     description: "Code UX is designed to run as a single-user trusted process on a developer's workstation or a dedicated server. This page documents what is and is not protected, the threat model, and the recommended deployment posture.",
   },
+  'operations-credential-security': {
+    id: 'operations-credential-security',
+    path: '/docs/operations-credential-security',
+    section: 'User Guide',
+    title: "Automation Credential Security",
+    description: "Code UX resolves canonical node credential IDs and named project binding keys through the credential broker. Stored values are not exposed to nodes, dashboard reads, MCP payloads, agent context, run inspection records...",
+  },
   'settings-google-drive-mount': {
     id: 'settings-google-drive-mount',
     path: '/docs/settings-google-drive-mount',
@@ -988,6 +996,7 @@ export const orderedDocs: DocsRegistryEntry[] = [
   docsRegistry['architecture-external-chat-providers'],
   docsRegistry['architecture-configuration-resolution'],
   docsRegistry['architecture-security'],
+  docsRegistry['operations-credential-security'],
   docsRegistry['settings-google-drive-mount'],
   docsRegistry['user-dashboard-custom-dashboards'],
   docsRegistry['architecture-custom-dashboard-foundation'],
diff --git a/docs-web/operations/credential-security.md b/docs-web/operations/credential-security.md
new file mode 100644
index 0000000000..e76d076cfc
--- /dev/null
+++ b/docs-web/operations/credential-security.md
@@ -0,0 +1,26 @@
+# Automation Credential Security
+
+Code UX resolves canonical node credential IDs and named project binding keys through the credential broker. Stored values are not exposed to nodes, dashboard reads, MCP payloads, agent context, run inspection records, or access audits.
+
+## Scope and policy
+
+- Project credentials are owned by one project.
+- Global credentials require an explicit project allowlist.
+- Both the binding and credential must approve the requested capability.
+- Revoked, unavailable, missing, cross-project, or insufficiently capable credentials fail closed.
+
+Create, rotate, and replace requests are write-only. API responses contain configuration and status metadata but never stored values.
+
+## Encryption and key custody
+
+The SQLite secret store uses AES-256-GCM envelope encryption with a unique data key, payload nonce, and key-wrapping nonce for every write. Credential ownership and workspace context are authenticated. SQLite stores ciphertext, authentication tags, wrapped keys, nonces, and key identifiers/versions—not root keys.
+
+Headless mode requires `CODE_UX_CREDENTIAL_KEY_FILE` to point to a mounted file containing a base64- or hexadecimal-encoded 32-byte key. Electron uses the OS `safeStorage` boundary. Vault and KMS adapters report explicit health states. If secure key material is unavailable, credential operations fail closed; there is no plaintext fallback.
+
+## Recovery and rotation
+
+Back up root keys separately from `app.db`; the database alone cannot recover credentials. Rotation creates a fresh encrypted envelope, increments the credential version, and records metadata about the transition. Revocation prevents subsequent resolution while retaining audit metadata.
+
+## Dashboard API
+
+Credential management uses project-scoped dashboard routes. List, health, and mutation responses return metadata only. Secret values are accepted only by create, rotate, and replace operations.
diff --git a/docs-web/routes/docs.operations-credential-security.lazy.tsx b/docs-web/routes/docs.operations-credential-security.lazy.tsx
new file mode 100644
index 0000000000..1d0ade949b
--- /dev/null
+++ b/docs-web/routes/docs.operations-credential-security.lazy.tsx
@@ -0,0 +1,11 @@
+import { createLazyFileRoute } from '@tanstack/react-router'
+import OperationsCredentialSecurityContent from '../content/docs/operations-credential-security.mdx'
+import { DocsPage } from '../components/docs/DocsPage'
+
+export const Route = createLazyFileRoute('/docs/operations-credential-security')({
+  component: () => (
+    <DocsPage id="operations-credential-security">
+      <OperationsCredentialSecurityContent />
+    </DocsPage>
+  )
+})
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 87f1e6ec11..5e0a632d23 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -105,6 +105,7 @@
 - [Operations Runbook](./operations/runbook.md)
 - [Secure Headless Server Mode](./operations/server-mode.md)
 - [Security Hardening](./operations/security-hardening.md)
+- [Automation Credential Security](./operations/credential-security.md)
 - [Logging and Correlation IDs](./operations/logging-and-correlation.md)
 - [CLI Commands Reference](./reference/cli-commands.md) - `codeux` management syntax, aliases, prompting, JSON payloads, and approvals
 - [CLI Management Surface](./operations/management-cli.md)
diff --git a/docs/index.md b/docs/index.md
index 2a2646bfb4..201c31ab40 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -104,6 +104,7 @@ Use this page as the main entrypoint.
 6. [Secure Headless Server Mode](./operations/server-mode.md)
 7. [Operations Runbook](./operations/runbook.md)
 8. [Security Hardening](./operations/security-hardening.md)
+9. [Automation Credential Security](./operations/credential-security.md)
 9. [Logging and Correlation IDs](./operations/logging-and-correlation.md)
 10. [CLI Commands Reference](./reference/cli-commands.md) - `codeux` management syntax, aliases, prompting, JSON payloads, and approvals
 11. [CLI Management Surface](./operations/management-cli.md)
@@ -211,6 +212,7 @@ Use this page as the main entrypoint.
 - [Operations Runbook](./operations/runbook.md)
 - [Secure Headless Server Mode](./operations/server-mode.md)
 - [Security Hardening](./operations/security-hardening.md)
+- [Automation Credential Security](./operations/credential-security.md)
 - [Logging and Correlation IDs](./operations/logging-and-correlation.md)
 - [CLI Commands Reference](./reference/cli-commands.md) - `codeux` management syntax, aliases, prompting, JSON payloads, and approvals
 - [CLI Management Surface](./operations/management-cli.md)
diff --git a/docs/operations/credential-security.md b/docs/operations/credential-security.md
new file mode 100644
index 0000000000..067fe67fc7
--- /dev/null
+++ b/docs/operations/credential-security.md
@@ -0,0 +1,30 @@
+# Automation Credential Security
+
+Code UX stores automation credentials through a broker rather than exposing secret values to node definitions, dashboard reads, MCP payloads, agent context, or run inspection records. Canonical node bindings reference credential metadata by ID; only the broker can resolve the value at execution time after project and capability checks. Named project binding keys use the same broker for other automation consumers.
+
+## Scope and policy
+
+- Project credentials can be managed only through their owning project.
+- Global credentials are opt-in and require an explicit project allowlist containing the configuring project.
+- Resolution succeeds only when both the credential and binding approve the requested capability.
+- Revoked, unavailable, missing, cross-project, or insufficiently capable credentials fail closed.
+
+The dashboard accepts secret values only on create, rotate, and replace requests. Responses contain configuration, scope, status, key-version, and validation metadata but never stored values. Access-event rows contain identifiers, binding keys, capabilities, outcomes, and denial reasons; they never contain secret material.
+
+## Encryption and key custody
+
+The SQLite secret store uses AES-256-GCM envelope encryption. Each write generates a unique 256-bit data key, payload nonce, and key-wrapping nonce. Credential ownership and workspace context are authenticated as additional data. SQLite stores only ciphertext, authentication tags, wrapped keys, nonces, and key identifiers/versions.
+
+Root keys are never stored in SQLite. Headless mode requires `CODE_UX_CREDENTIAL_KEY_FILE` to identify a mounted file whose contents decode from base64 or hexadecimal to exactly 32 bytes. The environment variable contains a path, not key material. Keep the mount readable only by the Code UX process and outside the project workspace.
+
+Electron uses the OS-backed `safeStorage` boundary and refuses credential operations when secure OS storage is unavailable. Vault and KMS adapters expose explicit health states. No provider silently falls back to plaintext or an insecure locally derived key.
+
+## Recovery and rotation
+
+Back up root keys independently from `app.db`. Losing a required key version makes its ciphertext unrecoverable by design. Restoring only SQLite is insufficient.
+
+Credential rotation writes a fresh envelope with a new data key and nonces, increments the credential version, and records metadata about the transition. Root-key providers must retain old key IDs and versions until envelopes are rewrapped. Revocation prevents resolution immediately while preserving audit metadata.
+
+## API surface
+
+Project-scoped routes live under `/api/projects/:projectId/credentials`. Supported operations are create, bind, test, rotate, replace, revoke, promote, and restrict. List and health endpoints return metadata only. Existing dashboard authentication and middleware apply before these routes.
diff --git a/src/app/dependency-factory/core-factory.ts b/src/app/dependency-factory/core-factory.ts
index 8e9b04cd42..55108c588e 100644
--- a/src/app/dependency-factory/core-factory.ts
+++ b/src/app/dependency-factory/core-factory.ts
@@ -66,6 +66,11 @@ import { SprintFileBrowserRepository } from "../../repositories/sprint-file-brow
 import { DockerService } from "../../services/docker-service.js";
 import { CustomDashboardRepository } from "../../repositories/custom-dashboard-repository.js";
 import { CustomDashboardValidationService } from "../../services/custom-dashboard-validation-service.js";
+import { AutomationCredentialRepository } from "../../repositories/automation-credential-repository.js";
+import { CredentialBroker } from "../../services/credentials/credential-broker.js";
+import { MountedKeyFileProvider } from "../../infrastructure/security/mounted-key-file-provider.js";
+import { EncryptedSqliteSecretStore } from "../../infrastructure/security/encrypted-sqlite-secret-store.js";
+import { getProcessCredentialKeyProvider } from "../../services/credentials/key-provider-registry.js";
 
 export interface CoreDependencies {
   providerRunner: IProviderRunner;
@@ -125,6 +130,8 @@ export interface CoreDependencies {
   sprintFileBrowserRepository: SprintFileBrowserRepository;
   customDashboardRepository: CustomDashboardRepository;
   customDashboardValidationService: CustomDashboardValidationService;
+  automationCredentialRepository: AutomationCredentialRepository;
+  credentialBroker: CredentialBroker;
 }
 
 export function createCoreDependencies(
@@ -180,6 +187,14 @@ export function createCoreDependencies(
   const subtaskRepository = new SubtaskFileRepository();
   const sessionTracking = new SessionTrackingRepository();
   const appDbStorage = new AppDbStorage();
+  const automationCredentialRepository = new AutomationCredentialRepository(appDbStorage);
+  const credentialKeyProvider = getProcessCredentialKeyProvider()
+    ?? new MountedKeyFileProvider(process.env.CODE_UX_CREDENTIAL_KEY_FILE);
+  const credentialBroker = new CredentialBroker(
+    automationCredentialRepository,
+    new EncryptedSqliteSecretStore(automationCredentialRepository, credentialKeyProvider),
+    credentialKeyProvider,
+  );
   const dashboardRealtimeEventRepository = new DashboardRealtimeEventRepository(appDbStorage);
   const dashboardRealtimeService = new DashboardRealtimeService(
     dashboardRealtimeEventRepository,
@@ -391,5 +406,7 @@ export function createCoreDependencies(
     sprintFileBrowserRepository,
     customDashboardRepository,
     customDashboardValidationService,
+    automationCredentialRepository,
+    credentialBroker,
   };
 }
diff --git a/src/app/dependency-factory/dashboard-factory.ts b/src/app/dependency-factory/dashboard-factory.ts
index 8c31109a1b..af70fdec29 100644
--- a/src/app/dependency-factory/dashboard-factory.ts
+++ b/src/app/dependency-factory/dashboard-factory.ts
@@ -34,6 +34,7 @@ import { NodeFlowService } from "../../services/node-flow-service.js";
 import { resolveEffectiveDashboardSettings } from "../../services/settings-resolution-service.js";
 
 export interface DashboardDependencies {
+  credentialBroker: CoreDependencies["credentialBroker"];
   chatThreadRuntimeService: ChatThreadRuntimeService;
   chatProviderRepository: CoreDependencies["chatProviderRepository"];
   chatProviderIngressService: ChatProviderIngressService;
@@ -226,6 +227,7 @@ export function createDashboardDependencies(
     projectManagementRepository,
     settingsRepository,
     providerExecutionService,
+    credentialBroker: coreDeps.credentialBroker,
     getDashboardSettings: (projectId) => resolveDashboardSettings({ projectId }),
   });
   const nodeFlowService = new NodeFlowService(coreDeps.nodeFlowRepository, nodeFlowRuntimeService);
@@ -549,6 +551,7 @@ export function createDashboardDependencies(
   schedulerServiceRef.set(schedulerService);
 
   return {
+    credentialBroker: coreDeps.credentialBroker,
     chatProviderRepository,
     chatThreadRuntimeService,
     chatProviderIngressService,
diff --git a/src/contracts/automation-credential-types.ts b/src/contracts/automation-credential-types.ts
new file mode 100644
index 0000000000..b3136f13bb
--- /dev/null
+++ b/src/contracts/automation-credential-types.ts
@@ -0,0 +1,86 @@
+export type AutomationCredentialScope = "project" | "global";
+export type AutomationCredentialStatus = "active" | "revoked" | "unavailable";
+export type AutomationCredentialCapability = "read" | "write" | "admin" | string;
+
+export interface AutomationCredentialMetadata {
+  id: string;
+  name: string;
+  kind: string;
+  scope: AutomationCredentialScope;
+  projectId: string | null;
+  allowedProjectIds: string[];
+  capabilities: AutomationCredentialCapability[];
+  status: AutomationCredentialStatus;
+  configured: boolean;
+  keyId: string;
+  keyVersion: number;
+  version: number;
+  lastValidatedAt: string | null;
+  validationStatus: "untested" | "valid" | "invalid" | "unavailable";
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreateAutomationCredentialInput {
+  name: string;
+  kind: string;
+  value: string;
+  scope?: AutomationCredentialScope;
+  allowedProjectIds?: string[];
+  capabilities?: AutomationCredentialCapability[];
+}
+
+export interface AutomationCredentialBinding {
+  id: string;
+  credentialId: string;
+  projectId: string;
+  bindingKey: string;
+  requiredCapabilities: AutomationCredentialCapability[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export type CredentialAccessOutcome = "granted" | "denied";
+export interface AutomationCredentialAccessEvent {
+  id: string;
+  credentialId: string | null;
+  projectId: string;
+  bindingKey: string | null;
+  capability: string | null;
+  operation: string;
+  outcome: CredentialAccessOutcome;
+  reason: string | null;
+  createdAt: string;
+}
+
+export interface AutomationCredentialRotation {
+  id: string;
+  credentialId: string;
+  fromVersion: number;
+  toVersion: number;
+  keyId: string;
+  keyVersion: number;
+  rotatedAt: string;
+}
+
+export interface CredentialResolutionRequest {
+  projectId: string;
+  bindingKey: string;
+  capability: AutomationCredentialCapability;
+  workspaceId: string;
+}
+
+export interface ResolvedCredential {
+  credentialId: string;
+  value: string;
+  version: number;
+}
+
+export interface CredentialBackendHealth {
+  available: boolean;
+  secure: boolean;
+  provider: string;
+  keyId: string | null;
+  keyVersion: number | null;
+  reason?: string;
+}
diff --git a/src/electron/credential-key-persistence.ts b/src/electron/credential-key-persistence.ts
new file mode 100644
index 0000000000..f8261a4610
--- /dev/null
+++ b/src/electron/credential-key-persistence.ts
@@ -0,0 +1,23 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { ProtectedKeyPersistence } from "../infrastructure/security/electron-safe-storage-key-provider.js";
+
+/** Persists only the OS-encrypted root-key blob; plaintext key bytes never reach this boundary. */
+export class ElectronCredentialKeyPersistence implements ProtectedKeyPersistence {
+  constructor(private readonly filePath: string) {}
+
+  async read(): Promise<Buffer | null> {
+    try { return await readFile(this.filePath); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+      throw error;
+    }
+  }
+
+  async write(value: Buffer): Promise<void> {
+    await mkdir(dirname(this.filePath), { recursive: true });
+    const temporaryPath = `${this.filePath}.tmp`;
+    await writeFile(temporaryPath, value, { mode: 0o600 });
+    await rename(temporaryPath, this.filePath);
+  }
+}
diff --git a/src/electron/main.ts b/src/electron/main.ts
index c0c7bd4395..e9517aee04 100644
--- a/src/electron/main.ts
+++ b/src/electron/main.ts
@@ -1,4 +1,4 @@
-import { app, BrowserWindow, dialog, ipcMain, nativeImage, session, shell } from "electron";
+import { app, BrowserWindow, dialog, ipcMain, nativeImage, safeStorage, session, shell } from "electron";
 import * as fs from "fs";
 import Module from "module";
 import * as os from "os";
@@ -15,6 +15,9 @@ import {
 } from "./dashboard-network-policy.js";
 import { openCodeUxUpdatesPage, toggleWindowMaximized } from "./window-controls.js";
 import { createDebouncedSaver, loadWindowState, saveWindowState } from "./window-state.js";
+import { ElectronCredentialKeyPersistence } from "./credential-key-persistence.js";
+import { ElectronSafeStorageKeyProvider } from "../infrastructure/security/electron-safe-storage-key-provider.js";
+import { setProcessCredentialKeyProvider } from "../services/credentials/key-provider-registry.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -299,6 +302,10 @@ async function startServer(): Promise<string> {
   registerPackagedNodeModules();
   const dotenv = await import("dotenv");
   dotenv.config({ path: path.join(projectRoot, ".env"), quiet: true });
+  setProcessCredentialKeyProvider(new ElectronSafeStorageKeyProvider(
+    safeStorage,
+    new ElectronCredentialKeyPersistence(path.join(app.getPath("userData"), "credential-root-key.bin")),
+  ));
 
   const [{ loadAppConfig }, { CodeUxServer }] = await Promise.all([
     import("../config/app-config.js"),
diff --git a/src/infrastructure/security/electron-safe-storage-key-provider.ts b/src/infrastructure/security/electron-safe-storage-key-provider.ts
new file mode 100644
index 0000000000..2efc89aebb
--- /dev/null
+++ b/src/infrastructure/security/electron-safe-storage-key-provider.ts
@@ -0,0 +1,43 @@
+import { randomBytes } from "node:crypto";
+import type { CredentialBackendHealth } from "../../contracts/automation-credential-types.js";
+import { KeyProviderUnavailableError, type KeyMaterial, type KeyProvider } from "../../services/credentials/key-provider.js";
+
+export interface ElectronSafeStorageBoundary {
+  isEncryptionAvailable(): boolean;
+  encryptString(value: string): Buffer;
+  decryptString(value: Buffer): string;
+}
+
+export interface ProtectedKeyPersistence {
+  read(): Promise<Buffer | null>;
+  write(value: Buffer): Promise<void>;
+}
+
+export class ElectronSafeStorageKeyProvider implements KeyProvider {
+  readonly providerName = "electron-safe-storage";
+  constructor(private readonly safeStorage: ElectronSafeStorageBoundary, private readonly persistence: ProtectedKeyPersistence, private readonly keyId = "electron-root", private readonly version = 1) {}
+
+  async health(): Promise<CredentialBackendHealth> {
+    if (!this.safeStorage.isEncryptionAvailable()) return { available: false, secure: false, provider: this.providerName, keyId: null, keyVersion: null, reason: "OS secure storage is unavailable." };
+    try { const key = await this.getActiveKey(); key.key.fill(0); return { available: true, secure: true, provider: this.providerName, keyId: this.keyId, keyVersion: this.version }; }
+    catch (error) { return { available: false, secure: false, provider: this.providerName, keyId: null, keyVersion: null, reason: error instanceof Error ? error.message : String(error) }; }
+  }
+
+  async getActiveKey(): Promise<KeyMaterial> {
+    if (!this.safeStorage.isEncryptionAvailable()) throw new KeyProviderUnavailableError("OS secure storage is unavailable.");
+    let protectedValue = await this.persistence.read();
+    if (!protectedValue) {
+      const generated = randomBytes(32);
+      try { protectedValue = this.safeStorage.encryptString(generated.toString("base64")); await this.persistence.write(protectedValue); }
+      finally { generated.fill(0); }
+    }
+    const key = Buffer.from(this.safeStorage.decryptString(protectedValue), "base64");
+    if (key.length !== 32) { key.fill(0); throw new KeyProviderUnavailableError("Protected credential root key is invalid."); }
+    return { key, keyId: this.keyId, version: this.version };
+  }
+
+  async getKey(keyId: string, version: number): Promise<KeyMaterial> {
+    if (keyId !== this.keyId || version !== this.version) throw new KeyProviderUnavailableError("Requested OS-protected key version is unavailable.");
+    return this.getActiveKey();
+  }
+}
diff --git a/src/infrastructure/security/encrypted-sqlite-secret-store.ts b/src/infrastructure/security/encrypted-sqlite-secret-store.ts
new file mode 100644
index 0000000000..20193715aa
--- /dev/null
+++ b/src/infrastructure/security/encrypted-sqlite-secret-store.ts
@@ -0,0 +1,21 @@
+import type { KeyProvider } from "../../services/credentials/key-provider.js";
+import type { SecretContext, SecretStore, StoredSecretEnvelope } from "../../services/credentials/secret-store.js";
+import { decryptEnvelope, encryptEnvelope } from "../../services/credentials/encryption-utils.js";
+import type { AutomationCredentialRepository } from "../../repositories/automation-credential-repository.js";
+
+export class EncryptedSqliteSecretStore implements SecretStore {
+  constructor(private readonly repository: AutomationCredentialRepository, private readonly keyProvider: KeyProvider) {}
+  async put(context: SecretContext, plaintext: Buffer): Promise<StoredSecretEnvelope> {
+    const health = await this.keyProvider.health();
+    if (!health.available || !health.secure) throw new Error(health.reason ?? "Secure key provider is unavailable.");
+    const rootKey = await this.keyProvider.getActiveKey();
+    try { const envelope=encryptEnvelope(context,plaintext,rootKey); this.repository.putEnvelope(envelope); return envelope; }
+    finally { rootKey.key.fill(0); }
+  }
+  async get(context: SecretContext): Promise<Buffer> {
+    const envelope=this.repository.getEnvelope(context.credentialId); if (!envelope) throw new Error("Credential secret is unavailable.");
+    const rootKey=await this.keyProvider.getKey(envelope.keyId,envelope.keyVersion);
+    try { return decryptEnvelope(context,envelope,rootKey); } finally { rootKey.key.fill(0); }
+  }
+  async delete(credentialId: string): Promise<void> { this.repository.deleteEnvelope(credentialId); }
+}
diff --git a/src/infrastructure/security/external-key-provider-adapters.ts b/src/infrastructure/security/external-key-provider-adapters.ts
new file mode 100644
index 0000000000..cb12b8658b
--- /dev/null
+++ b/src/infrastructure/security/external-key-provider-adapters.ts
@@ -0,0 +1,22 @@
+import type { CredentialBackendHealth } from "../../contracts/automation-credential-types.js";
+import { KeyProviderUnavailableError, type KeyMaterial, type KeyProvider } from "../../services/credentials/key-provider.js";
+
+export interface ExternalKeyServiceClient {
+  health(): Promise<{ available: boolean; reason?: string }>;
+  activeKey(): Promise<KeyMaterial>;
+  key(keyId: string, version: number): Promise<KeyMaterial>;
+}
+
+export class ExternalKeyProviderAdapter implements KeyProvider {
+  constructor(readonly providerName: "vault" | "kms", private readonly client?: ExternalKeyServiceClient) {}
+  async health(): Promise<CredentialBackendHealth> {
+    if (!this.client) return { available: false, secure: true, provider: this.providerName, keyId: null, keyVersion: null, reason: `${this.providerName} integration is not configured.` };
+    const health = await this.client.health();
+    return { available: health.available, secure: true, provider: this.providerName, keyId: null, keyVersion: null, reason: health.reason };
+  }
+  getActiveKey(): Promise<KeyMaterial> { if (!this.client) throw new KeyProviderUnavailableError(`${this.providerName} integration is unavailable.`); return this.client.activeKey(); }
+  getKey(keyId: string, version: number): Promise<KeyMaterial> { if (!this.client) throw new KeyProviderUnavailableError(`${this.providerName} integration is unavailable.`); return this.client.key(keyId, version); }
+}
+
+export class VaultKeyProviderAdapter extends ExternalKeyProviderAdapter { constructor(client?: ExternalKeyServiceClient) { super("vault", client); } }
+export class KmsKeyProviderAdapter extends ExternalKeyProviderAdapter { constructor(client?: ExternalKeyServiceClient) { super("kms", client); } }
diff --git a/src/infrastructure/security/mounted-key-file-provider.ts b/src/infrastructure/security/mounted-key-file-provider.ts
new file mode 100644
index 0000000000..d7d1061b35
--- /dev/null
+++ b/src/infrastructure/security/mounted-key-file-provider.ts
@@ -0,0 +1,38 @@
+import { readFile, stat } from "node:fs/promises";
+import type { CredentialBackendHealth } from "../../contracts/automation-credential-types.js";
+import { KeyProviderUnavailableError, type KeyMaterial, type KeyProvider } from "../../services/credentials/key-provider.js";
+
+export class MountedKeyFileProvider implements KeyProvider {
+  readonly providerName = "mounted-key-file";
+  constructor(private readonly filePath: string | undefined, private readonly keyId = "mounted-root", private readonly version = 1) {}
+
+  async health(): Promise<CredentialBackendHealth> {
+    try {
+      const material = await this.read();
+      material.key.fill(0);
+      return { available: true, secure: true, provider: this.providerName, keyId: this.keyId, keyVersion: this.version };
+    } catch (error) {
+      const reason=error instanceof Error ? error.message : String(error);
+      return { available: false, secure: !reason.includes("insecure permissions"), provider: this.providerName, keyId: null, keyVersion: null, reason };
+    }
+  }
+
+  getActiveKey(): Promise<KeyMaterial> { return this.read(); }
+  async getKey(keyId: string, version: number): Promise<KeyMaterial> {
+    if (keyId !== this.keyId || version !== this.version) throw new KeyProviderUnavailableError("Requested root key version is unavailable.");
+    return this.read();
+  }
+
+  private async read(): Promise<KeyMaterial> {
+    if (!this.filePath) throw new KeyProviderUnavailableError("No mounted credential key file is configured.");
+    try { const info=await stat(this.filePath); if ((info.mode & 0o077) !== 0) throw new KeyProviderUnavailableError("Mounted credential key file has insecure permissions; expected owner-only access."); }
+    catch (error) { if (error instanceof KeyProviderUnavailableError) throw error; throw new KeyProviderUnavailableError("Mounted credential key file is unavailable."); }
+    let raw: Buffer;
+    try { raw = await readFile(this.filePath); } catch { throw new KeyProviderUnavailableError("Mounted credential key file is unavailable."); }
+    const trimmed = raw.toString("utf8").trim();
+    raw.fill(0);
+    const key = /^[a-f\d]{64}$/i.test(trimmed) ? Buffer.from(trimmed, "hex") : Buffer.from(trimmed, "base64");
+    if (key.length !== 32) { key.fill(0); throw new KeyProviderUnavailableError("Mounted credential key must decode to exactly 32 bytes."); }
+    return { key, keyId: this.keyId, version: this.version };
+  }
+}
diff --git a/src/repositories/automation-credential-repository.ts b/src/repositories/automation-credential-repository.ts
new file mode 100644
index 0000000000..a37f1d0b56
--- /dev/null
+++ b/src/repositories/automation-credential-repository.ts
@@ -0,0 +1,88 @@
+import { randomUUID } from "node:crypto";
+import type { AutomationCredentialAccessEvent, AutomationCredentialBinding, AutomationCredentialMetadata, AutomationCredentialRotation, AutomationCredentialScope, AutomationCredentialStatus } from "../contracts/automation-credential-types.js";
+import { AppDbStorage } from "./app-db-storage.js";
+import type { DatabaseAdapter } from "./db/database-adapter.js";
+import { EntityNotFoundError, ValidationError, toNumber } from "./repository-utils.js";
+import type { StoredSecretEnvelope } from "../services/credentials/secret-store.js";
+
+interface CredentialRow { id: string; name: string; kind: string; scope: AutomationCredentialScope; project_id: string | null; allowed_project_ids_json: string; capabilities_json: string; status: AutomationCredentialStatus; key_id: string; key_version: number; version: number; last_validated_at: string | null; validation_status: AutomationCredentialMetadata["validationStatus"]; created_at: string; updated_at: string; configured?: number }
+interface SecretRow { credential_id: string; ciphertext: Buffer; nonce: Buffer; auth_tag: Buffer; wrapped_data_key: Buffer; wrap_nonce: Buffer; wrap_auth_tag: Buffer; key_id: string; key_version: number }
+interface BindingRow { id: string; credential_id: string; project_id: string; binding_key: string; required_capabilities_json: string; created_at: string; updated_at: string }
+
+export class AutomationCredentialRepository {
+  private readonly db: DatabaseAdapter;
+  constructor(storage: AppDbStorage = new AppDbStorage()) { this.db = storage.getDatabase(); }
+
+  requireProject(projectId: string): void {
+    if (!this.db.prepare("SELECT id FROM projects WHERE id = ?").get(projectId)) throw new EntityNotFoundError(`Project not found: ${projectId}`);
+  }
+
+  list(projectId: string): AutomationCredentialMetadata[] {
+    this.requireProject(projectId);
+    const rows = this.db.prepare(`SELECT c.*, EXISTS(SELECT 1 FROM automation_credential_secrets s WHERE s.credential_id=c.id) AS configured FROM automation_credentials c WHERE c.project_id = ? OR (c.scope = 'global' AND EXISTS (SELECT 1 FROM json_each(c.allowed_project_ids_json) WHERE value = ?)) ORDER BY c.updated_at DESC`).all(projectId, projectId) as CredentialRow[];
+    return rows.map((row) => this.mapCredential(row));
+  }
+
+  get(id: string): AutomationCredentialMetadata | null {
+    const row = this.db.prepare("SELECT c.*, EXISTS(SELECT 1 FROM automation_credential_secrets s WHERE s.credential_id=c.id) AS configured FROM automation_credentials c WHERE c.id = ?").get(id) as CredentialRow | undefined;
+    return row ? this.mapCredential(row) : null;
+  }
+
+  create(input: { id?: string; name: string; kind: string; scope: AutomationCredentialScope; projectId: string | null; allowedProjectIds: string[]; capabilities: string[]; keyId: string; keyVersion: number }): AutomationCredentialMetadata {
+    if (input.scope === "project" && !input.projectId) throw new ValidationError("Project credentials require a projectId.");
+    if (input.scope === "global" && input.projectId) throw new ValidationError("Global credentials cannot have an owning projectId.");
+    if (input.projectId) this.requireProject(input.projectId);
+    for (const projectId of input.allowedProjectIds) this.requireProject(projectId);
+    const id = input.id ?? randomUUID(); const now = new Date().toISOString();
+    this.db.prepare(`INSERT INTO automation_credentials (id,name,kind,scope,project_id,allowed_project_ids_json,capabilities_json,status,key_id,key_version,version,created_at,updated_at) VALUES (?,?,?,?,?,?,?,'active',?,?,1,?,?)`).run(id, input.name, input.kind, input.scope, input.projectId, JSON.stringify(input.allowedProjectIds), JSON.stringify(input.capabilities), input.keyId, input.keyVersion, now, now);
+    return this.get(id)!;
+  }
+
+  updateSecretMetadata(id: string, keyId: string, keyVersion: number, version: number): AutomationCredentialMetadata {
+    const now = new Date().toISOString();
+    this.db.prepare("UPDATE automation_credentials SET key_id=?, key_version=?, version=?, status='active', validation_status='untested', last_validated_at=NULL, updated_at=? WHERE id=?").run(keyId, keyVersion, version, now, id);
+    const result = this.get(id); if (!result) throw new EntityNotFoundError(`Credential not found: ${id}`); return result;
+  }
+
+  updateStatus(id: string, status: AutomationCredentialStatus): AutomationCredentialMetadata {
+    this.db.prepare("UPDATE automation_credentials SET status=?, updated_at=? WHERE id=?").run(status, new Date().toISOString(), id);
+    const result = this.get(id); if (!result) throw new EntityNotFoundError(`Credential not found: ${id}`); return result;
+  }
+
+  updateValidation(id: string, status: AutomationCredentialMetadata["validationStatus"]): AutomationCredentialMetadata {
+    this.db.prepare("UPDATE automation_credentials SET validation_status=?, last_validated_at=?, updated_at=? WHERE id=?").run(status, new Date().toISOString(), new Date().toISOString(), id);
+    const result = this.get(id); if (!result) throw new EntityNotFoundError(`Credential not found: ${id}`); return result;
+  }
+
+  restrict(id: string, allowedProjectIds: string[], capabilities: string[]): AutomationCredentialMetadata {
+    const credential = this.get(id); if (!credential) throw new EntityNotFoundError(`Credential not found: ${id}`);
+    for (const projectId of allowedProjectIds) this.requireProject(projectId);
+    this.db.prepare("UPDATE automation_credentials SET allowed_project_ids_json=?, capabilities_json=?, updated_at=? WHERE id=?").run(JSON.stringify(allowedProjectIds), JSON.stringify(capabilities), new Date().toISOString(), id);
+    return this.get(id)!;
+  }
+
+  promote(id: string, allowedProjectIds: string[]): AutomationCredentialMetadata {
+    const credential = this.get(id); if (!credential) throw new EntityNotFoundError(`Credential not found: ${id}`);
+    for (const projectId of allowedProjectIds) this.requireProject(projectId);
+    this.db.prepare("UPDATE automation_credentials SET scope='global', project_id=NULL, allowed_project_ids_json=?, updated_at=? WHERE id=?").run(JSON.stringify(allowedProjectIds), new Date().toISOString(), id);
+    return this.get(id)!;
+  }
+
+  putEnvelope(envelope: StoredSecretEnvelope): void {
+    this.db.prepare(`INSERT INTO automation_credential_secrets (credential_id,ciphertext,nonce,auth_tag,wrapped_data_key,wrap_nonce,wrap_auth_tag,key_id,key_version,updated_at) VALUES (?,?,?,?,?,?,?,?,?,?) ON CONFLICT(credential_id) DO UPDATE SET ciphertext=excluded.ciphertext,nonce=excluded.nonce,auth_tag=excluded.auth_tag,wrapped_data_key=excluded.wrapped_data_key,wrap_nonce=excluded.wrap_nonce,wrap_auth_tag=excluded.wrap_auth_tag,key_id=excluded.key_id,key_version=excluded.key_version,updated_at=excluded.updated_at`).run(envelope.credentialId,envelope.ciphertext,envelope.nonce,envelope.authTag,envelope.wrappedDataKey,envelope.wrapNonce,envelope.wrapAuthTag,envelope.keyId,envelope.keyVersion,new Date().toISOString());
+  }
+  getEnvelope(credentialId: string): StoredSecretEnvelope | null { const row=this.db.prepare("SELECT * FROM automation_credential_secrets WHERE credential_id=?").get(credentialId) as SecretRow|undefined; return row ? {credentialId:row.credential_id,ciphertext:row.ciphertext,nonce:row.nonce,authTag:row.auth_tag,wrappedDataKey:row.wrapped_data_key,wrapNonce:row.wrap_nonce,wrapAuthTag:row.wrap_auth_tag,keyId:row.key_id,keyVersion:toNumber(row.key_version)} : null; }
+  deleteEnvelope(id: string): void { this.db.prepare("DELETE FROM automation_credential_secrets WHERE credential_id=?").run(id); }
+
+  bind(credentialId: string, projectId: string, bindingKey: string, requiredCapabilities: string[]): AutomationCredentialBinding {
+    this.requireProject(projectId); const now=new Date().toISOString(); const id=randomUUID();
+    this.db.prepare(`INSERT INTO automation_credential_bindings (id,credential_id,project_id,binding_key,required_capabilities_json,created_at,updated_at) VALUES (?,?,?,?,?,?,?) ON CONFLICT(project_id,binding_key) DO UPDATE SET credential_id=excluded.credential_id,required_capabilities_json=excluded.required_capabilities_json,updated_at=excluded.updated_at`).run(id,credentialId,projectId,bindingKey,JSON.stringify(requiredCapabilities),now,now);
+    return this.getBinding(projectId,bindingKey)!;
+  }
+  getBinding(projectId: string, bindingKey: string): AutomationCredentialBinding | null { const row=this.db.prepare("SELECT * FROM automation_credential_bindings WHERE project_id=? AND binding_key=?").get(projectId,bindingKey) as BindingRow|undefined; return row ? this.mapBinding(row):null; }
+  recordAccess(input: Omit<AutomationCredentialAccessEvent,"id"|"createdAt">): void { this.db.prepare(`INSERT INTO automation_credential_access_events (id,credential_id,project_id,binding_key,capability,operation,outcome,reason,created_at) VALUES (?,?,?,?,?,?,?,?,?)`).run(randomUUID(),input.credentialId,input.projectId,input.bindingKey,input.capability,input.operation,input.outcome,input.reason,new Date().toISOString()); }
+  recordRotation(input: Omit<AutomationCredentialRotation,"id"|"rotatedAt">): void { this.db.prepare(`INSERT INTO automation_credential_rotations (id,credential_id,from_version,to_version,key_id,key_version,rotated_at) VALUES (?,?,?,?,?,?,?)`).run(randomUUID(),input.credentialId,input.fromVersion,input.toVersion,input.keyId,input.keyVersion,new Date().toISOString()); }
+
+  private mapCredential(row: CredentialRow): AutomationCredentialMetadata { return {id:row.id,name:row.name,kind:row.kind,scope:row.scope,projectId:row.project_id,allowedProjectIds:JSON.parse(row.allowed_project_ids_json) as string[],capabilities:JSON.parse(row.capabilities_json) as string[],status:row.status,configured:toNumber(row.configured)===1,keyId:row.key_id,keyVersion:toNumber(row.key_version),version:toNumber(row.version),lastValidatedAt:row.last_validated_at,validationStatus:row.validation_status,createdAt:row.created_at,updatedAt:row.updated_at}; }
+  private mapBinding(row: BindingRow): AutomationCredentialBinding { return {id:row.id,credentialId:row.credential_id,projectId:row.project_id,bindingKey:row.binding_key,requiredCapabilities:JSON.parse(row.required_capabilities_json) as string[],createdAt:row.created_at,updatedAt:row.updated_at}; }
+}
diff --git a/src/repositories/db/app-db-migrations.ts b/src/repositories/db/app-db-migrations.ts
index b874fd2de6..da475c1306 100644
--- a/src/repositories/db/app-db-migrations.ts
+++ b/src/repositories/db/app-db-migrations.ts
@@ -392,6 +392,89 @@ export function ensureCustomDashboardTables(db: DatabaseAdapter): void {
   ensureIndex(db, "idx_custom_dashboard_publications_project", "custom_dashboard_publications", "project_id, published_at DESC");
 }
 
+export function ensureAutomationCredentialTables(db: DatabaseAdapter): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS automation_credentials (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      kind TEXT NOT NULL,
+      scope TEXT NOT NULL CHECK (scope IN ('project', 'global')),
+      project_id TEXT,
+      allowed_project_ids_json TEXT NOT NULL DEFAULT '[]',
+      capabilities_json TEXT NOT NULL DEFAULT '[]',
+      status TEXT NOT NULL DEFAULT 'active',
+      key_id TEXT NOT NULL,
+      key_version INTEGER NOT NULL,
+      version INTEGER NOT NULL DEFAULT 1,
+      last_validated_at TEXT,
+      validation_status TEXT NOT NULL DEFAULT 'untested',
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,
+      CHECK ((scope = 'project' AND project_id IS NOT NULL) OR (scope = 'global' AND project_id IS NULL))
+    )
+  `);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS automation_credential_secrets (
+      credential_id TEXT PRIMARY KEY,
+      ciphertext BLOB NOT NULL,
+      nonce BLOB NOT NULL,
+      auth_tag BLOB NOT NULL,
+      wrapped_data_key BLOB NOT NULL,
+      wrap_nonce BLOB NOT NULL,
+      wrap_auth_tag BLOB NOT NULL,
+      key_id TEXT NOT NULL,
+      key_version INTEGER NOT NULL,
+      updated_at TEXT NOT NULL,
+      FOREIGN KEY (credential_id) REFERENCES automation_credentials(id) ON DELETE CASCADE
+    )
+  `);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS automation_credential_bindings (
+      id TEXT PRIMARY KEY,
+      credential_id TEXT NOT NULL,
+      project_id TEXT NOT NULL,
+      binding_key TEXT NOT NULL,
+      required_capabilities_json TEXT NOT NULL DEFAULT '[]',
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      FOREIGN KEY (credential_id) REFERENCES automation_credentials(id) ON DELETE CASCADE,
+      FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,
+      UNIQUE (project_id, binding_key)
+    )
+  `);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS automation_credential_access_events (
+      id TEXT PRIMARY KEY,
+      credential_id TEXT,
+      project_id TEXT NOT NULL,
+      binding_key TEXT,
+      capability TEXT,
+      operation TEXT NOT NULL,
+      outcome TEXT NOT NULL,
+      reason TEXT,
+      created_at TEXT NOT NULL
+    )
+  `);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS automation_credential_rotations (
+      id TEXT PRIMARY KEY,
+      credential_id TEXT NOT NULL,
+      from_version INTEGER NOT NULL,
+      to_version INTEGER NOT NULL,
+      key_id TEXT NOT NULL,
+      key_version INTEGER NOT NULL,
+      rotated_at TEXT NOT NULL,
+      FOREIGN KEY (credential_id) REFERENCES automation_credentials(id) ON DELETE CASCADE
+    )
+  `);
+  ensureIndex(db, "idx_automation_credentials_project", "automation_credentials", "project_id, status, updated_at DESC");
+  ensureIndex(db, "idx_automation_credentials_global", "automation_credentials", "scope, status, updated_at DESC");
+  ensureIndex(db, "idx_automation_credential_bindings_credential", "automation_credential_bindings", "credential_id, project_id");
+  ensureIndex(db, "idx_automation_credential_access_events_project", "automation_credential_access_events", "project_id, created_at DESC");
+  ensureIndex(db, "idx_automation_credential_rotations_credential", "automation_credential_rotations", "credential_id, rotated_at DESC");
+}
+
 export function migrateSprintLinkedIssuesExternalSources(db: DatabaseAdapter): void {
   ensureColumn(db, "sprint_linked_issues", "project_key", "TEXT");
   ensureColumn(db, "sprint_linked_issues", "external_id", "TEXT");
@@ -627,6 +710,7 @@ export function runMigrations(db: DatabaseAdapter): void {
   ensureNodeFlowTables(db);
   migratePersistedNodeFlowGraphs(db);
   ensureCustomDashboardTables(db);
+  ensureAutomationCredentialTables(db);
 
   ensureColumn(db, "projects", "initialization_mode", "TEXT NOT NULL DEFAULT 'existing'");
   ensureColumn(db, "provider_invocations", "tool_call_count", "INTEGER NOT NULL DEFAULT 0");
diff --git a/src/server/automation-credential-routes.ts b/src/server/automation-credential-routes.ts
new file mode 100644
index 0000000000..3eb0cf3b7c
--- /dev/null
+++ b/src/server/automation-credential-routes.ts
@@ -0,0 +1,21 @@
+import type { Express } from "express";
+import type { DashboardDependencies } from "./dashboard-server.js";
+import { asyncRoute } from "./route-utils.js";
+import { requireTrimmedString } from "./request-parsers.js";
+import type { CreateAutomationCredentialInput } from "../contracts/automation-credential-types.js";
+
+function broker(deps: DashboardDependencies) { if (!deps.credentialBroker) throw new Error("Credential broker is not enabled."); return deps.credentialBroker; }
+const strings=(value:unknown):string[]=>Array.isArray(value)?value.filter((item):item is string=>typeof item === "string"&&item.trim().length>0).map((item)=>item.trim()):[];
+
+export function registerAutomationCredentialRoutes(app: Express,deps:DashboardDependencies):void{
+  app.get("/api/credentials/health",asyncRoute(async(_req,res)=>{res.json(await broker(deps).health());}));
+  app.get("/api/projects/:projectId/credentials",asyncRoute(async(req,res)=>{res.json(broker(deps).list(requireTrimmedString(req.params.projectId,"projectId")));}));
+  app.post("/api/projects/:projectId/credentials",asyncRoute(async(req,res)=>{res.status(201).json(await broker(deps).create(requireTrimmedString(req.params.projectId,"projectId"),req.body as CreateAutomationCredentialInput));}));
+  app.post("/api/projects/:projectId/credentials/:credentialId/bind",asyncRoute(async(req,res)=>{const body=req.body as Record<string,unknown>;res.json(broker(deps).bind(requireTrimmedString(req.params.projectId,"projectId"),requireTrimmedString(req.params.credentialId,"credentialId"),requireTrimmedString(body.bindingKey,"bindingKey"),strings(body.capabilities)));}));
+  app.post("/api/projects/:projectId/credentials/:credentialId/test",asyncRoute(async(req,res)=>{res.json(await broker(deps).test(requireTrimmedString(req.params.projectId,"projectId"),requireTrimmedString(req.params.credentialId,"credentialId")));}));
+  app.post("/api/projects/:projectId/credentials/:credentialId/rotate",asyncRoute(async(req,res)=>{res.json(await broker(deps).rotate(requireTrimmedString(req.params.projectId,"projectId"),requireTrimmedString(req.params.credentialId,"credentialId"),requireTrimmedString((req.body as Record<string,unknown>).value,"value")));}));
+  app.post("/api/projects/:projectId/credentials/:credentialId/replace",asyncRoute(async(req,res)=>{res.json(await broker(deps).replace(requireTrimmedString(req.params.projectId,"projectId"),requireTrimmedString(req.params.credentialId,"credentialId"),requireTrimmedString((req.body as Record<string,unknown>).value,"value")));}));
+  app.post("/api/projects/:projectId/credentials/:credentialId/revoke",asyncRoute(async(req,res)=>{res.json(broker(deps).revoke(requireTrimmedString(req.params.projectId,"projectId"),requireTrimmedString(req.params.credentialId,"credentialId")));}));
+  app.post("/api/projects/:projectId/credentials/:credentialId/promote",asyncRoute(async(req,res)=>{res.json(await broker(deps).promote(requireTrimmedString(req.params.projectId,"projectId"),requireTrimmedString(req.params.credentialId,"credentialId"),strings((req.body as Record<string,unknown>).allowedProjectIds)));}));
+  app.post("/api/projects/:projectId/credentials/:credentialId/restrict",asyncRoute(async(req,res)=>{const body=req.body as Record<string,unknown>;res.json(broker(deps).restrict(requireTrimmedString(req.params.projectId,"projectId"),requireTrimmedString(req.params.credentialId,"credentialId"),strings(body.allowedProjectIds),strings(body.capabilities)));}));
+}
diff --git a/src/server/dashboard-route-registration.ts b/src/server/dashboard-route-registration.ts
index 95e851cf0b..196a19bd7f 100644
--- a/src/server/dashboard-route-registration.ts
+++ b/src/server/dashboard-route-registration.ts
@@ -29,6 +29,7 @@ import { registerUpdateStatusRoutes } from "./update-status-routes.js";
 import { registerMemoryRoutes } from "./memory-routes.js";
 import { registerKnowledgeRoutes } from "./knowledge-routes.js";
 import { registerDocsWebRoutes } from "./docs-web-routes.js";
+import { registerAutomationCredentialRoutes } from "./automation-credential-routes.js";
 import { registerChatProviderRoutes } from "./chat-provider-routes.js";
 import { registerChatProviderIngressRoutes } from "./chat-provider-ingress-routes.js";
 import { registerSpeechRoutes } from "./speech-routes.js";
@@ -110,6 +111,7 @@ const registerPreviewRouteGroup = (app: Express, deps: DashboardDependencies): v
 
 const registerSettingsRouteGroup = (app: Express, deps: DashboardDependencies, liveActivityCacheMs: number): void => {
   registerSettingsRoutes(app, deps, liveActivityCacheMs);
+  registerAutomationCredentialRoutes(app, deps);
   registerChatProviderRoutes(app, deps);
   registerChatProviderIngressRoutes(app, deps);
 };
diff --git a/src/server/dashboard-server.ts b/src/server/dashboard-server.ts
index bcff13a31c..2be9edfc1c 100644
--- a/src/server/dashboard-server.ts
+++ b/src/server/dashboard-server.ts
@@ -141,6 +141,7 @@ import type { NodeFlowService } from "../services/node-flow-service.js";
 import type { CustomDashboardRepository } from "../repositories/custom-dashboard-repository.js";
 import type { CustomDashboardValidationService } from "../services/custom-dashboard-validation-service.js";
 import type { SkillService } from "../services/skill-service.js";
+import type { CredentialBroker } from "../services/credentials/credential-broker.js";
 import type { ManagedRuntimeService } from "../services/managed-runtime-service.js";
 import type { ProviderToolManager } from "../services/provider-tool-manager.js";
 import {
@@ -189,6 +190,7 @@ export interface DashboardServerOptions {
   customDashboardRepository?: CustomDashboardRepository;
   customDashboardValidationService?: CustomDashboardValidationService;
   skillService?: SkillService;
+  credentialBroker?: CredentialBroker;
   managedRuntimeService?: ManagedRuntimeService;
   providerToolManager?: ProviderToolManager;
   playwrightBrowserManager?: PlaywrightBrowserManager;
diff --git a/src/services/credentials/credential-broker.ts b/src/services/credentials/credential-broker.ts
new file mode 100644
index 0000000000..992262a547
--- /dev/null
+++ b/src/services/credentials/credential-broker.ts
@@ -0,0 +1,88 @@
+import { randomUUID } from "node:crypto";
+import type { AutomationCredentialMetadata, CreateAutomationCredentialInput, CredentialBackendHealth, CredentialResolutionRequest, ResolvedCredential } from "../../contracts/automation-credential-types.js";
+import type { AutomationCredentialRepository } from "../../repositories/automation-credential-repository.js";
+import type { KeyProvider } from "./key-provider.js";
+import type { SecretStore } from "./secret-store.js";
+
+export class CredentialAccessDeniedError extends Error {
+  constructor(message: string) { super(message); this.name = "CredentialAccessDeniedError"; }
+}
+
+export class CredentialBroker {
+  constructor(private readonly repository: AutomationCredentialRepository, private readonly secretStore: SecretStore, private readonly keyProvider: KeyProvider) {}
+
+  health(): Promise<CredentialBackendHealth> { return this.keyProvider.health(); }
+  list(projectId: string): AutomationCredentialMetadata[] { return this.repository.list(projectId); }
+
+  async create(projectId: string, input: CreateAutomationCredentialInput): Promise<AutomationCredentialMetadata> {
+    this.repository.requireProject(projectId);
+    const name=input.name?.trim(); const kind=input.kind?.trim(); const value=input.value;
+    if (!name || !kind || typeof value !== "string" || value.length === 0) throw new Error("name, kind, and a non-empty value are required.");
+    const scope=input.scope ?? "project";
+    const allowedProjectIds=scope === "global" ? [...new Set(input.allowedProjectIds ?? [])] : [];
+    if (scope === "global" && !allowedProjectIds.includes(projectId)) throw new Error("Global credentials require an explicit allowlist containing the configuring project.");
+    const health=await this.keyProvider.health();
+    if (!health.available || !health.secure || !health.keyId || health.keyVersion === null) throw new Error(health.reason ?? "Secure credential storage is unavailable.");
+    const id=randomUUID();
+    const metadata=this.repository.create({id,name,kind,scope,projectId:scope === "project" ? projectId:null,allowedProjectIds,capabilities:[...new Set(input.capabilities ?? [])],keyId:health.keyId,keyVersion:health.keyVersion});
+    const plaintext=Buffer.from(value,"utf8");
+    try { await this.secretStore.put(this.context(metadata),plaintext); }
+    catch (error) { this.repository.updateStatus(id,"unavailable"); throw error; }
+    finally { plaintext.fill(0); }
+    return this.repository.get(id)!;
+  }
+
+  bind(projectId: string, credentialId: string, bindingKey: string, capabilities: string[]) {
+    const credential=this.requireAccessible(projectId,credentialId);
+    if (credential.status !== "active") throw new CredentialAccessDeniedError("Only active credentials can be bound.");
+    const required=[...new Set(capabilities)];
+    if (required.some((capability)=>!credential.capabilities.includes(capability))) throw new CredentialAccessDeniedError("Binding requests capabilities the credential does not grant.");
+    return this.repository.bind(credentialId,projectId,bindingKey.trim(),required);
+  }
+
+  async test(projectId: string, credentialId: string): Promise<AutomationCredentialMetadata> {
+    const credential=this.requireAccessible(projectId,credentialId);
+    try { const plaintext=await this.secretStore.get(this.context(credential)); plaintext.fill(0); return this.repository.updateValidation(credentialId,"valid"); }
+    catch { this.repository.updateValidation(credentialId,"invalid"); throw new Error("Credential validation failed."); }
+  }
+
+  async rotate(projectId: string, credentialId: string, value: string): Promise<AutomationCredentialMetadata> { return this.replaceValue(projectId,credentialId,value,true); }
+  async replace(projectId: string, credentialId: string, value: string): Promise<AutomationCredentialMetadata> { return this.replaceValue(projectId,credentialId,value,false); }
+  revoke(projectId: string, credentialId: string): AutomationCredentialMetadata { this.requireAccessible(projectId,credentialId); return this.repository.updateStatus(credentialId,"revoked"); }
+  async promote(projectId: string, credentialId: string, allowedProjectIds: string[]): Promise<AutomationCredentialMetadata> { const credential=this.requireAccessible(projectId,credentialId); if (credential.scope !== "project" || credential.projectId !== projectId) throw new CredentialAccessDeniedError("Only the owning project can promote this credential."); if (!allowedProjectIds.includes(projectId)) throw new Error("The global allowlist must retain the owning project."); const plaintext=await this.secretStore.get(this.context(credential)); const promoted=this.repository.promote(credentialId,[...new Set(allowedProjectIds)]); try { await this.secretStore.put(this.context(promoted),plaintext); return this.repository.get(credentialId)!; } catch(error){this.repository.updateStatus(credentialId,"unavailable");throw error;} finally { plaintext.fill(0); } }
+  restrict(projectId: string, credentialId: string, allowedProjectIds: string[], capabilities: string[]): AutomationCredentialMetadata { const credential=this.requireAccessible(projectId,credentialId); if (credential.scope === "global" && !allowedProjectIds.includes(projectId)) throw new Error("The configuring project must remain allowlisted."); return this.repository.restrict(credentialId,[...new Set(allowedProjectIds)],[...new Set(capabilities)]); }
+
+  async resolve(request: CredentialResolutionRequest): Promise<ResolvedCredential> {
+    const binding=this.repository.getBinding(request.projectId,request.bindingKey);
+    if (!binding) return this.deny(request,null,"No credential binding exists.");
+    const credential=this.repository.get(binding.credentialId);
+    if (!credential) return this.deny(request,binding.credentialId,"Bound credential is missing.");
+    if (!this.canAccess(credential,request.projectId)) return this.deny(request,credential.id,"Credential is outside the project scope.");
+    if (credential.status !== "active") return this.deny(request,credential.id,"Credential is not active.");
+    if (!credential.capabilities.includes(request.capability) || !binding.requiredCapabilities.includes(request.capability)) return this.deny(request,credential.id,"Required capability is not approved.");
+    try {
+      const secret=await this.secretStore.get(this.context(credential)); const value=secret.toString("utf8"); secret.fill(0);
+      this.repository.recordAccess({credentialId:credential.id,projectId:request.projectId,bindingKey:request.bindingKey,capability:request.capability,operation:"resolve",outcome:"granted",reason:null});
+      return {credentialId:credential.id,value,version:credential.version};
+    } catch { return this.deny(request,credential.id,"Credential backend is unavailable or authentication failed."); }
+  }
+
+  async resolveCredentialId(request: CredentialResolutionRequest & { credentialId: string }): Promise<ResolvedCredential> {
+    const credential=this.repository.get(request.credentialId);
+    if (!credential) return this.deny(request,request.credentialId,"Credential is missing.");
+    if (!this.canAccess(credential,request.projectId)) return this.deny(request,credential.id,"Credential is outside the project scope.");
+    if (credential.status !== "active") return this.deny(request,credential.id,"Credential is not active.");
+    if (!credential.capabilities.includes(request.capability)) return this.deny(request,credential.id,"Required capability is not approved.");
+    try {
+      const secret=await this.secretStore.get(this.context(credential)); const value=secret.toString("utf8"); secret.fill(0);
+      this.repository.recordAccess({credentialId:credential.id,projectId:request.projectId,bindingKey:request.bindingKey,capability:request.capability,operation:"resolve",outcome:"granted",reason:null});
+      return {credentialId:credential.id,value,version:credential.version};
+    } catch { return this.deny(request,credential.id,"Credential backend is unavailable or authentication failed."); }
+  }
+
+  private async replaceValue(projectId:string,credentialId:string,value:string,rotation:boolean):Promise<AutomationCredentialMetadata>{ const credential=this.requireAccessible(projectId,credentialId); if (!value) throw new Error("A non-empty replacement value is required."); const plaintext=Buffer.from(value,"utf8"); try { const envelope=await this.secretStore.put(this.context(credential),plaintext); const next=this.repository.updateSecretMetadata(credentialId,envelope.keyId,envelope.keyVersion,credential.version+1); if(rotation)this.repository.recordRotation({credentialId,fromVersion:credential.version,toVersion:next.version,keyId:envelope.keyId,keyVersion:envelope.keyVersion}); return next; } finally { plaintext.fill(0); } }
+  private context(credential:AutomationCredentialMetadata){ return {credentialId:credential.id,projectId:credential.projectId ?? "global",workspaceId:credential.projectId ?? "global"}; }
+  private canAccess(credential:AutomationCredentialMetadata,projectId:string):boolean{return credential.scope === "project" ? credential.projectId === projectId : credential.allowedProjectIds.includes(projectId);}
+  private requireAccessible(projectId:string,credentialId:string):AutomationCredentialMetadata{this.repository.requireProject(projectId);const credential=this.repository.get(credentialId);if(!credential||!this.canAccess(credential,projectId))throw new CredentialAccessDeniedError("Credential is not available to this project.");return credential;}
+  private deny(request:CredentialResolutionRequest,credentialId:string|null,reason:string):never{this.repository.recordAccess({credentialId,projectId:request.projectId,bindingKey:request.bindingKey,capability:request.capability,operation:"resolve",outcome:"denied",reason});throw new CredentialAccessDeniedError(reason);}
+}
diff --git a/src/services/credentials/encryption-utils.ts b/src/services/credentials/encryption-utils.ts
new file mode 100644
index 0000000000..2433560589
--- /dev/null
+++ b/src/services/credentials/encryption-utils.ts
@@ -0,0 +1,63 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import type { KeyMaterial } from "./key-provider.js";
+import type { SecretContext, StoredSecretEnvelope } from "./secret-store.js";
+
+const ALGORITHM = "aes-256-gcm";
+const NONCE_BYTES = 12;
+
+function aad(context: SecretContext, purpose: "credential" | "data-key"): Buffer {
+  return Buffer.from(JSON.stringify({
+    credentialId: context.credentialId,
+    projectId: context.projectId,
+    workspaceId: context.workspaceId,
+    purpose,
+    schema: 1,
+  }), "utf8");
+}
+
+function encrypt(key: Buffer, plaintext: Buffer, associatedData: Buffer): { ciphertext: Buffer; nonce: Buffer; authTag: Buffer } {
+  if (key.length !== 32) throw new Error("AES-256-GCM requires a 32-byte key.");
+  const nonce = randomBytes(NONCE_BYTES);
+  const cipher = createCipheriv(ALGORITHM, key, nonce);
+  cipher.setAAD(associatedData);
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  return { ciphertext, nonce, authTag: cipher.getAuthTag() };
+}
+
+function decrypt(key: Buffer, ciphertext: Buffer, nonce: Buffer, authTag: Buffer, associatedData: Buffer): Buffer {
+  if (key.length !== 32) throw new Error("AES-256-GCM requires a 32-byte key.");
+  const decipher = createDecipheriv(ALGORITHM, key, nonce);
+  decipher.setAAD(associatedData);
+  decipher.setAuthTag(authTag);
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+
+export function encryptEnvelope(context: SecretContext, plaintext: Buffer, rootKey: KeyMaterial): StoredSecretEnvelope {
+  const dataKey = randomBytes(32);
+  try {
+    const payload = encrypt(dataKey, plaintext, aad(context, "credential"));
+    const wrapped = encrypt(rootKey.key, dataKey, aad(context, "data-key"));
+    return {
+      credentialId: context.credentialId,
+      ciphertext: payload.ciphertext,
+      nonce: payload.nonce,
+      authTag: payload.authTag,
+      wrappedDataKey: wrapped.ciphertext,
+      wrapNonce: wrapped.nonce,
+      wrapAuthTag: wrapped.authTag,
+      keyId: rootKey.keyId,
+      keyVersion: rootKey.version,
+    };
+  } finally {
+    dataKey.fill(0);
+  }
+}
+
+export function decryptEnvelope(context: SecretContext, envelope: StoredSecretEnvelope, rootKey: KeyMaterial): Buffer {
+  const dataKey = decrypt(rootKey.key, envelope.wrappedDataKey, envelope.wrapNonce, envelope.wrapAuthTag, aad(context, "data-key"));
+  try {
+    return decrypt(dataKey, envelope.ciphertext, envelope.nonce, envelope.authTag, aad(context, "credential"));
+  } finally {
+    dataKey.fill(0);
+  }
+}
diff --git a/src/services/credentials/key-provider-registry.ts b/src/services/credentials/key-provider-registry.ts
new file mode 100644
index 0000000000..afb200093a
--- /dev/null
+++ b/src/services/credentials/key-provider-registry.ts
@@ -0,0 +1,13 @@
+import type { KeyProvider } from "./key-provider.js";
+
+let processKeyProvider: KeyProvider | null = null;
+
+/** Configures a host-specific provider before dependency construction (for example Electron safeStorage). */
+export function setProcessCredentialKeyProvider(provider: KeyProvider): void {
+  if (processKeyProvider) throw new Error("The process credential key provider is already configured.");
+  processKeyProvider = provider;
+}
+
+export function getProcessCredentialKeyProvider(): KeyProvider | null {
+  return processKeyProvider;
+}
diff --git a/src/services/credentials/key-provider.ts b/src/services/credentials/key-provider.ts
new file mode 100644
index 0000000000..5ecc2ee747
--- /dev/null
+++ b/src/services/credentials/key-provider.ts
@@ -0,0 +1,21 @@
+import type { CredentialBackendHealth } from "../../contracts/automation-credential-types.js";
+
+export interface KeyMaterial {
+  key: Buffer;
+  keyId: string;
+  version: number;
+}
+
+export interface KeyProvider {
+  readonly providerName: string;
+  health(): Promise<CredentialBackendHealth>;
+  getActiveKey(): Promise<KeyMaterial>;
+  getKey(keyId: string, version: number): Promise<KeyMaterial>;
+}
+
+export class KeyProviderUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "KeyProviderUnavailableError";
+  }
+}
diff --git a/src/services/credentials/secret-store.ts b/src/services/credentials/secret-store.ts
new file mode 100644
index 0000000000..2c6935557c
--- /dev/null
+++ b/src/services/credentials/secret-store.ts
@@ -0,0 +1,23 @@
+export interface SecretContext {
+  credentialId: string;
+  projectId: string;
+  workspaceId: string;
+}
+
+export interface StoredSecretEnvelope {
+  credentialId: string;
+  ciphertext: Buffer;
+  nonce: Buffer;
+  authTag: Buffer;
+  wrappedDataKey: Buffer;
+  wrapNonce: Buffer;
+  wrapAuthTag: Buffer;
+  keyId: string;
+  keyVersion: number;
+}
+
+export interface SecretStore {
+  put(context: SecretContext, plaintext: Buffer): Promise<StoredSecretEnvelope>;
+  get(context: SecretContext): Promise<Buffer>;
+  delete(credentialId: string): Promise<void>;
+}
diff --git a/src/services/node-flow-runtime-service.ts b/src/services/node-flow-runtime-service.ts
index d99082ef0b..92c16e1afb 100644
--- a/src/services/node-flow-runtime-service.ts
+++ b/src/services/node-flow-runtime-service.ts
@@ -10,6 +10,7 @@ import type { SettingsRepository } from "../repositories/settings-repository.js"
 import type { ProviderExecutionService } from "./provider-execution-service.js";
 import type { CliProviderId } from "../infrastructure/providers/cli/provider-command-specs.js";
 import type { ProviderRunResult } from "../infrastructure/providers/cli/provider-runner.js";
+import type { CredentialBroker } from "./credentials/credential-broker.js";
 import { buildProviderInvocationWorkspaceOptions } from "../infrastructure/providers/cli/invocation-workspace-preparer.js";
 import type {
   DashboardSettings,
@@ -40,6 +41,7 @@ interface NodeFlowRuntimeDeps {
   settingsRepository: SettingsRepository;
   providerExecutionService?: ProviderExecutionService;
   getDashboardSettings?: (projectId: string) => DashboardSettings;
+  credentialBroker?: CredentialBroker;
 }
 
 interface RuntimeContext {
@@ -334,6 +336,7 @@ export class NodeFlowRuntimeService {
       throw new ValidationError(`Provider prompt node ${node.id} requires a prompt value.`);
     }
     const providerSettings = this.resolveProviderSettings(context.projectId, config);
+    const boundCredential = await this.resolveNodeCredential(context, node, "provider");
     if (!CLI_PROVIDER_IDS.has(providerSettings.provider)) {
       throw new ValidationError(`Provider prompt node ${node.id} requires a CLI provider.`);
     }
@@ -359,7 +362,7 @@ export class NodeFlowRuntimeService {
       maxConcurrentTasks: providerSettings.maxConcurrentTasks,
       prompt,
       model: readString(config.model) ?? providerSettings.model,
-      apiKey: providerSettings.apiKey,
+      apiKey: boundCredential ?? providerSettings.apiKey,
       providerMountAuth: providerSettings.mountAuth,
       providerAuthPath: providerSettings.authPath,
       providerConfigMode: providerSettings.providerConfigMode,
@@ -448,6 +451,8 @@ export class NodeFlowRuntimeService {
       }
     }
     const headers = normalizeHeaders(readJsonObject(config.headers));
+    const boundCredential = await this.resolveNodeCredential(context, node, "auth");
+    if (boundCredential) headers.Authorization = boundCredential;
     const timeoutMs = normalizeTimeout(config.timeout ?? config.timeoutMs);
     const controller = new AbortController();
     const abortListener = (): void => controller.abort(context.options.signal?.reason);
@@ -494,6 +499,14 @@ export class NodeFlowRuntimeService {
     }
   }
 
+  private async resolveNodeCredential(context: RuntimeContext,node:NodeFlowNode,slot:string):Promise<string|undefined>{
+    const binding=node.credentialBindings?.find((candidate)=>candidate.slot===slot);
+    if (!binding) return undefined;
+    if (!this.deps.credentialBroker) throw new ValidationError("Credential broker is not configured for node flow runtime.");
+    const resolved=await this.deps.credentialBroker.resolveCredentialId({projectId:context.projectId,credentialId:binding.credentialId,bindingKey:`${context.flowId}:${node.id}:${slot}`,capability:"read",workspaceId:context.runId});
+    return resolved.value;
+  }
+
   private executeOutputNode(context: RuntimeContext, node: NodeFlowNode): NodeFlowJsonObject {
     const config = readNodeConfig(node);
     const valuePath = readString(config.path) ?? readString(config.valuePath);
diff --git a/tests/backend/repositories/automation-credential-repository.test.ts b/tests/backend/repositories/automation-credential-repository.test.ts
new file mode 100644
index 0000000000..9b8004c2cd
--- /dev/null
+++ b/tests/backend/repositories/automation-credential-repository.test.ts
@@ -0,0 +1,20 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AppDbStorage } from "../../../src/repositories/app-db-storage.js";
+import { ProjectManagementRepository } from "../../../src/repositories/project-management-repository.js";
+import { AutomationCredentialRepository } from "../../../src/repositories/automation-credential-repository.js";
+import { MountedKeyFileProvider } from "../../../src/infrastructure/security/mounted-key-file-provider.js";
+import { EncryptedSqliteSecretStore } from "../../../src/infrastructure/security/encrypted-sqlite-secret-store.js";
+import { CredentialBroker } from "../../../src/services/credentials/credential-broker.js";
+
+const dirs:string[]=[];
+async function fixture(){const dir=await mkdtemp(join(tmpdir(),"credential-test-"));dirs.push(dir);const dbPath=join(dir,"app.db");const keyPath=join(dir,"root.key");await writeFile(keyPath,Buffer.alloc(32,9).toString("base64"),{mode:0o600});const storage=new AppDbStorage(dbPath);const projects=new ProjectManagementRepository(storage);const first=projects.createProject({name:"First",sourceType:"local",sourceRef:join(dir,"first")});const second=projects.createProject({name:"Second",sourceType:"local",sourceRef:join(dir,"second")});const repository=new AutomationCredentialRepository(storage);const provider=new MountedKeyFileProvider(keyPath);const broker=new CredentialBroker(repository,new EncryptedSqliteSecretStore(repository,provider),provider);return{dir,dbPath,storage,repository,broker,first,second};}
+afterEach(async()=>{await Promise.all(dirs.splice(0).map((dir)=>rm(dir,{recursive:true,force:true})))});
+
+describe("automation credential repository and broker",()=>{
+  it("persists only encrypted material, resolves capabilities, rotates, and audits metadata",async()=>{const f=await fixture();const secret="plain-secret-marker";const created=await f.broker.create(f.first.id,{name:"Token",kind:"api-token",value:secret,capabilities:["read"]});expect(JSON.stringify(created)).not.toContain(secret);const persisted=f.storage.getDatabase().prepare("SELECT * FROM automation_credential_secrets WHERE credential_id=?").get(created.id) as Record<string,unknown>;expect(JSON.stringify(persisted)).not.toContain(secret);f.broker.bind(f.first.id,created.id,"node.http",["read"]);expect((await f.broker.resolve({projectId:f.first.id,bindingKey:"node.http",capability:"read",workspaceId:"run"})).value).toBe(secret);const rotated=await f.broker.rotate(f.first.id,created.id,"replacement");expect(rotated.version).toBe(2);expect((await f.broker.resolve({projectId:f.first.id,bindingKey:"node.http",capability:"read",workspaceId:"run"})).value).toBe("replacement");const event=f.storage.getDatabase().prepare("SELECT * FROM automation_credential_access_events ORDER BY created_at DESC LIMIT 1").get() as Record<string,unknown>;expect(JSON.stringify(event)).not.toContain(secret);expect(f.storage.getDatabase().prepare("SELECT COUNT(*) AS count FROM automation_credential_rotations").get()).toMatchObject({count:1});f.storage.close();});
+  it("fails closed for cross-project, revoked, missing, and insecure providers",async()=>{const f=await fixture();const created=await f.broker.create(f.first.id,{name:"Token",kind:"api-token",value:"secret",capabilities:["read"]});expect(()=>f.broker.bind(f.second.id,created.id,"node.http",["read"])).toThrow(/not available/);f.broker.bind(f.first.id,created.id,"node.http",["read"]);f.broker.revoke(f.first.id,created.id);await expect(f.broker.resolve({projectId:f.first.id,bindingKey:"node.http",capability:"read",workspaceId:"run"})).rejects.toThrow(/not active/);const insecurePath=join(f.dir,"insecure.key");await writeFile(insecurePath,Buffer.alloc(32,4).toString("base64"),{mode:0o644});const insecureHealth=await new MountedKeyFileProvider(insecurePath).health();expect(insecureHealth).toMatchObject({available:false,secure:false});f.storage.close();const unavailable=new MountedKeyFileProvider(undefined);expect((await unavailable.health()).available).toBe(false);});
+  it("requires explicit project allowlists and re-encrypts promoted credentials",async()=>{const f=await fixture();await expect(f.broker.create(f.first.id,{name:"Global",kind:"token",value:"secret",scope:"global",allowedProjectIds:[f.second.id],capabilities:["read"]})).rejects.toThrow(/explicit allowlist/);const projectCredential=await f.broker.create(f.first.id,{name:"Promoted",kind:"token",value:"secret",capabilities:["read"]});const promoted=await f.broker.promote(f.first.id,projectCredential.id,[f.first.id,f.second.id]);expect(promoted.scope).toBe("global");f.broker.bind(f.second.id,promoted.id,"node.global",["read"]);expect((await f.broker.resolve({projectId:f.second.id,bindingKey:"node.global",capability:"read",workspaceId:"run"})).value).toBe("secret");f.storage.close();});
+});
diff --git a/tests/backend/server/automation-credential-routes.test.ts b/tests/backend/server/automation-credential-routes.test.ts
new file mode 100644
index 0000000000..922e14cb03
--- /dev/null
+++ b/tests/backend/server/automation-credential-routes.test.ts
@@ -0,0 +1,8 @@
+import express from "express";
+import request from "supertest";
+import { describe, expect, it, vi } from "vitest";
+import { registerAutomationCredentialRoutes } from "../../../src/server/automation-credential-routes.js";
+
+describe("automation credential routes",()=>{
+  it("passes secret values only into write operations and returns metadata",async()=>{const metadata={id:"credential-1",name:"Token",kind:"api-token",scope:"project",projectId:"project-1",allowedProjectIds:[],capabilities:["read"],status:"active",configured:true,keyId:"root",keyVersion:1,version:1,lastValidatedAt:null,validationStatus:"untested",createdAt:"now",updatedAt:"now"};const credentialBroker={create:vi.fn().mockResolvedValue(metadata)};const app=express();app.use(express.json());registerAutomationCredentialRoutes(app,{credentialBroker} as any);const response=await request(app).post("/api/projects/project-1/credentials").send({name:"Token",kind:"api-token",value:"super-secret",capabilities:["read"]});expect(response.status).toBe(201);expect(response.body).toEqual(metadata);expect(JSON.stringify(response.body)).not.toContain("super-secret");expect(credentialBroker.create).toHaveBeenCalledWith("project-1",expect.objectContaining({value:"super-secret"}));});
+});
diff --git a/tests/backend/services/credential-encryption.test.ts b/tests/backend/services/credential-encryption.test.ts
new file mode 100644
index 0000000000..70a32906c6
--- /dev/null
+++ b/tests/backend/services/credential-encryption.test.ts
@@ -0,0 +1,12 @@
+import { randomBytes } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { decryptEnvelope, encryptEnvelope } from "../../../src/services/credentials/encryption-utils.js";
+
+const context={credentialId:"credential-1",projectId:"project-1",workspaceId:"workspace-1"};
+const root={key:Buffer.alloc(32,7),keyId:"root",version:1};
+
+describe("credential envelope encryption",()=>{
+  it("round trips with unique payload and wrap nonces",()=>{const first=encryptEnvelope(context,Buffer.from("secret"),root);const second=encryptEnvelope(context,Buffer.from("secret"),root);expect(decryptEnvelope(context,first,root).toString()).toBe("secret");expect(first.nonce.equals(second.nonce)).toBe(false);expect(first.wrapNonce.equals(second.wrapNonce)).toBe(false);expect(first.ciphertext.toString("utf8")).not.toContain("secret");});
+  it.each(["ciphertext","authTag","wrappedDataKey","wrapAuthTag"] as const)("rejects %s tampering",(field)=>{const envelope=encryptEnvelope(context,Buffer.from("secret"),root);envelope[field][0]^=1;expect(()=>decryptEnvelope(context,envelope,root)).toThrow();});
+  it("rejects wrong keys and authenticated context",()=>{const envelope=encryptEnvelope(context,Buffer.from("secret"),root);expect(()=>decryptEnvelope(context,envelope,{...root,key:randomBytes(32)})).toThrow();expect(()=>decryptEnvelope({...context,workspaceId:"other"},envelope,root)).toThrow();});
+});
diff --git a/tests/backend/services/node-flow-runtime-service.test.ts b/tests/backend/services/node-flow-runtime-service.test.ts
index dc1683f65a..072726e075 100644
--- a/tests/backend/services/node-flow-runtime-service.test.ts
+++ b/tests/backend/services/node-flow-runtime-service.test.ts
@@ -12,10 +12,11 @@ import { DEFAULT_DASHBOARD_SETTINGS } from "../../../src/repositories/settings-d
 import { NodeFlowRuntimeService } from "../../../src/services/node-flow-runtime-service.js";
 import type { ProviderExecutionService } from "../../../src/services/provider-execution-service.js";
 import type { NodeFlowGraph } from "../../../src/contracts/node-flow-types.js";
+import type { CredentialBroker } from "../../../src/services/credentials/credential-broker.js";
 
 const tempDirs: string[] = [];
 
-async function createRuntime(providerExecutionService?: Partial<ProviderExecutionService>): Promise<{
+async function createRuntime(providerExecutionService?: Partial<ProviderExecutionService>,credentialBroker?:Partial<CredentialBroker>): Promise<{
   dir: string;
   projectRepository: ProjectManagementRepository;
   nodeFlowRepository: NodeFlowRepository;
@@ -34,6 +35,7 @@ async function createRuntime(providerExecutionService?: Partial<ProviderExecutio
     projectManagementRepository: projectRepository,
     settingsRepository: new SettingsRepository(path.join(dir, "settings.db")),
     providerExecutionService: providerExecutionService as ProviderExecutionService | undefined,
+    credentialBroker: credentialBroker as CredentialBroker | undefined,
     getDashboardSettings: () => DEFAULT_DASHBOARD_SETTINGS,
   });
   return { dir, projectRepository, nodeFlowRepository, executionRepository, runtime };
@@ -90,14 +92,15 @@ describe("NodeFlowRuntimeService", () => {
         rawUsageJson: null,
       },
     });
-    const { dir, projectRepository, nodeFlowRepository, executionRepository, runtime } = await createRuntime({ executeProvider } as Partial<ProviderExecutionService>);
+    const resolveCredentialId=vi.fn().mockResolvedValue({credentialId:"credential-1",value:"bound-secret",version:1});
+    const { dir, projectRepository, nodeFlowRepository, executionRepository, runtime } = await createRuntime({ executeProvider } as Partial<ProviderExecutionService>,{resolveCredentialId});
     const project = projectRepository.createProject({ name: "Provider Project", sourceType: "local", sourceRef: dir });
     const flow = nodeFlowRepository.createFlow(project.id, {
       title: "Provider",
       graph: {
         nodes: [
           { id: "input", type: "input", title: "Input" },
-          { id: "prompt", type: "provider_prompt", title: "Prompt", data: { provider: "mockup-cli", prompt: "Answer {{input.question}}" } },
+          { id: "prompt", type: "provider_prompt", title: "Prompt", data: { provider: "mockup-cli", prompt: "Answer {{input.question}}" }, credentialBindings: [{slot:"provider",credentialId:"credential-1"}] },
           { id: "output", type: "output", title: "Output" },
         ],
         edges: [
@@ -113,10 +116,12 @@ describe("NodeFlowRuntimeService", () => {
       type: "node_flow_node",
       provider: "mockup-cli",
       prompt: "Answer now",
+      apiKey: "bound-secret",
       invocationId: expect.stringMatching(/^xi_/),
       trackPromptInInvocation: false,
       trackAssistantInInvocation: false,
     }));
+    expect(resolveCredentialId).toHaveBeenCalledWith(expect.objectContaining({projectId:project.id,credentialId:"credential-1",bindingKey:`${flow.id}:prompt:provider`,capability:"read"}));
     const promptRun = result.nodeRuns.find((nodeRun) => nodeRun.nodeId === "prompt");
     expect(promptRun?.executionInvocationId).toMatch(/^xi_/);
     expect(promptRun?.output).toMatchObject({ text: "provider answer", nativeSessionId: "native-1" });

From 27faf92be18c1a08090280c199bb90255dfdaae0 Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 04:44:42 +0000
Subject: [PATCH 03/25] feat(task T03): implement via codex

---
 .../node-flow-durable-execution.md            |   7 +
 docs-web/architecture/node-flows.md           |   2 +
 ...chitecture-node-flow-durable-execution.mdx |   7 +
 .../content/docs/architecture-node-flows.mdx  |   2 +
 docs-web/content/docs/registry.ts             |   9 ++
 .../content/docs/user-dashboard-scheduler.mdx |   4 +-
 ...cture-node-flow-durable-execution.lazy.tsx |  11 ++
 docs-web/user/dashboard/scheduler.md          |   4 +-
 docs/SUMMARY.md                               |   1 +
 .../node-flow-durable-execution.md            |  15 ++
 docs/architecture/node-flows.md               |   8 +-
 docs/dashboard/scheduler.md                   |   4 +-
 docs/index.md                                 |   2 +
 .../dependency-factory/dashboard-factory.ts   |   4 +
 .../node-flow-execution-policy-types.ts       |  45 ++++++
 src/contracts/node-flow-types.ts              |  55 ++++++-
 src/contracts/scheduler-types.ts              |   2 +
 src/mcp/management/node-flow-actions.ts       |   5 +
 src/repositories/db/app-db-migrations.ts      |  51 +++++++
 src/repositories/node-flow-repository.ts      | 143 +++++++++++++++++-
 src/repositories/scheduler-repository.ts      |  11 +-
 src/server/node-flow-routes.ts                |   7 +
 src/services/node-flow-runtime-service.ts     | 118 +++++++++++++--
 src/services/node-flow-service.ts             |   4 +
 .../node-flows/node-flow-attempt-service.ts   |  21 +++
 .../node-flows/node-flow-lease-service.ts     |   8 +
 .../node-flow-publication-service.ts          |  19 +++
 .../node-flows/node-flow-queue-service.ts     |  18 +++
 .../node-flows/node-flow-recovery-service.ts  |  27 ++++
 src/services/scheduler-service.ts             |  11 +-
 .../mcp/management-node-flow-actions.test.ts  |   1 +
 .../repositories/scheduler-repository.test.ts |   2 +
 tests/backend/server/node-flow-routes.test.ts |   1 +
 .../node-flow-recovery-service.test.ts        |  59 ++++++++
 .../node-flow-runtime-service.test.ts         |  45 ++++++
 .../services/scheduler-service.test.ts        |   1 +
 36 files changed, 707 insertions(+), 27 deletions(-)
 create mode 100644 docs-web/architecture/node-flow-durable-execution.md
 create mode 100644 docs-web/content/docs/architecture-node-flow-durable-execution.mdx
 create mode 100644 docs-web/routes/docs.architecture-node-flow-durable-execution.lazy.tsx
 create mode 100644 docs/architecture/node-flow-durable-execution.md
 create mode 100644 src/contracts/node-flow-execution-policy-types.ts
 create mode 100644 src/services/node-flows/node-flow-attempt-service.ts
 create mode 100644 src/services/node-flows/node-flow-lease-service.ts
 create mode 100644 src/services/node-flows/node-flow-publication-service.ts
 create mode 100644 src/services/node-flows/node-flow-queue-service.ts
 create mode 100644 src/services/node-flows/node-flow-recovery-service.ts
 create mode 100644 tests/backend/services/node-flow-recovery-service.test.ts

diff --git a/docs-web/architecture/node-flow-durable-execution.md b/docs-web/architecture/node-flow-durable-execution.md
new file mode 100644
index 0000000000..e5bc80f167
--- /dev/null
+++ b/docs-web/architecture/node-flow-durable-execution.md
@@ -0,0 +1,7 @@
+# Node Flow Durable Execution
+
+Node flows execute immutable published snapshots. A run explicitly pins a published version or follows the latest published version; later edits cannot change a pinned run.
+
+Runs are durably queued and leased with bounded global and project concurrency. Node attempts retain attempt number, executor and invocation identity, artifact digest, redacted payloads, credential ids, failure class, and retry decision. Retryable failures use bounded exponential backoff and jitter, while cancellation and timeout signals propagate to provider and HTTP work.
+
+On restart, expired pre-invocation work is safely requeued. Work with an external invocation and an unknown outcome moves to `attention_required` and is never silently replayed. Credential values are resolved only for the active node and are not retained in run history or diagnostics.
diff --git a/docs-web/architecture/node-flows.md b/docs-web/architecture/node-flows.md
index 493c84b123..f3f15bfffa 100644
--- a/docs-web/architecture/node-flows.md
+++ b/docs-web/architecture/node-flows.md
@@ -14,3 +14,5 @@ Node flows are project-owned, versioned Graph v2 workflows.
 | `output` | Selects the result. |
 
 These are the only executable definitions. Trigger, agent-router, task, condition, notification, and other palette concepts are planned entries without runtime handlers. Graph v1 migration preserves the legacy snapshot and appends deterministic v2.
+
+Execution uses immutable publications rather than the mutable editor row. Runs select a pinned publication or the latest published version, then use durable queue claims, leases, bounded quotas, timeout/cancellation propagation, and numbered retry attempts. Expired external attempts with unknown outcomes require operator attention and are not silently replayed. See [Node Flow Durable Execution](./node-flow-durable-execution.md).
diff --git a/docs-web/content/docs/architecture-node-flow-durable-execution.mdx b/docs-web/content/docs/architecture-node-flow-durable-execution.mdx
new file mode 100644
index 0000000000..e5bc80f167
--- /dev/null
+++ b/docs-web/content/docs/architecture-node-flow-durable-execution.mdx
@@ -0,0 +1,7 @@
+# Node Flow Durable Execution
+
+Node flows execute immutable published snapshots. A run explicitly pins a published version or follows the latest published version; later edits cannot change a pinned run.
+
+Runs are durably queued and leased with bounded global and project concurrency. Node attempts retain attempt number, executor and invocation identity, artifact digest, redacted payloads, credential ids, failure class, and retry decision. Retryable failures use bounded exponential backoff and jitter, while cancellation and timeout signals propagate to provider and HTTP work.
+
+On restart, expired pre-invocation work is safely requeued. Work with an external invocation and an unknown outcome moves to `attention_required` and is never silently replayed. Credential values are resolved only for the active node and are not retained in run history or diagnostics.
diff --git a/docs-web/content/docs/architecture-node-flows.mdx b/docs-web/content/docs/architecture-node-flows.mdx
index 493c84b123..31bf1274aa 100644
--- a/docs-web/content/docs/architecture-node-flows.mdx
+++ b/docs-web/content/docs/architecture-node-flows.mdx
@@ -14,3 +14,5 @@ Node flows are project-owned, versioned Graph v2 workflows.
 | `output` | Selects the result. |
 
 These are the only executable definitions. Trigger, agent-router, task, condition, notification, and other palette concepts are planned entries without runtime handlers. Graph v1 migration preserves the legacy snapshot and appends deterministic v2.
+
+Execution uses immutable publications rather than the mutable editor row. Runs select a pinned publication or the latest published version, then use durable queue claims, leases, bounded quotas, timeout/cancellation propagation, and numbered retry attempts. Expired external attempts with unknown outcomes require operator attention and are not silently replayed. See [Node Flow Durable Execution](/docs/architecture-node-flow-durable-execution).
diff --git a/docs-web/content/docs/registry.ts b/docs-web/content/docs/registry.ts
index 522ed80858..637afe7f3a 100644
--- a/docs-web/content/docs/registry.ts
+++ b/docs-web/content/docs/registry.ts
@@ -108,6 +108,7 @@ export type DocsSlug =
   | 'user-dashboard-custom-dashboards'
   | 'architecture-custom-dashboard-foundation'
   | 'architecture-managed-container-runtime'
+  | 'architecture-node-flow-durable-execution'
   | 'architecture-node-flow-foundation'
   | 'architecture-node-flows'
   | 'architecture-speech-input'
@@ -858,6 +859,13 @@ export const docsRegistry: Record<DocsSlug, DocsRegistryEntry> = {
     title: "Managed Container Runtime",
     description: "The managed container runtime removes first-invocation Docker builds while keeping provider binaries local to each user's Docker host.",
   },
+  'architecture-node-flow-durable-execution': {
+    id: 'architecture-node-flow-durable-execution',
+    path: '/docs/architecture-node-flow-durable-execution',
+    section: 'Architecture',
+    title: "Node Flow Durable Execution",
+    description: "Node flows execute immutable published snapshots. A run explicitly pins a published version or follows the latest published version; later edits cannot change a pinned run.",
+  },
   'architecture-node-flow-foundation': {
     id: 'architecture-node-flow-foundation',
     path: '/docs/architecture-node-flow-foundation',
@@ -1001,6 +1009,7 @@ export const orderedDocs: DocsRegistryEntry[] = [
   docsRegistry['user-dashboard-custom-dashboards'],
   docsRegistry['architecture-custom-dashboard-foundation'],
   docsRegistry['architecture-managed-container-runtime'],
+  docsRegistry['architecture-node-flow-durable-execution'],
   docsRegistry['architecture-node-flow-foundation'],
   docsRegistry['architecture-node-flows'],
   docsRegistry['architecture-speech-input'],
diff --git a/docs-web/content/docs/user-dashboard-scheduler.mdx b/docs-web/content/docs/user-dashboard-scheduler.mdx
index aeda9453e7..3331436bb2 100644
--- a/docs-web/content/docs/user-dashboard-scheduler.mdx
+++ b/docs-web/content/docs/user-dashboard-scheduler.mdx
@@ -22,11 +22,13 @@ Each scheduler entry has a **target** — the thing that runs when it fires:
 | **Message** | Posts a project message (for example, a recurring planning or status prompt). |
 | **Memory remediation** | Runs the long-term memory cleanup workflow on a schedule. |
 
-Node-flow entries store `nodeFlowTarget = { flowId, input?, flowVersion? }` inside the existing
+Node-flow entries store `nodeFlowTarget = { flowId, input?, versionSelection }` inside the existing
 target JSON payload, validate that the flow belongs to the selected project, and run through the
 node-flow runtime with scheduler trigger metadata when due. Blank dashboard input is omitted, and
 supplied input must be a JSON object.
 
+Choose a pinned published version when every occurrence must execute the same immutable snapshot, or latest published when each occurrence should pick up the newest publication. A legacy `flowVersion` is treated as a pinned version and affects execution, not just audit metadata.
+
 The backend scheduler contract also supports agent-created wakeups.
 Agent wakeups are stored in the target JSON payload with `origin` and `source` set to
 `agent_scheduler`, plus `createdByAgentId` when the creating agent provides it. Agent wakeups post
diff --git a/docs-web/routes/docs.architecture-node-flow-durable-execution.lazy.tsx b/docs-web/routes/docs.architecture-node-flow-durable-execution.lazy.tsx
new file mode 100644
index 0000000000..033f986814
--- /dev/null
+++ b/docs-web/routes/docs.architecture-node-flow-durable-execution.lazy.tsx
@@ -0,0 +1,11 @@
+import { createLazyFileRoute } from '@tanstack/react-router'
+import ArchitectureNodeFlowDurableExecutionContent from '../content/docs/architecture-node-flow-durable-execution.mdx'
+import { DocsPage } from '../components/docs/DocsPage'
+
+export const Route = createLazyFileRoute('/docs/architecture-node-flow-durable-execution')({
+  component: () => (
+    <DocsPage id="architecture-node-flow-durable-execution">
+      <ArchitectureNodeFlowDurableExecutionContent />
+    </DocsPage>
+  )
+})
diff --git a/docs-web/user/dashboard/scheduler.md b/docs-web/user/dashboard/scheduler.md
index c2ebc68e24..34481144bb 100644
--- a/docs-web/user/dashboard/scheduler.md
+++ b/docs-web/user/dashboard/scheduler.md
@@ -22,11 +22,13 @@ Each scheduler entry has a **target** — the thing that runs when it fires:
 | **Message** | Posts a project message (for example, a recurring planning or status prompt). |
 | **Memory remediation** | Runs the long-term memory cleanup workflow on a schedule. |
 
-Node-flow entries store `nodeFlowTarget = { flowId, input?, flowVersion? }` inside the existing
+Node-flow entries store `nodeFlowTarget = { flowId, input?, versionSelection }` inside the existing
 target JSON payload, validate that the flow belongs to the selected project, and run through the
 node-flow runtime with scheduler trigger metadata when due. Blank dashboard input is omitted, and
 supplied input must be a JSON object.
 
+Choose a pinned published version when every occurrence must execute the same immutable snapshot, or latest published when each occurrence should pick up the newest publication. A legacy `flowVersion` is treated as a pinned version and affects execution, not just audit metadata.
+
 The backend scheduler contract also supports agent-created wakeups.
 Agent wakeups are stored in the target JSON payload with `origin` and `source` set to
 `agent_scheduler`, plus `createdByAgentId` when the creating agent provides it. Agent wakeups post
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 5e0a632d23..933e7c124d 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -39,6 +39,7 @@
 - [Agent Knowledge Base](./architecture/agent-knowledge-base.md)
 - [Node Flow Foundation](./architecture/node-flow-foundation.md)
 - [Node Flows](./architecture/node-flows.md)
+- [Node Flow Durable Execution](./architecture/node-flow-durable-execution.md)
 - [Custom Dashboard Foundation](./architecture/custom-dashboard-foundation.md)
 - [Memory Claims and Evidence](./architecture/memory-claims.md)
 - [Speech Input Architecture](./architecture/speech-input.md)
diff --git a/docs/architecture/node-flow-durable-execution.md b/docs/architecture/node-flow-durable-execution.md
new file mode 100644
index 0000000000..334447c9de
--- /dev/null
+++ b/docs/architecture/node-flow-durable-execution.md
@@ -0,0 +1,15 @@
+# Node Flow Durable Execution
+
+Node-flow execution is publication based. Saving a flow appends an immutable version and publication containing the normalized graph and an immutable execution-policy snapshot. Manual, MCP, and scheduled callers select either `{ mode: "pinned", version: N }` or `{ mode: "latest_published" }`; the runtime never executes the mutable `node_flows` graph.
+
+## Durable lifecycle
+
+Runs move through `queued`, `running`, `approval_waiting`, `retry_waiting`, `attention_required`, and terminal `succeeded`, `failed`, or `cancelled` states. A queue claim assigns an executor, lease expiry, and heartbeat. Global and per-project limits bound active claims. Cancellation and node timeouts propagate through `AbortSignal`.
+
+Every node execution creates a numbered attempt with executor identity, optional execution invocation id, SHA-256 output digest, redacted input/output, credential ids, failure classification, and retry decision. Retryable timeout, quota, and transient failures use the publication policy's bounded exponential backoff and jitter. Credential values are resolved only at the node boundary and are never written to run, attempt, invocation, or diagnostic records.
+
+## Recovery contract
+
+Startup recovery scans queued and waiting work plus running work with expired leases. A pre-invocation attempt can be requeued safely without inserting a duplicate attempt. An expired attempt with an invocation id has an unknown externally observable outcome and moves to `attention_required`; Code UX does not silently replay it. Approval- and retry-waiting runs retain their durable state until their prerequisite becomes actionable.
+
+The relevant tables are `node_flow_publications`, `node_flow_runs`, `node_flow_node_runs`, and `node_flow_node_attempts`. Attempt history is available at `GET /api/node-flow-runs/:runId/attempts` and contains only redacted payloads and credential identifiers.
diff --git a/docs/architecture/node-flows.md b/docs/architecture/node-flows.md
index 6268a53066..bc355cf310 100644
--- a/docs/architecture/node-flows.md
+++ b/docs/architecture/node-flows.md
@@ -11,10 +11,12 @@ Node-flow persistence is owned by `NodeFlowRepository` and stored in SQLite:
 | Table | Purpose |
 | --- | --- |
 | `node_flows` | Current project-scoped flow record: id, project id, title, description, normalized `graph_json`, current version, and timestamps. |
-| `node_flow_versions` | Immutable snapshots written on create and every update. Versions keep the graph saved at that point, even though current runtime execution uses the latest flow record. |
+| `node_flow_versions` | Immutable edit snapshots written on create and every update. |
+| `node_flow_publications` | Immutable executable graph and execution-policy snapshots selected by pinned or latest-published runs. |
 | `node_flow_agent_skills` | Agent attachment table keyed by flow and agent preset. It stores the skill display name and description used when exposing the flow as a repeatable agent capability. |
 | `node_flow_runs` | Flow run records with status, version, trigger type, redacted trigger payload, redacted input/output, error message, timestamps, and optional `execution_invocation_id`. |
 | `node_flow_node_runs` | Per-node run records with status, node id, redacted input/output, error message, timestamps, and optional `execution_invocation_id`. |
+| `node_flow_node_attempts` | Numbered attempts with executor/invocation identity, artifact digest, credential ids, redacted payloads, failure class, and retry decision. |
 
 All graphs, widget schemas, run inputs, outputs, and trigger payloads are stored as JSON text and hydrated into typed contracts at the repository boundary. Flow, version, run, and attachment records belong to a project. Agent attachment operations verify that the target agent preset belongs to the same project as the flow.
 
@@ -37,7 +39,7 @@ Dashboard-only editable canvas state lives in `dashboard/src/v2/lib/nodes-canvas
 
 ## Runtime
 
-`NodeFlowRuntimeService.runFlow(projectId, flowId, input, options)` revalidates the saved graph, checks project ownership, and then executes nodes in the validator's topological order.
+`NodeFlowRuntimeService.runFlow(projectId, flowId, input, options)` resolves an explicit pinned or latest-published snapshot, revalidates that immutable graph, claims a durable lease, and executes nodes in topological order. See [Node Flow Durable Execution](./node-flow-durable-execution.md) for queue, retry, lease, recovery, quota, and redaction guarantees.
 
 Runtime-supported node types are:
 
@@ -75,7 +77,7 @@ Cancellation records cancelled node rows for the current and remaining nodes. At
 
 ## Scheduling
 
-Scheduler entries with `targetType: "node_flow"` persist `nodeFlowTarget = { flowId, input?, flowVersion? }` inside `scheduler_entries.target_json`. Ownership is validated when entries are created or updated and again before due-run execution.
+Scheduler entries with `targetType: "node_flow"` persist an explicit `versionSelection`: pinned schedules continue to execute version N after N+1 is published, while latest-published schedules resolve the newest publication at dispatch time. Legacy `flowVersion` values normalize to pinned selection and are executable semantics, not audit-only metadata. Ownership is validated when entries are created or updated and again before due-run execution.
 
 Due runs call `NodeFlowRuntimeService.runFlow` with `triggerType = "scheduler"` and trigger payload metadata for the scheduler entry id, scheduled occurrence time, target type, and persisted flow version when present. Node-flow schedules advance only when `runFlow` returns a run status of `succeeded`. Returned `failed` or `cancelled` runs mark the scheduler entry `failed` with the run error and still count the attempted occurrence in `lastRunAt` and `runCount`; runtime startup rejections mark failure without creating a false successful schedule run.
 
diff --git a/docs/dashboard/scheduler.md b/docs/dashboard/scheduler.md
index b7f31b8dcd..583234204c 100644
--- a/docs/dashboard/scheduler.md
+++ b/docs/dashboard/scheduler.md
@@ -78,7 +78,7 @@ The target payload keys are:
 - `chatTarget`: `{ bodyMarkdown, threadId?, title?, connectionId? }`
 - `memoryRemediationTarget`: `{ mode, source? }`
 - `taskTarget`: `{ taskId, provider?, origin: "agent_scheduler", source: "agent_scheduler", createdByAgentId? }`
-- `nodeFlowTarget`: `{ flowId, input?, flowVersion? }`
+- `nodeFlowTarget`: `{ flowId, input?, versionSelection }`; legacy `flowVersion` normalizes to pinned selection
 - `agentWakeupTarget`: `{ bodyMarkdown, threadId?, title?, connectionId?, origin: "agent_scheduler", source: "agent_scheduler", createdByAgentId? }`
 
 `node_flow` entries keep their flow id and optional input in `target_json`; ownership is checked when entries are created or updated and again before due-run execution. The persisted `flowVersion` is target metadata and is passed in scheduler trigger payloads for auditability; the current runtime executes through the latest node-flow runtime API. Due-run handling treats the returned node-flow run status as authoritative: only `succeeded` advances the schedule as successful, while `failed` and `cancelled` mark the scheduler entry `failed`, persist the run error, and record the attempted occurrence in `lastRunAt` and `runCount`. `agent_wakeup` and `task` entries always normalize `origin` and `source` to `agent_scheduler` in `target_json`. When the creator supplies `createdByAgentId`, it is preserved with the target payload for later authorization, audit, and notification work. Existing sprint, quicksprint, chat, memory remediation, recurrence, pause/resume, and `after_sprint_end` anchor rows continue to hydrate from the same JSON payload without a schema migration.
@@ -156,7 +156,7 @@ For sprint targets, failures from either automatic planning or direct orchestrat
 
 ### Node-Flow Schedules
 
-Node-flow schedules use `targetType: "node_flow"` and `nodeFlowTarget = { flowId, input?, flowVersion? }`.
+Node-flow schedules use `targetType: "node_flow"` and `nodeFlowTarget = { flowId, input?, versionSelection }`. A pinned selection always executes that published graph and policy snapshot after newer versions are published; `latest_published` resolves the newest publication per occurrence.
 
 Behavior:
 
diff --git a/docs/index.md b/docs/index.md
index 201c31ab40..21d4ab0ebf 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -66,6 +66,7 @@ Use this page as the main entrypoint.
 28. [Agent Knowledge Base](./architecture/agent-knowledge-base.md)
 29. [Node Flow Foundation](./architecture/node-flow-foundation.md)
 30. [Node Flows](./architecture/node-flows.md)
+31. [Node Flow Durable Execution](./architecture/node-flow-durable-execution.md)
 31. [Custom Dashboard Foundation](./architecture/custom-dashboard-foundation.md)
 32. [Memory Claims and Evidence](./architecture/memory-claims.md)
 33. [Speech Input Architecture](./architecture/speech-input.md)
@@ -158,6 +159,7 @@ Use this page as the main entrypoint.
 - [Agent Knowledge Base](./architecture/agent-knowledge-base.md)
 - [Node Flow Foundation](./architecture/node-flow-foundation.md)
 - [Node Flows](./architecture/node-flows.md)
+- [Node Flow Durable Execution](./architecture/node-flow-durable-execution.md)
 - [Custom Dashboard Foundation](./architecture/custom-dashboard-foundation.md)
 - [Memory Claims and Evidence](./architecture/memory-claims.md)
 - [Speech Input Architecture](./architecture/speech-input.md)
diff --git a/src/app/dependency-factory/dashboard-factory.ts b/src/app/dependency-factory/dashboard-factory.ts
index af70fdec29..da4d85983f 100644
--- a/src/app/dependency-factory/dashboard-factory.ts
+++ b/src/app/dependency-factory/dashboard-factory.ts
@@ -31,6 +31,7 @@ import { SpeechSynthesisService } from "../../services/speech-synthesis-service.
 import { SpeechModelManager } from "../../services/speech-model-manager.js";
 import { NodeFlowRuntimeService } from "../../services/node-flow-runtime-service.js";
 import { NodeFlowService } from "../../services/node-flow-service.js";
+import { NodeFlowRecoveryService } from "../../services/node-flows/node-flow-recovery-service.js";
 import { resolveEffectiveDashboardSettings } from "../../services/settings-resolution-service.js";
 
 export interface DashboardDependencies {
@@ -230,6 +231,9 @@ export function createDashboardDependencies(
     credentialBroker: coreDeps.credentialBroker,
     getDashboardSettings: (projectId) => resolveDashboardSettings({ projectId }),
   });
+  if (coreDeps.nodeFlowRepository) {
+    new NodeFlowRecoveryService(coreDeps.nodeFlowRepository).recover();
+  }
   const nodeFlowService = new NodeFlowService(coreDeps.nodeFlowRepository, nodeFlowRuntimeService);
 
   const activityCacheService = new ActivityCacheService(
diff --git a/src/contracts/node-flow-execution-policy-types.ts b/src/contracts/node-flow-execution-policy-types.ts
new file mode 100644
index 0000000000..151a316e9e
--- /dev/null
+++ b/src/contracts/node-flow-execution-policy-types.ts
@@ -0,0 +1,45 @@
+export type NodeFlowVersionSelection =
+  | { mode: "latest_published" }
+  | { mode: "pinned"; version: number };
+
+export type NodeFlowFailureClassification =
+  | "cancelled"
+  | "timeout"
+  | "quota"
+  | "validation"
+  | "credential"
+  | "transient"
+  | "permanent"
+  | "unknown_side_effect";
+
+export interface NodeFlowRetryPolicySnapshot {
+  maxAttempts: number;
+  backoffMs: number;
+  maxBackoffMs: number;
+  jitterRatio: number;
+  retryableClasses: NodeFlowFailureClassification[];
+}
+
+export interface NodeFlowExecutionPolicySnapshot {
+  maxConcurrentRuns: number;
+  maxConcurrentRunsPerProject: number;
+  leaseDurationMs: number;
+  heartbeatIntervalMs: number;
+  defaultTimeoutMs: number;
+  retry: NodeFlowRetryPolicySnapshot;
+}
+
+export const DEFAULT_NODE_FLOW_EXECUTION_POLICY: Readonly<NodeFlowExecutionPolicySnapshot> = Object.freeze({
+  maxConcurrentRuns: 4,
+  maxConcurrentRunsPerProject: 2,
+  leaseDurationMs: 30_000,
+  heartbeatIntervalMs: 10_000,
+  defaultTimeoutMs: 60_000,
+  retry: Object.freeze({
+    maxAttempts: 1,
+    backoffMs: 500,
+    maxBackoffMs: 30_000,
+    jitterRatio: 0.2,
+    retryableClasses: Object.freeze(["timeout", "quota", "transient"]) as NodeFlowFailureClassification[],
+  }),
+});
diff --git a/src/contracts/node-flow-types.ts b/src/contracts/node-flow-types.ts
index 8e19d7ab7a..cc6471c28b 100644
--- a/src/contracts/node-flow-types.ts
+++ b/src/contracts/node-flow-types.ts
@@ -160,6 +160,17 @@ export interface NodeFlowVersionRecord {
   createdAt: string;
 }
 
+export interface NodeFlowPublicationRecord {
+  id: string;
+  flowId: string;
+  projectId: string;
+  version: number;
+  graph: NodeFlowGraph;
+  policy: import("./node-flow-execution-policy-types.js").NodeFlowExecutionPolicySnapshot;
+  publishedBy: string;
+  createdAt: string;
+}
+
 export interface CreateNodeFlowInput {
   id?: string;
   title: string;
@@ -202,15 +213,25 @@ export interface AttachNodeFlowSkillInput {
   description?: string;
 }
 
-export type NodeFlowRunStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled";
-export type NodeFlowNodeRunStatus = "pending" | "running" | "succeeded" | "failed" | "skipped" | "cancelled";
+export type NodeFlowRunStatus =
+  | "queued" | "running" | "approval_waiting" | "retry_waiting"
+  | "attention_required" | "succeeded" | "failed" | "cancelled";
+export type NodeFlowNodeRunStatus =
+  | "pending" | "running" | "retry_waiting" | "attention_required"
+  | "succeeded" | "failed" | "skipped" | "cancelled";
 
 export interface NodeFlowRunRecord {
   id: string;
   flowId: string;
   projectId: string;
   version: number;
+  publicationId: string | null;
   status: NodeFlowRunStatus;
+  policy: import("./node-flow-execution-policy-types.js").NodeFlowExecutionPolicySnapshot;
+  leaseOwner: string | null;
+  leaseExpiresAt: string | null;
+  heartbeatAt: string | null;
+  cancelRequestedAt: string | null;
   executionInvocationId: string | null;
   triggerType: string;
   triggerPayload: NodeFlowJsonObject | null;
@@ -240,6 +261,27 @@ export interface NodeFlowNodeRunRecord {
   updatedAt: string;
 }
 
+export interface NodeFlowNodeAttemptRecord {
+  id: string;
+  runId: string;
+  nodeRunId: string;
+  nodeId: string;
+  attemptNumber: number;
+  status: NodeFlowNodeRunStatus;
+  executorId: string;
+  invocationId: string | null;
+  artifactDigest: string | null;
+  input: NodeFlowJsonObject | null;
+  output: NodeFlowJsonObject | null;
+  credentialIds: string[];
+  failureClassification: import("./node-flow-execution-policy-types.js").NodeFlowFailureClassification | null;
+  retryDecision: "retry" | "stop" | "attention_required" | null;
+  errorMessage: string | null;
+  startedAt: string;
+  finishedAt: string | null;
+  createdAt: string;
+}
+
 export interface NodeFlowListResponse {
   flows: NodeFlowRecord[];
 }
@@ -256,6 +298,8 @@ export interface CreateNodeFlowRunInput {
   flowId: string;
   projectId: string;
   version: number;
+  publicationId?: string | null;
+  policy?: import("./node-flow-execution-policy-types.js").NodeFlowExecutionPolicySnapshot;
   status?: NodeFlowRunStatus;
   executionInvocationId?: string | null;
   triggerType?: string;
@@ -274,6 +318,10 @@ export interface UpdateNodeFlowRunInput {
   errorMessage?: string | null;
   startedAt?: string | null;
   finishedAt?: string | null;
+  leaseOwner?: string | null;
+  leaseExpiresAt?: string | null;
+  heartbeatAt?: string | null;
+  cancelRequestedAt?: string | null;
 }
 
 export interface CreateNodeFlowNodeRunInput {
@@ -304,10 +352,13 @@ export interface RunNodeFlowOptions {
   triggerType?: string;
   triggerPayload?: NodeFlowJsonObject;
   signal?: AbortSignal;
+  versionSelection?: import("./node-flow-execution-policy-types.js").NodeFlowVersionSelection;
+  executorId?: string;
 }
 
 export interface NodeFlowRunSummaryResponse {
   run: NodeFlowRunRecord;
   nodeRuns: NodeFlowNodeRunRecord[];
+  attempts?: NodeFlowNodeAttemptRecord[];
   output: NodeFlowJsonObject | null;
 }
diff --git a/src/contracts/scheduler-types.ts b/src/contracts/scheduler-types.ts
index 366f3d9968..12bcc88f64 100644
--- a/src/contracts/scheduler-types.ts
+++ b/src/contracts/scheduler-types.ts
@@ -1,6 +1,7 @@
 import type { QuicksprintExecutionInput } from "./quicksprint-types.js";
 import type { ProviderId } from "./app-types.js";
 import type { NodeFlowJsonObject } from "./node-flow-types.js";
+import type { NodeFlowVersionSelection } from "./node-flow-execution-policy-types.js";
 
 export type ScheduleTargetType = "sprint" | "quicksprint" | "chat" | "memory_remediation" | "agent_wakeup" | "task" | "node_flow";
 export type ScheduleStatus = "scheduled" | "paused" | "completed" | "failed" | "cancelled";
@@ -79,6 +80,7 @@ export interface ScheduleNodeFlowTarget {
   flowId: string;
   input?: NodeFlowJsonObject;
   flowVersion?: number;
+  versionSelection?: NodeFlowVersionSelection;
 }
 
 export interface SchedulerEntryRecord {
diff --git a/src/mcp/management/node-flow-actions.ts b/src/mcp/management/node-flow-actions.ts
index cdb6cd138e..a35437f0b5 100644
--- a/src/mcp/management/node-flow-actions.ts
+++ b/src/mcp/management/node-flow-actions.ts
@@ -16,6 +16,7 @@ import type { NodeFlowService } from "../../services/node-flow-service.js";
 import {
   managementValidationError,
   parseOptionalObject,
+  parseOptionalNumber,
   parseOptionalString,
   parseRequiredObject,
   parseRequiredString,
@@ -139,8 +140,12 @@ export class NodeFlowActions {
     const projectId = parseRequiredString(payload, "projectId");
     const flowId = parseRequiredString(payload, "flowId");
     const input = parseOptionalObject<NodeFlowJsonObject>(payload, "input") ?? {};
+    const flowVersion = parseOptionalNumber(payload, "flowVersion", 1);
     const result = await this.nodeFlowService.runFlow(projectId, flowId, input, {
       triggerType: "mcp_management",
+      versionSelection: flowVersion === undefined
+        ? { mode: "latest_published" }
+        : { mode: "pinned", version: Math.floor(flowVersion) },
     });
     return { result: formatRunSummary(result) };
   }
diff --git a/src/repositories/db/app-db-migrations.ts b/src/repositories/db/app-db-migrations.ts
index da475c1306..d54064de0e 100644
--- a/src/repositories/db/app-db-migrations.ts
+++ b/src/repositories/db/app-db-migrations.ts
@@ -257,7 +257,54 @@ export function ensureNodeFlowTables(db: DatabaseAdapter): void {
     )
   `);
 
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS node_flow_publications (
+      id TEXT PRIMARY KEY,
+      flow_id TEXT NOT NULL,
+      project_id TEXT NOT NULL,
+      version INTEGER NOT NULL,
+      graph_json TEXT NOT NULL,
+      policy_json TEXT NOT NULL,
+      published_by TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      FOREIGN KEY (flow_id) REFERENCES node_flows(id) ON DELETE CASCADE,
+      FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,
+      UNIQUE (flow_id, version)
+    )
+  `);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS node_flow_node_attempts (
+      id TEXT PRIMARY KEY,
+      run_id TEXT NOT NULL,
+      node_run_id TEXT NOT NULL,
+      node_id TEXT NOT NULL,
+      attempt_number INTEGER NOT NULL,
+      status TEXT NOT NULL,
+      executor_id TEXT NOT NULL,
+      invocation_id TEXT,
+      artifact_digest TEXT,
+      input_json TEXT,
+      output_json TEXT,
+      credential_ids_json TEXT NOT NULL DEFAULT '[]',
+      failure_classification TEXT,
+      retry_decision TEXT,
+      error_message TEXT,
+      started_at TEXT NOT NULL,
+      finished_at TEXT,
+      created_at TEXT NOT NULL,
+      FOREIGN KEY (run_id) REFERENCES node_flow_runs(id) ON DELETE CASCADE,
+      FOREIGN KEY (node_run_id) REFERENCES node_flow_node_runs(id) ON DELETE CASCADE,
+      UNIQUE (run_id, node_id, attempt_number)
+    )
+  `);
+
   ensureColumn(db, "node_flow_runs", "execution_invocation_id", "TEXT");
+  ensureColumn(db, "node_flow_runs", "publication_id", "TEXT");
+  ensureColumn(db, "node_flow_runs", "policy_json", "TEXT NOT NULL DEFAULT '{}'");
+  ensureColumn(db, "node_flow_runs", "lease_owner", "TEXT");
+  ensureColumn(db, "node_flow_runs", "lease_expires_at", "TEXT");
+  ensureColumn(db, "node_flow_runs", "heartbeat_at", "TEXT");
+  ensureColumn(db, "node_flow_runs", "cancel_requested_at", "TEXT");
   ensureColumn(db, "node_flow_node_runs", "execution_invocation_id", "TEXT");
 
   ensureIndex(db, "idx_node_flows_project_updated", "node_flows", "project_id, updated_at DESC");
@@ -266,6 +313,10 @@ export function ensureNodeFlowTables(db: DatabaseAdapter): void {
   ensureIndex(db, "idx_node_flow_runs_flow_created", "node_flow_runs", "flow_id, created_at DESC");
   ensureIndex(db, "idx_node_flow_runs_project_created", "node_flow_runs", "project_id, created_at DESC");
   ensureIndex(db, "idx_node_flow_node_runs_run_created", "node_flow_node_runs", "run_id, created_at ASC");
+  ensureIndex(db, "idx_node_flow_publications_latest", "node_flow_publications", "flow_id, version DESC");
+  ensureIndex(db, "idx_node_flow_runs_queue", "node_flow_runs", "status, lease_expires_at, created_at ASC");
+  ensureIndex(db, "idx_node_flow_runs_project_status", "node_flow_runs", "project_id, status");
+  ensureIndex(db, "idx_node_flow_attempts_run_node", "node_flow_node_attempts", "run_id, node_id, attempt_number");
 }
 
 interface LegacyNodeFlowRow {
diff --git a/src/repositories/node-flow-repository.ts b/src/repositories/node-flow-repository.ts
index faf2e5ae48..c3648e3606 100644
--- a/src/repositories/node-flow-repository.ts
+++ b/src/repositories/node-flow-repository.ts
@@ -12,6 +12,8 @@ import type {
   NodeFlowJsonObject,
   NodeFlowJsonValue,
   NodeFlowNodeRunRecord,
+  NodeFlowNodeAttemptRecord,
+  NodeFlowPublicationRecord,
   NodeFlowRecord,
   NodeFlowRunRecord,
   NodeFlowSkillAttachment,
@@ -20,6 +22,8 @@ import type {
   UpdateNodeFlowInput,
   UpdateNodeFlowRunInput,
 } from "../contracts/node-flow-types.js";
+import { DEFAULT_NODE_FLOW_EXECUTION_POLICY } from "../contracts/node-flow-execution-policy-types.js";
+import type { NodeFlowExecutionPolicySnapshot, NodeFlowFailureClassification } from "../contracts/node-flow-execution-policy-types.js";
 import { migratePersistedNodeFlowGraphs } from "./db/app-db-migrations.js";
 
 interface NodeFlowRow {
@@ -59,7 +63,13 @@ interface NodeFlowRunRow {
   flow_id: string;
   project_id: string;
   version: number | string;
+  publication_id: string | null;
+  policy_json: string;
   status: string;
+  lease_owner: string | null;
+  lease_expires_at: string | null;
+  heartbeat_at: string | null;
+  cancel_requested_at: string | null;
   execution_invocation_id: string | null;
   trigger_type: string;
   trigger_payload_json: string | null;
@@ -72,6 +82,19 @@ interface NodeFlowRunRow {
   updated_at: string;
 }
 
+interface NodeFlowPublicationRow {
+  id: string; flow_id: string; project_id: string; version: number | string;
+  graph_json: string; policy_json: string; published_by: string; created_at: string;
+}
+
+interface NodeFlowAttemptRow {
+  id: string; run_id: string; node_run_id: string; node_id: string; attempt_number: number | string;
+  status: string; executor_id: string; invocation_id: string | null; artifact_digest: string | null;
+  input_json: string | null; output_json: string | null; credential_ids_json: string;
+  failure_classification: string | null; retry_decision: string | null; error_message: string | null;
+  started_at: string; finished_at: string | null; created_at: string;
+}
+
 interface NodeFlowNodeRunRow {
   id: string;
   run_id: string;
@@ -98,6 +121,7 @@ export class NodeFlowRepository {
   ) {
     this.db = storage.getDatabase();
     migratePersistedNodeFlowGraphs(this.db);
+    this.backfillPublications();
   }
 
   listFlows(projectId: string): NodeFlowRecord[] {
@@ -142,6 +166,7 @@ export class NodeFlowRepository {
         graphJson,
         createdAt: now,
       });
+      this.insertPublication(id, projectId, 1, graphJson, DEFAULT_NODE_FLOW_EXECUTION_POLICY, "system");
     });
 
     const created = this.requireFlow(id);
@@ -173,6 +198,7 @@ export class NodeFlowRepository {
         graphJson,
         createdAt: now,
       });
+      this.insertPublication(flowId, current.projectId, nextVersion, graphJson, DEFAULT_NODE_FLOW_EXECUTION_POLICY, "system");
     });
 
     const updated = this.requireFlow(flowId);
@@ -207,6 +233,26 @@ export class NodeFlowRepository {
     return row ? this.mapVersionRow(row) : null;
   }
 
+  listPublications(flowId: string): NodeFlowPublicationRecord[] {
+    this.requireFlow(flowId);
+    return (this.db.prepare(`SELECT * FROM node_flow_publications WHERE flow_id = ? ORDER BY version DESC`).all(flowId) as unknown as NodeFlowPublicationRow[])
+      .map((row) => this.mapPublicationRow(row));
+  }
+
+  getPublication(flowId: string, version?: number): NodeFlowPublicationRecord | null {
+    const row = version === undefined
+      ? this.db.prepare(`SELECT * FROM node_flow_publications WHERE flow_id = ? ORDER BY version DESC LIMIT 1`).get(flowId)
+      : this.db.prepare(`SELECT * FROM node_flow_publications WHERE flow_id = ? AND version = ?`).get(flowId, Math.floor(version));
+    return row ? this.mapPublicationRow(row as NodeFlowPublicationRow) : null;
+  }
+
+  publishVersion(flowId: string, version: number, policy: NodeFlowExecutionPolicySnapshot = DEFAULT_NODE_FLOW_EXECUTION_POLICY, publishedBy = "system"): NodeFlowPublicationRecord {
+    const snapshot = this.getVersion(flowId, version);
+    if (!snapshot) throw new EntityNotFoundError(`Node flow version not found: ${flowId}@${version}`);
+    this.insertPublication(flowId, snapshot.projectId, snapshot.version, this.serializeJson(snapshot.graph), policy, publishedBy);
+    return requireRecord(this.getPublication(flowId, version), "Node flow publication", `${flowId}@${version}`);
+  }
+
   attachToAgent(flowId: string, input: AttachNodeFlowSkillInput): NodeFlowSkillAttachment {
     const flow = this.requireFlow(flowId);
     const agentPresetId = input.agentPresetId?.trim();
@@ -317,14 +363,16 @@ export class NodeFlowRepository {
     const id = randomUUID();
     this.db.prepare(`
       INSERT INTO node_flow_runs (
-        id, flow_id, project_id, version, status, execution_invocation_id, trigger_type,
+        id, flow_id, project_id, version, publication_id, policy_json, status, execution_invocation_id, trigger_type,
         trigger_payload_json, input_json, output_json, error_message, started_at, finished_at, created_at, updated_at
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(
       id,
       input.flowId,
       input.projectId,
       Math.max(1, Math.floor(input.version)),
+      input.publicationId ?? null,
+      this.serializeJson(input.policy ?? DEFAULT_NODE_FLOW_EXECUTION_POLICY),
       input.status || "running",
       input.executionInvocationId ?? null,
       input.triggerType?.trim() || "manual",
@@ -350,7 +398,7 @@ export class NodeFlowRepository {
           output_json = ?,
           error_message = ?,
           started_at = ?,
-          finished_at = ?,
+          finished_at = ?, lease_owner = ?, lease_expires_at = ?, heartbeat_at = ?, cancel_requested_at = ?,
           updated_at = ?
       WHERE id = ?
     `).run(
@@ -360,12 +408,62 @@ export class NodeFlowRepository {
       input.errorMessage === undefined ? current.errorMessage : input.errorMessage,
       input.startedAt === undefined ? current.startedAt : input.startedAt,
       input.finishedAt === undefined ? current.finishedAt : input.finishedAt,
+      input.leaseOwner === undefined ? current.leaseOwner : input.leaseOwner,
+      input.leaseExpiresAt === undefined ? current.leaseExpiresAt : input.leaseExpiresAt,
+      input.heartbeatAt === undefined ? current.heartbeatAt : input.heartbeatAt,
+      input.cancelRequestedAt === undefined ? current.cancelRequestedAt : input.cancelRequestedAt,
       now,
       runId,
     );
     return requireRecord(this.getRun(runId), "Node flow run", runId);
   }
 
+  claimQueuedRun(runId: string, executorId: string, leaseDurationMs: number, now = new Date()): NodeFlowRunRecord | null {
+    const expiresAt = new Date(now.getTime() + leaseDurationMs).toISOString();
+    const result = this.db.prepare(`UPDATE node_flow_runs SET status = 'running', lease_owner = ?, lease_expires_at = ?, heartbeat_at = ?, started_at = COALESCE(started_at, ?), updated_at = ? WHERE id = ? AND status IN ('queued','retry_waiting') AND (lease_expires_at IS NULL OR lease_expires_at <= ?)`)
+      .run(executorId, expiresAt, now.toISOString(), now.toISOString(), now.toISOString(), runId, now.toISOString());
+    return result.changes > 0 ? this.getRun(runId) : null;
+  }
+
+  heartbeatRun(runId: string, executorId: string, leaseDurationMs: number, now = new Date()): boolean {
+    const result = this.db.prepare(`UPDATE node_flow_runs SET heartbeat_at = ?, lease_expires_at = ?, updated_at = ? WHERE id = ? AND status = 'running' AND lease_owner = ?`)
+      .run(now.toISOString(), new Date(now.getTime() + leaseDurationMs).toISOString(), now.toISOString(), runId, executorId);
+    return result.changes > 0;
+  }
+
+  countActiveRuns(projectId?: string): number {
+    const row = projectId
+      ? this.db.prepare(`SELECT COUNT(*) AS count FROM node_flow_runs WHERE project_id = ? AND status = 'running'`).get(projectId)
+      : this.db.prepare(`SELECT COUNT(*) AS count FROM node_flow_runs WHERE status = 'running'`).get();
+    return toNumber((row as { count: number | string }).count);
+  }
+
+  listRecoverableRuns(nowIso = new Date().toISOString()): NodeFlowRunRecord[] {
+    return (this.db.prepare(`SELECT * FROM node_flow_runs WHERE status IN ('queued','retry_waiting','approval_waiting') OR (status = 'running' AND lease_expires_at <= ?) ORDER BY created_at ASC`).all(nowIso) as unknown as NodeFlowRunRow[]).map((row) => this.mapRunRow(row));
+  }
+
+  requestCancellation(runId: string): NodeFlowRunRecord {
+    return this.updateRun(runId, { cancelRequestedAt: new Date().toISOString() });
+  }
+
+  createNodeAttempt(input: Omit<NodeFlowNodeAttemptRecord, "id" | "createdAt">): NodeFlowNodeAttemptRecord {
+    const id = randomUUID(); const now = new Date().toISOString();
+    this.db.prepare(`INSERT INTO node_flow_node_attempts (id, run_id, node_run_id, node_id, attempt_number, status, executor_id, invocation_id, artifact_digest, input_json, output_json, credential_ids_json, failure_classification, retry_decision, error_message, started_at, finished_at, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+      .run(id, input.runId, input.nodeRunId, input.nodeId, input.attemptNumber, input.status, input.executorId, input.invocationId, input.artifactDigest, this.serializeNullableJson(input.input), this.serializeNullableJson(input.output), JSON.stringify(input.credentialIds), input.failureClassification, input.retryDecision, input.errorMessage, input.startedAt, input.finishedAt, now);
+    return requireRecord(this.getNodeAttempt(id), "Node flow node attempt", id);
+  }
+
+  updateNodeAttempt(id: string, input: Partial<Pick<NodeFlowNodeAttemptRecord, "status" | "invocationId" | "artifactDigest" | "output" | "failureClassification" | "retryDecision" | "errorMessage" | "finishedAt">>): NodeFlowNodeAttemptRecord {
+    const current = requireRecord(this.getNodeAttempt(id), "Node flow node attempt", id);
+    this.db.prepare(`UPDATE node_flow_node_attempts SET status = ?, invocation_id = ?, artifact_digest = ?, output_json = ?, failure_classification = ?, retry_decision = ?, error_message = ?, finished_at = ? WHERE id = ?`)
+      .run(input.status ?? current.status, input.invocationId === undefined ? current.invocationId : input.invocationId, input.artifactDigest === undefined ? current.artifactDigest : input.artifactDigest, input.output === undefined ? this.serializeNullableJson(current.output) : this.serializeNullableJson(input.output), input.failureClassification === undefined ? current.failureClassification : input.failureClassification, input.retryDecision === undefined ? current.retryDecision : input.retryDecision, input.errorMessage === undefined ? current.errorMessage : input.errorMessage, input.finishedAt === undefined ? current.finishedAt : input.finishedAt, id);
+    return requireRecord(this.getNodeAttempt(id), "Node flow node attempt", id);
+  }
+
+  listNodeAttempts(runId: string): NodeFlowNodeAttemptRecord[] {
+    return (this.db.prepare(`SELECT * FROM node_flow_node_attempts WHERE run_id = ? ORDER BY node_id, attempt_number`).all(runId) as unknown as NodeFlowAttemptRow[]).map((row) => this.mapAttemptRow(row));
+  }
+
   createNodeRun(input: CreateNodeFlowNodeRunInput): NodeFlowNodeRunRecord {
     const run = requireRecord(this.getRun(input.runId), "Node flow run", input.runId);
     if (run.flowId !== input.flowId || run.projectId !== input.projectId) {
@@ -450,6 +548,19 @@ export class NodeFlowRepository {
     );
   }
 
+  private insertPublication(flowId: string, projectId: string, version: number, graphJson: string, policy: NodeFlowExecutionPolicySnapshot, publishedBy: string): void {
+    this.db.prepare(`INSERT OR IGNORE INTO node_flow_publications (id, flow_id, project_id, version, graph_json, policy_json, published_by, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+      .run(randomUUID(), flowId, projectId, version, graphJson, this.serializeJson(policy), publishedBy, new Date().toISOString());
+  }
+
+  private backfillPublications(): void {
+    const versions = this.db.prepare(`SELECT flow_id, project_id, version, graph_json, created_at FROM node_flow_versions`).all() as Array<{ flow_id: string; project_id: string; version: number | string; graph_json: string; created_at: string }>;
+    for (const version of versions) {
+      this.db.prepare(`INSERT OR IGNORE INTO node_flow_publications (id, flow_id, project_id, version, graph_json, policy_json, published_by, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(randomUUID(), version.flow_id, version.project_id, toNumber(version.version), version.graph_json, this.serializeJson(DEFAULT_NODE_FLOW_EXECUTION_POLICY), "migration", version.created_at);
+    }
+  }
+
   private requireProject(projectId: string): void {
     requireRecord(this.db.prepare(`SELECT id FROM projects WHERE id = ?`).get(projectId), "Project", projectId);
   }
@@ -489,6 +600,11 @@ export class NodeFlowRepository {
     return row ? this.mapNodeRunRow(row) : null;
   }
 
+  private getNodeAttempt(id: string): NodeFlowNodeAttemptRecord | null {
+    const row = this.db.prepare(`SELECT * FROM node_flow_node_attempts WHERE id = ?`).get(id) as NodeFlowAttemptRow | undefined;
+    return row ? this.mapAttemptRow(row) : null;
+  }
+
   private requireTitle(title: string | undefined): string {
     const normalized = title?.trim();
     if (!normalized) {
@@ -527,6 +643,11 @@ export class NodeFlowRepository {
     }
   }
 
+  private parsePolicy(value: string): NodeFlowExecutionPolicySnapshot {
+    try { return { ...DEFAULT_NODE_FLOW_EXECUTION_POLICY, ...JSON.parse(value) as NodeFlowExecutionPolicySnapshot }; }
+    catch { return { ...DEFAULT_NODE_FLOW_EXECUTION_POLICY }; }
+  }
+
   private isJsonValue(value: unknown): value is NodeFlowJsonValue {
     if (value === null) {
       return true;
@@ -594,7 +715,13 @@ export class NodeFlowRepository {
       flowId: row.flow_id,
       projectId: row.project_id,
       version: toNumber(row.version),
+      publicationId: row.publication_id,
       status: row.status as NodeFlowRunRecord["status"],
+      policy: this.parsePolicy(row.policy_json),
+      leaseOwner: row.lease_owner,
+      leaseExpiresAt: row.lease_expires_at,
+      heartbeatAt: row.heartbeat_at,
+      cancelRequestedAt: row.cancel_requested_at,
       executionInvocationId: row.execution_invocation_id,
       triggerType: row.trigger_type,
       triggerPayload: this.parseObject(row.trigger_payload_json),
@@ -627,6 +754,16 @@ export class NodeFlowRepository {
     };
   }
 
+  private mapPublicationRow(row: NodeFlowPublicationRow): NodeFlowPublicationRecord {
+    return { id: row.id, flowId: row.flow_id, projectId: row.project_id, version: toNumber(row.version), graph: this.parseGraph(row.graph_json), policy: this.parsePolicy(row.policy_json), publishedBy: row.published_by, createdAt: row.created_at };
+  }
+
+  private mapAttemptRow(row: NodeFlowAttemptRow): NodeFlowNodeAttemptRecord {
+    let credentialIds: string[] = [];
+    try { const parsed = JSON.parse(row.credential_ids_json) as unknown; if (Array.isArray(parsed)) credentialIds = parsed.filter((item): item is string => typeof item === "string"); } catch { /* legacy row */ }
+    return { id: row.id, runId: row.run_id, nodeRunId: row.node_run_id, nodeId: row.node_id, attemptNumber: toNumber(row.attempt_number), status: row.status as NodeFlowNodeRunRecord["status"], executorId: row.executor_id, invocationId: row.invocation_id, artifactDigest: row.artifact_digest, input: this.parseObject(row.input_json), output: this.parseObject(row.output_json), credentialIds, failureClassification: row.failure_classification as NodeFlowFailureClassification | null, retryDecision: row.retry_decision as NodeFlowNodeAttemptRecord["retryDecision"], errorMessage: row.error_message, startedAt: row.started_at, finishedAt: row.finished_at, createdAt: row.created_at };
+  }
+
   private publishProjectStructureRefresh(projectId: string): void {
     this.realtimeNotifier?.scheduleProjectStructureRefresh(projectId, { includeProjects: false });
   }
diff --git a/src/repositories/scheduler-repository.ts b/src/repositories/scheduler-repository.ts
index fff9c56e63..a073fa9159 100644
--- a/src/repositories/scheduler-repository.ts
+++ b/src/repositories/scheduler-repository.ts
@@ -364,8 +364,17 @@ export class SchedulerRepository {
         target.input = normalizedInput;
       }
       const flowVersion = this.normalizeOptionalPositiveInteger(input.nodeFlowTarget?.flowVersion, "nodeFlowTarget.flowVersion");
-      if (flowVersion !== undefined) {
+      const versionSelection = input.nodeFlowTarget?.versionSelection;
+      if (versionSelection?.mode === "pinned") {
+        target.versionSelection = { mode: "pinned", version: this.normalizeOptionalPositiveInteger(versionSelection.version, "nodeFlowTarget.versionSelection.version")! };
+        target.flowVersion = target.versionSelection.version;
+      } else if (versionSelection?.mode === "latest_published") {
+        target.versionSelection = { mode: "latest_published" };
+      } else if (flowVersion !== undefined) {
         target.flowVersion = flowVersion;
+        target.versionSelection = { mode: "pinned", version: flowVersion };
+      } else {
+        target.versionSelection = { mode: "latest_published" };
       }
       return { nodeFlowTarget: target };
     }
diff --git a/src/server/node-flow-routes.ts b/src/server/node-flow-routes.ts
index 4d9a3805cd..a608686dd4 100644
--- a/src/server/node-flow-routes.ts
+++ b/src/server/node-flow-routes.ts
@@ -66,6 +66,7 @@ export function registerNodeFlowRoutes(app: Express, deps: DashboardDependencies
       input?: Record<string, unknown>;
       triggerType?: string;
       triggerPayload?: NodeFlowJsonObject;
+      flowVersion?: number;
     };
     const result = await requireNodeFlowService(deps).runFlow(
       requireTrimmedString(body.projectId, "projectId"),
@@ -74,6 +75,9 @@ export function registerNodeFlowRoutes(app: Express, deps: DashboardDependencies
       {
         triggerType: body.triggerType,
         triggerPayload: body.triggerPayload,
+        versionSelection: body.flowVersion === undefined
+          ? { mode: "latest_published" }
+          : { mode: "pinned", version: body.flowVersion },
       },
     );
     res.status(201).json(result);
@@ -121,4 +125,7 @@ export function registerNodeFlowRoutes(app: Express, deps: DashboardDependencies
   app.get("/api/node-flow-runs/:runId/node-runs", syncRoute((req, res) => {
     res.json(requireNodeFlowService(deps).listNodeRuns(requireTrimmedString(req.params.runId, "runId")));
   }));
+  app.get("/api/node-flow-runs/:runId/attempts", syncRoute((req, res) => {
+    res.json(requireNodeFlowService(deps).listNodeAttempts(requireTrimmedString(req.params.runId, "runId")));
+  }));
 }
diff --git a/src/services/node-flow-runtime-service.ts b/src/services/node-flow-runtime-service.ts
index 92c16e1afb..57a8f95138 100644
--- a/src/services/node-flow-runtime-service.ts
+++ b/src/services/node-flow-runtime-service.ts
@@ -11,6 +11,11 @@ import type { ProviderExecutionService } from "./provider-execution-service.js";
 import type { CliProviderId } from "../infrastructure/providers/cli/provider-command-specs.js";
 import type { ProviderRunResult } from "../infrastructure/providers/cli/provider-runner.js";
 import type { CredentialBroker } from "./credentials/credential-broker.js";
+import { NodeFlowPublicationService } from "./node-flows/node-flow-publication-service.js";
+import { NodeFlowQueueService } from "./node-flows/node-flow-queue-service.js";
+import { NodeFlowAttemptService } from "./node-flows/node-flow-attempt-service.js";
+import { NodeFlowLeaseService } from "./node-flows/node-flow-lease-service.js";
+import type { NodeFlowFailureClassification } from "../contracts/node-flow-execution-policy-types.js";
 import { buildProviderInvocationWorkspaceOptions } from "../infrastructure/providers/cli/invocation-workspace-preparer.js";
 import type {
   DashboardSettings,
@@ -55,6 +60,8 @@ interface RuntimeContext {
   predecessors: Map<string, string[]>;
   descendants: Map<string, Set<string>>;
   options: RunNodeFlowOptions;
+  executorId: string;
+  currentAttemptId?: string;
 }
 
 interface NodeExecutionResult {
@@ -79,7 +86,9 @@ export class NodeFlowRuntimeService {
       throw new ValidationError("Node flow does not belong to the requested project.");
     }
 
-    const { graph, executionOrder } = normalizeNodeFlowGraph(flow.graph);
+    const selection = options.versionSelection ?? { mode: "latest_published" };
+    const publication = new NodeFlowPublicationService(this.deps.nodeFlowRepository).resolve(flow.id, selection);
+    const { graph, executionOrder } = normalizeNodeFlowGraph(publication.graph);
     this.requireSupportedNodes(graph);
     const sanitizedInput = maskSecrets(input);
     const startedAt = new Date().toISOString();
@@ -92,29 +101,39 @@ export class NodeFlowRuntimeService {
     });
     this.deps.executionRepository.appendExecutionInvocationMessage(parentInvocation.id, {
       role: "system",
-      contentMarkdown: `Node flow run started for flow ${flow.id} at version ${flow.version}.`,
+      contentMarkdown: `Node flow run started for flow ${flow.id} at published version ${publication.version}.`,
       metadata: {
         flowId: flow.id,
-        flowVersion: flow.version,
+        flowVersion: publication.version,
+        publicationId: publication.id,
       },
     });
 
     const run = this.deps.nodeFlowRepository.createRun({
       flowId: flow.id,
       projectId,
-      version: flow.version,
-      status: "running",
+      version: publication.version,
+      publicationId: publication.id,
+      policy: publication.policy,
+      status: "queued",
       executionInvocationId: parentInvocation.id,
       triggerType: options.triggerType,
       triggerPayload: options.triggerPayload ? maskSecrets(options.triggerPayload) : null,
       input: sanitizedInput,
-      startedAt,
+      startedAt: null,
     });
+    const executorId = options.executorId?.trim() || `node-flow-runtime:${process.pid}:${randomUUID()}`;
+    const claimedRun = new NodeFlowQueueService(this.deps.nodeFlowRepository).claim(run, executorId);
+    const leaseService = new NodeFlowLeaseService(this.deps.nodeFlowRepository);
+    const heartbeatTimer = setInterval(() => {
+      leaseService.heartbeat(claimedRun.id, executorId, publication.policy.leaseDurationMs);
+    }, publication.policy.heartbeatIntervalMs);
+    heartbeatTimer.unref?.();
 
     const context: RuntimeContext = {
       projectId,
       flowId: flow.id,
-      runId: run.id,
+      runId: claimedRun.id,
       graph,
       order: executionOrder,
       input,
@@ -122,6 +141,7 @@ export class NodeFlowRuntimeService {
       predecessors: buildPredecessors(graph),
       descendants: buildDescendants(graph),
       options,
+      executorId,
     };
 
     const blockedNodes = new Set<string>();
@@ -136,7 +156,7 @@ export class NodeFlowRuntimeService {
       }
       if (options.signal?.aborted) {
         terminalStatus = "cancelled";
-        terminalError = "Node flow run was cancelled.";
+        terminalError ??= "Node flow run was cancelled.";
         await this.persistSkippedNode(context, node, "cancelled", terminalError);
         for (const remainingNodeId of executionOrder.slice(executionOrder.indexOf(nodeId) + 1)) {
           const remaining = graph.nodes.find((candidate) => candidate.id === remainingNodeId);
@@ -155,28 +175,59 @@ export class NodeFlowRuntimeService {
         continue;
       }
 
+      const nodeInput = maskSecrets(this.buildNodeInput(context, node.id));
       const nodeRun = this.deps.nodeFlowRepository.createNodeRun({
         runId: run.id,
         flowId: flow.id,
         projectId,
         nodeId: node.id,
         status: "running",
-        input: maskSecrets(this.buildNodeInput(context, node.id)),
+        input: nodeInput,
         startedAt: new Date().toISOString(),
       });
 
-      try {
+      const attemptService = new NodeFlowAttemptService(this.deps.nodeFlowRepository);
+      const retryPolicy = {
+        ...publication.policy.retry,
+        ...(node.policy?.retry ?? {}),
+      };
+      let attemptNumber = 0;
+      while (attemptNumber < retryPolicy.maxAttempts) {
+        attemptNumber += 1;
+        const attempt = attemptService.start(nodeRun, executorId, nodeInput, (node.credentialBindings ?? []).map((binding) => binding.credentialId));
+        context.currentAttemptId = attempt.id;
+        const timeoutMs = node.policy?.timeout?.timeoutMs ?? publication.policy.defaultTimeoutMs;
+        const timeoutController = new AbortController();
+        const parentAbort = (): void => timeoutController.abort(options.signal?.reason);
+        options.signal?.addEventListener("abort", parentAbort, { once: true });
+        const timeout = setTimeout(() => timeoutController.abort(new Error(`Node ${node.id} timed out after ${timeoutMs}ms.`)), timeoutMs);
+        const previousOptions = context.options;
+        context.options = { ...options, signal: timeoutController.signal };
+        try {
         const result = await this.executeNode(context, node, nodeRun);
         context.outputs.set(node.id, result.output);
+        attemptService.succeed(attempt, maskSecrets(result.output), result.invocationId);
         this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, {
           status: "succeeded",
           executionInvocationId: result.invocationId ?? nodeRun.executionInvocationId,
           output: maskSecrets(result.output),
           finishedAt: new Date().toISOString(),
         });
+        clearTimeout(timeout); options.signal?.removeEventListener("abort", parentAbort); context.options = previousOptions;
+        break;
       } catch (error) {
+        clearTimeout(timeout); options.signal?.removeEventListener("abort", parentAbort); context.options = previousOptions;
         const message = error instanceof Error ? error.message : String(error);
-        const wasCancelled = options.signal?.aborted === true;
+        const classification = classifyFailure(error, options.signal?.aborted === true, timeoutController.signal.aborted);
+        const wasCancelled = classification === "cancelled";
+        const retryable = retryPolicy.retryableClasses.includes(classification) && attemptNumber < retryPolicy.maxAttempts;
+        attemptService.fail(attempt, classification, message, retryable, this.deps.nodeFlowRepository.listNodeAttempts(run.id).find((candidate) => candidate.id === attempt.id)?.invocationId);
+        if (retryable) {
+          this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, { status: "retry_waiting", errorMessage: message });
+          await delay(retryDelay(retryPolicy.backoffMs, retryPolicy.maxBackoffMs ?? retryPolicy.backoffMs, retryPolicy.jitterRatio ?? 0, attemptNumber), options.signal);
+          this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, { status: "running", errorMessage: null });
+          continue;
+        }
         const continueOnError = node.data?.continueOnError === true;
         const failureOutput = { error: message };
         context.outputs.set(node.id, failureOutput);
@@ -186,7 +237,10 @@ export class NodeFlowRuntimeService {
           errorMessage: message,
           finishedAt: new Date().toISOString(),
         });
-        if (wasCancelled) {
+        if (classification === "unknown_side_effect") {
+          terminalStatus = "attention_required";
+          terminalError = message;
+        } else if (wasCancelled) {
           terminalStatus = "cancelled";
           terminalError ??= message || "Node flow run was cancelled.";
           for (const remainingNodeId of executionOrder.slice(nodeIndex + 1)) {
@@ -204,6 +258,11 @@ export class NodeFlowRuntimeService {
             blockedNodes.add(descendant);
           }
         }
+        break;
+      }
+      }
+      if (terminalStatus === "cancelled" || terminalStatus === "attention_required") {
+        break;
       }
     }
 
@@ -214,9 +273,11 @@ export class NodeFlowRuntimeService {
       output: maskSecrets(output),
       errorMessage: terminalError,
       finishedAt,
+      leaseOwner: null,
+      leaseExpiresAt: null,
     });
     this.deps.executionRepository.updateExecutionInvocation(parentInvocation.id, {
-      status: terminalStatus === "succeeded" ? "completed" : terminalStatus,
+      status: terminalStatus === "succeeded" ? "completed" : terminalStatus === "attention_required" ? "failed" : terminalStatus,
       errorMessage: terminalError,
       finishedAt,
     });
@@ -232,9 +293,11 @@ export class NodeFlowRuntimeService {
       },
     });
 
+    clearInterval(heartbeatTimer);
     return {
       run: updatedRun,
       nodeRuns: this.deps.nodeFlowRepository.listNodeRuns(run.id),
+      attempts: this.deps.nodeFlowRepository.listNodeAttempts(run.id),
       output: updatedRun.output,
     };
   }
@@ -263,6 +326,9 @@ export class NodeFlowRuntimeService {
         startedAt: new Date().toISOString(),
       });
       this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, { executionInvocationId: invocation.id });
+      if (context.currentAttemptId) {
+        this.deps.nodeFlowRepository.updateNodeAttempt(context.currentAttemptId, { invocationId: invocation.id });
+      }
       try {
         const result = node.type === "provider_prompt"
           ? await this.executeProviderPromptNode(context, node, invocation.id)
@@ -761,6 +827,32 @@ function redactUrl(url: URL): string {
   return clone.toString();
 }
 
+function classifyFailure(error: unknown, parentAborted: boolean, attemptAborted: boolean): NodeFlowFailureClassification {
+  if (parentAborted) return "cancelled";
+  const message = error instanceof Error ? error.message : String(error);
+  if (attemptAborted || /timed? out|timeout/i.test(message)) return "timeout";
+  if (/quota|rate.?limit|429/i.test(message)) return "quota";
+  if (/credential|secret|access denied/i.test(message)) return "credential";
+  if (error instanceof ValidationError || /requires|unsupported|must /i.test(message)) return "validation";
+  if (/ECONNRESET|ECONNREFUSED|temporar|unavailable|502|503|504/i.test(message)) return "transient";
+  return "permanent";
+}
+
+function retryDelay(baseMs: number, maxMs: number, jitterRatio: number, attemptNumber: number): number {
+  const exponential = Math.min(maxMs, Math.max(0, baseMs) * (2 ** Math.max(0, attemptNumber - 1)));
+  const jitter = exponential * Math.max(0, Math.min(1, jitterRatio));
+  return Math.max(0, Math.round(exponential - jitter + (Math.random() * jitter * 2)));
+}
+
+async function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  if (ms <= 0) return;
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    const abort = (): void => { clearTimeout(timer); reject(new Error("Node flow run was cancelled.")); };
+    signal?.addEventListener("abort", abort, { once: true });
+  });
+}
+
 function providerFailureMessage(result: ProviderRunResult): string {
   const output = [result.stderr, result.stdout]
     .map((stream) => stream?.trim())
diff --git a/src/services/node-flow-service.ts b/src/services/node-flow-service.ts
index e6462ceb72..066e300c57 100644
--- a/src/services/node-flow-service.ts
+++ b/src/services/node-flow-service.ts
@@ -107,6 +107,10 @@ export class NodeFlowService {
     return { nodeRuns: this.repository.listNodeRuns(runId) };
   }
 
+  listNodeAttempts(runId: string) {
+    return { attempts: this.repository.listNodeAttempts(runId) };
+  }
+
   async runFlow(
     projectId: string,
     flowId: string,
diff --git a/src/services/node-flows/node-flow-attempt-service.ts b/src/services/node-flows/node-flow-attempt-service.ts
new file mode 100644
index 0000000000..cad3afb9f6
--- /dev/null
+++ b/src/services/node-flows/node-flow-attempt-service.ts
@@ -0,0 +1,21 @@
+import { createHash } from "crypto";
+import type { NodeFlowRepository } from "../../repositories/node-flow-repository.js";
+import type { NodeFlowJsonObject, NodeFlowNodeAttemptRecord, NodeFlowNodeRunRecord } from "../../contracts/node-flow-types.js";
+import type { NodeFlowFailureClassification } from "../../contracts/node-flow-execution-policy-types.js";
+
+export class NodeFlowAttemptService {
+  constructor(private readonly repository: NodeFlowRepository) {}
+
+  start(nodeRun: NodeFlowNodeRunRecord, executorId: string, input: NodeFlowJsonObject, credentialIds: string[]): NodeFlowNodeAttemptRecord {
+    const attemptNumber = this.repository.listNodeAttempts(nodeRun.runId).filter((attempt) => attempt.nodeId === nodeRun.nodeId).length + 1;
+    return this.repository.createNodeAttempt({ runId: nodeRun.runId, nodeRunId: nodeRun.id, nodeId: nodeRun.nodeId, attemptNumber, status: "running", executorId, invocationId: null, artifactDigest: null, input, output: null, credentialIds, failureClassification: null, retryDecision: null, errorMessage: null, startedAt: new Date().toISOString(), finishedAt: null });
+  }
+
+  succeed(attempt: NodeFlowNodeAttemptRecord, output: NodeFlowJsonObject, invocationId?: string | null): NodeFlowNodeAttemptRecord {
+    return this.repository.updateNodeAttempt(attempt.id, { status: "succeeded", invocationId: invocationId ?? null, output, artifactDigest: createHash("sha256").update(JSON.stringify(output)).digest("hex"), retryDecision: "stop", finishedAt: new Date().toISOString() });
+  }
+
+  fail(attempt: NodeFlowNodeAttemptRecord, classification: NodeFlowFailureClassification, errorMessage: string, retry: boolean, invocationId?: string | null): NodeFlowNodeAttemptRecord {
+    return this.repository.updateNodeAttempt(attempt.id, { status: classification === "cancelled" ? "cancelled" : "failed", invocationId: invocationId ?? attempt.invocationId, failureClassification: classification, retryDecision: classification === "unknown_side_effect" ? "attention_required" : retry ? "retry" : "stop", errorMessage, finishedAt: new Date().toISOString() });
+  }
+}
diff --git a/src/services/node-flows/node-flow-lease-service.ts b/src/services/node-flows/node-flow-lease-service.ts
new file mode 100644
index 0000000000..721b058e43
--- /dev/null
+++ b/src/services/node-flows/node-flow-lease-service.ts
@@ -0,0 +1,8 @@
+import type { NodeFlowRepository } from "../../repositories/node-flow-repository.js";
+
+export class NodeFlowLeaseService {
+  constructor(private readonly repository: NodeFlowRepository) {}
+  heartbeat(runId: string, executorId: string, leaseDurationMs: number): boolean {
+    return this.repository.heartbeatRun(runId, executorId, leaseDurationMs);
+  }
+}
diff --git a/src/services/node-flows/node-flow-publication-service.ts b/src/services/node-flows/node-flow-publication-service.ts
new file mode 100644
index 0000000000..78433d8c58
--- /dev/null
+++ b/src/services/node-flows/node-flow-publication-service.ts
@@ -0,0 +1,19 @@
+import { EntityNotFoundError } from "../../repositories/repository-utils.js";
+import type { NodeFlowRepository } from "../../repositories/node-flow-repository.js";
+import type { NodeFlowPublicationRecord } from "../../contracts/node-flow-types.js";
+import type { NodeFlowVersionSelection } from "../../contracts/node-flow-execution-policy-types.js";
+
+export class NodeFlowPublicationService {
+  constructor(private readonly repository: NodeFlowRepository) {}
+
+  resolve(flowId: string, selection: NodeFlowVersionSelection): NodeFlowPublicationRecord {
+    const publication = selection.mode === "pinned"
+      ? this.repository.getPublication(flowId, selection.version)
+      : this.repository.getPublication(flowId);
+    if (!publication) {
+      const suffix = selection.mode === "pinned" ? ` at version ${selection.version}` : "";
+      throw new EntityNotFoundError(`Published node flow not found: ${flowId}${suffix}`);
+    }
+    return publication;
+  }
+}
diff --git a/src/services/node-flows/node-flow-queue-service.ts b/src/services/node-flows/node-flow-queue-service.ts
new file mode 100644
index 0000000000..f96241ebfc
--- /dev/null
+++ b/src/services/node-flows/node-flow-queue-service.ts
@@ -0,0 +1,18 @@
+import type { NodeFlowRepository } from "../../repositories/node-flow-repository.js";
+import type { NodeFlowRunRecord } from "../../contracts/node-flow-types.js";
+
+export class NodeFlowQuotaExceededError extends Error {}
+
+export class NodeFlowQueueService {
+  constructor(private readonly repository: NodeFlowRepository) {}
+
+  claim(run: NodeFlowRunRecord, executorId: string): NodeFlowRunRecord {
+    if (this.repository.countActiveRuns() >= run.policy.maxConcurrentRuns
+      || this.repository.countActiveRuns(run.projectId) >= run.policy.maxConcurrentRunsPerProject) {
+      throw new NodeFlowQuotaExceededError("Node flow concurrency quota is exhausted.");
+    }
+    const claimed = this.repository.claimQueuedRun(run.id, executorId, run.policy.leaseDurationMs);
+    if (!claimed) throw new Error("Node flow run could not be claimed.");
+    return claimed;
+  }
+}
diff --git a/src/services/node-flows/node-flow-recovery-service.ts b/src/services/node-flows/node-flow-recovery-service.ts
new file mode 100644
index 0000000000..2af71113cb
--- /dev/null
+++ b/src/services/node-flows/node-flow-recovery-service.ts
@@ -0,0 +1,27 @@
+import type { NodeFlowRepository } from "../../repositories/node-flow-repository.js";
+import type { NodeFlowRunRecord } from "../../contracts/node-flow-types.js";
+
+export class NodeFlowRecoveryService {
+  constructor(private readonly repository: NodeFlowRepository) {}
+
+  recover(now = new Date()): NodeFlowRunRecord[] {
+    const recoverable = this.repository.listRecoverableRuns(now.toISOString());
+    return recoverable.map((run) => {
+      if (run.status !== "running") return run;
+      const attempts = this.repository.listNodeAttempts(run.id);
+      const active = attempts.find((attempt) => attempt.status === "running");
+      if (active) {
+        const nextStatus = active.invocationId ? "attention_required" : "queued";
+        return this.repository.updateRun(run.id, {
+          status: nextStatus,
+          errorMessage: active.invocationId
+            ? "An externally observable attempt lost its lease; its outcome is unknown and requires attention."
+            : "Lease expired before an external invocation began; the run was safely requeued.",
+          leaseOwner: null,
+          leaseExpiresAt: null,
+        });
+      }
+      return this.repository.updateRun(run.id, { status: "queued", leaseOwner: null, leaseExpiresAt: null });
+    });
+  }
+}
diff --git a/src/services/scheduler-service.ts b/src/services/scheduler-service.ts
index 70d8ab7c9e..8fc5dd55f8 100644
--- a/src/services/scheduler-service.ts
+++ b/src/services/scheduler-service.ts
@@ -38,7 +38,7 @@ export interface SchedulerServiceDeps {
   taskRerunService?: TaskRerunService;
   memoryRemediationService?: MemoryRemediationService;
   nodeFlowRuntimeService?: NodeFlowRuntimeService;
-  nodeFlowRepository?: Pick<NodeFlowRepository, "getFlow">;
+  nodeFlowRepository?: Pick<NodeFlowRepository, "getFlow" | "getPublication">;
   logger: Logger;
   tickIntervalMs?: number;
 }
@@ -403,6 +403,9 @@ export class SchedulerService {
       target.input ?? {},
       {
         triggerType: "scheduler",
+        versionSelection: target.versionSelection ?? (target.flowVersion !== undefined
+          ? { mode: "pinned", version: target.flowVersion }
+          : { mode: "latest_published" }),
         triggerPayload: {
           schedulerEntryId: entry.id,
           scheduledFor: occurrenceIso,
@@ -440,6 +443,12 @@ export class SchedulerService {
         throw new Error("nodeFlowTarget.flowId is required.");
       }
       this.validateNodeFlowTargetOwnership(projectId, flowId);
+      const selection = input.nodeFlowTarget?.versionSelection
+        ?? (input.nodeFlowTarget?.flowVersion !== undefined ? { mode: "pinned" as const, version: input.nodeFlowTarget.flowVersion } : { mode: "latest_published" as const });
+      if (selection.mode === "pinned" && typeof this.deps.nodeFlowRepository?.getPublication === "function"
+        && !this.deps.nodeFlowRepository.getPublication(flowId, selection.version)) {
+          throw new Error("Scheduled node flow version must reference a published version.");
+      }
       return;
     }
 
diff --git a/tests/backend/mcp/management-node-flow-actions.test.ts b/tests/backend/mcp/management-node-flow-actions.test.ts
index 54711b8284..dbd69abd52 100644
--- a/tests/backend/mcp/management-node-flow-actions.test.ts
+++ b/tests/backend/mcp/management-node-flow-actions.test.ts
@@ -112,6 +112,7 @@ describe("manage_node_flows", () => {
 
     expect(nodeFlowService.runFlow).toHaveBeenCalledWith("project-1", "flow-1", { prompt: "Ship" }, {
       triggerType: "mcp_management",
+      versionSelection: { mode: "latest_published" },
     });
     expect(parsed.result.run.id).toBe("run-1");
     expect(parsed.result.output).toEqual({ ok: true });
diff --git a/tests/backend/repositories/scheduler-repository.test.ts b/tests/backend/repositories/scheduler-repository.test.ts
index 1bac634aa3..6a3b1cbf78 100644
--- a/tests/backend/repositories/scheduler-repository.test.ts
+++ b/tests/backend/repositories/scheduler-repository.test.ts
@@ -390,6 +390,7 @@ describe("SchedulerRepository", () => {
       flowId: "flow-1",
       input: { prompt: "Ship it", count: 2, nested: { ok: true } },
       flowVersion: 3,
+      versionSelection: { mode: "pinned", version: 3 },
     });
     expect(schedulerRepository.getEntry(entry.id)?.nodeFlowTarget).toEqual(entry.nodeFlowTarget);
 
@@ -411,6 +412,7 @@ describe("SchedulerRepository", () => {
     expect(updated.nodeFlowTarget).toEqual({
       flowId: "flow-2",
       input: { next: true },
+      versionSelection: { mode: "latest_published" },
     });
   });
 
diff --git a/tests/backend/server/node-flow-routes.test.ts b/tests/backend/server/node-flow-routes.test.ts
index add15bec4d..662fa498a1 100644
--- a/tests/backend/server/node-flow-routes.test.ts
+++ b/tests/backend/server/node-flow-routes.test.ts
@@ -138,6 +138,7 @@ describe("node flow routes", () => {
     expect(nodeFlowService.runFlow).toHaveBeenCalledWith("project-1", "flow-1", { prompt: "Ship" }, {
       triggerType: "manual",
       triggerPayload: undefined,
+      versionSelection: { mode: "latest_published" },
     });
   });
 });
diff --git a/tests/backend/services/node-flow-recovery-service.test.ts b/tests/backend/services/node-flow-recovery-service.test.ts
new file mode 100644
index 0000000000..918f0e4719
--- /dev/null
+++ b/tests/backend/services/node-flow-recovery-service.test.ts
@@ -0,0 +1,59 @@
+import { afterEach, describe, expect, it } from "vitest";
+import * as fs from "fs/promises";
+import * as os from "os";
+import * as path from "path";
+import { AppDbStorage } from "../../../src/repositories/app-db-storage.js";
+import { NodeFlowRepository } from "../../../src/repositories/node-flow-repository.js";
+import { ProjectManagementRepository } from "../../../src/repositories/project-management-repository.js";
+import { NodeFlowRecoveryService } from "../../../src/services/node-flows/node-flow-recovery-service.js";
+import { NodeFlowQueueService, NodeFlowQuotaExceededError } from "../../../src/services/node-flows/node-flow-queue-service.js";
+import { DEFAULT_NODE_FLOW_EXECUTION_POLICY } from "../../../src/contracts/node-flow-execution-policy-types.js";
+
+const dirs: string[] = [];
+afterEach(async () => Promise.all(dirs.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true }))));
+
+describe("NodeFlowRecoveryService", () => {
+  it("enforces the immutable project concurrency quota before claiming", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "flow-quota-")); dirs.push(dir);
+    const storage = new AppDbStorage(path.join(dir, "app.db"));
+    const projects = new ProjectManagementRepository(storage); const repository = new NodeFlowRepository(storage);
+    const project = projects.createProject({ name: "Quota", sourceType: "local", sourceRef: dir });
+    const flow = repository.createFlow(project.id, { title: "Quota", graph: { nodes: [{ id: "input", type: "input", title: "Input" }], edges: [] } });
+    const run = repository.createRun({ flowId: flow.id, projectId: project.id, version: 1, status: "queued", policy: { ...DEFAULT_NODE_FLOW_EXECUTION_POLICY, maxConcurrentRunsPerProject: 0 } });
+
+    expect(() => new NodeFlowQueueService(repository).claim(run, "executor")).toThrow(NodeFlowQuotaExceededError);
+    expect(repository.getRun(run.id)?.status).toBe("queued");
+  });
+
+  it("requeues an expired pre-invocation attempt without creating a duplicate attempt", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "flow-recovery-")); dirs.push(dir);
+    const storage = new AppDbStorage(path.join(dir, "app.db"));
+    const projects = new ProjectManagementRepository(storage); const repository = new NodeFlowRepository(storage);
+    const project = projects.createProject({ name: "Recovery", sourceType: "local", sourceRef: dir });
+    const flow = repository.createFlow(project.id, { title: "Recover", graph: { nodes: [{ id: "input", type: "input", title: "Input" }], edges: [] } });
+    const run = repository.createRun({ flowId: flow.id, projectId: project.id, version: 1, status: "running" });
+    repository.updateRun(run.id, { leaseOwner: "dead", leaseExpiresAt: "2020-01-01T00:00:00.000Z" });
+    const nodeRun = repository.createNodeRun({ runId: run.id, flowId: flow.id, projectId: project.id, nodeId: "input", status: "running" });
+    repository.createNodeAttempt({ runId: run.id, nodeRunId: nodeRun.id, nodeId: "input", attemptNumber: 1, status: "running", executorId: "dead", invocationId: null, artifactDigest: null, input: {}, output: null, credentialIds: [], failureClassification: null, retryDecision: null, errorMessage: null, startedAt: "2020-01-01T00:00:00.000Z", finishedAt: null });
+
+    const [recovered] = new NodeFlowRecoveryService(repository).recover();
+    expect(recovered?.status).toBe("queued");
+    expect(repository.listNodeAttempts(run.id)).toHaveLength(1);
+  });
+
+  it("requires attention when an expired attempt has an external invocation", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "flow-recovery-")); dirs.push(dir);
+    const storage = new AppDbStorage(path.join(dir, "app.db"));
+    const projects = new ProjectManagementRepository(storage); const repository = new NodeFlowRepository(storage);
+    const project = projects.createProject({ name: "Recovery External", sourceType: "local", sourceRef: dir });
+    const flow = repository.createFlow(project.id, { title: "Recover", graph: { nodes: [{ id: "http", type: "http_request", title: "HTTP" }], edges: [] } });
+    const run = repository.createRun({ flowId: flow.id, projectId: project.id, version: 1, status: "running" });
+    repository.updateRun(run.id, { leaseOwner: "dead", leaseExpiresAt: "2020-01-01T00:00:00.000Z" });
+    const nodeRun = repository.createNodeRun({ runId: run.id, flowId: flow.id, projectId: project.id, nodeId: "http", status: "running" });
+    repository.createNodeAttempt({ runId: run.id, nodeRunId: nodeRun.id, nodeId: "http", attemptNumber: 1, status: "running", executorId: "dead", invocationId: "external-1", artifactDigest: null, input: {}, output: null, credentialIds: [], failureClassification: null, retryDecision: null, errorMessage: null, startedAt: "2020-01-01T00:00:00.000Z", finishedAt: null });
+
+    const [recovered] = new NodeFlowRecoveryService(repository).recover();
+    expect(recovered?.status).toBe("attention_required");
+    expect(recovered?.errorMessage).toMatch(/outcome is unknown/i);
+  });
+});
diff --git a/tests/backend/services/node-flow-runtime-service.test.ts b/tests/backend/services/node-flow-runtime-service.test.ts
index 072726e075..6a94053222 100644
--- a/tests/backend/services/node-flow-runtime-service.test.ts
+++ b/tests/backend/services/node-flow-runtime-service.test.ts
@@ -46,6 +46,51 @@ afterEach(async () => {
 });
 
 describe("NodeFlowRuntimeService", () => {
+  it("executes an explicitly pinned publication while latest selection follows the newest publication", async () => {
+    const { dir, projectRepository, nodeFlowRepository, runtime } = await createRuntime();
+    const project = projectRepository.createProject({ name: "Version Project", sourceType: "local", sourceRef: dir });
+    const flow = nodeFlowRepository.createFlow(project.id, { title: "Versioned", graph: { nodes: [{ id: "set", type: "set_fields", title: "Set", data: { fields: { release: "v1" } } }], edges: [] } });
+    nodeFlowRepository.updateFlow(flow.id, { graph: { nodes: [{ id: "set", type: "set_fields", title: "Set", data: { fields: { release: "v2" } } }], edges: [] } });
+
+    const pinned = await runtime.runFlow(project.id, flow.id, {}, { versionSelection: { mode: "pinned", version: 1 } });
+    const latest = await runtime.runFlow(project.id, flow.id, {}, { versionSelection: { mode: "latest_published" } });
+
+    expect(pinned.run.version).toBe(1);
+    expect(pinned.output).toEqual({ release: "v1" });
+    expect(latest.run.version).toBe(2);
+    expect(latest.output).toEqual({ release: "v2" });
+  });
+
+  it("retries classified transient failures and persists redacted numbered attempts", async () => {
+    const executeProvider = vi.fn()
+      .mockRejectedValueOnce(new Error("503 temporarily unavailable"))
+      .mockResolvedValue({ ok: true, stdout: "ok", stderr: "", code: 0, text: "ok", nativeSessionId: null, usageTelemetry: { transcriptText: "ok", inputTokens: 0, cachedInputTokens: 0, outputTokens: 0, reasoningOutputTokens: 0, totalTokens: 0, usageSource: "reported", rawUsageJson: null } });
+    const { dir, projectRepository, nodeFlowRepository, runtime } = await createRuntime({ executeProvider } as Partial<ProviderExecutionService>);
+    const project = projectRepository.createProject({ name: "Retry Project", sourceType: "local", sourceRef: dir });
+    const flow = nodeFlowRepository.createFlow(project.id, { title: "Retry", graph: { nodes: [{ id: "prompt", type: "provider_prompt", title: "Prompt", data: { provider: "mockup-cli", prompt: "{{input.apiToken}}" }, policy: { retry: { maxAttempts: 2, backoffMs: 0, maxBackoffMs: 0 } } }], edges: [] } });
+
+    const result = await runtime.runFlow(project.id, flow.id, { apiToken: "never-store" });
+
+    expect(result.run.status).toBe("succeeded");
+    expect(executeProvider).toHaveBeenCalledTimes(2);
+    expect(result.attempts?.map((attempt) => [attempt.attemptNumber, attempt.retryDecision])).toEqual([[1, "retry"], [2, "stop"]]);
+    expect(JSON.stringify(result.attempts)).not.toContain("never-store");
+  });
+
+  it("propagates node timeouts to the executor and classifies the attempt", async () => {
+    const executeProvider = vi.fn().mockImplementation(({ signal }: { signal?: AbortSignal }) => new Promise((_resolve, reject) => {
+      signal?.addEventListener("abort", () => reject(signal.reason), { once: true });
+    }));
+    const { dir, projectRepository, nodeFlowRepository, runtime } = await createRuntime({ executeProvider } as Partial<ProviderExecutionService>);
+    const project = projectRepository.createProject({ name: "Timeout Project", sourceType: "local", sourceRef: dir });
+    const flow = nodeFlowRepository.createFlow(project.id, { title: "Timeout", graph: { nodes: [{ id: "prompt", type: "provider_prompt", title: "Prompt", data: { provider: "mockup-cli", prompt: "wait" }, policy: { timeout: { timeoutMs: 5 } } }], edges: [] } });
+
+    const result = await runtime.runFlow(project.id, flow.id, {});
+
+    expect(result.run.status).toBe("failed");
+    expect(result.attempts?.[0]).toMatchObject({ failureClassification: "timeout", retryDecision: "stop" });
+  });
+
   it("executes deterministic nodes in topological order and persists the succeeded run", async () => {
     const { dir, projectRepository, nodeFlowRepository, runtime } = await createRuntime();
     const project = projectRepository.createProject({ name: "Runtime Project", sourceType: "local", sourceRef: dir });
diff --git a/tests/backend/services/scheduler-service.test.ts b/tests/backend/services/scheduler-service.test.ts
index 4bac0cd5b2..cf21d93cb2 100644
--- a/tests/backend/services/scheduler-service.test.ts
+++ b/tests/backend/services/scheduler-service.test.ts
@@ -533,6 +533,7 @@ describe("SchedulerService", () => {
 
     expect(nodeFlowRuntimeService.runFlow).toHaveBeenCalledWith("project-1", "flow-1", { prompt: "Ship" }, {
       triggerType: "scheduler",
+      versionSelection: { mode: "pinned", version: 2 },
       triggerPayload: {
         schedulerEntryId: "entry-1",
         scheduledFor: "2026-05-18T09:00:00.000Z",

From d53fe2f507ed3485ae0af8ec52a2e7a65871068f Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 05:17:37 +0000
Subject: [PATCH 04/25] feat(task T04): implement via codex

---
 .../node-flow-builtins-and-security.md        |  25 ++
 docs-web/architecture/node-flows.md           |  10 +-
 ...ecture-node-flow-builtins-and-security.mdx |  25 ++
 .../content/docs/architecture-node-flows.mdx  |  10 +-
 docs-web/content/docs/registry.ts             |   9 +
 ...e-node-flow-builtins-and-security.lazy.tsx |  11 +
 docs/SUMMARY.md                               |   1 +
 .../node-flow-builtins-and-security.md        |  58 +++++
 docs/architecture/node-flows.md               |  12 +-
 docs/index.md                                 |   2 +
 src/app/dependency-factory/core-factory.ts    |  12 +
 .../dependency-factory/dashboard-factory.ts   |  20 ++
 src/contracts/node-flow-types.ts              |   4 +-
 .../node-flows/node-definition-registry.ts    |  51 ++++
 .../automation-approval-repository.ts         | 112 +++++++++
 .../automation-outbox-repository.ts           |  83 +++++++
 .../automation-webhook-trigger-repository.ts  |  51 ++++
 src/repositories/db/app-db-migrations.ts      |  71 ++++++
 src/server/dashboard-route-registration.ts    |   2 +
 src/server/dashboard-server.ts                |   4 +
 src/server/node-flow-routes.ts                |  29 +++
 src/server/node-flow-webhook-routes.ts        |  26 ++
 src/services/node-flow-runtime-service.ts     | 121 +++++++++-
 src/services/node-flows/approval-service.ts   |  37 +++
 .../node-flows/builtins/builtin-executors.ts  | 142 +++++++++++
 src/services/node-flows/builtins/index.ts     |   1 +
 .../node-flows/egress-policy-service.ts       | 224 ++++++++++++++++++
 src/services/node-flows/oauth-broker.ts       | 107 +++++++++
 src/services/node-flows/outbox-service.ts     |  42 ++++
 .../node-definition-registry.test.ts          |  11 +-
 ...automation-governance-repositories.test.ts |  50 ++++
 .../server/node-flow-webhook-routes.test.ts   |  20 ++
 .../services/node-flow-builtins.test.ts       |  28 +++
 .../node-flow-egress-policy-service.test.ts   |  42 ++++
 .../services/node-flow-oauth-broker.test.ts   |  32 +++
 .../node-flow-runtime-service.test.ts         |  56 +++--
 36 files changed, 1499 insertions(+), 42 deletions(-)
 create mode 100644 docs-web/architecture/node-flow-builtins-and-security.md
 create mode 100644 docs-web/content/docs/architecture-node-flow-builtins-and-security.mdx
 create mode 100644 docs-web/routes/docs.architecture-node-flow-builtins-and-security.lazy.tsx
 create mode 100644 docs/architecture/node-flow-builtins-and-security.md
 create mode 100644 src/repositories/automation-approval-repository.ts
 create mode 100644 src/repositories/automation-outbox-repository.ts
 create mode 100644 src/repositories/automation-webhook-trigger-repository.ts
 create mode 100644 src/server/node-flow-webhook-routes.ts
 create mode 100644 src/services/node-flows/approval-service.ts
 create mode 100644 src/services/node-flows/builtins/builtin-executors.ts
 create mode 100644 src/services/node-flows/builtins/index.ts
 create mode 100644 src/services/node-flows/egress-policy-service.ts
 create mode 100644 src/services/node-flows/oauth-broker.ts
 create mode 100644 src/services/node-flows/outbox-service.ts
 create mode 100644 tests/backend/repositories/automation-governance-repositories.test.ts
 create mode 100644 tests/backend/server/node-flow-webhook-routes.test.ts
 create mode 100644 tests/backend/services/node-flow-builtins.test.ts
 create mode 100644 tests/backend/services/node-flow-egress-policy-service.test.ts
 create mode 100644 tests/backend/services/node-flow-oauth-broker.test.ts

diff --git a/docs-web/architecture/node-flow-builtins-and-security.md b/docs-web/architecture/node-flow-builtins-and-security.md
new file mode 100644
index 0000000000..74a54d6688
--- /dev/null
+++ b/docs-web/architecture/node-flow-builtins-and-security.md
@@ -0,0 +1,25 @@
+# Node Flow Built-ins and External-Effect Security
+
+The governed catalog adds deterministic branches, bounded collection processing, durable approvals, and replay-safe external effects while keeping the versioned definition registry as the executable authority.
+
+## Control and integration nodes
+
+- `condition` selects `true` or `false`; `switch` selects one named case or `default`. Unselected branches persist as skipped node runs.
+- `foreach` accepts no more than 1,000 items. `merge` supports `object`, `array`, and `first` strategies.
+- `delay` is cancellable and capped at one hour. `execute_subflow` requires same-project ownership, rejects direct self-reference, and caps depth at eight.
+- `approval` persists an operator decision. `email_draft` never sends. `email_send` requires approval and uses the idempotent outbox.
+- `webhook_trigger` emits payloads accepted through secret-authenticated webhook ingress.
+
+## Network policy
+
+HTTP nodes and future custom nodes use the same `EgressPolicyService`. HTTPS is required unless HTTP is explicitly enabled. Private, loopback, link-local, metadata, multicast, and other non-public addresses remain blocked in both modes. Credentials in URLs and raw restricted headers are rejected.
+
+Every redirect is manually revalidated. DNS is checked for private results and rebinding. Host and port allowlists, response-size and content-type limits, propagated cancellation and timeouts, capped retries, idempotency requirements for unsafe retry, normalized headers, and per-key rate windows keep requests bounded.
+
+## OAuth, approvals, and outbox
+
+OAuth authorization uses PKCE S256 and short-lived AES-256-GCM state tied to an allowlisted callback origin. Tokens live behind the connection store, rotate on refresh, enforce scopes and expiry, and are never written into graph JSON or agent-visible output. Revocation, reconnect, and health checks expose no token values.
+
+Approvals are unique per run, node, and logical item. Outbox entries use a unique key derived from publication, run, node, and logical item, and store the provider message id after success. A restart while an entry is sending changes it to `attention_required`; Code UX does not automatically replay an unknown provider outcome.
+
+Webhook configuration returns a newly rotated path token and secret while persisting only their hashes. Ingress requires `x-codeux-webhook-secret` and dispatches the latest published flow version.
diff --git a/docs-web/architecture/node-flows.md b/docs-web/architecture/node-flows.md
index f3f15bfffa..ed7653f450 100644
--- a/docs-web/architecture/node-flows.md
+++ b/docs-web/architecture/node-flows.md
@@ -11,8 +11,16 @@ Node flows are project-owned, versioned Graph v2 workflows.
 | `template` | Renders text templates. |
 | `provider_prompt` | Invokes a configured CLI provider. |
 | `http_request` | Performs a bounded HTTP/HTTPS request. |
+| `condition`, `switch` | Selects one explicit output branch and persists unselected branches as skipped. |
+| `foreach`, `merge` | Bounds item fan-out and combines active inputs with an explicit strategy. |
+| `delay`, `approval` | Waits with cancellation or persists an operator decision gate. |
+| `email_draft`, `email_send` | Produces a draft, or sends only after approval through the idempotent outbox. |
+| `execute_subflow` | Executes a same-project published flow with recursion bounds. |
+| `webhook_trigger` | Emits secret-authenticated webhook input. |
 | `output` | Selects the result. |
 
-These are the only executable definitions. Trigger, agent-router, task, condition, notification, and other palette concepts are planned entries without runtime handlers. Graph v1 migration preserves the legacy snapshot and appends deterministic v2.
+These are the executable definitions. Other custom palette concepts remain non-executable until a versioned handler is registered. Graph v1 migration preserves the legacy snapshot and appends deterministic v2.
 
 Execution uses immutable publications rather than the mutable editor row. Runs select a pinned publication or the latest published version, then use durable queue claims, leases, bounded quotas, timeout/cancellation propagation, and numbered retry attempts. Expired external attempts with unknown outcomes require operator attention and are not silently replayed. See [Node Flow Durable Execution](./node-flow-durable-execution.md).
+
+HTTP and future custom-node requests share one HTTPS-first egress policy with URL-credential rejection, DNS and redirect revalidation, private-network and metadata blocking, host/port allowlists, bounded content, retries, timeouts, and rate limits. See [Built-ins and External-Effect Security](./node-flow-builtins-and-security.md).
diff --git a/docs-web/content/docs/architecture-node-flow-builtins-and-security.mdx b/docs-web/content/docs/architecture-node-flow-builtins-and-security.mdx
new file mode 100644
index 0000000000..74a54d6688
--- /dev/null
+++ b/docs-web/content/docs/architecture-node-flow-builtins-and-security.mdx
@@ -0,0 +1,25 @@
+# Node Flow Built-ins and External-Effect Security
+
+The governed catalog adds deterministic branches, bounded collection processing, durable approvals, and replay-safe external effects while keeping the versioned definition registry as the executable authority.
+
+## Control and integration nodes
+
+- `condition` selects `true` or `false`; `switch` selects one named case or `default`. Unselected branches persist as skipped node runs.
+- `foreach` accepts no more than 1,000 items. `merge` supports `object`, `array`, and `first` strategies.
+- `delay` is cancellable and capped at one hour. `execute_subflow` requires same-project ownership, rejects direct self-reference, and caps depth at eight.
+- `approval` persists an operator decision. `email_draft` never sends. `email_send` requires approval and uses the idempotent outbox.
+- `webhook_trigger` emits payloads accepted through secret-authenticated webhook ingress.
+
+## Network policy
+
+HTTP nodes and future custom nodes use the same `EgressPolicyService`. HTTPS is required unless HTTP is explicitly enabled. Private, loopback, link-local, metadata, multicast, and other non-public addresses remain blocked in both modes. Credentials in URLs and raw restricted headers are rejected.
+
+Every redirect is manually revalidated. DNS is checked for private results and rebinding. Host and port allowlists, response-size and content-type limits, propagated cancellation and timeouts, capped retries, idempotency requirements for unsafe retry, normalized headers, and per-key rate windows keep requests bounded.
+
+## OAuth, approvals, and outbox
+
+OAuth authorization uses PKCE S256 and short-lived AES-256-GCM state tied to an allowlisted callback origin. Tokens live behind the connection store, rotate on refresh, enforce scopes and expiry, and are never written into graph JSON or agent-visible output. Revocation, reconnect, and health checks expose no token values.
+
+Approvals are unique per run, node, and logical item. Outbox entries use a unique key derived from publication, run, node, and logical item, and store the provider message id after success. A restart while an entry is sending changes it to `attention_required`; Code UX does not automatically replay an unknown provider outcome.
+
+Webhook configuration returns a newly rotated path token and secret while persisting only their hashes. Ingress requires `x-codeux-webhook-secret` and dispatches the latest published flow version.
diff --git a/docs-web/content/docs/architecture-node-flows.mdx b/docs-web/content/docs/architecture-node-flows.mdx
index 31bf1274aa..b19d3c6608 100644
--- a/docs-web/content/docs/architecture-node-flows.mdx
+++ b/docs-web/content/docs/architecture-node-flows.mdx
@@ -11,8 +11,16 @@ Node flows are project-owned, versioned Graph v2 workflows.
 | `template` | Renders text templates. |
 | `provider_prompt` | Invokes a configured CLI provider. |
 | `http_request` | Performs a bounded HTTP/HTTPS request. |
+| `condition`, `switch` | Selects one explicit output branch and persists unselected branches as skipped. |
+| `foreach`, `merge` | Bounds item fan-out and combines active inputs with an explicit strategy. |
+| `delay`, `approval` | Waits with cancellation or persists an operator decision gate. |
+| `email_draft`, `email_send` | Produces a draft, or sends only after approval through the idempotent outbox. |
+| `execute_subflow` | Executes a same-project published flow with recursion bounds. |
+| `webhook_trigger` | Emits secret-authenticated webhook input. |
 | `output` | Selects the result. |
 
-These are the only executable definitions. Trigger, agent-router, task, condition, notification, and other palette concepts are planned entries without runtime handlers. Graph v1 migration preserves the legacy snapshot and appends deterministic v2.
+These are the executable definitions. Other custom palette concepts remain non-executable until a versioned handler is registered. Graph v1 migration preserves the legacy snapshot and appends deterministic v2.
 
 Execution uses immutable publications rather than the mutable editor row. Runs select a pinned publication or the latest published version, then use durable queue claims, leases, bounded quotas, timeout/cancellation propagation, and numbered retry attempts. Expired external attempts with unknown outcomes require operator attention and are not silently replayed. See [Node Flow Durable Execution](/docs/architecture-node-flow-durable-execution).
+
+HTTP and future custom-node requests share one HTTPS-first egress policy with URL-credential rejection, DNS and redirect revalidation, private-network and metadata blocking, host/port allowlists, bounded content, retries, timeouts, and rate limits. See [Built-ins and External-Effect Security](/docs/architecture-node-flow-builtins-and-security).
diff --git a/docs-web/content/docs/registry.ts b/docs-web/content/docs/registry.ts
index 637afe7f3a..42d840a534 100644
--- a/docs-web/content/docs/registry.ts
+++ b/docs-web/content/docs/registry.ts
@@ -108,6 +108,7 @@ export type DocsSlug =
   | 'user-dashboard-custom-dashboards'
   | 'architecture-custom-dashboard-foundation'
   | 'architecture-managed-container-runtime'
+  | 'architecture-node-flow-builtins-and-security'
   | 'architecture-node-flow-durable-execution'
   | 'architecture-node-flow-foundation'
   | 'architecture-node-flows'
@@ -859,6 +860,13 @@ export const docsRegistry: Record<DocsSlug, DocsRegistryEntry> = {
     title: "Managed Container Runtime",
     description: "The managed container runtime removes first-invocation Docker builds while keeping provider binaries local to each user's Docker host.",
   },
+  'architecture-node-flow-builtins-and-security': {
+    id: 'architecture-node-flow-builtins-and-security',
+    path: '/docs/architecture-node-flow-builtins-and-security',
+    section: 'Architecture',
+    title: "Node Flow Built-ins and External-Effect Security",
+    description: "The governed catalog adds deterministic branches, bounded collection processing, durable approvals, and replay-safe external effects while keeping the versioned definition registry as the executable authority.",
+  },
   'architecture-node-flow-durable-execution': {
     id: 'architecture-node-flow-durable-execution',
     path: '/docs/architecture-node-flow-durable-execution',
@@ -1009,6 +1017,7 @@ export const orderedDocs: DocsRegistryEntry[] = [
   docsRegistry['user-dashboard-custom-dashboards'],
   docsRegistry['architecture-custom-dashboard-foundation'],
   docsRegistry['architecture-managed-container-runtime'],
+  docsRegistry['architecture-node-flow-builtins-and-security'],
   docsRegistry['architecture-node-flow-durable-execution'],
   docsRegistry['architecture-node-flow-foundation'],
   docsRegistry['architecture-node-flows'],
diff --git a/docs-web/routes/docs.architecture-node-flow-builtins-and-security.lazy.tsx b/docs-web/routes/docs.architecture-node-flow-builtins-and-security.lazy.tsx
new file mode 100644
index 0000000000..85e5318bd6
--- /dev/null
+++ b/docs-web/routes/docs.architecture-node-flow-builtins-and-security.lazy.tsx
@@ -0,0 +1,11 @@
+import { createLazyFileRoute } from '@tanstack/react-router'
+import ArchitectureNodeFlowBuiltinsAndSecurityContent from '../content/docs/architecture-node-flow-builtins-and-security.mdx'
+import { DocsPage } from '../components/docs/DocsPage'
+
+export const Route = createLazyFileRoute('/docs/architecture-node-flow-builtins-and-security')({
+  component: () => (
+    <DocsPage id="architecture-node-flow-builtins-and-security">
+      <ArchitectureNodeFlowBuiltinsAndSecurityContent />
+    </DocsPage>
+  )
+})
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 933e7c124d..820eada147 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -40,6 +40,7 @@
 - [Node Flow Foundation](./architecture/node-flow-foundation.md)
 - [Node Flows](./architecture/node-flows.md)
 - [Node Flow Durable Execution](./architecture/node-flow-durable-execution.md)
+- [Node Flow Built-ins and External-Effect Security](./architecture/node-flow-builtins-and-security.md)
 - [Custom Dashboard Foundation](./architecture/custom-dashboard-foundation.md)
 - [Memory Claims and Evidence](./architecture/memory-claims.md)
 - [Speech Input Architecture](./architecture/speech-input.md)
diff --git a/docs/architecture/node-flow-builtins-and-security.md b/docs/architecture/node-flow-builtins-and-security.md
new file mode 100644
index 0000000000..1156cb9ca5
--- /dev/null
+++ b/docs/architecture/node-flow-builtins-and-security.md
@@ -0,0 +1,58 @@
+# Node Flow Built-ins and External-Effect Security
+
+The governed built-in catalog extends publication-based node-flow execution with deterministic control nodes and durable boundaries for external effects. The definition registry remains the executable authority; a graph can only run a node when its versioned manifest is registered and executable.
+
+## Built-in catalog
+
+| Node | Contract |
+| --- | --- |
+| `condition` | Evaluates a bounded operator and selects exactly the `true` or `false` output port. Unselected branches persist as skipped node runs. |
+| `switch` | Evaluates no more than 100 configured cases and selects one named case or `default`. |
+| `foreach` | Validates an array and emits at most 1,000 items. Inputs above the configured bound fail before fan-out. |
+| `merge` | Combines active upstream values with `object`, `array`, or `first` strategy. |
+| `delay` | Waits for a cancellable duration from zero through one hour. |
+| `approval` | Creates or reuses a durable approval keyed by run, node, and logical item. |
+| `email_draft` | Produces a draft only and never contacts a provider. |
+| `email_send` | Requires an approved decision, then dispatches through the idempotent outbox. |
+| `execute_subflow` | Executes a published flow owned by the same project, rejects direct self-reference, and caps nesting at eight. |
+| `webhook_trigger` | Emits input accepted by a secret-authenticated webhook configuration. |
+
+The existing `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output` nodes retain their previous contracts. Typed manifest ports identify branch handles, many-valued merge inputs, and trigger outputs. Branch routing only runs a node when at least one incoming edge is active, allowing merges to join a selected path without treating an unselected sibling as a failure.
+
+## Governed egress
+
+`EgressPolicyService` is the single request boundary for HTTP nodes and future custom-node network calls. HTTPS is required by default. A node must explicitly opt into HTTP, and even then private networking remains blocked. The service rejects credentials embedded in URLs; loopback, private, link-local, carrier-grade NAT, benchmarking, multicast, and cloud-metadata addresses; metadata hostnames; restricted raw headers; and ports or hosts outside configured allowlists.
+
+Each redirect is handled manually and fully revalidated. DNS is resolved twice before dispatch, and a changed or newly private result is treated as rebinding. Cross-origin redirects remove credential headers. Response bodies are streamed into a bounded buffer, content types are allowlisted, timeouts and caller cancellation propagate, retry counts are capped, unsafe methods require an idempotency key before retry, and an in-process rate window bounds requests per project and host.
+
+## OAuth boundary
+
+`OAuthBroker` implements authorization-code flow with PKCE S256. Authorization state is authenticated AES-256-GCM ciphertext containing a short expiry, callback origin, redirect URI, verifier, connection id, and nonce. Callback origins must be explicitly allowlisted and match the state. Token exchange and refresh results are stored behind an `OAuthConnectionStore`; access and refresh tokens are returned only to provider-bound execution code, never to graph JSON or agent-visible output.
+
+Refresh happens shortly before expiry and rotates the stored refresh token when the provider returns one. Required scopes are checked before access. Revocation deletes local state after provider revocation; reconnect begins from a revoked local connection; health checks refresh when necessary and expose only health, expiry, and scopes.
+
+## Approvals and outbox
+
+`automation_approvals` persists pending and terminal decisions. Repeating the same run, node, and logical item returns the existing decision, so restarts do not create a second prompt. Email sending is approval-gated by default; `email_draft` is the non-irreversible default.
+
+`automation_outbox` has a unique SHA-256 idempotency key derived from publication id, run id, node id, and logical item. Provider message ids are stored after success. A process restart while an entry is `sending` changes it to `attention_required`, because the provider may have accepted the operation; Code UX does not replay an unknown external outcome automatically.
+
+## Webhook routes
+
+Creating `POST /api/node-flows/:flowId/webhook` rotates and returns a path token and secret once. Only their hashes are persisted. `POST /api/webhooks/node-flows/:pathToken` requires the secret in `x-codeux-webhook-secret`, uses constant-time digest comparison, and dispatches the latest published version with `triggerType: webhook`. The response returns only run identity and status.
+
+Example condition edges use explicit handles:
+
+```json
+{
+  "nodes": [
+    { "id": "check", "type": "condition", "title": "Check", "data": { "path": "input.enabled" } },
+    { "id": "draft", "type": "email_draft", "title": "Draft", "data": { "to": "owner@example.test", "subject": "Ready", "body": "Review this draft." } },
+    { "id": "done", "type": "output", "title": "Done" }
+  ],
+  "edges": [
+    { "fromNodeId": "check", "fromHandle": "true", "toNodeId": "draft" },
+    { "fromNodeId": "check", "fromHandle": "false", "toNodeId": "done" }
+  ]
+}
+```
diff --git a/docs/architecture/node-flows.md b/docs/architecture/node-flows.md
index bc355cf310..f8ba39cec3 100644
--- a/docs/architecture/node-flows.md
+++ b/docs/architecture/node-flows.md
@@ -50,11 +50,19 @@ Runtime-supported node types are:
 | `template` | Renders `template` or `prompt` into `outputKey` (default `text`). |
 | `provider_prompt` | Renders a prompt and calls an existing CLI provider configuration through `ProviderExecutionService`. |
 | `http_request` | Performs bounded HTTP/HTTPS requests with method, URL, headers, query, body, timeout, and optional JSON path extraction. |
+| `condition`, `switch` | Select one explicit output branch; non-selected branches are persisted as skipped. |
+| `foreach` | Validates and emits a bounded item list. |
+| `merge` | Combines active inputs with `object`, `array`, or `first` strategy. |
+| `delay` | Waits for a bounded cancellable duration. |
+| `approval` | Persists an operator decision gate. |
+| `email_draft`, `email_send` | Creates a draft, or sends only after approval through the idempotent outbox. |
+| `execute_subflow` | Executes a same-project published subflow with recursion bounds. |
+| `webhook_trigger` | Emits authenticated webhook input. |
 | `output` | Selects final output from a path, configured fields, or upstream output. |
 
 Template interpolation reads from `{{ input.path }}` and `{{ nodes.nodeId.path }}`. Node config is built from widget defaults, node `data`, and optional `data.values`, with later values overriding defaults.
 
-Provider prompt nodes require a configured CLI provider. HTTP nodes require `http` or `https` URLs and support `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, and `HEAD`. HTTP timeout defaults to 30 seconds and is capped at 60 seconds.
+Provider prompt nodes require a configured CLI provider. HTTP nodes require HTTPS unless HTTP is explicitly enabled and support `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, and `HEAD`. Requests pass through the shared SSRF, redirect, DNS, response-size, content-type, retry, timeout, and rate-limit policy described in [Node Flow Built-ins and External-Effect Security](./node-flow-builtins-and-security.md).
 
 ## Invocation Tracking
 
@@ -105,6 +113,6 @@ Use these rules:
 
 Graph v2 is the single workflow model used by backend, MCP, runtime, and dashboard. It adds `schemaVersion: 2`, stable definition references, typed ports and flow schemas, credential-id bindings, retry and timeout policies, capability and side-effect metadata, disabled state, and optional immutable publication metadata. Plaintext credentials, secret-shaped fields, generated source, and custom code are not valid graph data.
 
-The executable registry is exactly `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output`. Planned trigger, agent-router, task, condition, notification, and integration entries are not executable until handlers exist.
+The executable registry contains the original deterministic/provider/HTTP nodes plus `condition`, `switch`, `foreach`, `merge`, `delay`, `approval`, `email_draft`, `email_send`, `execute_subflow`, and `webhook_trigger`. Unregistered custom types remain non-executable.
 
 Backend Graph v1 migration retains the exact prior version and appends deterministic v2. Browser canvas v1 migration returns the untouched legacy snapshot separately from the normalized graph.
diff --git a/docs/index.md b/docs/index.md
index 21d4ab0ebf..d459e6830d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -67,6 +67,7 @@ Use this page as the main entrypoint.
 29. [Node Flow Foundation](./architecture/node-flow-foundation.md)
 30. [Node Flows](./architecture/node-flows.md)
 31. [Node Flow Durable Execution](./architecture/node-flow-durable-execution.md)
+32. [Node Flow Built-ins and External-Effect Security](./architecture/node-flow-builtins-and-security.md)
 31. [Custom Dashboard Foundation](./architecture/custom-dashboard-foundation.md)
 32. [Memory Claims and Evidence](./architecture/memory-claims.md)
 33. [Speech Input Architecture](./architecture/speech-input.md)
@@ -160,6 +161,7 @@ Use this page as the main entrypoint.
 - [Node Flow Foundation](./architecture/node-flow-foundation.md)
 - [Node Flows](./architecture/node-flows.md)
 - [Node Flow Durable Execution](./architecture/node-flow-durable-execution.md)
+- [Node Flow Built-ins and External-Effect Security](./architecture/node-flow-builtins-and-security.md)
 - [Custom Dashboard Foundation](./architecture/custom-dashboard-foundation.md)
 - [Memory Claims and Evidence](./architecture/memory-claims.md)
 - [Speech Input Architecture](./architecture/speech-input.md)
diff --git a/src/app/dependency-factory/core-factory.ts b/src/app/dependency-factory/core-factory.ts
index 55108c588e..4e56765e25 100644
--- a/src/app/dependency-factory/core-factory.ts
+++ b/src/app/dependency-factory/core-factory.ts
@@ -67,6 +67,9 @@ import { DockerService } from "../../services/docker-service.js";
 import { CustomDashboardRepository } from "../../repositories/custom-dashboard-repository.js";
 import { CustomDashboardValidationService } from "../../services/custom-dashboard-validation-service.js";
 import { AutomationCredentialRepository } from "../../repositories/automation-credential-repository.js";
+import { AutomationApprovalRepository } from "../../repositories/automation-approval-repository.js";
+import { AutomationOutboxRepository } from "../../repositories/automation-outbox-repository.js";
+import { AutomationWebhookTriggerRepository } from "../../repositories/automation-webhook-trigger-repository.js";
 import { CredentialBroker } from "../../services/credentials/credential-broker.js";
 import { MountedKeyFileProvider } from "../../infrastructure/security/mounted-key-file-provider.js";
 import { EncryptedSqliteSecretStore } from "../../infrastructure/security/encrypted-sqlite-secret-store.js";
@@ -131,6 +134,9 @@ export interface CoreDependencies {
   customDashboardRepository: CustomDashboardRepository;
   customDashboardValidationService: CustomDashboardValidationService;
   automationCredentialRepository: AutomationCredentialRepository;
+  automationApprovalRepository: AutomationApprovalRepository;
+  automationOutboxRepository: AutomationOutboxRepository;
+  automationWebhookTriggerRepository: AutomationWebhookTriggerRepository;
   credentialBroker: CredentialBroker;
 }
 
@@ -188,6 +194,9 @@ export function createCoreDependencies(
   const sessionTracking = new SessionTrackingRepository();
   const appDbStorage = new AppDbStorage();
   const automationCredentialRepository = new AutomationCredentialRepository(appDbStorage);
+  const automationApprovalRepository = new AutomationApprovalRepository(appDbStorage);
+  const automationOutboxRepository = new AutomationOutboxRepository(appDbStorage);
+  const automationWebhookTriggerRepository = new AutomationWebhookTriggerRepository(appDbStorage);
   const credentialKeyProvider = getProcessCredentialKeyProvider()
     ?? new MountedKeyFileProvider(process.env.CODE_UX_CREDENTIAL_KEY_FILE);
   const credentialBroker = new CredentialBroker(
@@ -407,6 +416,9 @@ export function createCoreDependencies(
     customDashboardRepository,
     customDashboardValidationService,
     automationCredentialRepository,
+    automationApprovalRepository,
+    automationOutboxRepository,
+    automationWebhookTriggerRepository,
     credentialBroker,
   };
 }
diff --git a/src/app/dependency-factory/dashboard-factory.ts b/src/app/dependency-factory/dashboard-factory.ts
index da4d85983f..494ba30a63 100644
--- a/src/app/dependency-factory/dashboard-factory.ts
+++ b/src/app/dependency-factory/dashboard-factory.ts
@@ -33,6 +33,12 @@ import { NodeFlowRuntimeService } from "../../services/node-flow-runtime-service
 import { NodeFlowService } from "../../services/node-flow-service.js";
 import { NodeFlowRecoveryService } from "../../services/node-flows/node-flow-recovery-service.js";
 import { resolveEffectiveDashboardSettings } from "../../services/settings-resolution-service.js";
+import { ApprovalService } from "../../services/node-flows/approval-service.js";
+import { MockSideEffectProvider, OutboxService } from "../../services/node-flows/outbox-service.js";
+import { EgressPolicyService } from "../../services/node-flows/egress-policy-service.js";
+import { AutomationApprovalRepository } from "../../repositories/automation-approval-repository.js";
+import { AutomationOutboxRepository } from "../../repositories/automation-outbox-repository.js";
+import { AutomationWebhookTriggerRepository } from "../../repositories/automation-webhook-trigger-repository.js";
 
 export interface DashboardDependencies {
   credentialBroker: CoreDependencies["credentialBroker"];
@@ -44,6 +50,8 @@ export interface DashboardDependencies {
   speechSynthesisService: SpeechSynthesisService;
   speechModelManager: SpeechModelManager;
   nodeFlowService: CoreDependencies["nodeFlowService"];
+  approvalService: ApprovalService;
+  automationWebhookTriggerRepository: CoreDependencies["automationWebhookTriggerRepository"];
   activityCacheService: ActivityCacheService;
   taskRerunService: TaskRerunService;
   executionControlService: ExecutionControlService;
@@ -222,6 +230,13 @@ export function createDashboardDependencies(
   const speechModelManager = new SpeechModelManager(
     logger.child({ component: "speech-model-manager" }),
   );
+  const approvalRepository = coreDeps.automationApprovalRepository
+    ?? new AutomationApprovalRepository(coreDeps.appDbStorage);
+  const outboxRepository = coreDeps.automationOutboxRepository
+    ?? new AutomationOutboxRepository(coreDeps.appDbStorage);
+  const webhookTriggerRepository = coreDeps.automationWebhookTriggerRepository
+    ?? new AutomationWebhookTriggerRepository(coreDeps.appDbStorage);
+  const approvalService = new ApprovalService(approvalRepository);
   const nodeFlowRuntimeService = new NodeFlowRuntimeService({
     nodeFlowRepository: coreDeps.nodeFlowRepository,
     executionRepository,
@@ -229,6 +244,9 @@ export function createDashboardDependencies(
     settingsRepository,
     providerExecutionService,
     credentialBroker: coreDeps.credentialBroker,
+    egressPolicyService: new EgressPolicyService(),
+    approvalService,
+    outboxService: new OutboxService(outboxRepository, new MockSideEffectProvider()),
     getDashboardSettings: (projectId) => resolveDashboardSettings({ projectId }),
   });
   if (coreDeps.nodeFlowRepository) {
@@ -564,6 +582,8 @@ export function createDashboardDependencies(
     speechSynthesisService,
     speechModelManager,
     nodeFlowService,
+    approvalService,
+    automationWebhookTriggerRepository: webhookTriggerRepository,
     activityCacheService,
     taskRerunService,
     executionControlService,
diff --git a/src/contracts/node-flow-types.ts b/src/contracts/node-flow-types.ts
index cc6471c28b..d675f327d9 100644
--- a/src/contracts/node-flow-types.ts
+++ b/src/contracts/node-flow-types.ts
@@ -217,7 +217,7 @@ export type NodeFlowRunStatus =
   | "queued" | "running" | "approval_waiting" | "retry_waiting"
   | "attention_required" | "succeeded" | "failed" | "cancelled";
 export type NodeFlowNodeRunStatus =
-  | "pending" | "running" | "retry_waiting" | "attention_required"
+  | "pending" | "running" | "approval_waiting" | "retry_waiting" | "attention_required"
   | "succeeded" | "failed" | "skipped" | "cancelled";
 
 export interface NodeFlowRunRecord {
@@ -353,6 +353,8 @@ export interface RunNodeFlowOptions {
   triggerPayload?: NodeFlowJsonObject;
   signal?: AbortSignal;
   versionSelection?: import("./node-flow-execution-policy-types.js").NodeFlowVersionSelection;
+  /** Internal recursion guard propagated only by Execute Subflow. */
+  subflowDepth?: number;
   executorId?: string;
 }
 
diff --git a/src/domain/node-flows/node-definition-registry.ts b/src/domain/node-flows/node-definition-registry.ts
index 498c0fc1d4..f32a23f8d5 100644
--- a/src/domain/node-flows/node-definition-registry.ts
+++ b/src/domain/node-flows/node-definition-registry.ts
@@ -22,6 +22,27 @@ const field = (
   required = false,
 ): NodeWidgetField => ({ id, label, type, required });
 
+const builtin = (input: {
+  type: string; label: string; description: string; category: string;
+  properties?: Record<string, NodeFlowValueSchema>; fields?: NodeWidgetField[];
+  ports?: NodeFlowPort[]; sideEffect?: NodeDefinitionManifest["sideEffect"];
+  capabilities?: string[];
+}): NodeDefinitionManifest => ({
+  type: input.type,
+  version: 1,
+  executable: true,
+  executionKind: "local",
+  configurationSchema: objectSchema([], input.properties),
+  ui: { label: input.label, description: input.description, category: input.category, widgetSchema: { fields: input.fields ?? [] } },
+  ports: input.ports ?? [dataPort("input", "input"), dataPort("output", "output")],
+  credentials: [],
+  capabilities: input.capabilities ?? [],
+  sideEffect: input.sideEffect ?? "none",
+  defaultPolicy: { retry: { maxAttempts: 1, backoffMs: 0 } },
+  documentation: "docs/architecture/node-flow-builtins-and-security.md",
+  deprecation: { deprecated: false },
+});
+
 const manifests: NodeDefinitionManifest[] = [
   {
     type: "input", version: 1, executable: true, executionKind: "local",
@@ -67,6 +88,36 @@ const manifests: NodeDefinitionManifest[] = [
     defaultPolicy: { retry: { maxAttempts: 1, backoffMs: 0 }, timeout: { timeoutMs: 30_000 } }, documentation: "docs/architecture/node-flows.md#runtime",
     deprecation: { deprecated: false },
   },
+  builtin({ type: "condition", label: "Condition", description: "Selects one explicit boolean branch.", category: "control",
+    properties: { path: { type: "string" }, operator: { type: "string" }, value: { type: "any" } },
+    fields: [field("path", "Value path", "text"), field("operator", "Operator", "select")],
+    ports: [dataPort("input", "input"), dataPort("true", "output"), dataPort("false", "output")] }),
+  builtin({ type: "switch", label: "Switch", description: "Selects one named case or the default branch.", category: "control",
+    properties: { path: { type: "string" }, cases: { type: "array", items: { type: "object" } } },
+    fields: [field("path", "Value path", "text"), field("cases", "Cases", "json")],
+    ports: [dataPort("input", "input"), { ...dataPort("case", "output"), cardinality: "many" }, dataPort("default", "output")] }),
+  builtin({ type: "foreach", label: "Foreach", description: "Emits a bounded list for deterministic fan-out.", category: "control",
+    properties: { path: { type: "string" }, maxItems: { type: "number" } }, fields: [field("path", "Items path", "text"), field("maxItems", "Maximum items", "number")],
+    ports: [dataPort("input", "input"), { ...dataPort("items", "output"), schema: { type: "array", items: { type: "any" } } }, dataPort("empty", "output")] }),
+  builtin({ type: "merge", label: "Merge", description: "Combines upstream values with an explicit strategy.", category: "transform",
+    properties: { strategy: { type: "string" } }, fields: [field("strategy", "Strategy", "select")],
+    ports: [{ ...dataPort("input", "input"), cardinality: "many" }, dataPort("output", "output")] }),
+  builtin({ type: "delay", label: "Delay", description: "Waits for a bounded duration with cancellation.", category: "control",
+    properties: { delayMs: { type: "number" } }, fields: [field("delayMs", "Delay (ms)", "number", true)] }),
+  builtin({ type: "approval", label: "Approval", description: "Persists an operator decision gate.", category: "control",
+    properties: { summary: { type: "string" }, logicalItem: { type: "string" } }, fields: [field("summary", "Summary", "textarea")],
+    ports: [dataPort("input", "input"), dataPort("approved", "output"), dataPort("rejected", "output")], sideEffect: "write" }),
+  builtin({ type: "email_draft", label: "Email Draft", description: "Creates an email draft without sending it.", category: "integration",
+    properties: { to: { type: "any" }, subject: { type: "string" }, body: { type: "string" } },
+    fields: [field("to", "To", "text", true), field("subject", "Subject", "text", true), field("body", "Body", "textarea", true)] }),
+  builtin({ type: "email_send", label: "Email Send", description: "Sends an approved email through the idempotent outbox.", category: "integration",
+    properties: { to: { type: "any" }, subject: { type: "string" }, body: { type: "string" }, logicalItem: { type: "string" } },
+    fields: [field("to", "To", "text", true), field("subject", "Subject", "text", true), field("body", "Body", "textarea", true)],
+    sideEffect: "external", capabilities: ["email.send"] }),
+  builtin({ type: "execute_subflow", label: "Execute Subflow", description: "Executes a project-owned published flow.", category: "control",
+    properties: { flowId: { type: "string" }, input: { type: "object" } }, fields: [field("flowId", "Flow ID", "text", true), field("input", "Input", "json")] }),
+  builtin({ type: "webhook_trigger", label: "Webhook Trigger", description: "Emits authenticated webhook input.", category: "trigger",
+    ports: [dataPort("output", "output")], capabilities: ["webhook.receive"] }),
   {
     type: "output", version: 1, executable: true, executionKind: "local",
     configurationSchema: objectSchema(),
diff --git a/src/repositories/automation-approval-repository.ts b/src/repositories/automation-approval-repository.ts
new file mode 100644
index 0000000000..b623b3494d
--- /dev/null
+++ b/src/repositories/automation-approval-repository.ts
@@ -0,0 +1,112 @@
+import { randomUUID } from "node:crypto";
+import { AppDbStorage } from "./app-db-storage.js";
+import type { DatabaseAdapter } from "./db/database-adapter.js";
+import { EntityNotFoundError, ValidationError } from "./repository-utils.js";
+import type { NodeFlowJsonObject } from "../contracts/node-flow-types.js";
+
+export type AutomationApprovalStatus = "pending" | "approved" | "rejected" | "expired";
+
+export interface AutomationApprovalRecord {
+  id: string;
+  projectId: string;
+  flowId: string;
+  runId: string;
+  nodeId: string;
+  logicalItem: string;
+  status: AutomationApprovalStatus;
+  request: NodeFlowJsonObject;
+  decision: NodeFlowJsonObject | null;
+  requestedAt: string;
+  decidedAt: string | null;
+  decidedBy: string | null;
+  expiresAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface ApprovalRow {
+  id: string; project_id: string; flow_id: string; run_id: string; node_id: string;
+  logical_item: string; status: AutomationApprovalStatus; request_json: string;
+  decision_json: string | null; requested_at: string; decided_at: string | null;
+  decided_by: string | null; expires_at: string | null; created_at: string; updated_at: string;
+}
+
+export class AutomationApprovalRepository {
+  private readonly db: DatabaseAdapter;
+
+  constructor(storage: AppDbStorage = new AppDbStorage()) {
+    this.db = storage.getDatabase();
+  }
+
+  request(input: {
+    projectId: string; flowId: string; runId: string; nodeId: string;
+    logicalItem: string; request: NodeFlowJsonObject; expiresAt?: string | null;
+  }): AutomationApprovalRecord {
+    const logicalItem = input.logicalItem.trim() || "default";
+    const existing = this.getForItem(input.runId, input.nodeId, logicalItem);
+    if (existing) return existing;
+    const id = randomUUID();
+    const now = new Date().toISOString();
+    this.db.prepare(`INSERT INTO automation_approvals
+      (id, project_id, flow_id, run_id, node_id, logical_item, status, request_json,
+       requested_at, expires_at, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, 'pending', ?, ?, ?, ?, ?)`)
+      .run(id, input.projectId, input.flowId, input.runId, input.nodeId, logicalItem,
+        JSON.stringify(input.request), now, input.expiresAt ?? null, now, now);
+    return this.require(id);
+  }
+
+  get(id: string): AutomationApprovalRecord | null {
+    const row = this.db.prepare("SELECT * FROM automation_approvals WHERE id = ?").get(id) as ApprovalRow | undefined;
+    return row ? this.map(row) : null;
+  }
+
+  getForItem(runId: string, nodeId: string, logicalItem = "default"): AutomationApprovalRecord | null {
+    const row = this.db.prepare("SELECT * FROM automation_approvals WHERE run_id = ? AND node_id = ? AND logical_item = ?")
+      .get(runId, nodeId, logicalItem) as ApprovalRow | undefined;
+    return row ? this.map(row) : null;
+  }
+
+  listForRun(runId: string): AutomationApprovalRecord[] {
+    return (this.db.prepare("SELECT * FROM automation_approvals WHERE run_id = ? ORDER BY created_at").all(runId) as ApprovalRow[])
+      .map((row) => this.map(row));
+  }
+
+  decide(id: string, input: { status: "approved" | "rejected"; decidedBy: string; decision?: NodeFlowJsonObject }): AutomationApprovalRecord {
+    const current = this.require(id);
+    if (current.status !== "pending") {
+      if (current.status === input.status) return current;
+      throw new ValidationError(`Approval ${id} has already been decided.`);
+    }
+    const decidedBy = input.decidedBy.trim();
+    if (!decidedBy) throw new ValidationError("decidedBy is required.");
+    const now = new Date().toISOString();
+    this.db.prepare(`UPDATE automation_approvals SET status = ?, decision_json = ?, decided_at = ?,
+      decided_by = ?, updated_at = ? WHERE id = ? AND status = 'pending'`)
+      .run(input.status, JSON.stringify(input.decision ?? {}), now, decidedBy, now, id);
+    return this.require(id);
+  }
+
+  expireDue(now = new Date()): number {
+    return this.db.prepare(`UPDATE automation_approvals SET status = 'expired', updated_at = ?
+      WHERE status = 'pending' AND expires_at IS NOT NULL AND expires_at <= ?`)
+      .run(now.toISOString(), now.toISOString()).changes;
+  }
+
+  private require(id: string): AutomationApprovalRecord {
+    const record = this.get(id);
+    if (!record) throw new EntityNotFoundError(`Automation approval not found: ${id}`);
+    return record;
+  }
+
+  private map(row: ApprovalRow): AutomationApprovalRecord {
+    return {
+      id: row.id, projectId: row.project_id, flowId: row.flow_id, runId: row.run_id,
+      nodeId: row.node_id, logicalItem: row.logical_item, status: row.status,
+      request: JSON.parse(row.request_json) as NodeFlowJsonObject,
+      decision: row.decision_json ? JSON.parse(row.decision_json) as NodeFlowJsonObject : null,
+      requestedAt: row.requested_at, decidedAt: row.decided_at, decidedBy: row.decided_by,
+      expiresAt: row.expires_at, createdAt: row.created_at, updatedAt: row.updated_at,
+    };
+  }
+}
diff --git a/src/repositories/automation-outbox-repository.ts b/src/repositories/automation-outbox-repository.ts
new file mode 100644
index 0000000000..686b69e3ff
--- /dev/null
+++ b/src/repositories/automation-outbox-repository.ts
@@ -0,0 +1,83 @@
+import { createHash, randomUUID } from "node:crypto";
+import { AppDbStorage } from "./app-db-storage.js";
+import type { DatabaseAdapter } from "./db/database-adapter.js";
+import type { NodeFlowJsonObject } from "../contracts/node-flow-types.js";
+
+export type AutomationOutboxStatus = "pending" | "sending" | "sent" | "failed" | "attention_required";
+export interface AutomationOutboxRecord {
+  id: string; idempotencyKey: string; projectId: string; flowId: string; publicationId: string;
+  runId: string; nodeId: string; logicalItem: string; effectType: string; status: AutomationOutboxStatus;
+  payload: NodeFlowJsonObject; providerMessageId: string | null; attemptCount: number;
+  lastError: string | null; createdAt: string; updatedAt: string; sentAt: string | null;
+}
+interface OutboxRow {
+  id: string; idempotency_key: string; project_id: string; flow_id: string; publication_id: string;
+  run_id: string; node_id: string; logical_item: string; effect_type: string; status: AutomationOutboxStatus;
+  payload_json: string; provider_message_id: string | null; attempt_count: number;
+  last_error: string | null; created_at: string; updated_at: string; sent_at: string | null;
+}
+
+export function deriveOutboxIdempotencyKey(input: { publicationId: string; runId: string; nodeId: string; logicalItem: string }): string {
+  return createHash("sha256").update([input.publicationId, input.runId, input.nodeId, input.logicalItem].join("\0")).digest("hex");
+}
+
+export class AutomationOutboxRepository {
+  private readonly db: DatabaseAdapter;
+  constructor(storage: AppDbStorage = new AppDbStorage()) { this.db = storage.getDatabase(); }
+
+  enqueue(input: Omit<AutomationOutboxRecord, "id" | "idempotencyKey" | "status" | "providerMessageId" | "attemptCount" | "lastError" | "createdAt" | "updatedAt" | "sentAt">): AutomationOutboxRecord {
+    const idempotencyKey = deriveOutboxIdempotencyKey(input);
+    const existing = this.getByKey(idempotencyKey);
+    if (existing) return existing;
+    const id = randomUUID(); const now = new Date().toISOString();
+    this.db.prepare(`INSERT INTO automation_outbox
+      (id, idempotency_key, project_id, flow_id, publication_id, run_id, node_id, logical_item,
+       effect_type, status, payload_json, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?, ?, ?)`)
+      .run(id, idempotencyKey, input.projectId, input.flowId, input.publicationId, input.runId,
+        input.nodeId, input.logicalItem, input.effectType, JSON.stringify(input.payload), now, now);
+    return this.getByKey(idempotencyKey)!;
+  }
+
+  get(id: string): AutomationOutboxRecord | null {
+    const row = this.db.prepare("SELECT * FROM automation_outbox WHERE id = ?").get(id) as OutboxRow | undefined;
+    return row ? this.map(row) : null;
+  }
+  getByKey(key: string): AutomationOutboxRecord | null {
+    const row = this.db.prepare("SELECT * FROM automation_outbox WHERE idempotency_key = ?").get(key) as OutboxRow | undefined;
+    return row ? this.map(row) : null;
+  }
+  listForRun(runId: string): AutomationOutboxRecord[] {
+    return (this.db.prepare("SELECT * FROM automation_outbox WHERE run_id = ? ORDER BY created_at").all(runId) as OutboxRow[]).map((row) => this.map(row));
+  }
+  claim(id: string): AutomationOutboxRecord | null {
+    const now = new Date().toISOString();
+    const result = this.db.prepare(`UPDATE automation_outbox SET status = 'sending', attempt_count = attempt_count + 1,
+      updated_at = ? WHERE id = ? AND status IN ('pending', 'failed')`).run(now, id);
+    return result.changes > 0 ? this.get(id) : null;
+  }
+  markSent(id: string, providerMessageId: string): AutomationOutboxRecord {
+    const now = new Date().toISOString();
+    this.db.prepare(`UPDATE automation_outbox SET status = 'sent', provider_message_id = ?, last_error = NULL,
+      sent_at = ?, updated_at = ? WHERE id = ?`).run(providerMessageId, now, now, id);
+    return this.get(id)!;
+  }
+  markFailed(id: string, error: string, unknownOutcome = false): AutomationOutboxRecord {
+    this.db.prepare("UPDATE automation_outbox SET status = ?, last_error = ?, updated_at = ? WHERE id = ?")
+      .run(unknownOutcome ? "attention_required" : "failed", error, new Date().toISOString(), id);
+    return this.get(id)!;
+  }
+  recoverSending(): number {
+    return this.db.prepare(`UPDATE automation_outbox SET status = 'attention_required',
+      last_error = COALESCE(last_error, 'Process restarted while provider outcome was unknown.'), updated_at = ?
+      WHERE status = 'sending'`).run(new Date().toISOString()).changes;
+  }
+  private map(row: OutboxRow): AutomationOutboxRecord {
+    return { id: row.id, idempotencyKey: row.idempotency_key, projectId: row.project_id,
+      flowId: row.flow_id, publicationId: row.publication_id, runId: row.run_id, nodeId: row.node_id,
+      logicalItem: row.logical_item, effectType: row.effect_type, status: row.status,
+      payload: JSON.parse(row.payload_json) as NodeFlowJsonObject, providerMessageId: row.provider_message_id,
+      attemptCount: Number(row.attempt_count), lastError: row.last_error, createdAt: row.created_at,
+      updatedAt: row.updated_at, sentAt: row.sent_at };
+  }
+}
diff --git a/src/repositories/automation-webhook-trigger-repository.ts b/src/repositories/automation-webhook-trigger-repository.ts
new file mode 100644
index 0000000000..4ecc801405
--- /dev/null
+++ b/src/repositories/automation-webhook-trigger-repository.ts
@@ -0,0 +1,51 @@
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { AppDbStorage } from "./app-db-storage.js";
+import type { DatabaseAdapter } from "./db/database-adapter.js";
+import { EntityNotFoundError, ValidationError } from "./repository-utils.js";
+
+export interface AutomationWebhookTriggerRecord {
+  id: string; projectId: string; flowId: string; enabled: boolean;
+  createdAt: string; updatedAt: string; lastTriggeredAt: string | null;
+}
+interface WebhookRow { id: string; project_id: string; flow_id: string; path_token_hash: string; secret_hash: string; enabled: number; created_at: string; updated_at: string; last_triggered_at: string | null }
+const digest = (value: string): string => createHash("sha256").update(value).digest("hex");
+
+export class AutomationWebhookTriggerRepository {
+  private readonly db: DatabaseAdapter;
+  constructor(storage: AppDbStorage = new AppDbStorage()) { this.db = storage.getDatabase(); }
+  create(projectId: string, flowId: string): { trigger: AutomationWebhookTriggerRecord; pathToken: string; secret: string } {
+    const flow = this.db.prepare("SELECT project_id FROM node_flows WHERE id = ?").get(flowId) as { project_id: string } | undefined;
+    if (!flow) throw new EntityNotFoundError(`Node flow not found: ${flowId}`);
+    if (flow.project_id !== projectId) throw new ValidationError("Node flow does not belong to the requested project.");
+    const pathToken = randomBytes(24).toString("base64url"); const secret = randomBytes(32).toString("base64url");
+    const id = randomUUID(); const now = new Date().toISOString();
+    this.db.prepare(`INSERT INTO automation_webhook_triggers
+      (id, project_id, flow_id, path_token_hash, secret_hash, enabled, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, 1, ?, ?)
+      ON CONFLICT(project_id, flow_id) DO UPDATE SET path_token_hash=excluded.path_token_hash,
+      secret_hash=excluded.secret_hash, enabled=1, updated_at=excluded.updated_at`)
+      .run(id, projectId, flowId, digest(pathToken), digest(secret), now, now);
+    return { trigger: this.getByFlow(flowId)!, pathToken, secret };
+  }
+  getByFlow(flowId: string): AutomationWebhookTriggerRecord | null {
+    const row = this.db.prepare("SELECT * FROM automation_webhook_triggers WHERE flow_id = ?").get(flowId) as WebhookRow | undefined;
+    return row ? this.map(row) : null;
+  }
+  authenticate(pathToken: string, secret: string): AutomationWebhookTriggerRecord | null {
+    const row = this.db.prepare("SELECT * FROM automation_webhook_triggers WHERE path_token_hash = ? AND enabled = 1")
+      .get(digest(pathToken)) as WebhookRow | undefined;
+    if (!row) return null;
+    const expected = Buffer.from(row.secret_hash, "hex"); const actual = Buffer.from(digest(secret), "hex");
+    if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) return null;
+    this.db.prepare("UPDATE automation_webhook_triggers SET last_triggered_at = ?, updated_at = ? WHERE id = ?")
+      .run(new Date().toISOString(), new Date().toISOString(), row.id);
+    return this.map(row);
+  }
+  setEnabled(flowId: string, enabled: boolean): AutomationWebhookTriggerRecord {
+    this.db.prepare("UPDATE automation_webhook_triggers SET enabled = ?, updated_at = ? WHERE flow_id = ?")
+      .run(enabled ? 1 : 0, new Date().toISOString(), flowId);
+    const record = this.getByFlow(flowId); if (!record) throw new EntityNotFoundError(`Webhook trigger not found for flow: ${flowId}`);
+    return record;
+  }
+  private map(row: WebhookRow): AutomationWebhookTriggerRecord { return { id: row.id, projectId: row.project_id, flowId: row.flow_id, enabled: Boolean(row.enabled), createdAt: row.created_at, updatedAt: row.updated_at, lastTriggeredAt: row.last_triggered_at }; }
+}
diff --git a/src/repositories/db/app-db-migrations.ts b/src/repositories/db/app-db-migrations.ts
index d54064de0e..3206e63557 100644
--- a/src/repositories/db/app-db-migrations.ts
+++ b/src/repositories/db/app-db-migrations.ts
@@ -319,6 +319,76 @@ export function ensureNodeFlowTables(db: DatabaseAdapter): void {
   ensureIndex(db, "idx_node_flow_attempts_run_node", "node_flow_node_attempts", "run_id, node_id, attempt_number");
 }
 
+export function ensureAutomationGovernanceTables(db: DatabaseAdapter): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS automation_approvals (
+      id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL,
+      flow_id TEXT NOT NULL,
+      run_id TEXT NOT NULL,
+      node_id TEXT NOT NULL,
+      logical_item TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'pending',
+      request_json TEXT NOT NULL DEFAULT '{}',
+      decision_json TEXT,
+      requested_at TEXT NOT NULL,
+      decided_at TEXT,
+      decided_by TEXT,
+      expires_at TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,
+      FOREIGN KEY (flow_id) REFERENCES node_flows(id) ON DELETE CASCADE,
+      FOREIGN KEY (run_id) REFERENCES node_flow_runs(id) ON DELETE CASCADE,
+      UNIQUE (run_id, node_id, logical_item)
+    )
+  `);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS automation_outbox (
+      id TEXT PRIMARY KEY,
+      idempotency_key TEXT NOT NULL UNIQUE,
+      project_id TEXT NOT NULL,
+      flow_id TEXT NOT NULL,
+      publication_id TEXT NOT NULL,
+      run_id TEXT NOT NULL,
+      node_id TEXT NOT NULL,
+      logical_item TEXT NOT NULL,
+      effect_type TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'pending',
+      payload_json TEXT NOT NULL,
+      provider_message_id TEXT,
+      attempt_count INTEGER NOT NULL DEFAULT 0,
+      last_error TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      sent_at TEXT,
+      FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,
+      FOREIGN KEY (flow_id) REFERENCES node_flows(id) ON DELETE CASCADE,
+      FOREIGN KEY (run_id) REFERENCES node_flow_runs(id) ON DELETE CASCADE
+    )
+  `);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS automation_webhook_triggers (
+      id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL,
+      flow_id TEXT NOT NULL,
+      path_token_hash TEXT NOT NULL UNIQUE,
+      secret_hash TEXT NOT NULL,
+      enabled INTEGER NOT NULL DEFAULT 1,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      last_triggered_at TEXT,
+      FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,
+      FOREIGN KEY (flow_id) REFERENCES node_flows(id) ON DELETE CASCADE,
+      UNIQUE (project_id, flow_id)
+    )
+  `);
+  ensureIndex(db, "idx_automation_approvals_run_status", "automation_approvals", "run_id, status, created_at");
+  ensureIndex(db, "idx_automation_outbox_status", "automation_outbox", "status, updated_at");
+  ensureIndex(db, "idx_automation_outbox_run", "automation_outbox", "run_id, node_id");
+  ensureIndex(db, "idx_automation_webhooks_flow", "automation_webhook_triggers", "flow_id, enabled");
+}
+
 interface LegacyNodeFlowRow {
   id: string;
   project_id: string;
@@ -759,6 +829,7 @@ export function runMigrations(db: DatabaseAdapter): void {
   ensureTaskSelfReflectionRatingTables(db);
   ensureConversationDraftTables(db);
   ensureNodeFlowTables(db);
+  ensureAutomationGovernanceTables(db);
   migratePersistedNodeFlowGraphs(db);
   ensureCustomDashboardTables(db);
   ensureAutomationCredentialTables(db);
diff --git a/src/server/dashboard-route-registration.ts b/src/server/dashboard-route-registration.ts
index 196a19bd7f..aea5368746 100644
--- a/src/server/dashboard-route-registration.ts
+++ b/src/server/dashboard-route-registration.ts
@@ -34,6 +34,7 @@ import { registerChatProviderRoutes } from "./chat-provider-routes.js";
 import { registerChatProviderIngressRoutes } from "./chat-provider-ingress-routes.js";
 import { registerSpeechRoutes } from "./speech-routes.js";
 import { registerNodeFlowRoutes } from "./node-flow-routes.js";
+import { registerNodeFlowWebhookRoutes } from "./node-flow-webhook-routes.js";
 import { registerCustomDashboardRoutes } from "./custom-dashboard-routes.js";
 
 export interface DashboardRouteRegistrationOptions {
@@ -121,6 +122,7 @@ const registerProjectConfigurationRouteGroup = (app: Express, deps: DashboardDep
   registerAgentPresetRoutes(app, deps);
   registerInstructionFileRoutes(app, deps);
   registerNodeFlowRoutes(app, deps);
+  registerNodeFlowWebhookRoutes(app, deps);
   registerCustomDashboardRoutes(app, deps);
 };
 
diff --git a/src/server/dashboard-server.ts b/src/server/dashboard-server.ts
index 2be9edfc1c..720b41f26b 100644
--- a/src/server/dashboard-server.ts
+++ b/src/server/dashboard-server.ts
@@ -142,6 +142,8 @@ import type { CustomDashboardRepository } from "../repositories/custom-dashboard
 import type { CustomDashboardValidationService } from "../services/custom-dashboard-validation-service.js";
 import type { SkillService } from "../services/skill-service.js";
 import type { CredentialBroker } from "../services/credentials/credential-broker.js";
+import type { ApprovalService } from "../services/node-flows/approval-service.js";
+import type { AutomationWebhookTriggerRepository } from "../repositories/automation-webhook-trigger-repository.js";
 import type { ManagedRuntimeService } from "../services/managed-runtime-service.js";
 import type { ProviderToolManager } from "../services/provider-tool-manager.js";
 import {
@@ -187,6 +189,8 @@ export interface DashboardServerOptions {
   speechSynthesisService?: SpeechSynthesisService;
   speechModelManager?: SpeechModelManager;
   nodeFlowService?: NodeFlowService;
+  approvalService?: ApprovalService;
+  automationWebhookTriggerRepository?: AutomationWebhookTriggerRepository;
   customDashboardRepository?: CustomDashboardRepository;
   customDashboardValidationService?: CustomDashboardValidationService;
   skillService?: SkillService;
diff --git a/src/server/node-flow-routes.ts b/src/server/node-flow-routes.ts
index a608686dd4..4032685d0b 100644
--- a/src/server/node-flow-routes.ts
+++ b/src/server/node-flow-routes.ts
@@ -128,4 +128,33 @@ export function registerNodeFlowRoutes(app: Express, deps: DashboardDependencies
   app.get("/api/node-flow-runs/:runId/attempts", syncRoute((req, res) => {
     res.json(requireNodeFlowService(deps).listNodeAttempts(requireTrimmedString(req.params.runId, "runId")));
   }));
+
+  app.get("/api/node-flow-runs/:runId/approvals", syncRoute((req, res) => {
+    if (!deps.approvalService) throw new HttpRouteError(404, "Approval service is not enabled.");
+    res.json({ approvals: deps.approvalService.listForRun(requireTrimmedString(req.params.runId, "runId")) });
+  }));
+
+  app.post("/api/automation-approvals/:approvalId/decision", syncRoute((req, res) => {
+    if (!deps.approvalService) throw new HttpRouteError(404, "Approval service is not enabled.");
+    const body = req.body as { decision?: string; decidedBy?: string; metadata?: NodeFlowJsonObject };
+    const approvalId = requireTrimmedString(req.params.approvalId, "approvalId");
+    const decidedBy = requireTrimmedString(body.decidedBy, "decidedBy");
+    if (body.decision === "approve") res.json(deps.approvalService.approve(approvalId, decidedBy, body.metadata));
+    else if (body.decision === "reject") res.json(deps.approvalService.reject(approvalId, decidedBy, body.metadata));
+    else throw new HttpRouteError(400, "decision must be approve or reject.");
+  }));
+
+  app.get("/api/node-flows/:flowId/webhook", syncRoute((req, res) => {
+    if (!deps.automationWebhookTriggerRepository) throw new HttpRouteError(404, "Webhook triggers are not enabled.");
+    res.json(deps.automationWebhookTriggerRepository.getByFlow(requireTrimmedString(req.params.flowId, "flowId")));
+  }));
+
+  app.post("/api/node-flows/:flowId/webhook", syncRoute((req, res) => {
+    if (!deps.automationWebhookTriggerRepository) throw new HttpRouteError(404, "Webhook triggers are not enabled.");
+    const flowId = requireTrimmedString(req.params.flowId, "flowId");
+    const flow = requireNodeFlowService(deps).get(flowId);
+    if (!flow) throw new HttpRouteError(404, `Node flow not found: ${flowId}`);
+    const configured = deps.automationWebhookTriggerRepository.create(flow.projectId, flow.id);
+    res.status(201).json({ ...configured.trigger, pathToken: configured.pathToken, secret: configured.secret });
+  }));
 }
diff --git a/src/server/node-flow-webhook-routes.ts b/src/server/node-flow-webhook-routes.ts
new file mode 100644
index 0000000000..7795ed7b9d
--- /dev/null
+++ b/src/server/node-flow-webhook-routes.ts
@@ -0,0 +1,26 @@
+import type { Express } from "express";
+import type { DashboardDependencies } from "./dashboard-server.js";
+import { asyncRoute } from "./route-utils.js";
+import { HttpRouteError } from "./http-errors.js";
+import { requireTrimmedString } from "./request-parsers.js";
+import type { NodeFlowJsonObject } from "../contracts/node-flow-types.js";
+
+export function registerNodeFlowWebhookRoutes(app: Express, deps: DashboardDependencies): void {
+  if (!deps.automationWebhookTriggerRepository || !deps.nodeFlowService) return;
+  app.post("/api/webhooks/node-flows/:pathToken", asyncRoute(async (req, res) => {
+    const secretHeader = req.headers["x-codeux-webhook-secret"];
+    const secret = Array.isArray(secretHeader) ? secretHeader[0] : secretHeader;
+    if (typeof secret !== "string" || !secret.trim()) throw new HttpRouteError(401, "Webhook authentication failed.");
+    const trigger = deps.automationWebhookTriggerRepository!.authenticate(
+      requireTrimmedString(req.params.pathToken, "pathToken"),
+      secret.trim(),
+    );
+    if (!trigger) throw new HttpRouteError(401, "Webhook authentication failed.");
+    const payload = req.body && typeof req.body === "object" && !Array.isArray(req.body)
+      ? req.body as NodeFlowJsonObject : {};
+    const result = await deps.nodeFlowService!.runFlow(trigger.projectId, trigger.flowId, payload, {
+      triggerType: "webhook", triggerPayload: payload, versionSelection: { mode: "latest_published" },
+    });
+    res.status(202).json({ runId: result.run.id, status: result.run.status });
+  }));
+}
diff --git a/src/services/node-flow-runtime-service.ts b/src/services/node-flow-runtime-service.ts
index 57a8f95138..a3f662e047 100644
--- a/src/services/node-flow-runtime-service.ts
+++ b/src/services/node-flow-runtime-service.ts
@@ -15,6 +15,11 @@ import { NodeFlowPublicationService } from "./node-flows/node-flow-publication-s
 import { NodeFlowQueueService } from "./node-flows/node-flow-queue-service.js";
 import { NodeFlowAttemptService } from "./node-flows/node-flow-attempt-service.js";
 import { NodeFlowLeaseService } from "./node-flows/node-flow-lease-service.js";
+import { EgressPolicyService } from "./node-flows/egress-policy-service.js";
+import { BuiltinExecutors } from "./node-flows/builtins/builtin-executors.js";
+import type { ApprovalService } from "./node-flows/approval-service.js";
+import { ApprovalRequiredError } from "./node-flows/approval-service.js";
+import type { OutboxService } from "./node-flows/outbox-service.js";
 import type { NodeFlowFailureClassification } from "../contracts/node-flow-execution-policy-types.js";
 import { buildProviderInvocationWorkspaceOptions } from "../infrastructure/providers/cli/invocation-workspace-preparer.js";
 import type {
@@ -47,6 +52,9 @@ interface NodeFlowRuntimeDeps {
   providerExecutionService?: ProviderExecutionService;
   getDashboardSettings?: (projectId: string) => DashboardSettings;
   credentialBroker?: CredentialBroker;
+  egressPolicyService?: EgressPolicyService;
+  approvalService?: ApprovalService;
+  outboxService?: OutboxService;
 }
 
 interface RuntimeContext {
@@ -57,20 +65,40 @@ interface RuntimeContext {
   order: string[];
   input: NodeFlowJsonObject;
   outputs: Map<string, NodeFlowJsonObject>;
+  selectedPorts: Map<string, Set<string>>;
   predecessors: Map<string, string[]>;
   descendants: Map<string, Set<string>>;
   options: RunNodeFlowOptions;
   executorId: string;
   currentAttemptId?: string;
+  publicationId: string;
+  subflowDepth: number;
 }
 
 interface NodeExecutionResult {
   output: NodeFlowJsonObject;
   invocationId?: string | null;
+  selectedPorts?: string[];
 }
 
 export class NodeFlowRuntimeService {
-  constructor(private readonly deps: NodeFlowRuntimeDeps) {}
+  private readonly egressPolicyService: EgressPolicyService;
+  private readonly builtins: BuiltinExecutors;
+
+  constructor(private readonly deps: NodeFlowRuntimeDeps) {
+    this.egressPolicyService = deps.egressPolicyService ?? new EgressPolicyService();
+    this.builtins = new BuiltinExecutors({
+      approvalService: deps.approvalService,
+      outboxService: deps.outboxService,
+      executeSubflow: async ({ projectId, flowId, input, depth, signal }) => {
+        const summary = await this.runFlow(projectId, flowId, input, { signal, subflowDepth: depth, triggerType: "subflow" });
+        if (summary.run.status !== "succeeded") {
+          throw new Error(summary.run.errorMessage ?? `Subflow ${flowId} ended with status ${summary.run.status}.`);
+        }
+        return summary.output ?? {};
+      },
+    });
+  }
 
   async runFlow(
     projectId: string,
@@ -138,10 +166,13 @@ export class NodeFlowRuntimeService {
       order: executionOrder,
       input,
       outputs: new Map(),
+      selectedPorts: new Map(),
       predecessors: buildPredecessors(graph),
       descendants: buildDescendants(graph),
       options,
       executorId,
+      publicationId: publication.id,
+      subflowDepth: options.subflowDepth ?? 0,
     };
 
     const blockedNodes = new Set<string>();
@@ -170,6 +201,10 @@ export class NodeFlowRuntimeService {
         await this.persistSkippedNode(context, node, "skipped", "Skipped because an upstream node failed.");
         continue;
       }
+      if (this.isInactiveBranch(context, node.id)) {
+        await this.persistSkippedNode(context, node, "skipped", "Skipped because its incoming branch was not selected.");
+        continue;
+      }
       if (node.disabled) {
         await this.persistSkippedNode(context, node, "skipped", "Skipped because the node is disabled.");
         continue;
@@ -206,6 +241,7 @@ export class NodeFlowRuntimeService {
         try {
         const result = await this.executeNode(context, node, nodeRun);
         context.outputs.set(node.id, result.output);
+        if (result.selectedPorts) context.selectedPorts.set(node.id, new Set(result.selectedPorts));
         attemptService.succeed(attempt, maskSecrets(result.output), result.invocationId);
         this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, {
           status: "succeeded",
@@ -219,6 +255,15 @@ export class NodeFlowRuntimeService {
         clearTimeout(timeout); options.signal?.removeEventListener("abort", parentAbort); context.options = previousOptions;
         const message = error instanceof Error ? error.message : String(error);
         const classification = classifyFailure(error, options.signal?.aborted === true, timeoutController.signal.aborted);
+        if (error instanceof ApprovalRequiredError) {
+          attemptService.fail(attempt, "permanent", message, false);
+          this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, {
+            status: "approval_waiting", errorMessage: message, finishedAt: null,
+          });
+          terminalStatus = "approval_waiting";
+          terminalError = message;
+          break;
+        }
         const wasCancelled = classification === "cancelled";
         const retryable = retryPolicy.retryableClasses.includes(classification) && attemptNumber < retryPolicy.maxAttempts;
         attemptService.fail(attempt, classification, message, retryable, this.deps.nodeFlowRepository.listNodeAttempts(run.id).find((candidate) => candidate.id === attempt.id)?.invocationId);
@@ -261,13 +306,13 @@ export class NodeFlowRuntimeService {
         break;
       }
       }
-      if (terminalStatus === "cancelled" || terminalStatus === "attention_required") {
+      if (terminalStatus === "cancelled" || terminalStatus === "attention_required" || terminalStatus === "approval_waiting") {
         break;
       }
     }
 
     const output = this.buildFlowOutput(context);
-    const finishedAt = new Date().toISOString();
+    const finishedAt = terminalStatus === "approval_waiting" ? null : new Date().toISOString();
     const updatedRun = this.deps.nodeFlowRepository.updateRun(run.id, {
       status: terminalStatus,
       output: maskSecrets(output),
@@ -277,8 +322,8 @@ export class NodeFlowRuntimeService {
       leaseExpiresAt: null,
     });
     this.deps.executionRepository.updateExecutionInvocation(parentInvocation.id, {
-      status: terminalStatus === "succeeded" ? "completed" : terminalStatus === "attention_required" ? "failed" : terminalStatus,
-      errorMessage: terminalError,
+      status: terminalStatus === "succeeded" ? "completed" : terminalStatus === "attention_required" ? "failed" : terminalStatus === "approval_waiting" ? "running" : terminalStatus,
+      errorMessage: terminalStatus === "approval_waiting" ? null : terminalError,
       finishedAt,
     });
     this.deps.executionRepository.appendExecutionInvocationMessage(parentInvocation.id, {
@@ -364,7 +409,13 @@ export class NodeFlowRuntimeService {
       case "output":
         return { output: this.executeOutputNode(context, node) };
       default:
-        throw new ValidationError(`Unsupported node flow node type: ${node.type}.`);
+        return this.builtins.execute(node.type, {
+          projectId: context.projectId, flowId: context.flowId, publicationId: context.publicationId,
+          runId: context.runId, nodeId: node.id,
+          config: evaluateTemplates(readNodeConfig(node), context) as NodeFlowJsonObject,
+          upstream: this.buildUpstreamObject(context, node.id), flowInput: context.input,
+          signal: context.options.signal, subflowDepth: context.subflowDepth,
+        });
     }
   }
 
@@ -518,7 +569,7 @@ export class NodeFlowRuntimeService {
     }
     const headers = normalizeHeaders(readJsonObject(config.headers));
     const boundCredential = await this.resolveNodeCredential(context, node, "auth");
-    if (boundCredential) headers.Authorization = boundCredential;
+    const credentialHeaders = boundCredential ? { authorization: boundCredential } : undefined;
     const timeoutMs = normalizeTimeout(config.timeout ?? config.timeoutMs);
     const controller = new AbortController();
     const abortListener = (): void => controller.abort(context.options.signal?.reason);
@@ -530,18 +581,31 @@ export class NodeFlowRuntimeService {
       metadata: { flowId: context.flowId, runId: context.runId, nodeId: node.id },
     });
     try {
-      const response = await fetch(url, {
+      const response = await this.egressPolicyService.request({
+        url,
         method,
         headers,
+        credentialHeaders,
         body: buildHttpBody(method, headers, config.body),
         signal: controller.signal,
+        rateLimitKey: `${context.projectId}:${url.hostname}`,
+        policy: {
+          allowHttp: config.allowHttp === true,
+          allowedHosts: readStringArray(config.allowedHosts),
+          allowedPorts: readNumberArray(config.allowedPorts),
+          maxRedirects: readOptionalNumber(config.maxRedirects),
+          maxResponseBytes: readOptionalNumber(config.maxResponseBytes),
+          allowedContentTypes: readStringArray(config.allowedContentTypes),
+          timeoutMs,
+          maxRetries: readOptionalNumber(config.maxRetries),
+          requestsPerMinute: readOptionalNumber(config.requestsPerMinute),
+        },
       });
-      const contentType = response.headers.get("content-type") ?? "";
-      const body = contentType.includes("application/json")
-        ? await response.json() as NodeFlowJsonValue
-        : await response.text();
+      const body = response.contentType.includes("application/json")
+        ? response.json() as NodeFlowJsonValue
+        : response.text();
       if (!response.ok) {
-        throw new Error(`HTTP node ${node.id} failed with ${response.status} ${response.statusText}.`);
+        throw new Error(`HTTP node ${node.id} failed with status ${response.status}.`);
       }
       const responsePath = readString(config.responsePath) ?? readString(config.extractJsonPath);
       const extracted = responsePath ? readPath(body, responsePath) : body;
@@ -597,6 +661,21 @@ export class NodeFlowRuntimeService {
     };
   }
 
+  private buildUpstreamObject(context: RuntimeContext, nodeId: string): NodeFlowJsonObject {
+    return Object.fromEntries((context.predecessors.get(nodeId) ?? [])
+      .filter((id) => context.outputs.has(id)).map((id) => [id, context.outputs.get(id) ?? {}]));
+  }
+
+  private isInactiveBranch(context: RuntimeContext, nodeId: string): boolean {
+    const incoming = context.graph.edges.filter((edge) => edge.toNodeId === nodeId);
+    if (incoming.length === 0) return false;
+    return !incoming.some((edge) => {
+      if (!context.outputs.has(edge.fromNodeId)) return false;
+      const selected = context.selectedPorts.get(edge.fromNodeId);
+      return !selected || !edge.fromHandle || selected.has(edge.fromHandle);
+    });
+  }
+
   private firstUpstreamObject(context: RuntimeContext, nodeId: string): NodeFlowJsonObject {
     const predecessorIds = context.predecessors.get(nodeId) ?? [];
     if (predecessorIds.length === 1) {
@@ -762,6 +841,22 @@ function readBoolean(value: unknown): boolean {
   return value === true;
 }
 
+function readStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  return value.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0).map((entry) => entry.trim());
+}
+
+function readNumberArray(value: unknown): number[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const values = value.map(Number).filter((entry) => Number.isInteger(entry) && entry > 0 && entry <= 65_535);
+  return values.length > 0 ? values : undefined;
+}
+
+function readOptionalNumber(value: unknown): number | undefined {
+  const parsed = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
 function toJsonValue(value: unknown): NodeFlowJsonValue {
   if (value === undefined) {
     return null;
diff --git a/src/services/node-flows/approval-service.ts b/src/services/node-flows/approval-service.ts
new file mode 100644
index 0000000000..4391688f35
--- /dev/null
+++ b/src/services/node-flows/approval-service.ts
@@ -0,0 +1,37 @@
+import { ValidationError } from "../../repositories/repository-utils.js";
+import { AutomationApprovalRepository, type AutomationApprovalRecord } from "../../repositories/automation-approval-repository.js";
+import type { NodeFlowJsonObject } from "../../contracts/node-flow-types.js";
+
+export class ApprovalRequiredError extends Error {
+  constructor(public readonly approval: AutomationApprovalRecord) {
+    super(`Approval is required: ${approval.id}`);
+    this.name = "ApprovalRequiredError";
+  }
+}
+
+export class ApprovalService {
+  constructor(private readonly repository: AutomationApprovalRepository) {}
+
+  requireApproval(input: {
+    projectId: string; flowId: string; runId: string; nodeId: string;
+    logicalItem?: string; request: NodeFlowJsonObject; expiresAt?: string | null;
+  }): AutomationApprovalRecord {
+    const logicalItem = input.logicalItem?.trim() || "default";
+    this.repository.expireDue();
+    const approval = this.repository.getForItem(input.runId, input.nodeId, logicalItem)
+      ?? this.repository.request({ ...input, logicalItem });
+    if (approval.status === "approved") return approval;
+    if (approval.status === "rejected" || approval.status === "expired") {
+      throw new ValidationError(`Approval ${approval.id} is ${approval.status}.`);
+    }
+    throw new ApprovalRequiredError(approval);
+  }
+
+  approve(id: string, decidedBy: string, decision: NodeFlowJsonObject = {}): AutomationApprovalRecord {
+    return this.repository.decide(id, { status: "approved", decidedBy, decision });
+  }
+  reject(id: string, decidedBy: string, decision: NodeFlowJsonObject = {}): AutomationApprovalRecord {
+    return this.repository.decide(id, { status: "rejected", decidedBy, decision });
+  }
+  listForRun(runId: string): AutomationApprovalRecord[] { return this.repository.listForRun(runId); }
+}
diff --git a/src/services/node-flows/builtins/builtin-executors.ts b/src/services/node-flows/builtins/builtin-executors.ts
new file mode 100644
index 0000000000..5a5530a138
--- /dev/null
+++ b/src/services/node-flows/builtins/builtin-executors.ts
@@ -0,0 +1,142 @@
+import { ValidationError } from "../../../repositories/repository-utils.js";
+import type { NodeFlowJsonObject, NodeFlowJsonValue } from "../../../contracts/node-flow-types.js";
+import type { ApprovalService } from "../approval-service.js";
+import type { OutboxService } from "../outbox-service.js";
+
+export const MAX_FOREACH_ITEMS = 1_000;
+export const MAX_SUBFLOW_DEPTH = 8;
+export const MAX_DELAY_MS = 60 * 60_000;
+
+export interface BuiltinExecutionContext {
+  projectId: string; flowId: string; publicationId: string; runId: string; nodeId: string;
+  config: NodeFlowJsonObject; upstream: NodeFlowJsonObject; flowInput: NodeFlowJsonObject;
+  signal?: AbortSignal; subflowDepth: number;
+}
+export interface BuiltinExecutionResult { output: NodeFlowJsonObject; selectedPorts?: string[] }
+export interface BuiltinExecutorDependencies {
+  approvalService?: ApprovalService;
+  outboxService?: OutboxService;
+  executeSubflow?: (input: { projectId: string; flowId: string; input: NodeFlowJsonObject; depth: number; signal?: AbortSignal }) => Promise<NodeFlowJsonObject>;
+}
+
+export class BuiltinExecutors {
+  constructor(private readonly deps: BuiltinExecutorDependencies = {}) {}
+
+  async execute(type: string, context: BuiltinExecutionContext): Promise<BuiltinExecutionResult> {
+    switch (type) {
+      case "condition": return executeCondition(context);
+      case "switch": return executeSwitch(context);
+      case "foreach": return executeForeach(context);
+      case "merge": return executeMerge(context);
+      case "delay": return executeDelay(context);
+      case "approval": return this.executeApproval(context);
+      case "email_draft": return executeEmailDraft(context);
+      case "email_send": return this.executeEmailSend(context);
+      case "execute_subflow": return this.executeSubflow(context);
+      case "webhook_trigger": return { output: { ...context.flowInput } };
+      default: throw new ValidationError(`Unsupported built-in node type: ${type}.`);
+    }
+  }
+
+  private executeApproval(context: BuiltinExecutionContext): BuiltinExecutionResult {
+    if (!this.deps.approvalService) throw new ValidationError("Approval service is not configured.");
+    const approval = this.deps.approvalService.requireApproval({ projectId: context.projectId, flowId: context.flowId,
+      runId: context.runId, nodeId: context.nodeId, logicalItem: readString(context.config.logicalItem) ?? "default",
+      request: { summary: readString(context.config.summary) ?? "Approval required", payload: context.upstream } });
+    return { output: { approved: true, approvalId: approval.id, ...context.upstream }, selectedPorts: ["approved"] };
+  }
+
+  private async executeEmailSend(context: BuiltinExecutionContext): Promise<BuiltinExecutionResult> {
+    if (!this.deps.approvalService || !this.deps.outboxService) throw new ValidationError("Email side-effect services are not configured.");
+    const draft = buildEmail(context);
+    const logicalItem = readString(context.config.logicalItem) ?? "default";
+    this.deps.approvalService.requireApproval({ projectId: context.projectId, flowId: context.flowId, runId: context.runId,
+      nodeId: context.nodeId, logicalItem, request: { effectType: "email", draft } });
+    const sent = await this.deps.outboxService.dispatch({ projectId: context.projectId, flowId: context.flowId,
+      publicationId: context.publicationId, runId: context.runId, nodeId: context.nodeId, logicalItem,
+      effectType: "email", payload: draft });
+    if (sent.status === "attention_required") throw new Error(sent.lastError ?? "Email provider outcome is unknown.");
+    if (sent.status !== "sent") throw new Error(sent.lastError ?? "Email send failed.");
+    return { output: { sent: true, outboxId: sent.id, providerMessageId: sent.providerMessageId } };
+  }
+
+  private async executeSubflow(context: BuiltinExecutionContext): Promise<BuiltinExecutionResult> {
+    const flowId = readString(context.config.flowId);
+    if (!flowId) throw new ValidationError("Execute Subflow requires flowId.");
+    if (flowId === context.flowId) throw new ValidationError("A node flow cannot directly execute itself.");
+    if (context.subflowDepth >= MAX_SUBFLOW_DEPTH) throw new ValidationError(`Subflow depth exceeds ${MAX_SUBFLOW_DEPTH}.`);
+    if (!this.deps.executeSubflow) throw new ValidationError("Subflow execution is not configured.");
+    return { output: await this.deps.executeSubflow({ projectId: context.projectId, flowId,
+      input: readObject(context.config.input) ?? context.upstream, depth: context.subflowDepth + 1, signal: context.signal }) };
+  }
+}
+
+function executeCondition(context: BuiltinExecutionContext): BuiltinExecutionResult {
+  const actual = readPath({ input: context.flowInput, upstream: context.upstream }, readString(context.config.path) ?? "upstream");
+  const expected = context.config.value;
+  const operator = readString(context.config.operator) ?? "truthy";
+  const matched = compare(actual, expected, operator);
+  return { output: { matched, value: toJson(actual) }, selectedPorts: [matched ? "true" : "false"] };
+}
+
+function executeSwitch(context: BuiltinExecutionContext): BuiltinExecutionResult {
+  const actual = readPath({ input: context.flowInput, upstream: context.upstream }, readString(context.config.path) ?? "upstream");
+  const cases = Array.isArray(context.config.cases) ? context.config.cases : [];
+  if (cases.length > 100) throw new ValidationError("Switch cases are limited to 100.");
+  const selected = cases.find((entry) => {
+    const item = readObject(entry); return item && compare(actual, item.value, readString(item.operator) ?? "equals");
+  });
+  const selectedCase = selected ? readString(readObject(selected)?.port) ?? readString(readObject(selected)?.id) ?? "default" : "default";
+  return { output: { value: toJson(actual), selectedCase }, selectedPorts: [selectedCase] };
+}
+
+function executeForeach(context: BuiltinExecutionContext): BuiltinExecutionResult {
+  const path = readString(context.config.path) ?? "upstream.items";
+  const value = readPath({ input: context.flowInput, upstream: context.upstream }, path);
+  if (!Array.isArray(value)) throw new ValidationError("Foreach input must resolve to an array.");
+  const configured = Number(context.config.maxItems ?? MAX_FOREACH_ITEMS);
+  const maxItems = Math.max(1, Math.min(MAX_FOREACH_ITEMS, Number.isFinite(configured) ? Math.floor(configured) : MAX_FOREACH_ITEMS));
+  if (value.length > maxItems) throw new ValidationError(`Foreach input exceeds the bounded item limit of ${maxItems}.`);
+  return { output: { items: value.map(toJson), count: value.length }, selectedPorts: value.length ? ["items"] : ["empty"] };
+}
+
+function executeMerge(context: BuiltinExecutionContext): BuiltinExecutionResult {
+  const strategy = readString(context.config.strategy) ?? "object";
+  const values = Object.values(context.upstream);
+  if (strategy === "array") return { output: { items: values } };
+  if (strategy === "first") return { output: readObject(values[0]) ?? { value: toJson(values[0]) } };
+  if (strategy === "object") return { output: Object.assign({}, ...values.filter((value) => readObject(value))) as NodeFlowJsonObject };
+  throw new ValidationError(`Unsupported merge strategy: ${strategy}.`);
+}
+
+async function executeDelay(context: BuiltinExecutionContext): Promise<BuiltinExecutionResult> {
+  const parsed = Number(context.config.delayMs ?? 0);
+  if (!Number.isFinite(parsed) || parsed < 0 || parsed > MAX_DELAY_MS) throw new ValidationError(`Delay must be between 0 and ${MAX_DELAY_MS}ms.`);
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(resolve, Math.floor(parsed));
+    context.signal?.addEventListener("abort", () => { clearTimeout(timer); reject(context.signal?.reason ?? new Error("Delay cancelled.")); }, { once: true });
+  });
+  return { output: { ...context.upstream, delayedMs: Math.floor(parsed) } };
+}
+
+function executeEmailDraft(context: BuiltinExecutionContext): BuiltinExecutionResult { return { output: { draft: buildEmail(context), sent: false } }; }
+function buildEmail(context: BuiltinExecutionContext): NodeFlowJsonObject {
+  const to = context.config.to; const subject = readString(context.config.subject); const body = readString(context.config.body);
+  if ((!readString(to) && !Array.isArray(to)) || !subject || !body) throw new ValidationError("Email requires to, subject, and body.");
+  return { to: to as NodeFlowJsonValue, subject, body, ...(readString(context.config.from) ? { from: readString(context.config.from)! } : {}) };
+}
+function compare(actual: unknown, expected: unknown, operator: string): boolean {
+  switch (operator) {
+    case "truthy": return Boolean(actual); case "falsy": return !actual;
+    case "equals": return JSON.stringify(actual) === JSON.stringify(expected);
+    case "not_equals": return JSON.stringify(actual) !== JSON.stringify(expected);
+    case "contains": return typeof actual === "string" ? actual.includes(String(expected)) : Array.isArray(actual) && actual.some((entry) => JSON.stringify(entry) === JSON.stringify(expected));
+    case "greater_than": return typeof actual === "number" && typeof expected === "number" && actual > expected;
+    case "less_than": return typeof actual === "number" && typeof expected === "number" && actual < expected;
+    default: throw new ValidationError(`Unsupported condition operator: ${operator}.`);
+  }
+}
+function readPath(value: unknown, path: string): unknown { return path.split(".").reduce<unknown>((current, key) => current && typeof current === "object" ? (current as Record<string, unknown>)[key] : undefined, value); }
+function readString(value: unknown): string | null { return typeof value === "string" && value.trim() ? value.trim() : null; }
+function readObject(value: unknown): NodeFlowJsonObject | null { return value && typeof value === "object" && !Array.isArray(value) ? value as NodeFlowJsonObject : null; }
+function toJson(value: unknown): NodeFlowJsonValue { return value === undefined ? null : JSON.parse(JSON.stringify(value)) as NodeFlowJsonValue; }
diff --git a/src/services/node-flows/builtins/index.ts b/src/services/node-flows/builtins/index.ts
new file mode 100644
index 0000000000..76f84ed29b
--- /dev/null
+++ b/src/services/node-flows/builtins/index.ts
@@ -0,0 +1 @@
+export * from "./builtin-executors.js";
diff --git a/src/services/node-flows/egress-policy-service.ts b/src/services/node-flows/egress-policy-service.ts
new file mode 100644
index 0000000000..750d6b8ade
--- /dev/null
+++ b/src/services/node-flows/egress-policy-service.ts
@@ -0,0 +1,224 @@
+import { lookup as dnsLookup } from "node:dns/promises";
+import { isIP } from "node:net";
+import { ValidationError } from "../../repositories/repository-utils.js";
+
+const RESTRICTED_HEADERS = new Set([
+  "authorization", "cookie", "host", "proxy-authorization", "proxy-connection",
+  "connection", "transfer-encoding", "upgrade", "x-forwarded-for", "x-real-ip",
+]);
+const DEFAULT_CONTENT_TYPES = ["application/json", "text/"];
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const RETRYABLE_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
+
+export interface EgressPolicy {
+  allowHttp?: boolean;
+  allowedHosts?: string[];
+  allowedPorts?: number[];
+  maxRedirects?: number;
+  maxResponseBytes?: number;
+  allowedContentTypes?: string[];
+  timeoutMs?: number;
+  maxRetries?: number;
+  requestsPerMinute?: number;
+}
+
+export interface EgressRequest {
+  url: string | URL;
+  method?: string;
+  headers?: Record<string, string>;
+  credentialHeaders?: Record<string, string>;
+  body?: BodyInit;
+  signal?: AbortSignal;
+  policy?: EgressPolicy;
+  rateLimitKey?: string;
+}
+
+export interface EgressResponse {
+  url: string;
+  status: number;
+  ok: boolean;
+  headers: Record<string, string>;
+  contentType: string;
+  body: Uint8Array;
+  text(): string;
+  json(): unknown;
+}
+
+export interface EgressPolicyServiceOptions {
+  fetch?: typeof fetch;
+  lookup?: (hostname: string) => Promise<Array<{ address: string; family: number }>>;
+  defaults?: EgressPolicy;
+}
+
+export class EgressPolicyService {
+  private readonly fetchImpl: typeof fetch;
+  private readonly lookup: NonNullable<EgressPolicyServiceOptions["lookup"]>;
+  private readonly defaults: EgressPolicy;
+  private readonly rateWindows = new Map<string, number[]>();
+
+  constructor(options: EgressPolicyServiceOptions = {}) {
+    this.fetchImpl = options.fetch ?? fetch;
+    this.lookup = options.lookup ?? (async (hostname) => dnsLookup(hostname, { all: true, verbatim: true }));
+    this.defaults = options.defaults ?? {};
+  }
+
+  async request(input: EgressRequest): Promise<EgressResponse> {
+    const policy = { ...this.defaults, ...input.policy };
+    const method = (input.method ?? "GET").toUpperCase();
+    const headers = normalizeRequestHeaders(input.headers, false);
+    Object.assign(headers, normalizeRequestHeaders(input.credentialHeaders, true));
+    this.enforceRateLimit(input.rateLimitKey ?? new URL(input.url).hostname, policy.requestsPerMinute ?? 60);
+
+    const retries = Math.max(0, Math.min(5, Math.floor(policy.maxRetries ?? 0)));
+    let lastError: unknown;
+    for (let attempt = 0; attempt <= retries; attempt += 1) {
+      try {
+        const response = await this.requestWithRedirects(input.url, method, headers, input.body, input.signal, policy);
+        if (!RETRYABLE_STATUSES.has(response.status) || attempt === retries || !isRetrySafe(method, headers)) return response;
+      } catch (error) {
+        lastError = error;
+        if (attempt === retries || !isRetrySafe(method, headers) || error instanceof ValidationError) throw error;
+      }
+      await boundedBackoff(attempt, input.signal);
+    }
+    throw lastError instanceof Error ? lastError : new Error("Egress request failed.");
+  }
+
+  async validateUrl(value: string | URL, policy: EgressPolicy = {}): Promise<{ url: URL; addresses: string[] }> {
+    let url: URL;
+    try { url = new URL(value); } catch { throw new ValidationError("Egress URL is invalid."); }
+    if (url.username || url.password) throw new ValidationError("Credentials in URLs are not allowed.");
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && policy.allowHttp === true)) {
+      throw new ValidationError("Egress URL must use HTTPS unless HTTP is explicitly enabled.");
+    }
+    const hostname = url.hostname.toLowerCase().replace(/\.$/, "").replace(/^\[|\]$/g, "");
+    if (!hostname || hostname === "localhost" || hostname.endsWith(".localhost") || hostname === "metadata.google.internal") {
+      throw new ValidationError("Private, loopback, and metadata hosts are not allowed.");
+    }
+    const allowedHosts = policy.allowedHosts?.map((entry) => entry.toLowerCase());
+    if (allowedHosts?.length && !allowedHosts.some((entry) => hostname === entry || (entry.startsWith("*.") && hostname.endsWith(entry.slice(1))))) {
+      throw new ValidationError(`Egress host is not allowlisted: ${hostname}.`);
+    }
+    const port = url.port ? Number(url.port) : url.protocol === "https:" ? 443 : 80;
+    const allowedPorts = policy.allowedPorts ?? (url.protocol === "https:" ? [443] : [80]);
+    if (!Number.isInteger(port) || !allowedPorts.includes(port)) throw new ValidationError(`Egress port is not allowlisted: ${port}.`);
+
+    const addresses = isIP(hostname)
+      ? [hostname]
+      : (await this.lookup(hostname)).map((entry) => entry.address);
+    if (addresses.length === 0) throw new ValidationError("Egress host did not resolve to an address.");
+    if (addresses.some(isBlockedAddress)) throw new ValidationError("Private, loopback, link-local, and metadata addresses are not allowed.");
+    const rebound = isIP(hostname) ? addresses : (await this.lookup(hostname)).map((entry) => entry.address);
+    if (rebound.length === 0 || !sameAddressSet(addresses, rebound) || rebound.some(isBlockedAddress)) {
+      throw new ValidationError("DNS rebinding was detected for the egress host.");
+    }
+    return { url, addresses: [...new Set(addresses)].sort() };
+  }
+
+  private async requestWithRedirects(
+    initialUrl: string | URL, method: string, headers: Record<string, string>, body: BodyInit | undefined,
+    parentSignal: AbortSignal | undefined, policy: EgressPolicy,
+  ): Promise<EgressResponse> {
+    let current = (await this.validateUrl(initialUrl, policy)).url;
+    const maxRedirects = Math.max(0, Math.min(10, Math.floor(policy.maxRedirects ?? 3)));
+    for (let redirects = 0; ; redirects += 1) {
+      const timeoutMs = Math.max(1, Math.min(120_000, Math.floor(policy.timeoutMs ?? 30_000)));
+      const controller = new AbortController();
+      const abort = (): void => controller.abort(parentSignal?.reason);
+      parentSignal?.addEventListener("abort", abort, { once: true });
+      const timer = setTimeout(() => controller.abort(new Error(`Egress request timed out after ${timeoutMs}ms.`)), timeoutMs);
+      let response: Response;
+      try {
+        response = await this.fetchImpl(current, { method, headers, body, redirect: "manual", signal: controller.signal });
+        if (REDIRECT_STATUSES.has(response.status)) {
+          if (redirects >= maxRedirects) throw new ValidationError("Egress redirect limit exceeded.");
+          const location = response.headers.get("location");
+          if (!location) throw new ValidationError("Egress redirect response omitted Location.");
+          const next = new URL(location, current);
+          if (next.origin !== current.origin) {
+            delete headers.authorization;
+            delete headers.cookie;
+          }
+          current = (await this.validateUrl(next, policy)).url;
+          continue;
+        }
+        return await this.readResponse(response, current, policy);
+      } finally {
+        clearTimeout(timer); parentSignal?.removeEventListener("abort", abort);
+      }
+    }
+  }
+
+  private async readResponse(response: Response, url: URL, policy: EgressPolicy): Promise<EgressResponse> {
+    const maxBytes = Math.max(1, Math.min(50 * 1024 * 1024, Math.floor(policy.maxResponseBytes ?? 2 * 1024 * 1024)));
+    const declaredLength = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declaredLength) && declaredLength > maxBytes) throw new ValidationError("Egress response exceeds the configured size limit.");
+    const contentType = (response.headers.get("content-type") ?? "application/octet-stream").split(";", 1)[0]!.trim().toLowerCase();
+    const allowed = policy.allowedContentTypes ?? DEFAULT_CONTENT_TYPES;
+    if (response.status !== 204 && !allowed.some((entry) => contentType === entry || (entry.endsWith("/") && contentType.startsWith(entry)))) {
+      throw new ValidationError(`Egress response content type is not allowed: ${contentType}.`);
+    }
+    const chunks: Uint8Array[] = []; let total = 0;
+    if (response.body) {
+      const reader = response.body.getReader();
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        total += value.byteLength;
+        if (total > maxBytes) { await reader.cancel(); throw new ValidationError("Egress response exceeds the configured size limit."); }
+        chunks.push(value);
+      }
+    }
+    const bytes = new Uint8Array(total); let offset = 0;
+    for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength; }
+    return {
+      url: url.toString(), status: response.status, ok: response.ok,
+      headers: Object.fromEntries([...response.headers].map(([key, value]) => [key.toLowerCase(), value])),
+      contentType, body: bytes,
+      text: () => new TextDecoder().decode(bytes),
+      json: () => JSON.parse(new TextDecoder().decode(bytes)) as unknown,
+    };
+  }
+
+  private enforceRateLimit(key: string, limit: number): void {
+    const boundedLimit = Math.max(1, Math.min(10_000, Math.floor(limit)));
+    const cutoff = Date.now() - 60_000;
+    const recent = (this.rateWindows.get(key) ?? []).filter((time) => time > cutoff);
+    if (recent.length >= boundedLimit) throw new ValidationError("Egress rate limit exceeded.");
+    recent.push(Date.now()); this.rateWindows.set(key, recent);
+  }
+}
+
+function normalizeRequestHeaders(input: Record<string, string> | undefined, trusted: boolean): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [rawName, rawValue] of Object.entries(input ?? {})) {
+    const name = rawName.trim().toLowerCase();
+    if (!/^[!#$%&'*+.^_`|~0-9a-z-]+$/.test(name) || /[\r\n]/.test(rawValue)) throw new ValidationError("Egress header is invalid.");
+    if (!trusted && RESTRICTED_HEADERS.has(name)) throw new ValidationError(`Egress header is restricted: ${name}.`);
+    if (name === "host" || name === "connection" || name.startsWith("proxy-")) throw new ValidationError(`Egress header is restricted: ${name}.`);
+    result[name] = String(rawValue).trim();
+  }
+  return result;
+}
+
+function isBlockedAddress(address: string): boolean {
+  const normalized = address.toLowerCase().split("%", 1)[0]!;
+  if (normalized === "::1" || normalized === "::" || normalized.startsWith("fe80:") || normalized.startsWith("fc") || normalized.startsWith("fd") || normalized.startsWith("ff") || normalized.startsWith("2001:db8:")) return true;
+  const mapped = normalized.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/)?.[1];
+  if (mapped) return isBlockedAddress(mapped);
+  if (isIP(normalized) === 4) {
+    const [a, b] = normalized.split(".").map(Number);
+    return a === 0 || a === 10 || a === 127 || a >= 224 || (a === 169 && b === 254)
+      || (a === 172 && b! >= 16 && b! <= 31) || (a === 192 && b === 168)
+      || (a === 100 && b! >= 64 && b! <= 127) || (a === 192 && b === 0)
+      || (a === 192 && b === 2) || (a === 198 && (b === 18 || b === 19 || b === 51))
+      || (a === 203 && b === 0);
+  }
+  return isIP(normalized) !== 6;
+}
+const sameAddressSet = (left: string[], right: string[]): boolean => [...new Set(left)].sort().join("|") === [...new Set(right)].sort().join("|");
+const isRetrySafe = (method: string, headers: Record<string, string>): boolean => ["GET", "HEAD", "OPTIONS"].includes(method) || Boolean(headers["idempotency-key"]);
+async function boundedBackoff(attempt: number, signal?: AbortSignal): Promise<void> {
+  const ms = Math.min(2_000, 100 * (2 ** attempt));
+  await new Promise<void>((resolve, reject) => { const timer = setTimeout(resolve, ms); signal?.addEventListener("abort", () => { clearTimeout(timer); reject(signal.reason); }, { once: true }); });
+}
diff --git a/src/services/node-flows/oauth-broker.ts b/src/services/node-flows/oauth-broker.ts
new file mode 100644
index 0000000000..18a3cd8085
--- /dev/null
+++ b/src/services/node-flows/oauth-broker.ts
@@ -0,0 +1,107 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+import { ValidationError } from "../../repositories/repository-utils.js";
+
+export interface OAuthTokenSet {
+  accessToken: string; refreshToken?: string; expiresAt: string; scopes: string[]; tokenType?: string;
+}
+export interface OAuthTokenClient {
+  exchangeCode(input: { code: string; redirectUri: string; codeVerifier: string }): Promise<OAuthTokenSet>;
+  refresh(refreshToken: string): Promise<OAuthTokenSet>;
+  revoke?(token: string): Promise<void>;
+  health?(accessToken: string): Promise<boolean>;
+}
+export interface OAuthConnectionStore {
+  get(connectionId: string): Promise<OAuthTokenSet | null> | OAuthTokenSet | null;
+  set(connectionId: string, tokens: OAuthTokenSet): Promise<void> | void;
+  delete(connectionId: string): Promise<void> | void;
+}
+interface OAuthStatePayload { connectionId: string; origin: string; redirectUri: string; verifier: string; expiresAt: number; nonce: string }
+
+export class OAuthBroker {
+  private readonly consumedStates = new Set<string>();
+  constructor(private readonly input: { key: Buffer; store: OAuthConnectionStore; client: OAuthTokenClient; allowedCallbackOrigins: string[] }) {
+    if (input.key.byteLength !== 32) throw new ValidationError("OAuth state encryption key must contain 32 bytes.");
+  }
+
+  beginAuthorization(input: { connectionId: string; authorizationUrl: string; redirectUri: string; scopes: string[] }): { authorizationUrl: string; state: string } {
+    const redirect = new URL(input.redirectUri); this.assertCallbackOrigin(redirect.origin);
+    const verifier = randomBytes(32).toString("base64url");
+    const payload: OAuthStatePayload = { connectionId: input.connectionId, origin: redirect.origin, redirectUri: redirect.toString(), verifier, expiresAt: Date.now() + 10 * 60_000, nonce: randomBytes(16).toString("hex") };
+    const state = this.encrypt(payload);
+    const url = new URL(input.authorizationUrl);
+    url.searchParams.set("response_type", "code"); url.searchParams.set("redirect_uri", redirect.toString());
+    url.searchParams.set("scope", [...new Set(input.scopes)].sort().join(" ")); url.searchParams.set("state", state);
+    url.searchParams.set("code_challenge_method", "S256");
+    url.searchParams.set("code_challenge", createHash("sha256").update(verifier).digest("base64url"));
+    return { authorizationUrl: url.toString(), state };
+  }
+
+  async completeAuthorization(input: { state: string; code: string; callbackOrigin: string }): Promise<{ connectionId: string; expiresAt: string; scopes: string[] }> {
+    const state = this.decrypt(input.state);
+    const stateDigest = createHash("sha256").update(input.state).digest("hex");
+    if (this.consumedStates.has(stateDigest)) throw new ValidationError("OAuth authorization state has already been used.");
+    this.assertCallbackOrigin(input.callbackOrigin);
+    if (state.origin !== new URL(input.callbackOrigin).origin) throw new ValidationError("OAuth callback origin does not match authorization state.");
+    if (state.expiresAt <= Date.now()) throw new ValidationError("OAuth authorization state has expired.");
+    this.consumedStates.add(stateDigest);
+    const tokens = normalizeTokens(await this.input.client.exchangeCode({ code: input.code, redirectUri: state.redirectUri, codeVerifier: state.verifier }));
+    await this.input.store.set(state.connectionId, tokens);
+    return { connectionId: state.connectionId, expiresAt: tokens.expiresAt, scopes: tokens.scopes };
+  }
+
+  async getAccessToken(connectionId: string, requiredScopes: string[] = []): Promise<string> {
+    let tokens = await this.input.store.get(connectionId);
+    if (!tokens) throw new ValidationError("OAuth connection must be reconnected.");
+    if (requiredScopes.some((scope) => !tokens!.scopes.includes(scope))) throw new ValidationError("OAuth connection does not grant the required scopes.");
+    if (Date.parse(tokens.expiresAt) <= Date.now() + 30_000) {
+      if (!tokens.refreshToken) throw new ValidationError("OAuth connection has expired and must be reconnected.");
+      const refreshed = normalizeTokens(await this.input.client.refresh(tokens.refreshToken));
+      tokens = { ...refreshed, refreshToken: refreshed.refreshToken ?? tokens.refreshToken };
+      await this.input.store.set(connectionId, tokens);
+    }
+    return tokens.accessToken;
+  }
+
+  async revoke(connectionId: string): Promise<void> {
+    const tokens = await this.input.store.get(connectionId);
+    if (tokens && this.input.client.revoke) await this.input.client.revoke(tokens.refreshToken ?? tokens.accessToken);
+    await this.input.store.delete(connectionId);
+  }
+  async reconnect(connectionId: string): Promise<void> { await this.revoke(connectionId); }
+  async health(connectionId: string): Promise<{ healthy: boolean; expiresAt: string | null; scopes: string[] }> {
+    let tokens = await this.input.store.get(connectionId);
+    if (!tokens) return { healthy: false, expiresAt: null, scopes: [] };
+    try { const accessToken = await this.getAccessToken(connectionId); tokens = await this.input.store.get(connectionId) ?? tokens; return { healthy: this.input.client.health ? await this.input.client.health(accessToken) : true, expiresAt: tokens.expiresAt, scopes: tokens.scopes }; }
+    catch { return { healthy: false, expiresAt: tokens.expiresAt, scopes: tokens.scopes }; }
+  }
+
+  private assertCallbackOrigin(origin: string): void {
+    let normalized: string; try { normalized = new URL(origin).origin; } catch { throw new ValidationError("OAuth callback origin is invalid."); }
+    if (!this.input.allowedCallbackOrigins.some((allowed) => new URL(allowed).origin === normalized)) throw new ValidationError("OAuth callback origin is not allowlisted.");
+  }
+  private encrypt(payload: OAuthStatePayload): string {
+    const iv = randomBytes(12); const cipher = createCipheriv("aes-256-gcm", this.input.key, iv);
+    const ciphertext = Buffer.concat([cipher.update(JSON.stringify(payload), "utf8"), cipher.final()]);
+    return Buffer.concat([iv, cipher.getAuthTag(), ciphertext]).toString("base64url");
+  }
+  private decrypt(value: string): OAuthStatePayload {
+    try {
+      const packed = Buffer.from(value, "base64url"); if (packed.length < 29) throw new Error("short state");
+      const decipher = createDecipheriv("aes-256-gcm", this.input.key, packed.subarray(0, 12));
+      decipher.setAuthTag(packed.subarray(12, 28));
+      return JSON.parse(Buffer.concat([decipher.update(packed.subarray(28)), decipher.final()]).toString("utf8")) as OAuthStatePayload;
+    } catch { throw new ValidationError("OAuth authorization state is invalid."); }
+  }
+}
+
+function normalizeTokens(tokens: OAuthTokenSet): OAuthTokenSet {
+  if (!tokens.accessToken || !Number.isFinite(Date.parse(tokens.expiresAt))) throw new ValidationError("OAuth provider returned an invalid token response.");
+  return { ...tokens, scopes: [...new Set(tokens.scopes)].sort(), tokenType: tokens.tokenType ?? "Bearer" };
+}
+
+export class InMemoryOAuthConnectionStore implements OAuthConnectionStore {
+  private readonly records = new Map<string, OAuthTokenSet>();
+  get(id: string): OAuthTokenSet | null { return this.records.get(id) ?? null; }
+  set(id: string, tokens: OAuthTokenSet): void { this.records.set(id, { ...tokens }); }
+  delete(id: string): void { this.records.delete(id); }
+}
diff --git a/src/services/node-flows/outbox-service.ts b/src/services/node-flows/outbox-service.ts
new file mode 100644
index 0000000000..8c1bfef991
--- /dev/null
+++ b/src/services/node-flows/outbox-service.ts
@@ -0,0 +1,42 @@
+import { AutomationOutboxRepository, type AutomationOutboxRecord } from "../../repositories/automation-outbox-repository.js";
+import type { NodeFlowJsonObject } from "../../contracts/node-flow-types.js";
+
+export interface SideEffectProviderResult { providerMessageId: string }
+export interface SideEffectProvider { send(effectType: string, payload: NodeFlowJsonObject, idempotencyKey: string): Promise<SideEffectProviderResult> }
+
+export class OutboxService {
+  constructor(private readonly repository: AutomationOutboxRepository, private readonly provider: SideEffectProvider) {
+    this.repository.recoverSending();
+  }
+
+  async dispatch(input: {
+    projectId: string; flowId: string; publicationId: string; runId: string; nodeId: string;
+    logicalItem?: string; effectType: string; payload: NodeFlowJsonObject;
+  }): Promise<AutomationOutboxRecord> {
+    const record = this.repository.enqueue({ ...input, logicalItem: input.logicalItem?.trim() || "default" });
+    if (record.status === "sent" || record.status === "attention_required") return record;
+    const claimed = this.repository.claim(record.id);
+    if (!claimed) return this.repository.get(record.id)!;
+    try {
+      const result = await this.provider.send(claimed.effectType, claimed.payload, claimed.idempotencyKey);
+      return this.repository.markSent(claimed.id, result.providerMessageId);
+    } catch (error) {
+      const unknownOutcome = error instanceof UnknownSideEffectOutcomeError;
+      return this.repository.markFailed(claimed.id, error instanceof Error ? error.message : String(error), unknownOutcome);
+    }
+  }
+}
+
+export class UnknownSideEffectOutcomeError extends Error {
+  constructor(message = "The provider may have accepted the side effect, so automatic replay is disabled.") {
+    super(message); this.name = "UnknownSideEffectOutcomeError";
+  }
+}
+
+export class MockSideEffectProvider implements SideEffectProvider {
+  readonly sends: Array<{ effectType: string; payload: NodeFlowJsonObject; idempotencyKey: string }> = [];
+  async send(effectType: string, payload: NodeFlowJsonObject, idempotencyKey: string): Promise<SideEffectProviderResult> {
+    this.sends.push({ effectType, payload, idempotencyKey });
+    return { providerMessageId: `mock-${idempotencyKey.slice(0, 16)}` };
+  }
+}
diff --git a/tests/backend/domain/node-flows/node-definition-registry.test.ts b/tests/backend/domain/node-flows/node-definition-registry.test.ts
index fd4fdefe02..6c2d175aba 100644
--- a/tests/backend/domain/node-flows/node-definition-registry.test.ts
+++ b/tests/backend/domain/node-flows/node-definition-registry.test.ts
@@ -2,11 +2,16 @@ import { describe, expect, it } from "vitest";
 import { listNodeDefinitions, resolveNodeDefinition } from "../../../../src/domain/node-flows/node-definition-registry.js";
 
 describe("node definition registry", () => {
-  it("registers only the six implemented executable node types", () => {
+  it("registers the governed executable catalog", () => {
     expect(listNodeDefinitions().filter((definition) => definition.executable).map((definition) => definition.type)).toEqual([
-      "input", "set_fields", "template", "provider_prompt", "http_request", "output",
+      "input", "set_fields", "template", "provider_prompt", "http_request", "condition", "switch",
+      "foreach", "merge", "delay", "approval", "email_draft", "email_send", "execute_subflow",
+      "webhook_trigger", "output",
     ]);
-    expect(resolveNodeDefinition("condition", 1)).toBeNull();
+    expect(resolveNodeDefinition("condition", 1)).toMatchObject({
+      executable: true,
+      ports: expect.arrayContaining([expect.objectContaining({ id: "true" }), expect.objectContaining({ id: "false" })]),
+    });
     expect(resolveNodeDefinition("http_request", 1)).toMatchObject({
       executionKind: "http",
       sideEffect: "external",
diff --git a/tests/backend/repositories/automation-governance-repositories.test.ts b/tests/backend/repositories/automation-governance-repositories.test.ts
new file mode 100644
index 0000000000..ae0a962d38
--- /dev/null
+++ b/tests/backend/repositories/automation-governance-repositories.test.ts
@@ -0,0 +1,50 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AppDbStorage } from "../../../src/repositories/app-db-storage.js";
+import { ProjectManagementRepository } from "../../../src/repositories/project-management-repository.js";
+import { NodeFlowRepository } from "../../../src/repositories/node-flow-repository.js";
+import { AutomationApprovalRepository } from "../../../src/repositories/automation-approval-repository.js";
+import { AutomationOutboxRepository } from "../../../src/repositories/automation-outbox-repository.js";
+import { MockSideEffectProvider, OutboxService } from "../../../src/services/node-flows/outbox-service.js";
+
+const dirs: string[] = [];
+afterEach(async () => Promise.all(dirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true }))));
+
+async function fixture() {
+  const dir = await mkdtemp(join(tmpdir(), "automation-governance-")); dirs.push(dir);
+  const dbPath = join(dir, "app.db"); const storage = new AppDbStorage(dbPath);
+  const project = new ProjectManagementRepository(storage).createProject({ name: "Governance", sourceType: "local", sourceRef: dir });
+  const flows = new NodeFlowRepository(storage);
+  const flow = flows.createFlow(project.id, { title: "Flow", graph: { nodes: [{ id: "draft", type: "email_draft", title: "Draft" }], edges: [] } });
+  const publication = flows.getPublication(flow.id)!;
+  const run = flows.createRun({ flowId: flow.id, projectId: project.id, version: flow.version, publicationId: publication.id, status: "running" });
+  return { dir, dbPath, storage, project, flow, publication, run };
+}
+
+describe("automation governance repositories", () => {
+  it("persists approval decisions across repository restarts", async () => {
+    const { storage, project, flow, run } = await fixture();
+    const first = new AutomationApprovalRepository(storage);
+    const requested = first.request({ projectId: project.id, flowId: flow.id, runId: run.id, nodeId: "approve", logicalItem: "one", request: { summary: "Send" } });
+    first.decide(requested.id, { status: "approved", decidedBy: "operator" });
+    expect(new AutomationApprovalRepository(storage).get(requested.id)).toMatchObject({ status: "approved", decidedBy: "operator" });
+    storage.close();
+  });
+
+  it("deduplicates outbox sends and marks restart-unknown outcomes for attention", async () => {
+    const { storage, project, flow, publication, run } = await fixture();
+    const repository = new AutomationOutboxRepository(storage); const provider = new MockSideEffectProvider();
+    const service = new OutboxService(repository, provider);
+    const input = { projectId: project.id, flowId: flow.id, publicationId: publication.id, runId: run.id, nodeId: "send", logicalItem: "one", effectType: "email", payload: { to: "a@example.test" } };
+    const first = await service.dispatch(input); const second = await service.dispatch(input);
+    expect(second.id).toBe(first.id); expect(provider.sends).toHaveLength(1); expect(first.providerMessageId).toMatch(/^mock-/);
+
+    const pending = repository.enqueue({ ...input, logicalItem: "two" });
+    repository.claim(pending.id);
+    new OutboxService(repository, provider);
+    expect(repository.get(pending.id)).toMatchObject({ status: "attention_required" });
+    storage.close();
+  });
+});
diff --git a/tests/backend/server/node-flow-webhook-routes.test.ts b/tests/backend/server/node-flow-webhook-routes.test.ts
new file mode 100644
index 0000000000..5062f4c026
--- /dev/null
+++ b/tests/backend/server/node-flow-webhook-routes.test.ts
@@ -0,0 +1,20 @@
+import express from "express";
+import request from "supertest";
+import { describe, expect, it, vi } from "vitest";
+import { registerNodeFlowWebhookRoutes } from "../../../src/server/node-flow-webhook-routes.js";
+
+describe("node flow webhook ingress", () => {
+  it("rejects unauthenticated requests and dispatches authenticated payloads", async () => {
+    const authenticate = vi.fn((pathToken: string, secret: string) => pathToken === "path" && secret === "secret"
+      ? { projectId: "project-1", flowId: "flow-1" } : null);
+    const runFlow = vi.fn().mockResolvedValue({ run: { id: "run-1", status: "succeeded" } });
+    const app = express(); app.use(express.json());
+    registerNodeFlowWebhookRoutes(app, { automationWebhookTriggerRepository: { authenticate }, nodeFlowService: { runFlow } } as never);
+
+    expect((await request(app).post("/api/webhooks/node-flows/path").send({ ok: true })).status).toBe(401);
+    const accepted = await request(app).post("/api/webhooks/node-flows/path")
+      .set("x-codeux-webhook-secret", "secret").send({ ok: true });
+    expect(accepted.status).toBe(202);
+    expect(runFlow).toHaveBeenCalledWith("project-1", "flow-1", { ok: true }, expect.objectContaining({ triggerType: "webhook" }));
+  });
+});
diff --git a/tests/backend/services/node-flow-builtins.test.ts b/tests/backend/services/node-flow-builtins.test.ts
new file mode 100644
index 0000000000..5134bcbb69
--- /dev/null
+++ b/tests/backend/services/node-flow-builtins.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { BuiltinExecutors, MAX_FOREACH_ITEMS } from "../../../src/services/node-flows/builtins/builtin-executors.js";
+
+const base = { projectId: "p", flowId: "f", publicationId: "pub", runId: "r", nodeId: "n", upstream: {}, flowInput: {}, subflowDepth: 0 };
+
+describe("governed built-in executors", () => {
+  it("selects explicit condition and switch ports", async () => {
+    const executors = new BuiltinExecutors();
+    await expect(executors.execute("condition", { ...base, flowInput: { enabled: true }, config: { path: "input.enabled" } }))
+      .resolves.toMatchObject({ selectedPorts: ["true"] });
+    await expect(executors.execute("switch", { ...base, flowInput: { tier: "pro" }, config: { path: "input.tier", cases: [{ id: "paid", value: "pro" }] } }))
+      .resolves.toMatchObject({ selectedPorts: ["paid"] });
+  });
+
+  it("bounds foreach and delay", async () => {
+    const executors = new BuiltinExecutors();
+    await expect(executors.execute("foreach", { ...base, upstream: { items: Array(MAX_FOREACH_ITEMS + 1).fill(null) }, config: { path: "upstream.items" } }))
+      .rejects.toThrow(/bounded item limit/i);
+    await expect(executors.execute("delay", { ...base, config: { delayMs: 3_600_001 } })).rejects.toThrow(/Delay must be between/i);
+  });
+
+  it("supports deterministic merge strategies and subflow recursion guards", async () => {
+    const executors = new BuiltinExecutors({ executeSubflow: async () => ({ ok: true }) });
+    await expect(executors.execute("merge", { ...base, upstream: { a: { one: 1 }, b: { two: 2 } }, config: { strategy: "object" } }))
+      .resolves.toMatchObject({ output: { one: 1, two: 2 } });
+    await expect(executors.execute("execute_subflow", { ...base, config: { flowId: "f" } })).rejects.toThrow(/cannot directly execute itself/i);
+  });
+});
diff --git a/tests/backend/services/node-flow-egress-policy-service.test.ts b/tests/backend/services/node-flow-egress-policy-service.test.ts
new file mode 100644
index 0000000000..4eee4f284a
--- /dev/null
+++ b/tests/backend/services/node-flow-egress-policy-service.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it, vi } from "vitest";
+import { EgressPolicyService } from "../../../src/services/node-flows/egress-policy-service.js";
+
+const publicLookup = async (): Promise<Array<{ address: string; family: number }>> => [{ address: "8.8.8.8", family: 4 }];
+
+describe("EgressPolicyService", () => {
+  it.each([
+    "https://127.0.0.1/x", "https://10.0.0.1/x", "https://169.254.169.254/latest/meta-data",
+    "https://metadata.google.internal/x", "https://localhost/x", "https://[::1]/x",
+  ])("rejects private, loopback, and metadata target %s", async (url) => {
+    await expect(new EgressPolicyService().validateUrl(url)).rejects.toThrow(/private|loopback|metadata/i);
+  });
+
+  it("requires HTTPS, rejects URL credentials and raw credential headers", async () => {
+    const service = new EgressPolicyService({ lookup: publicLookup });
+    await expect(service.validateUrl("http://api.example.test/x")).rejects.toThrow(/HTTPS/);
+    await expect(service.validateUrl("https://user:pass@api.example.test/x")).rejects.toThrow(/credentials/i);
+    await expect(service.request({ url: "https://api.example.test/x", headers: { Authorization: "Bearer raw" } })).rejects.toThrow(/restricted/i);
+  });
+
+  it("detects rebinding and revalidates redirects", async () => {
+    let lookups = 0;
+    const rebinding = new EgressPolicyService({ lookup: async () => [{ address: ++lookups === 1 ? "8.8.8.8" : "127.0.0.1", family: 4 }] });
+    await expect(rebinding.validateUrl("https://api.example.test/x")).rejects.toThrow(/rebinding/i);
+
+    const fetchMock = vi.fn().mockResolvedValueOnce(new Response(null, { status: 302, headers: { location: "http://127.0.0.1/secret" } }));
+    const redirects = new EgressPolicyService({ lookup: publicLookup, fetch: fetchMock });
+    await expect(redirects.request({ url: "https://api.example.test/x" })).rejects.toThrow(/HTTPS|private/i);
+  });
+
+  it("bounds response size, retry count, and host allowlists", async () => {
+    const oversized = new EgressPolicyService({ lookup: publicLookup, fetch: vi.fn().mockResolvedValue(new Response("12345", { headers: { "content-type": "text/plain", "content-length": "5" } })) });
+    await expect(oversized.request({ url: "https://api.example.test/x", policy: { maxResponseBytes: 4 } })).rejects.toThrow(/size limit/i);
+    await expect(oversized.validateUrl("https://other.example.test/x", { allowedHosts: ["api.example.test"] })).rejects.toThrow(/allowlisted/i);
+
+    const fetchMock = vi.fn().mockImplementation(async () => new Response("retry", { status: 503, headers: { "content-type": "text/plain" } }));
+    const retries = new EgressPolicyService({ lookup: publicLookup, fetch: fetchMock });
+    const response = await retries.request({ url: "https://api.example.test/x", policy: { maxRetries: 2 } });
+    expect(response.status).toBe(503);
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+  });
+});
diff --git a/tests/backend/services/node-flow-oauth-broker.test.ts b/tests/backend/services/node-flow-oauth-broker.test.ts
new file mode 100644
index 0000000000..35bf55c516
--- /dev/null
+++ b/tests/backend/services/node-flow-oauth-broker.test.ts
@@ -0,0 +1,32 @@
+import { randomBytes } from "node:crypto";
+import { describe, expect, it, vi } from "vitest";
+import { InMemoryOAuthConnectionStore, OAuthBroker } from "../../../src/services/node-flows/oauth-broker.js";
+
+describe("OAuthBroker", () => {
+  it("uses encrypted PKCE state, rotates refresh tokens, checks scopes, health, and revocation", async () => {
+    const store = new InMemoryOAuthConnectionStore();
+    const client = {
+      exchangeCode: vi.fn().mockResolvedValue({ accessToken: "access-1", refreshToken: "refresh-1", expiresAt: new Date(Date.now() - 1).toISOString(), scopes: ["mail.send"] }),
+      refresh: vi.fn().mockResolvedValue({ accessToken: "access-2", refreshToken: "refresh-2", expiresAt: new Date(Date.now() + 60_000).toISOString(), scopes: ["mail.send"] }),
+      revoke: vi.fn().mockResolvedValue(undefined), health: vi.fn().mockResolvedValue(true),
+    };
+    const broker = new OAuthBroker({ key: randomBytes(32), store, client, allowedCallbackOrigins: ["https://app.example.test"] });
+    const started = broker.beginAuthorization({ connectionId: "mail", authorizationUrl: "https://oauth.example.test/authorize", redirectUri: "https://app.example.test/oauth/callback", scopes: ["mail.send"] });
+    expect(started.state).not.toContain("mail");
+    expect(new URL(started.authorizationUrl).searchParams.get("code_challenge_method")).toBe("S256");
+    await broker.completeAuthorization({ state: started.state, code: "code", callbackOrigin: "https://app.example.test" });
+    await expect(broker.getAccessToken("mail", ["mail.send"])).resolves.toBe("access-2");
+    await expect(broker.getAccessToken("mail", ["mail.read"])).rejects.toThrow(/scopes/i);
+    await expect(broker.health("mail")).resolves.toMatchObject({ healthy: true, scopes: ["mail.send"] });
+    await broker.revoke("mail");
+    await expect(broker.health("mail")).resolves.toMatchObject({ healthy: false });
+    expect(client.revoke).toHaveBeenCalled();
+  });
+
+  it("rejects callback-origin mismatches and tampered state", async () => {
+    const broker = new OAuthBroker({ key: randomBytes(32), store: new InMemoryOAuthConnectionStore(), client: { exchangeCode: vi.fn(), refresh: vi.fn() }, allowedCallbackOrigins: ["https://app.example.test"] });
+    const started = broker.beginAuthorization({ connectionId: "x", authorizationUrl: "https://oauth.example.test", redirectUri: "https://app.example.test/callback", scopes: [] });
+    await expect(broker.completeAuthorization({ state: `${started.state}x`, code: "x", callbackOrigin: "https://app.example.test" })).rejects.toThrow(/state is invalid/i);
+    await expect(broker.completeAuthorization({ state: started.state, code: "x", callbackOrigin: "https://evil.example.test" })).rejects.toThrow(/not allowlisted/i);
+  });
+});
diff --git a/tests/backend/services/node-flow-runtime-service.test.ts b/tests/backend/services/node-flow-runtime-service.test.ts
index 6a94053222..c08eeb0df2 100644
--- a/tests/backend/services/node-flow-runtime-service.test.ts
+++ b/tests/backend/services/node-flow-runtime-service.test.ts
@@ -1,6 +1,5 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import * as fs from "fs/promises";
-import * as http from "http";
 import * as os from "os";
 import * as path from "path";
 import { AppDbStorage } from "../../../src/repositories/app-db-storage.js";
@@ -13,10 +12,11 @@ import { NodeFlowRuntimeService } from "../../../src/services/node-flow-runtime-
 import type { ProviderExecutionService } from "../../../src/services/provider-execution-service.js";
 import type { NodeFlowGraph } from "../../../src/contracts/node-flow-types.js";
 import type { CredentialBroker } from "../../../src/services/credentials/credential-broker.js";
+import { EgressPolicyService } from "../../../src/services/node-flows/egress-policy-service.js";
 
 const tempDirs: string[] = [];
 
-async function createRuntime(providerExecutionService?: Partial<ProviderExecutionService>,credentialBroker?:Partial<CredentialBroker>): Promise<{
+async function createRuntime(providerExecutionService?: Partial<ProviderExecutionService>,credentialBroker?:Partial<CredentialBroker>, egressPolicyService?: EgressPolicyService): Promise<{
   dir: string;
   projectRepository: ProjectManagementRepository;
   nodeFlowRepository: NodeFlowRepository;
@@ -36,6 +36,7 @@ async function createRuntime(providerExecutionService?: Partial<ProviderExecutio
     settingsRepository: new SettingsRepository(path.join(dir, "settings.db")),
     providerExecutionService: providerExecutionService as ProviderExecutionService | undefined,
     credentialBroker: credentialBroker as CredentialBroker | undefined,
+    egressPolicyService,
     getDashboardSettings: () => DEFAULT_DASHBOARD_SETTINGS,
   });
   return { dir, projectRepository, nodeFlowRepository, executionRepository, runtime };
@@ -46,6 +47,30 @@ afterEach(async () => {
 });
 
 describe("NodeFlowRuntimeService", () => {
+  it("persists unselected condition branches as skipped while the selected branch runs", async () => {
+    const { dir, projectRepository, nodeFlowRepository, runtime } = await createRuntime();
+    const project = projectRepository.createProject({ name: "Branch Project", sourceType: "local", sourceRef: dir });
+    const flow = nodeFlowRepository.createFlow(project.id, { title: "Branch", graph: {
+      nodes: [
+        { id: "condition", type: "condition", title: "Condition", data: { path: "input.enabled" } },
+        { id: "yes", type: "set_fields", title: "Yes", data: { fields: { branch: "yes" } } },
+        { id: "no", type: "set_fields", title: "No", data: { fields: { branch: "no" } } },
+        { id: "merge", type: "merge", title: "Merge", data: { strategy: "object" } },
+        { id: "output", type: "output", title: "Output" },
+      ],
+      edges: [
+        { fromNodeId: "condition", fromHandle: "true", toNodeId: "yes" },
+        { fromNodeId: "condition", fromHandle: "false", toNodeId: "no" },
+        { fromNodeId: "yes", toNodeId: "merge" }, { fromNodeId: "no", toNodeId: "merge" },
+        { fromNodeId: "merge", toNodeId: "output" },
+      ],
+    } });
+    const result = await runtime.runFlow(project.id, flow.id, { enabled: true });
+    expect(result.run.status).toBe("succeeded");
+    expect(result.nodeRuns.find((node) => node.nodeId === "no")?.status).toBe("skipped");
+    expect(result.output).toMatchObject({ branch: "yes" });
+  });
+
   it("executes an explicitly pinned publication while latest selection follows the newest publication", async () => {
     const { dir, projectRepository, nodeFlowRepository, runtime } = await createRuntime();
     const project = projectRepository.createProject({ name: "Version Project", sourceType: "local", sourceRef: dir });
@@ -173,21 +198,12 @@ describe("NodeFlowRuntimeService", () => {
     expect(executionRepository.getExecutionInvocation(promptRun!.executionInvocationId!)?.type).toBe("node_flow_node");
   });
 
-  it("executes HTTP request nodes with query, body, timeout, and JSON response extraction", async () => {
-    const server = http.createServer((req, res) => {
-      if (req.url?.startsWith("/ok?name=Ada")) {
-        res.setHeader("content-type", "application/json");
-        res.end(JSON.stringify({ data: { message: "hello" } }));
-        return;
-      }
-      res.statusCode = 404;
-      res.end("not found");
-    });
-    await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
-    try {
-      const address = server.address();
-      const port = typeof address === "object" && address ? address.port : 0;
-      const { dir, projectRepository, nodeFlowRepository, runtime } = await createRuntime();
+  it("executes governed HTTP request nodes with query, body, timeout, and JSON response extraction", async () => {
+      const fetchMock = vi.fn().mockResolvedValue(new Response(JSON.stringify({ data: { message: "hello" } }), {
+        status: 200, headers: { "content-type": "application/json" },
+      }));
+      const egressPolicyService = new EgressPolicyService({ fetch: fetchMock, lookup: async () => [{ address: "8.8.8.8", family: 4 }] });
+      const { dir, projectRepository, nodeFlowRepository, runtime } = await createRuntime(undefined, undefined, egressPolicyService);
       const project = projectRepository.createProject({ name: "HTTP Project", sourceType: "local", sourceRef: dir });
       const flow = nodeFlowRepository.createFlow(project.id, {
         title: "HTTP",
@@ -199,7 +215,7 @@ describe("NodeFlowRuntimeService", () => {
               title: "HTTP",
               data: {
                 method: "POST",
-                url: `http://127.0.0.1:${port}/ok`,
+                url: "https://api.example.test/ok",
                 query: { name: "Ada" },
                 body: { ok: true },
                 timeout: 1000,
@@ -216,9 +232,7 @@ describe("NodeFlowRuntimeService", () => {
       expect(result.run.status).toBe("succeeded");
       expect(result.output).toMatchObject({ status: 200, extracted: "hello" });
       expect(result.nodeRuns[0]?.executionInvocationId).toMatch(/^xi_/);
-    } finally {
-      await new Promise<void>((resolve) => server.close(() => resolve()));
-    }
+      expect(fetchMock).toHaveBeenCalledWith(expect.objectContaining({ search: "?name=Ada" }), expect.objectContaining({ redirect: "manual" }));
   });
 
   it("fails HTTP nodes clearly and skips downstream nodes without continueOnError", async () => {

From 4b389d6f6627c322b2a44057a0abd50878268fe0 Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 05:49:21 +0000
Subject: [PATCH 05/25] feat(task T05): implement via codex

---
 .code-ux/nodes/README.md                      |   5 +
 docs-web/architecture/custom-nodes.md         |  31 ++
 docs-web/architecture/index.md                |   1 +
 .../docs/architecture-custom-nodes.mdx        |  31 ++
 .../content/docs/architecture-overview.mdx    |   1 +
 docs-web/content/docs/registry.ts             |   9 +
 .../docs.architecture-custom-nodes.lazy.tsx   |  11 +
 docs/SUMMARY.md                               |   1 +
 docs/architecture/custom-nodes.md             |  63 ++++
 docs/index.md                                 |   2 +
 .../dependency-factory/dashboard-factory.ts   |  17 +-
 src/contracts/custom-node-types.ts            | 229 ++++++++++++
 src/contracts/node-definition-types.ts        |   2 +-
 .../node-flows/node-definition-registry.ts    |  16 +-
 src/repositories/custom-node-repository.ts    | 189 ++++++++++
 src/repositories/db/app-db-migrations.ts      |  50 +++
 .../custom-nodes/custom-node-build-service.ts | 339 ++++++++++++++++++
 .../custom-node-project-service.ts            | 133 +++++++
 .../custom-node-runtime-service.ts            | 196 ++++++++++
 src/services/node-flow-runtime-service.ts     |  45 ++-
 .../custom-node-repository.test.ts            |  50 +++
 .../services/custom-node-services.test.ts     | 150 ++++++++
 22 files changed, 1564 insertions(+), 7 deletions(-)
 create mode 100644 .code-ux/nodes/README.md
 create mode 100644 docs-web/architecture/custom-nodes.md
 create mode 100644 docs-web/content/docs/architecture-custom-nodes.mdx
 create mode 100644 docs-web/routes/docs.architecture-custom-nodes.lazy.tsx
 create mode 100644 docs/architecture/custom-nodes.md
 create mode 100644 src/contracts/custom-node-types.ts
 create mode 100644 src/repositories/custom-node-repository.ts
 create mode 100644 src/services/custom-nodes/custom-node-build-service.ts
 create mode 100644 src/services/custom-nodes/custom-node-project-service.ts
 create mode 100644 src/services/custom-nodes/custom-node-runtime-service.ts
 create mode 100644 tests/backend/repositories/custom-node-repository.test.ts
 create mode 100644 tests/backend/services/custom-node-services.test.ts

diff --git a/.code-ux/nodes/README.md b/.code-ux/nodes/README.md
new file mode 100644
index 0000000000..59a8616080
--- /dev/null
+++ b/.code-ux/nodes/README.md
@@ -0,0 +1,5 @@
+# Custom node packages
+
+Code UX generates each project-owned TypeScript node under `.code-ux/nodes/<node-id>/`.
+Packages are drafts until container validation passes and an immutable artifact is explicitly published.
+Generated source is never imported or executed by the Code UX server process.
diff --git a/docs-web/architecture/custom-nodes.md b/docs-web/architecture/custom-nodes.md
new file mode 100644
index 0000000000..904d7b70a2
--- /dev/null
+++ b/docs-web/architecture/custom-nodes.md
@@ -0,0 +1,31 @@
+# Custom Node Architecture and Security
+
+Custom nodes are project-owned TypeScript packages that pass explicit validation and publication gates before Code UX can execute them. Generated code is never imported or evaluated by the Code UX server.
+
+## Availability
+
+Custom execution is available only for an immutable published type/version and only while the `CODE_UX_CUSTOM_NODES_ENABLED=true` feature gate is enabled. Unpublished definitions are absent from the executable registry, and a disabled gate rejects a run before credential resolution or Docker startup. No dashboard or public management route bypasses these gates.
+
+## Generated package and validation
+
+Packages live at `.code-ux/nodes/<node-id>/` and include a manifest, exact package metadata, frozen pnpm lockfile, strict TypeScript configuration, typed local SDK, `src/index.ts`, an isolated runner, deterministic tests, fixtures, and a multi-stage Dockerfile.
+
+The SDK exposes immutable input/config, correlation and invocation ids, cancellation, a redacting logger, deterministic clock, bounded HTTP and credential slots, temporary storage, and artifacts. It does not expose the project path, host environment, raw filesystem, subprocesses, Docker, or raw networking.
+
+Validation fails closed on malformed schemas or identity, undeclared capabilities, excessive resources, symlinks, unpinned dependencies, lockfile drift, a modified trusted Docker recipe, prohibited APIs, vulnerability-audit failure, TypeScript or deterministic-test failure, fixture mismatch, output-schema failure, resource/network-policy failure, or secret-canary leakage. The exact recipe restores locked dependencies with lifecycle scripts disabled, then performs typecheck, build, and tests in a network-disabled stage. The vulnerability check is an injected governed hook; validation fails when it is not configured.
+
+A passed revision produces an immutable content-addressed envelope with source and build digests, immutable image id, dependency inventory, validation report, creator/invocation/correlation metadata, and declared capabilities. Publication registers only its typed definition and digest. Flow graphs never embed custom source.
+
+## Isolated execution
+
+Published images run as non-root with a read-only root, all capabilities dropped, `no-new-privileges`, optional seccomp/AppArmor profiles, bounded CPU/memory/PIDs/time/stdout, and a size-limited no-exec tmpfs. The runtime uses `--network none` and mounts neither the project nor the Docker socket nor persistent run state.
+
+Each invocation receives a fresh mode-`0600` stdin envelope. Credential values come only from the existing project-scoped `CredentialBroker`; they are never added to the environment, image, labels, cache keys, graph JSON, or persistent volume. The envelope and scratch state are deleted after the run.
+
+HTTP remains fail closed unless a transport backed by the existing `EgressPolicyService` is supplied. The default runner rejects HTTP rather than enabling bridge or host networking. Any future transport must preserve the existing host/port allowlists, DNS and redirect revalidation, response-size, timeout, retry, and rate bounds.
+
+The parent validates the output schema and recursively replaces resolved credential values in outputs, logs, traces, and diagnostics before persistence. Content-addressed image caching therefore retains immutable code only, not credentials or cross-run mutable state.
+
+## Persistence
+
+`custom_nodes` stores lifecycle state, `custom_node_artifacts` stores immutable artifact envelopes, and `custom_node_publications` binds a type/version to an artifact digest. The published versioned registry is the executable authority.
diff --git a/docs-web/architecture/index.md b/docs-web/architecture/index.md
index a82e90633e..4acab22faf 100644
--- a/docs-web/architecture/index.md
+++ b/docs-web/architecture/index.md
@@ -22,6 +22,7 @@ It is for contributors and integrators who need to reason about *how* Code UX ma
 | 12 | [Speech input](./speech-input.md) | Persisted transcription settings, privacy boundary, provider fallback contract |
 | 13 | [Security model](./security.md) | Authentication, authorisation, secrets, network surface |
 | 14 | [Worker clarification contract](./worker-clarification-contract.md) | Durable human-owned worker questions, idempotent replies, and continuation boundary |
+| 15 | [Custom nodes](./custom-nodes.md) | Generated TypeScript packages, validation/publication gates, and hardened container execution |
 
 ## Runtime Notes
 
diff --git a/docs-web/content/docs/architecture-custom-nodes.mdx b/docs-web/content/docs/architecture-custom-nodes.mdx
new file mode 100644
index 0000000000..904d7b70a2
--- /dev/null
+++ b/docs-web/content/docs/architecture-custom-nodes.mdx
@@ -0,0 +1,31 @@
+# Custom Node Architecture and Security
+
+Custom nodes are project-owned TypeScript packages that pass explicit validation and publication gates before Code UX can execute them. Generated code is never imported or evaluated by the Code UX server.
+
+## Availability
+
+Custom execution is available only for an immutable published type/version and only while the `CODE_UX_CUSTOM_NODES_ENABLED=true` feature gate is enabled. Unpublished definitions are absent from the executable registry, and a disabled gate rejects a run before credential resolution or Docker startup. No dashboard or public management route bypasses these gates.
+
+## Generated package and validation
+
+Packages live at `.code-ux/nodes/<node-id>/` and include a manifest, exact package metadata, frozen pnpm lockfile, strict TypeScript configuration, typed local SDK, `src/index.ts`, an isolated runner, deterministic tests, fixtures, and a multi-stage Dockerfile.
+
+The SDK exposes immutable input/config, correlation and invocation ids, cancellation, a redacting logger, deterministic clock, bounded HTTP and credential slots, temporary storage, and artifacts. It does not expose the project path, host environment, raw filesystem, subprocesses, Docker, or raw networking.
+
+Validation fails closed on malformed schemas or identity, undeclared capabilities, excessive resources, symlinks, unpinned dependencies, lockfile drift, a modified trusted Docker recipe, prohibited APIs, vulnerability-audit failure, TypeScript or deterministic-test failure, fixture mismatch, output-schema failure, resource/network-policy failure, or secret-canary leakage. The exact recipe restores locked dependencies with lifecycle scripts disabled, then performs typecheck, build, and tests in a network-disabled stage. The vulnerability check is an injected governed hook; validation fails when it is not configured.
+
+A passed revision produces an immutable content-addressed envelope with source and build digests, immutable image id, dependency inventory, validation report, creator/invocation/correlation metadata, and declared capabilities. Publication registers only its typed definition and digest. Flow graphs never embed custom source.
+
+## Isolated execution
+
+Published images run as non-root with a read-only root, all capabilities dropped, `no-new-privileges`, optional seccomp/AppArmor profiles, bounded CPU/memory/PIDs/time/stdout, and a size-limited no-exec tmpfs. The runtime uses `--network none` and mounts neither the project nor the Docker socket nor persistent run state.
+
+Each invocation receives a fresh mode-`0600` stdin envelope. Credential values come only from the existing project-scoped `CredentialBroker`; they are never added to the environment, image, labels, cache keys, graph JSON, or persistent volume. The envelope and scratch state are deleted after the run.
+
+HTTP remains fail closed unless a transport backed by the existing `EgressPolicyService` is supplied. The default runner rejects HTTP rather than enabling bridge or host networking. Any future transport must preserve the existing host/port allowlists, DNS and redirect revalidation, response-size, timeout, retry, and rate bounds.
+
+The parent validates the output schema and recursively replaces resolved credential values in outputs, logs, traces, and diagnostics before persistence. Content-addressed image caching therefore retains immutable code only, not credentials or cross-run mutable state.
+
+## Persistence
+
+`custom_nodes` stores lifecycle state, `custom_node_artifacts` stores immutable artifact envelopes, and `custom_node_publications` binds a type/version to an artifact digest. The published versioned registry is the executable authority.
diff --git a/docs-web/content/docs/architecture-overview.mdx b/docs-web/content/docs/architecture-overview.mdx
index d4d9c67af9..821388f8af 100644
--- a/docs-web/content/docs/architecture-overview.mdx
+++ b/docs-web/content/docs/architecture-overview.mdx
@@ -22,6 +22,7 @@ It is for contributors and integrators who need to reason about *how* Code UX ma
 | 12 | [Speech input](/docs/architecture-speech-input) | Persisted transcription settings, privacy boundary, provider fallback contract |
 | 13 | [Security model](/docs/architecture-security) | Authentication, authorisation, secrets, network surface |
 | 14 | [Worker clarification contract](/docs/architecture-worker-clarification-contract) | Durable human-owned worker questions, idempotent replies, and continuation boundary |
+| 15 | [Custom nodes](/docs/architecture-custom-nodes) | Generated TypeScript packages, validation/publication gates, and hardened container execution |
 
 ## Runtime Notes
 
diff --git a/docs-web/content/docs/registry.ts b/docs-web/content/docs/registry.ts
index 42d840a534..23b762da50 100644
--- a/docs-web/content/docs/registry.ts
+++ b/docs-web/content/docs/registry.ts
@@ -107,6 +107,7 @@ export type DocsSlug =
   | 'settings-google-drive-mount'
   | 'user-dashboard-custom-dashboards'
   | 'architecture-custom-dashboard-foundation'
+  | 'architecture-custom-nodes'
   | 'architecture-managed-container-runtime'
   | 'architecture-node-flow-builtins-and-security'
   | 'architecture-node-flow-durable-execution'
@@ -853,6 +854,13 @@ export const docsRegistry: Record<DocsSlug, DocsRegistryEntry> = {
     title: "Custom Dashboard Foundation",
     description: "Custom dashboards are a persisted domain model for project-scoped dashboard generation. The foundation stores manifests, generated file bundles, data-source node graphs, validation history, and publication state, and...",
   },
+  'architecture-custom-nodes': {
+    id: 'architecture-custom-nodes',
+    path: '/docs/architecture-custom-nodes',
+    section: 'Architecture',
+    title: "Custom Node Architecture and Security",
+    description: "Custom nodes are project-owned TypeScript packages that pass explicit validation and publication gates before Code UX can execute them. Generated code is never imported or evaluated by the Code UX server.",
+  },
   'architecture-managed-container-runtime': {
     id: 'architecture-managed-container-runtime',
     path: '/docs/architecture-managed-container-runtime',
@@ -1016,6 +1024,7 @@ export const orderedDocs: DocsRegistryEntry[] = [
   docsRegistry['settings-google-drive-mount'],
   docsRegistry['user-dashboard-custom-dashboards'],
   docsRegistry['architecture-custom-dashboard-foundation'],
+  docsRegistry['architecture-custom-nodes'],
   docsRegistry['architecture-managed-container-runtime'],
   docsRegistry['architecture-node-flow-builtins-and-security'],
   docsRegistry['architecture-node-flow-durable-execution'],
diff --git a/docs-web/routes/docs.architecture-custom-nodes.lazy.tsx b/docs-web/routes/docs.architecture-custom-nodes.lazy.tsx
new file mode 100644
index 0000000000..42fab00e9a
--- /dev/null
+++ b/docs-web/routes/docs.architecture-custom-nodes.lazy.tsx
@@ -0,0 +1,11 @@
+import { createLazyFileRoute } from '@tanstack/react-router'
+import ArchitectureCustomNodesContent from '../content/docs/architecture-custom-nodes.mdx'
+import { DocsPage } from '../components/docs/DocsPage'
+
+export const Route = createLazyFileRoute('/docs/architecture-custom-nodes')({
+  component: () => (
+    <DocsPage id="architecture-custom-nodes">
+      <ArchitectureCustomNodesContent />
+    </DocsPage>
+  )
+})
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 820eada147..1d7a3c0e6f 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -41,6 +41,7 @@
 - [Node Flows](./architecture/node-flows.md)
 - [Node Flow Durable Execution](./architecture/node-flow-durable-execution.md)
 - [Node Flow Built-ins and External-Effect Security](./architecture/node-flow-builtins-and-security.md)
+- [Custom Node Architecture and Security](./architecture/custom-nodes.md)
 - [Custom Dashboard Foundation](./architecture/custom-dashboard-foundation.md)
 - [Memory Claims and Evidence](./architecture/memory-claims.md)
 - [Speech Input Architecture](./architecture/speech-input.md)
diff --git a/docs/architecture/custom-nodes.md b/docs/architecture/custom-nodes.md
new file mode 100644
index 0000000000..78a6ea816e
--- /dev/null
+++ b/docs/architecture/custom-nodes.md
@@ -0,0 +1,63 @@
+# Custom Node Architecture and Security
+
+Custom nodes are project-owned TypeScript packages that move through an explicit draft, validation, publication, and container-execution boundary. Generated code is never imported, evaluated, or executed in the Code UX process.
+
+## Availability and gates
+
+Custom execution is available only when both gates pass:
+
+1. A source revision has completed validation, produced an immutable artifact, and been explicitly published.
+2. `CODE_UX_CUSTOM_NODES_ENABLED=true` (or an equivalent explicitly enabled runtime dependency) is active.
+
+An unpublished type/version is absent from the executable node-definition registry. A disabled feature gate rejects execution before credentials are resolved or Docker starts. There is no dashboard or public management route that bypasses these service gates.
+
+## Package contract
+
+`CustomNodeProjectService` generates `.code-ux/nodes/<node-id>/` with `node.json`, exact package metadata, a frozen pnpm lockfile, strict TypeScript configuration, `src/index.ts`, a local typed SDK, an isolated stdio runner, deterministic tests, fixtures, and a multi-stage Dockerfile.
+
+The handler receives only `NodeExecutionContext`: immutable JSON input/config, correlation and invocation ids, an abort signal, a redacting logger, a deterministic clock, bounded HTTP and credential slots, tmpfs-backed temporary storage, and artifact writing. It does not receive a project path, process environment, host filesystem handle, subprocess API, Docker handle, or raw network client.
+
+## Validation and publication
+
+`CustomNodeBuildService` changes a draft to `validating` and runs these fail-closed checks:
+
+- manifest identity, value schemas, credential slots, capabilities, and resource limits
+- package size, file count, symlink, exact dependency, and frozen-lockfile checks
+- prohibited API scans for filesystem, environment, subprocess, Docker, raw network, worker, and alternate-runtime access
+- least-privilege comparison between declared capabilities and SDK usage
+- a required vulnerability-audit hook
+- an exact trusted Docker recipe whose locked, script-disabled dependency restore is separate from network-disabled TypeScript, build, and deterministic-test stages
+- an isolated fixture execution with CPU, memory, PID, time, output, scratch, and network bounds
+- output-schema, deterministic expected-output, and secret-canary checks
+
+Any failed check records a `failed` report and no artifact. A passed build records dependency inventory, source revision, deterministic build digest, Docker image id, validation report, creator/invocation/correlation metadata, manifest, and declared capabilities. The artifact envelope is content-addressed and immutable. Publication stores only its digest and registers a typed `custom.*@version` definition; flow graph JSON contains the definition reference and configuration, never source.
+
+The audit hook is intentionally injected so custom nodes consume the governed dependency policy instead of creating a second vulnerability policy. With no hook, validation fails.
+
+## Runtime boundary
+
+`CustomNodeRuntimeService` resolves only a published artifact and launches its immutable image with:
+
+- `--network none`, never host networking
+- a non-root uid, read-only root filesystem, all Linux capabilities dropped, and `no-new-privileges`
+- optional configured seccomp and AppArmor profiles
+- CPU, memory/swap, PID, timeout, stdout, and tmpfs size limits from the validated manifest
+- no project mount, Docker socket, host environment, persistent volume, or cross-run writable state
+- a fresh stdin credential/input envelope and a fresh tmpfs scratch directory per invocation
+- Docker logging disabled; bounded stdout/stderr are captured by the parent
+
+Credential values are resolved through the existing `CredentialBroker` using the project, credential id, workspace, and required capability. They are never placed in an image layer, image label, cache key, graph, or process environment. The temporary stdin file is mode `0600`, removed after the invocation, and its in-memory values are cleared.
+
+The SDK's HTTP authority is fail closed unless a transport backed by the existing `EgressPolicyService` is supplied. The default network-none runner rejects HTTP calls; it never falls back to Docker bridge networking or a second allowlist. A future broker transport must retain the T02 host/port, DNS-rebinding, redirect, response-size, timeout, retry, and rate policies before enabling `network.http` publication.
+
+Outputs are schema-checked before persistence. Resolved credential canaries are recursively redacted from JSON output and replaced in logs and diagnostics. Run directories are unique and deleted after each invocation, so image caching retains only immutable code and cannot retain plaintext credentials or mutable run state.
+
+## Persistence
+
+SQLite separates mutable lifecycle state from immutable execution authority:
+
+- `custom_nodes` stores the current draft identity, lifecycle state, report, and selected artifact digest.
+- `custom_node_artifacts` stores immutable content-addressed artifact envelopes.
+- `custom_node_publications` binds one custom type/version to one artifact digest.
+
+This mirrors node-flow publication: the versioned registry remains the executable authority, while source stays in the project package directory.
diff --git a/docs/index.md b/docs/index.md
index d459e6830d..7c8f643b42 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -68,6 +68,7 @@ Use this page as the main entrypoint.
 30. [Node Flows](./architecture/node-flows.md)
 31. [Node Flow Durable Execution](./architecture/node-flow-durable-execution.md)
 32. [Node Flow Built-ins and External-Effect Security](./architecture/node-flow-builtins-and-security.md)
+33. [Custom Node Architecture and Security](./architecture/custom-nodes.md)
 31. [Custom Dashboard Foundation](./architecture/custom-dashboard-foundation.md)
 32. [Memory Claims and Evidence](./architecture/memory-claims.md)
 33. [Speech Input Architecture](./architecture/speech-input.md)
@@ -162,6 +163,7 @@ Use this page as the main entrypoint.
 - [Node Flows](./architecture/node-flows.md)
 - [Node Flow Durable Execution](./architecture/node-flow-durable-execution.md)
 - [Node Flow Built-ins and External-Effect Security](./architecture/node-flow-builtins-and-security.md)
+- [Custom Node Architecture and Security](./architecture/custom-nodes.md)
 - [Custom Dashboard Foundation](./architecture/custom-dashboard-foundation.md)
 - [Memory Claims and Evidence](./architecture/memory-claims.md)
 - [Speech Input Architecture](./architecture/speech-input.md)
diff --git a/src/app/dependency-factory/dashboard-factory.ts b/src/app/dependency-factory/dashboard-factory.ts
index 494ba30a63..32367a3a6f 100644
--- a/src/app/dependency-factory/dashboard-factory.ts
+++ b/src/app/dependency-factory/dashboard-factory.ts
@@ -39,6 +39,10 @@ import { EgressPolicyService } from "../../services/node-flows/egress-policy-ser
 import { AutomationApprovalRepository } from "../../repositories/automation-approval-repository.js";
 import { AutomationOutboxRepository } from "../../repositories/automation-outbox-repository.js";
 import { AutomationWebhookTriggerRepository } from "../../repositories/automation-webhook-trigger-repository.js";
+import { CustomNodeRepository } from "../../repositories/custom-node-repository.js";
+import { CustomNodeRuntimeService } from "../../services/custom-nodes/custom-node-runtime-service.js";
+import { customNodeDefinitionFromArtifact } from "../../contracts/custom-node-types.js";
+import { registerCustomNodeDefinition } from "../../domain/node-flows/node-definition-registry.js";
 
 export interface DashboardDependencies {
   credentialBroker: CoreDependencies["credentialBroker"];
@@ -237,6 +241,16 @@ export function createDashboardDependencies(
   const webhookTriggerRepository = coreDeps.automationWebhookTriggerRepository
     ?? new AutomationWebhookTriggerRepository(coreDeps.appDbStorage);
   const approvalService = new ApprovalService(approvalRepository);
+  const egressPolicyService = new EgressPolicyService();
+  const customNodeRepository = new CustomNodeRepository(coreDeps.appDbStorage);
+  for (const { artifact } of customNodeRepository.listPublications()) {
+    registerCustomNodeDefinition(customNodeDefinitionFromArtifact(artifact));
+  }
+  const customNodeRuntimeService = new CustomNodeRuntimeService({
+    repository: customNodeRepository,
+    credentialBroker: coreDeps.credentialBroker,
+    egressPolicyService,
+  });
   const nodeFlowRuntimeService = new NodeFlowRuntimeService({
     nodeFlowRepository: coreDeps.nodeFlowRepository,
     executionRepository,
@@ -244,7 +258,8 @@ export function createDashboardDependencies(
     settingsRepository,
     providerExecutionService,
     credentialBroker: coreDeps.credentialBroker,
-    egressPolicyService: new EgressPolicyService(),
+    egressPolicyService,
+    customNodeRuntimeService,
     approvalService,
     outboxService: new OutboxService(outboxRepository, new MockSideEffectProvider()),
     getDashboardSettings: (projectId) => resolveDashboardSettings({ projectId }),
diff --git a/src/contracts/custom-node-types.ts b/src/contracts/custom-node-types.ts
new file mode 100644
index 0000000000..0181a20880
--- /dev/null
+++ b/src/contracts/custom-node-types.ts
@@ -0,0 +1,229 @@
+import type { NodeDefinitionManifest } from "./node-definition-types.js";
+import type { NodeFlowJsonObject, NodeFlowJsonValue, NodeFlowValueSchema } from "./node-flow-types.js";
+
+export const CUSTOM_NODE_SCHEMA_VERSION = 1 as const;
+export const CUSTOM_NODE_FEATURE_FLAG = "CODE_UX_CUSTOM_NODES_ENABLED" as const;
+
+export type CustomNodeLifecycleStatus = "draft" | "validating" | "passed" | "failed" | "published";
+export type CustomNodeCapability =
+  | "network.http"
+  | "credentials.read"
+  | "temporary-storage.write"
+  | "artifacts.write"
+  | "clock.read";
+
+export interface CustomNodeCredentialSlot {
+  slot: string;
+  label: string;
+  required: boolean;
+  allowedKinds: string[];
+  requiredCapability: string;
+}
+
+export interface CustomNodeResourceLimits {
+  cpu: number;
+  memoryMb: number;
+  pids: number;
+  timeoutMs: number;
+  maxOutputBytes: number;
+  scratchMb: number;
+}
+
+export interface CustomNodeHttpPolicy {
+  allowedHosts: string[];
+  allowedPorts?: number[];
+  maxRequests: number;
+  timeoutMs: number;
+  maxResponseBytes: number;
+}
+
+export interface CustomNodeManifest {
+  schemaVersion: typeof CUSTOM_NODE_SCHEMA_VERSION;
+  id: string;
+  nodeType: string;
+  version: number;
+  name: string;
+  description: string;
+  entrypoint: "dist/index.js";
+  inputSchema: NodeFlowValueSchema;
+  outputSchema: NodeFlowValueSchema;
+  configurationSchema: NodeFlowValueSchema;
+  capabilities: CustomNodeCapability[];
+  credentials: CustomNodeCredentialSlot[];
+  resources: CustomNodeResourceLimits;
+  http?: CustomNodeHttpPolicy;
+}
+
+export interface CustomNodeLogger {
+  debug(message: string, fields?: NodeFlowJsonObject): void;
+  info(message: string, fields?: NodeFlowJsonObject): void;
+  warn(message: string, fields?: NodeFlowJsonObject): void;
+  error(message: string, fields?: NodeFlowJsonObject): void;
+}
+
+export interface CustomNodeHttpRequest {
+  url: string;
+  method?: "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
+  headers?: Record<string, string>;
+  body?: string;
+}
+
+export interface CustomNodeHttpResponse {
+  status: number;
+  headers: Record<string, string>;
+  body: string;
+}
+
+export interface CustomNodeArtifactWriter {
+  write(name: string, content: string | Uint8Array, mediaType: string): Promise<{ name: string; digest: string; size: number }>;
+}
+
+/** The only authority exposed to generated code. Implementations are supplied by the isolated runner. */
+export interface NodeExecutionContext {
+  input: Readonly<NodeFlowJsonObject>;
+  config: Readonly<NodeFlowJsonObject>;
+  correlationId: string;
+  invocationId: string;
+  signal: AbortSignal;
+  logger: CustomNodeLogger;
+  clock: { now(): string };
+  http: { request(request: CustomNodeHttpRequest): Promise<CustomNodeHttpResponse> };
+  credentials: { get(slot: string): Promise<string> };
+  temporaryStorage: {
+    read(path: string): Promise<Uint8Array | null>;
+    write(path: string, content: string | Uint8Array): Promise<void>;
+  };
+  artifacts: CustomNodeArtifactWriter;
+}
+
+export type CustomNodeHandler = (context: NodeExecutionContext) => Promise<NodeFlowJsonObject>;
+
+export interface CustomNodeValidationIssue {
+  check: string;
+  code: string;
+  message: string;
+}
+
+export interface CustomNodeValidationCheck {
+  name: string;
+  passed: boolean;
+  durationMs: number;
+  details?: string;
+}
+
+export interface CustomNodeValidationReport {
+  valid: boolean;
+  checks: CustomNodeValidationCheck[];
+  issues: CustomNodeValidationIssue[];
+  validatedAt: string;
+}
+
+export interface CustomNodeDependency {
+  name: string;
+  version: string;
+  integrity?: string;
+}
+
+export interface CustomNodeArtifact {
+  digest: string;
+  nodeId: string;
+  projectId: string;
+  version: number;
+  sourceRevision: string;
+  buildDigest: string;
+  runtimeImageDigest: string;
+  dependencies: CustomNodeDependency[];
+  validationReport: CustomNodeValidationReport;
+  createdBy: string;
+  invocationId: string;
+  correlationId: string;
+  capabilities: CustomNodeCapability[];
+  manifest: CustomNodeManifest;
+  createdAt: string;
+}
+
+export interface CustomNodeRecord {
+  id: string;
+  projectId: string;
+  status: CustomNodeLifecycleStatus;
+  sourceRevision: string;
+  manifest: CustomNodeManifest;
+  validationReport: CustomNodeValidationReport | null;
+  artifactDigest: string | null;
+  createdBy: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CustomNodePublication {
+  id: string;
+  nodeId: string;
+  projectId: string;
+  nodeType: string;
+  version: number;
+  artifactDigest: string;
+  publishedBy: string;
+  publishedAt: string;
+}
+
+export interface CustomNodeExecutionRequest {
+  projectId: string;
+  nodeType: string;
+  version: number;
+  input: NodeFlowJsonObject;
+  config: NodeFlowJsonObject;
+  credentialBindings: Record<string, string>;
+  workspaceId: string;
+  invocationId: string;
+  correlationId: string;
+  signal?: AbortSignal;
+}
+
+export interface CustomNodeExecutionResult {
+  output: NodeFlowJsonObject;
+  artifactDigest: string;
+  logs: string;
+  diagnostics: string;
+}
+
+export interface CreateCustomNodeDraftInput {
+  manifest: CustomNodeManifest;
+  sourceRevision: string;
+  createdBy: string;
+}
+
+export function customNodeDefinitionFromArtifact(artifact: CustomNodeArtifact): NodeDefinitionManifest {
+  const { manifest } = artifact;
+  return {
+    type: manifest.nodeType,
+    version: manifest.version,
+    executable: true,
+    executionKind: "custom",
+    configurationSchema: manifest.configurationSchema,
+    ui: {
+      label: manifest.name,
+      description: manifest.description,
+      category: "custom",
+      widgetSchema: { fields: [] },
+    },
+    ports: [
+      { id: "input", direction: "input", schema: manifest.inputSchema, cardinality: "many" },
+      { id: "output", direction: "output", schema: manifest.outputSchema, cardinality: "one" },
+    ],
+    credentials: manifest.credentials.map((slot) => ({
+      slot: slot.slot,
+      label: slot.label,
+      required: slot.required,
+      allowedKinds: [...slot.allowedKinds],
+    })),
+    capabilities: [...manifest.capabilities],
+    sideEffect: manifest.capabilities.includes("network.http") ? "external" : "none",
+    defaultPolicy: { retry: { maxAttempts: 1, backoffMs: 0 }, timeout: { timeoutMs: manifest.resources.timeoutMs } },
+    documentation: "docs/architecture/custom-nodes.md",
+    deprecation: { deprecated: false },
+  };
+}
+
+export function isNodeFlowJsonObject(value: NodeFlowJsonValue): value is NodeFlowJsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
diff --git a/src/contracts/node-definition-types.ts b/src/contracts/node-definition-types.ts
index 6e49a1fca6..9638fa2d0a 100644
--- a/src/contracts/node-definition-types.ts
+++ b/src/contracts/node-definition-types.ts
@@ -6,7 +6,7 @@ import type {
   NodeWidgetSchema,
 } from "./node-flow-types.js";
 
-export type NodeDefinitionExecutionKind = "local" | "provider" | "http" | "unavailable";
+export type NodeDefinitionExecutionKind = "local" | "provider" | "http" | "custom" | "unavailable";
 
 export interface NodeDefinitionCredentialRequirement {
   slot: string;
diff --git a/src/domain/node-flows/node-definition-registry.ts b/src/domain/node-flows/node-definition-registry.ts
index f32a23f8d5..960b1f3702 100644
--- a/src/domain/node-flows/node-definition-registry.ts
+++ b/src/domain/node-flows/node-definition-registry.ts
@@ -131,7 +131,7 @@ const manifests: NodeDefinitionManifest[] = [
 const keyFor = (type: string, version: number): string => `${type}@${version}`;
 const registry = new Map(manifests.map((manifest) => [keyFor(manifest.type, manifest.version), manifest]));
 
-export const listNodeDefinitions = (): readonly NodeDefinitionManifest[] => manifests;
+export const listNodeDefinitions = (): readonly NodeDefinitionManifest[] => [...manifests];
 
 export const resolveNodeDefinition = (type: string, version: number): NodeDefinitionManifest | null => (
   registry.get(keyFor(type, version)) ?? null
@@ -140,3 +140,17 @@ export const resolveNodeDefinition = (type: string, version: number): NodeDefini
 export const resolveLatestNodeDefinition = (type: string): NodeDefinitionManifest | null => (
   manifests.filter((manifest) => manifest.type === type).sort((left, right) => right.version - left.version)[0] ?? null
 );
+
+export const registerCustomNodeDefinition = (manifest: NodeDefinitionManifest): void => {
+  if (manifest.executionKind !== "custom" || !manifest.type.startsWith("custom.") || manifest.executable !== true) {
+    throw new Error("Only executable custom node definitions can be registered dynamically.");
+  }
+  const key = keyFor(manifest.type, manifest.version);
+  const existing = registry.get(key);
+  if (existing) {
+    if (JSON.stringify(existing) !== JSON.stringify(manifest)) throw new Error(`Node definition is immutable once registered: ${key}.`);
+    return;
+  }
+  registry.set(key, manifest);
+  manifests.push(manifest);
+};
diff --git a/src/repositories/custom-node-repository.ts b/src/repositories/custom-node-repository.ts
new file mode 100644
index 0000000000..f4d41d6ce5
--- /dev/null
+++ b/src/repositories/custom-node-repository.ts
@@ -0,0 +1,189 @@
+import { randomUUID } from "node:crypto";
+import type {
+  CreateCustomNodeDraftInput,
+  CustomNodeArtifact,
+  CustomNodeLifecycleStatus,
+  CustomNodeManifest,
+  CustomNodePublication,
+  CustomNodeRecord,
+  CustomNodeValidationReport,
+} from "../contracts/custom-node-types.js";
+import { AppDbStorage } from "./app-db-storage.js";
+import type { DatabaseAdapter } from "./db/database-adapter.js";
+import { EntityNotFoundError, ValidationError } from "./repository-utils.js";
+
+interface CustomNodeRow {
+  id: string;
+  project_id: string;
+  status: string;
+  source_revision: string;
+  manifest_json: string;
+  validation_report_json: string | null;
+  artifact_digest: string | null;
+  created_by: string;
+  created_at: string;
+  updated_at: string;
+}
+
+interface CustomNodeArtifactRow { artifact_json: string }
+interface CustomNodePublicationRow {
+  id: string; node_id: string; project_id: string; node_type: string; version: number | string;
+  artifact_digest: string; published_by: string; published_at: string;
+}
+
+const LIFECYCLE_STATUSES: readonly CustomNodeLifecycleStatus[] = ["draft", "validating", "passed", "failed", "published"];
+
+export class CustomNodeRepository {
+  private readonly db: DatabaseAdapter;
+
+  constructor(storage: AppDbStorage = new AppDbStorage()) {
+    this.db = storage.getDatabase();
+  }
+
+  createDraft(projectId: string, input: CreateCustomNodeDraftInput): CustomNodeRecord {
+    this.requireProject(projectId);
+    if (!input.sourceRevision.trim()) throw new ValidationError("Custom node source revision is required.");
+    if (!input.createdBy.trim()) throw new ValidationError("Custom node creator is required.");
+    const now = new Date().toISOString();
+    this.db.prepare(`
+      INSERT INTO custom_nodes (
+        id, project_id, status, source_revision, manifest_json, validation_report_json,
+        artifact_digest, created_by, created_at, updated_at
+      ) VALUES (?, ?, 'draft', ?, ?, NULL, NULL, ?, ?, ?)
+    `).run(input.manifest.id, projectId, input.sourceRevision.trim(), JSON.stringify(input.manifest), input.createdBy.trim(), now, now);
+    return this.requireNode(input.manifest.id);
+  }
+
+  getNode(nodeId: string): CustomNodeRecord | null {
+    const row = this.db.prepare("SELECT * FROM custom_nodes WHERE id = ?").get(nodeId) as CustomNodeRow | undefined;
+    return row ? this.mapNode(row) : null;
+  }
+
+  listProjectNodes(projectId: string): CustomNodeRecord[] {
+    this.requireProject(projectId);
+    return (this.db.prepare("SELECT * FROM custom_nodes WHERE project_id = ? ORDER BY updated_at DESC").all(projectId) as unknown as CustomNodeRow[])
+      .map((row) => this.mapNode(row));
+  }
+
+  beginValidation(nodeId: string): CustomNodeRecord {
+    const node = this.requireNode(nodeId);
+    if (node.status === "published") throw new ValidationError("Published custom node revisions are immutable.");
+    this.updateLifecycle(nodeId, "validating", null, null);
+    return this.requireNode(nodeId);
+  }
+
+  completeValidation(nodeId: string, report: CustomNodeValidationReport, artifact: CustomNodeArtifact | null): CustomNodeRecord {
+    const node = this.requireNode(nodeId);
+    if (node.status !== "validating") throw new ValidationError("Custom node must be validating before validation can complete.");
+    if (report.valid !== Boolean(artifact)) throw new ValidationError("Passed validation requires an artifact and failed validation must not publish one.");
+    if (artifact && (artifact.nodeId !== node.id || artifact.projectId !== node.projectId || artifact.sourceRevision !== node.sourceRevision)) {
+      throw new ValidationError("Custom node artifact does not match the validated draft.");
+    }
+    this.db.transaction(() => {
+      if (artifact) this.insertArtifact(artifact);
+      this.updateLifecycle(nodeId, report.valid ? "passed" : "failed", report, artifact?.digest ?? null);
+    });
+    return this.requireNode(nodeId);
+  }
+
+  publish(nodeId: string, publishedBy: string): CustomNodePublication {
+    const node = this.requireNode(nodeId);
+    if (node.status !== "passed" || !node.artifactDigest || node.validationReport?.valid !== true) {
+      throw new ValidationError("Only a passed custom node artifact can be published.");
+    }
+    if (!publishedBy.trim()) throw new ValidationError("Custom node publisher is required.");
+    const artifact = this.getArtifact(node.artifactDigest);
+    if (!artifact) throw new EntityNotFoundError(`Custom node artifact not found: ${node.artifactDigest}`);
+    const now = new Date().toISOString();
+    const publication: CustomNodePublication = {
+      id: randomUUID(), nodeId: node.id, projectId: node.projectId, nodeType: node.manifest.nodeType,
+      version: node.manifest.version, artifactDigest: artifact.digest, publishedBy: publishedBy.trim(), publishedAt: now,
+    };
+    this.db.transaction(() => {
+      this.db.prepare(`
+        INSERT INTO custom_node_publications (
+          id, node_id, project_id, node_type, version, artifact_digest, published_by, published_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(publication.id, publication.nodeId, publication.projectId, publication.nodeType, publication.version,
+        publication.artifactDigest, publication.publishedBy, publication.publishedAt);
+      this.updateLifecycle(node.id, "published", node.validationReport, node.artifactDigest);
+    });
+    return publication;
+  }
+
+  getArtifact(digest: string): CustomNodeArtifact | null {
+    const row = this.db.prepare("SELECT artifact_json FROM custom_node_artifacts WHERE digest = ?").get(digest) as CustomNodeArtifactRow | undefined;
+    return row ? JSON.parse(row.artifact_json) as CustomNodeArtifact : null;
+  }
+
+  resolvePublished(nodeType: string, version: number): { publication: CustomNodePublication; artifact: CustomNodeArtifact } | null {
+    const row = this.db.prepare("SELECT * FROM custom_node_publications WHERE node_type = ? AND version = ?")
+      .get(nodeType, version) as CustomNodePublicationRow | undefined;
+    if (!row) return null;
+    const publication = this.mapPublication(row);
+    const artifact = this.getArtifact(publication.artifactDigest);
+    return artifact ? { publication, artifact } : null;
+  }
+
+  listPublications(): Array<{ publication: CustomNodePublication; artifact: CustomNodeArtifact }> {
+    const rows = this.db.prepare("SELECT * FROM custom_node_publications ORDER BY published_at ASC").all() as unknown as CustomNodePublicationRow[];
+    return rows.flatMap((row) => {
+      const publication = this.mapPublication(row);
+      const artifact = this.getArtifact(publication.artifactDigest);
+      return artifact ? [{ publication, artifact }] : [];
+    });
+  }
+
+  private insertArtifact(artifact: CustomNodeArtifact): void {
+    const serialized = JSON.stringify(artifact);
+    const existing = this.db.prepare("SELECT artifact_json FROM custom_node_artifacts WHERE digest = ?").get(artifact.digest) as CustomNodeArtifactRow | undefined;
+    if (existing) {
+      if (existing.artifact_json !== serialized) throw new ValidationError("Content-addressed custom node artifact digest collision.");
+      return;
+    }
+    this.db.prepare(`
+      INSERT INTO custom_node_artifacts (digest, node_id, project_id, version, artifact_json, created_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `).run(artifact.digest, artifact.nodeId, artifact.projectId, artifact.version, serialized, artifact.createdAt);
+  }
+
+  private updateLifecycle(
+    nodeId: string,
+    status: CustomNodeLifecycleStatus,
+    report: CustomNodeValidationReport | null,
+    artifactDigest: string | null,
+  ): void {
+    this.db.prepare(`
+      UPDATE custom_nodes
+      SET status = ?, validation_report_json = ?, artifact_digest = ?, updated_at = ?
+      WHERE id = ?
+    `).run(status, report ? JSON.stringify(report) : null, artifactDigest, new Date().toISOString(), nodeId);
+  }
+
+  private requireProject(projectId: string): void {
+    if (!this.db.prepare("SELECT id FROM projects WHERE id = ?").get(projectId)) throw new EntityNotFoundError(`Project not found: ${projectId}`);
+  }
+
+  private requireNode(nodeId: string): CustomNodeRecord {
+    const node = this.getNode(nodeId);
+    if (!node) throw new EntityNotFoundError(`Custom node not found: ${nodeId}`);
+    return node;
+  }
+
+  private mapNode(row: CustomNodeRow): CustomNodeRecord {
+    if (!LIFECYCLE_STATUSES.includes(row.status as CustomNodeLifecycleStatus)) throw new ValidationError(`Invalid custom node status: ${row.status}`);
+    return {
+      id: row.id, projectId: row.project_id, status: row.status as CustomNodeLifecycleStatus,
+      sourceRevision: row.source_revision, manifest: JSON.parse(row.manifest_json) as CustomNodeManifest,
+      validationReport: row.validation_report_json ? JSON.parse(row.validation_report_json) as CustomNodeValidationReport : null,
+      artifactDigest: row.artifact_digest, createdBy: row.created_by, createdAt: row.created_at, updatedAt: row.updated_at,
+    };
+  }
+
+  private mapPublication(row: CustomNodePublicationRow): CustomNodePublication {
+    return {
+      id: row.id, nodeId: row.node_id, projectId: row.project_id, nodeType: row.node_type,
+      version: Number(row.version), artifactDigest: row.artifact_digest, publishedBy: row.published_by, publishedAt: row.published_at,
+    };
+  }
+}
diff --git a/src/repositories/db/app-db-migrations.ts b/src/repositories/db/app-db-migrations.ts
index 3206e63557..a83425e514 100644
--- a/src/repositories/db/app-db-migrations.ts
+++ b/src/repositories/db/app-db-migrations.ts
@@ -596,6 +596,55 @@ export function ensureAutomationCredentialTables(db: DatabaseAdapter): void {
   ensureIndex(db, "idx_automation_credential_rotations_credential", "automation_credential_rotations", "credential_id, rotated_at DESC");
 }
 
+export function ensureCustomNodeTables(db: DatabaseAdapter): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS custom_nodes (
+      id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'draft',
+      source_revision TEXT NOT NULL,
+      manifest_json TEXT NOT NULL,
+      validation_report_json TEXT,
+      artifact_digest TEXT,
+      created_by TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE
+    )
+  `);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS custom_node_artifacts (
+      digest TEXT PRIMARY KEY,
+      node_id TEXT NOT NULL,
+      project_id TEXT NOT NULL,
+      version INTEGER NOT NULL,
+      artifact_json TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      FOREIGN KEY (node_id) REFERENCES custom_nodes(id) ON DELETE CASCADE,
+      FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE
+    )
+  `);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS custom_node_publications (
+      id TEXT PRIMARY KEY,
+      node_id TEXT NOT NULL,
+      project_id TEXT NOT NULL,
+      node_type TEXT NOT NULL,
+      version INTEGER NOT NULL,
+      artifact_digest TEXT NOT NULL,
+      published_by TEXT NOT NULL,
+      published_at TEXT NOT NULL,
+      FOREIGN KEY (node_id) REFERENCES custom_nodes(id) ON DELETE CASCADE,
+      FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,
+      FOREIGN KEY (artifact_digest) REFERENCES custom_node_artifacts(digest),
+      UNIQUE (node_type, version)
+    )
+  `);
+  ensureIndex(db, "idx_custom_nodes_project_status", "custom_nodes", "project_id, status, updated_at DESC");
+  ensureIndex(db, "idx_custom_node_artifacts_node", "custom_node_artifacts", "node_id, version DESC");
+  ensureIndex(db, "idx_custom_node_publications_project", "custom_node_publications", "project_id, published_at DESC");
+}
+
 export function migrateSprintLinkedIssuesExternalSources(db: DatabaseAdapter): void {
   ensureColumn(db, "sprint_linked_issues", "project_key", "TEXT");
   ensureColumn(db, "sprint_linked_issues", "external_id", "TEXT");
@@ -833,6 +882,7 @@ export function runMigrations(db: DatabaseAdapter): void {
   migratePersistedNodeFlowGraphs(db);
   ensureCustomDashboardTables(db);
   ensureAutomationCredentialTables(db);
+  ensureCustomNodeTables(db);
 
   ensureColumn(db, "projects", "initialization_mode", "TEXT NOT NULL DEFAULT 'existing'");
   ensureColumn(db, "provider_invocations", "tool_call_count", "INTEGER NOT NULL DEFAULT 0");
diff --git a/src/services/custom-nodes/custom-node-build-service.ts b/src/services/custom-nodes/custom-node-build-service.ts
new file mode 100644
index 0000000000..7225c87ee3
--- /dev/null
+++ b/src/services/custom-nodes/custom-node-build-service.ts
@@ -0,0 +1,339 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import type {
+  CustomNodeArtifact,
+  CustomNodeCapability,
+  CustomNodeDependency,
+  CustomNodeManifest,
+  CustomNodeValidationCheck,
+  CustomNodeValidationIssue,
+  CustomNodeValidationReport,
+} from "../../contracts/custom-node-types.js";
+import { CUSTOM_NODE_SCHEMA_VERSION } from "../../contracts/custom-node-types.js";
+import type { CustomNodeRepository } from "../../repositories/custom-node-repository.js";
+import { EntityNotFoundError, ValidationError } from "../../repositories/repository-utils.js";
+import { customNodeDefinitionFromArtifact } from "../../contracts/custom-node-types.js";
+import { registerCustomNodeDefinition } from "../../domain/node-flows/node-definition-registry.js";
+import { runCommandStrict, type CommandResult } from "../cli-process-runner.js";
+import { createCustomNodeDockerfile, CustomNodeProjectService } from "./custom-node-project-service.js";
+import { buildCustomNodeDockerRunArgs, redactSecrets, validateValueAgainstSchema } from "./custom-node-runtime-service.js";
+
+const ALLOWED_CAPABILITIES = new Set<CustomNodeCapability>([
+  "network.http", "credentials.read", "temporary-storage.write", "artifacts.write", "clock.read",
+]);
+const SOURCE_LIMIT_BYTES = 2 * 1024 * 1024;
+const FILE_LIMIT = 256;
+const PROHIBITED_SOURCE_PATTERNS: Array<{ code: string; pattern: RegExp; message: string }> = [
+  { code: "host_filesystem", pattern: /(?:from\s*|import\s*\(|require\s*\()\s*["'](?:node:)?fs(?:\/promises)?["']|process\.cwd|import\.meta\.url/, message: "Host filesystem APIs are prohibited." },
+  { code: "host_environment", pattern: /process\.env|process\.argv|process\.execPath/, message: "Host process environment APIs are prohibited." },
+  { code: "subprocess", pattern: /["'](?:node:)?child_process["']|\bspawn\s*\(|\bexec(?:File)?\s*\(|\bfork\s*\(/, message: "Subprocess APIs are prohibited." },
+  { code: "docker", pattern: /\/var\/run\/docker\.sock|DOCKER_HOST|\bdocker\s+(?:run|exec|build)/i, message: "Docker access is prohibited." },
+  { code: "raw_network", pattern: /\bfetch\s*\(|["'](?:node:)?(?:http|https|net|tls|dns)(?:\/promises)?["']|\bWebSocket\b/, message: "Raw network APIs are prohibited; use context.http." },
+  { code: "native_escape", pattern: /["'](?:node:)?(?:worker_threads|cluster)["']|\bDeno\.|\bBun\./, message: "Native worker and alternate runtime APIs are prohibited." },
+];
+
+export interface CustomNodeAuditResult { passed: boolean; details: string }
+export interface ValidateCustomNodeInput {
+  projectRoot: string;
+  nodeId: string;
+  creator: string;
+  invocationId: string;
+  correlationId: string;
+  signal?: AbortSignal;
+}
+
+export interface CustomNodeBuildServiceDeps {
+  repository: CustomNodeRepository;
+  projectService?: CustomNodeProjectService;
+  commandRunner?: (command: string, args: string[], cwd: string, options?: { signal?: AbortSignal; timeout?: number; maxStdoutChars?: number; stdinFile?: string }) => Promise<CommandResult>;
+  vulnerabilityAudit?: (dependencies: readonly CustomNodeDependency[], signal?: AbortSignal) => Promise<CustomNodeAuditResult>;
+  runtimeImage?: string;
+}
+
+export class CustomNodeBuildService {
+  private readonly projectService: CustomNodeProjectService;
+
+  constructor(private readonly deps: CustomNodeBuildServiceDeps) {
+    this.projectService = deps.projectService ?? new CustomNodeProjectService();
+  }
+
+  publish(nodeId: string, publishedBy: string): CustomNodeArtifact {
+    const publication = this.deps.repository.publish(nodeId, publishedBy);
+    const artifact = this.deps.repository.getArtifact(publication.artifactDigest);
+    if (!artifact) throw new EntityNotFoundError(`Custom node artifact not found: ${publication.artifactDigest}`);
+    registerCustomNodeDefinition(customNodeDefinitionFromArtifact(artifact));
+    return artifact;
+  }
+
+  registerPublishedDefinitions(): number {
+    const published = this.deps.repository.listPublications();
+    for (const { artifact } of published) registerCustomNodeDefinition(customNodeDefinitionFromArtifact(artifact));
+    return published.length;
+  }
+
+  async validateAndBuild(input: ValidateCustomNodeInput): Promise<{ report: CustomNodeValidationReport; artifact: CustomNodeArtifact | null }> {
+    const node = this.deps.repository.getNode(input.nodeId);
+    if (!node) throw new EntityNotFoundError(`Custom node not found: ${input.nodeId}`);
+    const root = this.projectService.resolveNodeRoot(input.projectRoot, input.nodeId);
+    this.deps.repository.beginValidation(node.id);
+    const started = Date.now();
+    const checks: CustomNodeValidationCheck[] = [];
+    const issues: CustomNodeValidationIssue[] = [];
+    try {
+      const bundle = await readSourceBundle(root);
+      const manifest = parseManifest(bundle.get("node.json"));
+      runCheck("manifest-schema", checks, issues, () => validateManifest(manifest, node.manifest));
+      runCheck("prohibited-api-scan", checks, issues, () => scanProhibitedApis(bundle));
+      runCheck("capability-comparison", checks, issues, () => compareCapabilities(manifest, bundle));
+      const packageJson = parsePackageJson(bundle.get("package.json"));
+      const dependencies = dependencyInventory(packageJson);
+      runCheck("lockfile-verification", checks, issues, () => verifyLockfile(bundle.get("pnpm-lock.yaml"), dependencies));
+      runCheck("trusted-build-recipe", checks, issues, () => {
+        if (bundle.get("Dockerfile") !== createCustomNodeDockerfile()) throw new ValidationError("Custom node Dockerfile must match the trusted generated build recipe.");
+      });
+      runCheck("resource-policy", checks, issues, () => validateResourcePolicy(manifest));
+
+      if (issues.length === 0) {
+        const auditStarted = Date.now();
+        const audit = this.deps.vulnerabilityAudit
+          ? await this.deps.vulnerabilityAudit(dependencies, input.signal)
+          : { passed: false, details: "The governed vulnerability-audit hook is not configured." };
+        checks.push({ name: "vulnerability-audit", passed: audit.passed, durationMs: Date.now() - auditStarted, details: audit.details });
+        if (!audit.passed) issues.push({ check: "vulnerability-audit", code: "vulnerability_audit_failed", message: audit.details });
+      }
+
+      let runtimeImageDigest = "";
+      if (issues.length === 0) {
+        const sourceDigest = digestBundle(bundle);
+        const tag = `code-ux-custom-node:${sourceDigest.slice("sha256:".length, 28)}`;
+        const buildStarted = Date.now();
+        try {
+          await this.run("docker", ["build", "--pull=false", "--label", `code-ux.custom-node-source=${sourceDigest}`, "-t", tag, "."], root, input.signal, 10 * 60_000);
+          const inspect = await this.run("docker", ["image", "inspect", "--format", "{{.Id}}", tag], root, input.signal, 30_000);
+          runtimeImageDigest = inspect.stdout.trim();
+          if (!/^sha256:[a-f0-9]{64}$/i.test(runtimeImageDigest)) throw new Error("Docker returned a non-content-addressed image id.");
+          checks.push({ name: "typescript-and-tests", passed: true, durationMs: Date.now() - buildStarted, details: "Frozen install, typecheck, build, and deterministic tests completed in the image build." });
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          checks.push({ name: "typescript-and-tests", passed: false, durationMs: Date.now() - buildStarted, details: message });
+          issues.push({ check: "typescript-and-tests", code: "container_build_failed", message });
+        }
+
+        if (runtimeImageDigest && issues.length === 0) {
+          await this.validateFixture({ root, manifest, runtimeImageDigest, sourceDigest, input, checks, issues });
+        }
+
+        if (issues.length === 0) {
+          const report = reportFor(checks, issues);
+          const artifactSeed = {
+            nodeId: node.id, projectId: node.projectId, version: manifest.version,
+            sourceRevision: node.sourceRevision, buildDigest: sourceDigest, runtimeImageDigest,
+            dependencies, validationReport: report, createdBy: input.creator,
+            invocationId: input.invocationId, correlationId: input.correlationId,
+            capabilities: manifest.capabilities, manifest,
+          };
+          const createdAt = new Date().toISOString();
+          const digest = `sha256:${createHash("sha256").update(canonicalJson(artifactSeed)).digest("hex")}`;
+          const artifact: CustomNodeArtifact = { digest, ...artifactSeed, createdAt };
+          this.deps.repository.completeValidation(node.id, report, artifact);
+          return { report, artifact };
+        }
+      }
+    } catch (error) {
+      issues.push({ check: "validation", code: "validation_error", message: error instanceof Error ? error.message : String(error) });
+    }
+    const report = reportFor(checks, issues);
+    if (checks.length === 0) checks.push({ name: "validation", passed: false, durationMs: Date.now() - started, details: issues[0]?.message });
+    this.deps.repository.completeValidation(node.id, report, null);
+    return { report, artifact: null };
+  }
+
+  private async validateFixture(args: {
+    root: string; manifest: CustomNodeManifest; runtimeImageDigest: string; sourceDigest: string;
+    input: ValidateCustomNodeInput; checks: CustomNodeValidationCheck[]; issues: CustomNodeValidationIssue[];
+  }): Promise<void> {
+    const started = Date.now();
+    const runDirectory = await fs.mkdtemp(path.join(os.tmpdir(), "code-ux-custom-node-validation-"));
+    const canary = `CODEUX_SECRET_CANARY_${args.input.correlationId}`;
+    try {
+      const fixture = JSON.parse(await fs.readFile(path.join(args.root, "fixtures", "basic.json"), "utf8")) as { input: unknown; config: unknown; output: unknown };
+      if (!isObject(fixture.input) || !isObject(fixture.config) || !isObject(fixture.output)) throw new ValidationError("Fixture input, config, and output must be objects.");
+      const inputIssues = validateValueAgainstSchema(fixture.input, args.manifest.inputSchema, "fixture.input");
+      if (inputIssues.length) throw new ValidationError(inputIssues[0]!);
+      const envelope = { input: fixture.input, config: fixture.config, correlationId: args.input.correlationId, invocationId: args.input.invocationId, credentials: { __canary: canary }, now: "2026-01-01T00:00:00.000Z" };
+      const inputPath = path.join(runDirectory, "input.json");
+      await fs.writeFile(inputPath, JSON.stringify(envelope), { mode: 0o600 });
+      if (process.platform !== "win32") await fs.chmod(inputPath, 0o600);
+      const artifact = {
+        digest: args.sourceDigest, runtimeImageDigest: args.runtimeImageDigest, manifest: args.manifest,
+      } as CustomNodeArtifact;
+      const plan = buildCustomNodeDockerRunArgs({ artifact, containerName: `code-ux-custom-node-validation-${args.input.nodeId}` });
+      const result = await this.run("docker", plan, args.root, args.input.signal, args.manifest.resources.timeoutMs, inputPath);
+      const outputText = result.stdout;
+      if (Buffer.byteLength(outputText) > args.manifest.resources.maxOutputBytes) throw new ValidationError("Fixture output exceeded the declared limit.");
+      const output = JSON.parse(outputText) as unknown;
+      const outputIssues = validateValueAgainstSchema(output, args.manifest.outputSchema, "fixture.output");
+      if (outputIssues.length) throw new ValidationError(outputIssues[0]!);
+      if (canonicalJson(output) !== canonicalJson(fixture.output)) throw new ValidationError("Fixture output did not match the deterministic expected output.");
+      const observable = redactSecrets(`${result.stdout}\n${result.stderr}\n${outputText}`, [canary]);
+      if (observable.includes(canary)) throw new ValidationError("Secret canary survived output redaction.");
+      args.checks.push({ name: "fixture-resource-network-secret", passed: true, durationMs: Date.now() - started, details: "Fixture ran with network-none, bounded resources, an ephemeral scratch/run directory, and secret-canary redaction." });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      args.checks.push({ name: "fixture-resource-network-secret", passed: false, durationMs: Date.now() - started, details: message });
+      args.issues.push({ check: "fixture-resource-network-secret", code: "fixture_failed", message });
+    } finally {
+      await fs.rm(runDirectory, { recursive: true, force: true });
+    }
+  }
+
+  private async run(command: string, args: string[], cwd: string, signal: AbortSignal | undefined, timeout: number, stdinFile?: string): Promise<CommandResult> {
+    const runner = this.deps.commandRunner ?? ((cmd, argv, dir, options) => runCommandStrict(cmd, argv, dir, process.env, options));
+    return runner(command, args, cwd, { signal, timeout, maxStdoutChars: 1024 * 1024, stdinFile });
+  }
+}
+
+async function readSourceBundle(root: string): Promise<Map<string, string>> {
+  const bundle = new Map<string, string>();
+  const visit = async (directory: string): Promise<void> => {
+    for (const entry of await fs.readdir(directory, { withFileTypes: true })) {
+      const target = path.join(directory, entry.name);
+      const relative = path.relative(root, target).split(path.sep).join("/");
+      if (entry.isSymbolicLink()) throw new ValidationError(`Symbolic links are prohibited in custom node packages: ${relative}`);
+      if (entry.isDirectory()) {
+        if (!new Set(["node_modules", "dist", ".git"]).has(entry.name)) await visit(target);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (bundle.size >= FILE_LIMIT) throw new ValidationError("Custom node package contains too many files.");
+      const stat = await fs.stat(target);
+      if (stat.size > SOURCE_LIMIT_BYTES) throw new ValidationError(`Custom node file is too large: ${relative}`);
+      bundle.set(relative, await fs.readFile(target, "utf8"));
+    }
+  };
+  await visit(root);
+  for (const required of ["node.json", "package.json", "pnpm-lock.yaml", "tsconfig.json", "Dockerfile", "src/index.ts", "src/sdk.ts", "src/runner.ts", "tests/index.test.ts", "fixtures/basic.json"]) {
+    if (!bundle.has(required)) throw new ValidationError(`Custom node package is missing ${required}.`);
+  }
+  return bundle;
+}
+
+function parseManifest(value: string | undefined): CustomNodeManifest {
+  if (!value) throw new ValidationError("Custom node manifest is missing.");
+  try { return JSON.parse(value) as CustomNodeManifest; } catch { throw new ValidationError("Custom node manifest is invalid JSON."); }
+}
+
+function parsePackageJson(value: string | undefined): Record<string, unknown> {
+  if (!value) throw new ValidationError("Custom node package metadata is missing.");
+  try { const parsed = JSON.parse(value) as unknown; if (isObject(parsed)) return parsed; } catch { /* normalized below */ }
+  throw new ValidationError("Custom node package metadata is invalid JSON.");
+}
+
+function validateManifest(manifest: CustomNodeManifest, persisted: CustomNodeManifest): void {
+  if (manifest.schemaVersion !== CUSTOM_NODE_SCHEMA_VERSION) throw new ValidationError("Unsupported custom node manifest schema version.");
+  if (!/^[a-z][a-z0-9-]{2,63}$/.test(manifest.id) || manifest.nodeType !== `custom.${manifest.id}`) throw new ValidationError("Custom node id or type is invalid.");
+  if (manifest.id !== persisted.id || manifest.nodeType !== persisted.nodeType || manifest.version !== persisted.version) throw new ValidationError("Filesystem manifest does not match the persisted draft identity.");
+  if (!Number.isInteger(manifest.version) || manifest.version < 1 || manifest.entrypoint !== "dist/index.js") throw new ValidationError("Custom node version or entrypoint is invalid.");
+  for (const schema of [manifest.inputSchema, manifest.outputSchema, manifest.configurationSchema]) validateSchema(schema);
+  const slots = new Set<string>();
+  for (const slot of manifest.credentials) {
+    if (!/^[a-z][a-z0-9_-]{0,63}$/.test(slot.slot) || slots.has(slot.slot) || !slot.requiredCapability.trim()) throw new ValidationError("Custom node credential slots must be unique and valid.");
+    slots.add(slot.slot);
+  }
+  if (new Set(manifest.capabilities).size !== manifest.capabilities.length || manifest.capabilities.some((capability) => !ALLOWED_CAPABILITIES.has(capability))) throw new ValidationError("Custom node declares an unknown or duplicate capability.");
+  if (manifest.http && !manifest.capabilities.includes("network.http")) throw new ValidationError("HTTP policy requires network.http capability.");
+  if (manifest.capabilities.includes("network.http") && !manifest.http) throw new ValidationError("network.http capability requires a bounded HTTP policy.");
+  if (manifest.credentials.length && !manifest.capabilities.includes("credentials.read")) throw new ValidationError("Credential slots require credentials.read capability.");
+}
+
+function validateSchema(schema: unknown): void {
+  if (!isObject(schema) || !["any", "object", "array", "string", "number", "boolean", "null"].includes(String(schema.type))) throw new ValidationError("Custom node value schema is invalid.");
+  if (schema.type === "object" && schema.properties !== undefined) {
+    if (!isObject(schema.properties)) throw new ValidationError("Custom node schema properties must be an object.");
+    for (const child of Object.values(schema.properties)) validateSchema(child);
+  }
+  if (schema.type === "array" && schema.items !== undefined) validateSchema(schema.items);
+}
+
+function scanProhibitedApis(bundle: ReadonlyMap<string, string>): void {
+  for (const [file, source] of bundle) {
+    if (!file.startsWith("src/") || file === "src/sdk.ts" || file === "src/runner.ts") continue;
+    for (const rule of PROHIBITED_SOURCE_PATTERNS) if (rule.pattern.test(source)) throw new ValidationError(`${rule.message} (${file}, ${rule.code})`);
+  }
+}
+
+function compareCapabilities(manifest: CustomNodeManifest, bundle: ReadonlyMap<string, string>): void {
+  const source = [...bundle].filter(([file]) => file.startsWith("src/") && !["src/sdk.ts", "src/runner.ts"].includes(file)).map(([, content]) => content).join("\n");
+  const inferred = new Set<CustomNodeCapability>();
+  if (/context\.http\b/.test(source)) inferred.add("network.http");
+  if (/context\.credentials\b/.test(source)) inferred.add("credentials.read");
+  if (/context\.temporaryStorage\b/.test(source)) inferred.add("temporary-storage.write");
+  if (/context\.artifacts\b/.test(source)) inferred.add("artifacts.write");
+  if (/context\.clock\b/.test(source)) inferred.add("clock.read");
+  const declared = new Set(manifest.capabilities);
+  const missing = [...inferred].filter((capability) => !declared.has(capability));
+  const unused = [...declared].filter((capability) => !inferred.has(capability) && capability !== "credentials.read");
+  if (missing.length || unused.length) throw new ValidationError(`Declared capabilities must exactly match SDK usage (missing: ${missing.join(", ") || "none"}; unused: ${unused.join(", ") || "none"}).`);
+}
+
+function validateResourcePolicy(manifest: CustomNodeManifest): void {
+  const { resources } = manifest;
+  if (!(resources.cpu >= 0.1 && resources.cpu <= 4)) throw new ValidationError("Custom node CPU limit must be between 0.1 and 4.");
+  if (!Number.isInteger(resources.memoryMb) || resources.memoryMb < 32 || resources.memoryMb > 2048) throw new ValidationError("Custom node memory limit must be between 32 and 2048 MiB.");
+  if (!Number.isInteger(resources.pids) || resources.pids < 16 || resources.pids > 256) throw new ValidationError("Custom node PID limit must be between 16 and 256.");
+  if (!Number.isInteger(resources.timeoutMs) || resources.timeoutMs < 100 || resources.timeoutMs > 120_000) throw new ValidationError("Custom node timeout must be between 100 and 120000ms.");
+  if (!Number.isInteger(resources.maxOutputBytes) || resources.maxOutputBytes < 1024 || resources.maxOutputBytes > 2 * 1024 * 1024) throw new ValidationError("Custom node output limit is invalid.");
+  if (!Number.isInteger(resources.scratchMb) || resources.scratchMb < 1 || resources.scratchMb > 256) throw new ValidationError("Custom node scratch limit is invalid.");
+  if (manifest.http) {
+    if (!manifest.http.allowedHosts.length || manifest.http.allowedHosts.some((host) => !/^[a-z0-9.-]+$/i.test(host))) throw new ValidationError("Custom node HTTP hosts must be explicit DNS names.");
+    if (manifest.http.maxRequests < 1 || manifest.http.maxRequests > 100 || manifest.http.timeoutMs > resources.timeoutMs || manifest.http.maxResponseBytes > resources.maxOutputBytes) throw new ValidationError("Custom node HTTP policy exceeds resource bounds.");
+  }
+}
+
+function dependencyInventory(packageJson: Record<string, unknown>): CustomNodeDependency[] {
+  const result: CustomNodeDependency[] = [];
+  for (const field of ["dependencies", "devDependencies"] as const) {
+    const dependencies = packageJson[field];
+    if (!isObject(dependencies)) continue;
+    for (const [name, version] of Object.entries(dependencies)) {
+      if (typeof version !== "string" || !/^[0-9]+\.[0-9]+\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?$/.test(version)) throw new ValidationError(`Dependency ${name} must use an exact version.`);
+      result.push({ name, version });
+    }
+  }
+  return result.sort((left, right) => left.name.localeCompare(right.name));
+}
+
+function verifyLockfile(lockfile: string | undefined, dependencies: readonly CustomNodeDependency[]): void {
+  if (!lockfile?.startsWith("lockfileVersion: '9.0'")) throw new ValidationError("A pnpm v9 frozen lockfile is required.");
+  for (const dependency of dependencies) {
+    if (!lockfile.includes(`specifier: ${dependency.version}`) || !lockfile.includes(`version: ${dependency.version}`)) throw new ValidationError(`Lockfile does not pin ${dependency.name}@${dependency.version}.`);
+  }
+}
+
+function digestBundle(bundle: ReadonlyMap<string, string>): string {
+  const hash = createHash("sha256");
+  for (const [file, content] of [...bundle].sort(([left], [right]) => left.localeCompare(right))) hash.update(file).update("\0").update(content).update("\0");
+  return `sha256:${hash.digest("hex")}`;
+}
+
+function runCheck(name: string, checks: CustomNodeValidationCheck[], issues: CustomNodeValidationIssue[], action: () => void): void {
+  const started = Date.now();
+  try { action(); checks.push({ name, passed: true, durationMs: Date.now() - started }); }
+  catch (error) { const message = error instanceof Error ? error.message : String(error); checks.push({ name, passed: false, durationMs: Date.now() - started, details: message }); issues.push({ check: name, code: `${name.replace(/-/g, "_")}_failed`, message }); }
+}
+
+function reportFor(checks: CustomNodeValidationCheck[], issues: CustomNodeValidationIssue[]): CustomNodeValidationReport {
+  return { valid: issues.length === 0, checks, issues, validatedAt: new Date().toISOString() };
+}
+
+function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (isObject(value)) return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+  return JSON.stringify(value);
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
diff --git a/src/services/custom-nodes/custom-node-project-service.ts b/src/services/custom-nodes/custom-node-project-service.ts
new file mode 100644
index 0000000000..fb33698a2a
--- /dev/null
+++ b/src/services/custom-nodes/custom-node-project-service.ts
@@ -0,0 +1,133 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { CustomNodeManifest } from "../../contracts/custom-node-types.js";
+import { CUSTOM_NODE_SCHEMA_VERSION } from "../../contracts/custom-node-types.js";
+import { ValidationError } from "../../repositories/repository-utils.js";
+
+const NODE_ID_PATTERN = /^[a-z][a-z0-9-]{2,63}$/;
+
+export interface GenerateCustomNodeProjectInput {
+  projectRoot: string;
+  nodeId: string;
+  name: string;
+  description?: string;
+  overwrite?: boolean;
+}
+
+export interface GeneratedCustomNodeProject {
+  root: string;
+  manifest: CustomNodeManifest;
+  files: string[];
+}
+
+export class CustomNodeProjectService {
+  async generate(input: GenerateCustomNodeProjectInput): Promise<GeneratedCustomNodeProject> {
+    const nodeId = input.nodeId.trim();
+    if (!NODE_ID_PATTERN.test(nodeId)) {
+      throw new ValidationError("Custom node id must be 3-64 lowercase letters, numbers, or hyphens and start with a letter.");
+    }
+    const projectRoot = path.resolve(input.projectRoot);
+    const root = path.resolve(projectRoot, ".code-ux", "nodes", nodeId);
+    this.requireContained(projectRoot, root);
+    if (!input.overwrite) {
+      await fs.access(root).then(
+        () => { throw new ValidationError(`Custom node project already exists: ${nodeId}`); },
+        () => undefined,
+      );
+    } else {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+
+    const manifest = defaultManifest(nodeId, input.name, input.description ?? "");
+    const files = projectFiles(manifest);
+    await fs.mkdir(root, { recursive: true, mode: 0o700 });
+    for (const [relativePath, content] of Object.entries(files)) {
+      const target = path.resolve(root, relativePath);
+      this.requireContained(root, target);
+      await fs.mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+      await fs.writeFile(target, content, { encoding: "utf8", mode: 0o600 });
+    }
+    return { root, manifest, files: Object.keys(files).sort() };
+  }
+
+  async readManifest(projectRoot: string, nodeId: string): Promise<CustomNodeManifest> {
+    const root = this.resolveNodeRoot(projectRoot, nodeId);
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(await fs.readFile(path.join(root, "node.json"), "utf8"));
+    } catch (error) {
+      throw new ValidationError(`Unable to read custom node manifest: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return parsed as CustomNodeManifest;
+  }
+
+  resolveNodeRoot(projectRoot: string, nodeId: string): string {
+    if (!NODE_ID_PATTERN.test(nodeId)) throw new ValidationError("Invalid custom node id.");
+    const base = path.resolve(projectRoot);
+    const root = path.resolve(base, ".code-ux", "nodes", nodeId);
+    this.requireContained(base, root);
+    return root;
+  }
+
+  private requireContained(basePath: string, targetPath: string): void {
+    const relative = path.relative(basePath, targetPath);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) throw new ValidationError("Custom node path escapes the project root.");
+  }
+}
+
+function defaultManifest(nodeId: string, name: string, description: string): CustomNodeManifest {
+  return {
+    schemaVersion: CUSTOM_NODE_SCHEMA_VERSION,
+    id: nodeId,
+    nodeType: `custom.${nodeId}`,
+    version: 1,
+    name: name.trim() || nodeId,
+    description: description.trim(),
+    entrypoint: "dist/index.js",
+    inputSchema: { type: "object" },
+    outputSchema: { type: "object" },
+    configurationSchema: { type: "object" },
+    capabilities: ["clock.read"],
+    credentials: [],
+    resources: { cpu: 0.5, memoryMb: 128, pids: 64, timeoutMs: 30_000, maxOutputBytes: 262_144, scratchMb: 32 },
+  };
+}
+
+function projectFiles(manifest: CustomNodeManifest): Record<string, string> {
+  const packageName = `@codeux-custom/${manifest.id}`;
+  return {
+    "node.json": `${JSON.stringify(manifest, null, 2)}\n`,
+    "package.json": `${JSON.stringify({
+      name: packageName, version: `${manifest.version}.0.0`, private: true, type: "module", packageManager: "pnpm@10.33.0",
+      scripts: { typecheck: "tsc --noEmit", build: "tsc", test: "node --test dist/tests/*.test.js" },
+      devDependencies: { "@types/node": "25.6.0", typescript: "5.9.3" },
+    }, null, 2)}\n`,
+    "pnpm-lock.yaml": lockfile(packageName),
+    "tsconfig.json": `${JSON.stringify({ compilerOptions: {
+      target: "ES2022", module: "NodeNext", moduleResolution: "NodeNext", strict: true,
+      outDir: "dist", rootDir: ".", declaration: true, noUncheckedIndexedAccess: true,
+    }, include: ["src/**/*.ts", "tests/**/*.ts"] }, null, 2)}\n`,
+    "src/sdk.ts": sdkSource(),
+    "src/index.ts": `import type { CustomNodeHandler } from "./sdk.js";\n\nexport const run: CustomNodeHandler = async (context) => {\n  context.logger.info("custom node started", { correlationId: context.correlationId });\n  return { ...context.input, executedAt: context.clock.now() };\n};\n`,
+    "src/runner.ts": runnerSource(),
+    "tests/index.test.ts": `import assert from "node:assert/strict";\nimport test from "node:test";\nimport { run } from "../src/index.js";\n\ntest("returns deterministic fixture output", async () => {\n  const context = { input: { value: 1 }, config: {}, correlationId: "fixture", invocationId: "fixture", signal: new AbortController().signal, logger: { debug() {}, info() {}, warn() {}, error() {} }, clock: { now: () => "2026-01-01T00:00:00.000Z" }, http: { request: async () => { throw new Error("not declared"); } }, credentials: { get: async () => { throw new Error("not declared"); } }, temporaryStorage: { read: async () => null, write: async () => undefined }, artifacts: { write: async (name: string, content: string | Uint8Array) => ({ name, digest: "fixture", size: typeof content === "string" ? content.length : content.byteLength }) } };\n  assert.deepEqual(await run(context), { value: 1, executedAt: "2026-01-01T00:00:00.000Z" });\n});\n`,
+    "fixtures/basic.json": `${JSON.stringify({ input: { value: 1 }, config: {}, output: { value: 1, executedAt: "2026-01-01T00:00:00.000Z" } }, null, 2)}\n`,
+    "Dockerfile": createCustomNodeDockerfile(),
+  };
+}
+
+function lockfile(packageName: string): string {
+  return `lockfileVersion: '9.0'\n\nsettings:\n  autoInstallPeers: false\n  excludeLinksFromLockfile: false\n\nimporters:\n  .:\n    devDependencies:\n      '@types/node':\n        specifier: 25.6.0\n        version: 25.6.0\n      typescript:\n        specifier: 5.9.3\n        version: 5.9.3\n\npackages:\n  '@types/node@25.6.0':\n    resolution: {integrity: sha512-+qIYRKdNYJwY3vRCZMdJbPLJAtGjQBudzZzdzwQYkEPQd+PJGixUL5QfvCLDaULoLv+RhT3LDkwEfKaAkgSmNQ==}\n  typescript@5.9.3:\n    resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}\n    engines: {node: '>=14.17'}\n    hasBin: true\n  undici-types@7.19.2:\n    resolution: {integrity: sha512-qYVnV5OEm2AW8cJMCpdV20CDyaN3g0AjDlOGf1OW4iaDEx8MwdtChUp4zu4H0VP3nDRF/8RKWH+IPp9uW0YGZg==}\n\nsnapshots:\n  '@types/node@25.6.0':\n    dependencies:\n      undici-types: 7.19.2\n  typescript@5.9.3: {}\n  undici-types@7.19.2: {}\n# ${packageName}\n`;
+}
+
+function sdkSource(): string {
+  return `export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };\nexport type JsonObject = { [key: string]: Json };\nexport interface NodeExecutionContext {\n  readonly input: Readonly<JsonObject>; readonly config: Readonly<JsonObject>; readonly correlationId: string; readonly invocationId: string; readonly signal: AbortSignal;\n  readonly logger: { debug(message: string, fields?: JsonObject): void; info(message: string, fields?: JsonObject): void; warn(message: string, fields?: JsonObject): void; error(message: string, fields?: JsonObject): void };\n  readonly clock: { now(): string };\n  readonly http: { request(request: { url: string; method?: string; headers?: Record<string, string>; body?: string }): Promise<{ status: number; headers: Record<string, string>; body: string }> };\n  readonly credentials: { get(slot: string): Promise<string> };\n  readonly temporaryStorage: { read(path: string): Promise<Uint8Array | null>; write(path: string, content: string | Uint8Array): Promise<void> };\n  readonly artifacts: { write(name: string, content: string | Uint8Array, mediaType: string): Promise<{ name: string; digest: string; size: number }> };\n}\nexport type CustomNodeHandler = (context: NodeExecutionContext) => Promise<JsonObject>;\n`;
+}
+
+function runnerSource(): string {
+  return `import * as fs from "node:fs/promises";\nimport * as crypto from "node:crypto";\nimport * as path from "node:path";\nimport { run } from "./index.js";\nimport type { Json, JsonObject, NodeExecutionContext } from "./sdk.js";\nconst scratch = "/tmp/codeux"; const chunks: Buffer[] = []; for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));\nconst envelope = JSON.parse(Buffer.concat(chunks).toString("utf8")) as { input: JsonObject; config: JsonObject; correlationId: string; invocationId: string; credentials: Record<string, string>; now: string };\nconst secrets = Object.values(envelope.credentials); const redactText = (value: string): string => { let text = value; for (const secret of secrets) if (secret) text = text.split(secret).join("[REDACTED]"); return text; }; const redactJson = (value: Json): Json => typeof value === "string" ? redactText(value) : Array.isArray(value) ? value.map(redactJson) : value && typeof value === "object" ? Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, redactJson(entry)])) : value;\nconst log = (level: string, message: string, fields?: JsonObject): void => process.stderr.write(JSON.stringify({ level, message: redactText(message), fields: fields ? redactJson(fields) : undefined, correlationId: envelope.correlationId }) + "\\n");\nconst safePath = (value: string): string => { const target = path.resolve(scratch, value); if (target !== scratch && !target.startsWith(scratch + path.sep)) throw new Error("temporary storage path escaped scratch"); return target; };\nconst context: NodeExecutionContext = { input: Object.freeze(envelope.input), config: Object.freeze(envelope.config), correlationId: envelope.correlationId, invocationId: envelope.invocationId, signal: new AbortController().signal, logger: { debug: (m,f) => log("debug",m,f), info: (m,f) => log("info",m,f), warn: (m,f) => log("warn",m,f), error: (m,f) => log("error",m,f) }, clock: { now: () => envelope.now }, http: { request: async () => { throw new Error("HTTP requires the Code UX egress broker and is unavailable in a network-none runner"); } }, credentials: { get: async (slot) => { const value = envelope.credentials[slot]; if (!value) throw new Error("credential slot is unavailable"); return value; } }, temporaryStorage: { read: async (file) => fs.readFile(safePath(file)).catch(() => null), write: async (file, content) => { const target = safePath(file); await fs.mkdir(path.dirname(target), { recursive: true }); await fs.writeFile(target, content); } }, artifacts: { write: async (name, content) => { const target = safePath("artifacts/" + name); await fs.mkdir(path.dirname(target), { recursive: true }); await fs.writeFile(target, content); const bytes = typeof content === "string" ? Buffer.from(content) : content; return { name, digest: "sha256:" + crypto.createHash("sha256").update(bytes).digest("hex"), size: bytes.byteLength }; } } };\ntry { const output = await run(context); process.stdout.write(JSON.stringify(output)); } catch (error) { log("error", error instanceof Error ? error.message : String(error)); process.exitCode = 1; }\n`;
+}
+
+export function createCustomNodeDockerfile(): string {
+  return `# syntax=docker/dockerfile:1.7\nFROM node:22-bookworm-slim AS build\nWORKDIR /build\nCOPY package.json pnpm-lock.yaml ./\nRUN corepack enable && pnpm install --frozen-lockfile --ignore-scripts\nCOPY tsconfig.json ./\nCOPY src ./src\nCOPY tests ./tests\nRUN --network=none pnpm run typecheck && pnpm run build && pnpm run test\n\nFROM gcr.io/distroless/nodejs22-debian12:nonroot\nWORKDIR /app\nCOPY --from=build --chown=65532:65532 /build/dist ./dist\nUSER 65532:65532\nENTRYPOINT ["/nodejs/bin/node", "/app/dist/src/runner.js"]\n`;
+}
diff --git a/src/services/custom-nodes/custom-node-runtime-service.ts b/src/services/custom-nodes/custom-node-runtime-service.ts
new file mode 100644
index 0000000000..f184828106
--- /dev/null
+++ b/src/services/custom-nodes/custom-node-runtime-service.ts
@@ -0,0 +1,196 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import type {
+  CustomNodeArtifact,
+  CustomNodeExecutionRequest,
+  CustomNodeExecutionResult,
+  CustomNodeManifest,
+} from "../../contracts/custom-node-types.js";
+import type { NodeFlowJsonObject, NodeFlowJsonValue, NodeFlowValueSchema } from "../../contracts/node-flow-types.js";
+import type { CustomNodeRepository } from "../../repositories/custom-node-repository.js";
+import { EntityNotFoundError, ValidationError } from "../../repositories/repository-utils.js";
+import { DOCKER_DROP_ALL_CAPS_ARGS, DOCKER_NETWORK_NONE_ARGS, DOCKER_NO_NEW_PRIVILEGES_ARGS } from "../cli-docker-utils.js";
+import { runCommandStrict, type CommandResult } from "../cli-process-runner.js";
+import type { CredentialBroker } from "../credentials/credential-broker.js";
+import type { EgressPolicyService } from "../node-flows/egress-policy-service.js";
+
+export const CUSTOM_NODE_CONTAINER_SCRATCH = "/tmp/codeux";
+
+export interface CustomNodeDockerPlanInput {
+  artifact: CustomNodeArtifact;
+  containerName: string;
+  seccompProfile?: string;
+  appArmorProfile?: string;
+}
+
+export function buildCustomNodeDockerRunArgs(input: CustomNodeDockerPlanInput): string[] {
+  const limits = input.artifact.manifest.resources;
+  const args = [
+    "run", "--rm", "-i", "--name", input.containerName,
+    ...DOCKER_NETWORK_NONE_ARGS,
+    ...DOCKER_NO_NEW_PRIVILEGES_ARGS,
+    ...DOCKER_DROP_ALL_CAPS_ARGS,
+    "--read-only",
+    "--user", "65532:65532",
+    "--pids-limit", String(limits.pids),
+    "--memory", `${limits.memoryMb}m`,
+    "--memory-swap", `${limits.memoryMb}m`,
+    "--cpus", String(limits.cpu),
+    "--tmpfs", `${CUSTOM_NODE_CONTAINER_SCRATCH}:rw,nosuid,nodev,noexec,size=${limits.scratchMb}m,mode=700,uid=65532,gid=65532`,
+    "--log-driver", "none",
+    "--label", "code-ux.managed=true",
+    "--label", "code-ux.custom-node=true",
+    "--label", `code-ux.custom-node-digest=${input.artifact.digest}`,
+  ];
+  if (input.seccompProfile) args.push("--security-opt", `seccomp=${input.seccompProfile}`);
+  if (input.appArmorProfile) args.push("--security-opt", `apparmor=${input.appArmorProfile}`);
+  args.push(input.artifact.runtimeImageDigest);
+  return args;
+}
+
+export interface CustomNodeRuntimeServiceDeps {
+  repository: CustomNodeRepository;
+  credentialBroker: CredentialBroker;
+  egressPolicyService: EgressPolicyService;
+  featureEnabled?: boolean;
+  commandRunner?: (command: string, args: string[], cwd: string, options: { signal?: AbortSignal; timeout: number; maxStdoutChars: number; stdinFile?: string }) => Promise<CommandResult>;
+  seccompProfile?: string;
+  appArmorProfile?: string;
+}
+
+export class CustomNodeRuntimeService {
+  constructor(private readonly deps: CustomNodeRuntimeServiceDeps) {}
+
+  async execute(request: CustomNodeExecutionRequest): Promise<CustomNodeExecutionResult> {
+    if (!(this.deps.featureEnabled ?? process.env.CODE_UX_CUSTOM_NODES_ENABLED === "true")) {
+      throw new ValidationError("Custom node execution is disabled by the custom-node feature gate.");
+    }
+    const resolved = this.deps.repository.resolvePublished(request.nodeType, request.version);
+    if (!resolved || resolved.publication.projectId !== request.projectId) {
+      throw new EntityNotFoundError(`Published custom node not found: ${request.nodeType}@${request.version}`);
+    }
+    const { artifact } = resolved;
+    await this.validateDeclaredEgress(artifact.manifest);
+    const credentials = await this.resolveCredentials(artifact.manifest, request);
+    const secrets = Object.values(credentials);
+    const runDirectory = await fs.mkdtemp(path.join(os.tmpdir(), "code-ux-custom-node-run-"));
+    try {
+      if (process.platform !== "win32") await fs.chmod(runDirectory, 0o700);
+      const envelope = {
+        input: request.input,
+        config: request.config,
+        correlationId: request.correlationId,
+        invocationId: request.invocationId,
+        credentials,
+        now: new Date().toISOString(),
+      };
+      const inputPath = path.join(runDirectory, "input.json");
+      await fs.writeFile(inputPath, JSON.stringify(envelope), { mode: 0o600 });
+      if (process.platform !== "win32") await fs.chmod(inputPath, 0o600);
+      const dockerArgs = buildCustomNodeDockerRunArgs({
+        artifact,
+        containerName: containerName(request.invocationId),
+        seccompProfile: this.deps.seccompProfile,
+        appArmorProfile: this.deps.appArmorProfile,
+      });
+      const runner = this.deps.commandRunner ?? (async (command, args, cwd, options) => runCommandStrict(command, args, cwd, process.env, options));
+      const result = await runner("docker", dockerArgs, process.cwd(), {
+        signal: request.signal,
+        timeout: artifact.manifest.resources.timeoutMs,
+        maxStdoutChars: artifact.manifest.resources.maxOutputBytes,
+        stdinFile: inputPath,
+      });
+      const rawOutput = result.stdout;
+      if (Buffer.byteLength(rawOutput) > artifact.manifest.resources.maxOutputBytes) throw new ValidationError("Custom node output exceeded its declared limit.");
+      let output: unknown;
+      try { output = JSON.parse(rawOutput); } catch { throw new ValidationError("Custom node did not produce valid JSON output."); }
+      const schemaIssues = validateValueAgainstSchema(output, artifact.manifest.outputSchema, "output");
+      if (schemaIssues.length > 0) throw new ValidationError(`Custom node output schema validation failed: ${schemaIssues[0]}`);
+      const safeOutput = redactJson(output as NodeFlowJsonValue, secrets);
+      if (!isObject(safeOutput)) throw new ValidationError("Custom node output must be a JSON object.");
+      return {
+        output: safeOutput,
+        artifactDigest: artifact.digest,
+        logs: redactSecrets(result.stderr, secrets),
+        diagnostics: JSON.stringify(safeOutput),
+      };
+    } finally {
+      for (const key of Object.keys(credentials)) credentials[key] = "";
+      await fs.rm(runDirectory, { recursive: true, force: true });
+    }
+  }
+
+  private async resolveCredentials(manifest: CustomNodeManifest, request: CustomNodeExecutionRequest): Promise<Record<string, string>> {
+    const resolved: Record<string, string> = {};
+    for (const slot of manifest.credentials) {
+      const bindingKey = request.credentialBindings[slot.slot];
+      if (!bindingKey) {
+        if (slot.required) throw new ValidationError(`Required custom node credential slot is not bound: ${slot.slot}`);
+        continue;
+      }
+      const credential = await this.deps.credentialBroker.resolveCredentialId({
+        projectId: request.projectId,
+        bindingKey,
+        credentialId: bindingKey,
+        capability: slot.requiredCapability,
+        workspaceId: request.workspaceId,
+      });
+      resolved[slot.slot] = credential.value;
+    }
+    return resolved;
+  }
+
+  private async validateDeclaredEgress(manifest: CustomNodeManifest): Promise<void> {
+    if (!manifest.capabilities.includes("network.http")) return;
+    if (!manifest.http) throw new ValidationError("Published custom node is missing its bounded HTTP policy.");
+    for (const host of manifest.http.allowedHosts) {
+      await this.deps.egressPolicyService.validateUrl(`https://${host}`, {
+        allowedHosts: manifest.http.allowedHosts,
+        allowedPorts: manifest.http.allowedPorts ?? [443],
+        timeoutMs: manifest.http.timeoutMs,
+        maxResponseBytes: manifest.http.maxResponseBytes,
+        requestsPerMinute: manifest.http.maxRequests,
+      });
+    }
+  }
+}
+
+function containerName(invocationId: string): string {
+  return `code-ux-custom-node-${invocationId.toLowerCase().replace(/[^a-z0-9_.-]/g, "-").slice(0, 48)}`;
+}
+
+export function validateValueAgainstSchema(value: unknown, schema: NodeFlowValueSchema, field: string): string[] {
+  if (schema.type === "any") return [];
+  if (schema.type === "null") return value === null ? [] : [`${field} must be null`];
+  if (schema.type === "array") {
+    if (!Array.isArray(value)) return [`${field} must be an array`];
+    return schema.items ? value.flatMap((item, index) => validateValueAgainstSchema(item, schema.items!, `${field}[${index}]`)) : [];
+  }
+  if (schema.type === "object") {
+    if (!isObject(value)) return [`${field} must be an object`];
+    const issues = (schema.required ?? []).filter((key) => !(key in value)).map((key) => `${field}.${key} is required`);
+    for (const [key, child] of Object.entries(schema.properties ?? {})) {
+      if (key in value) issues.push(...validateValueAgainstSchema(value[key], child, `${field}.${key}`));
+    }
+    return issues;
+  }
+  return typeof value === schema.type ? [] : [`${field} must be ${schema.type}`];
+}
+
+export function redactSecrets(value: string, secrets: readonly string[]): string {
+  let redacted = value;
+  for (const secret of secrets) if (secret) redacted = redacted.split(secret).join("[REDACTED]");
+  return redacted;
+}
+
+function redactJson(value: NodeFlowJsonValue, secrets: readonly string[]): NodeFlowJsonValue {
+  if (typeof value === "string") return redactSecrets(value, secrets);
+  if (Array.isArray(value)) return value.map((entry) => redactJson(entry, secrets));
+  if (isObject(value)) return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, redactJson(entry as NodeFlowJsonValue, secrets)]));
+  return value;
+}
+
+function isObject(value: unknown): value is NodeFlowJsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
diff --git a/src/services/node-flow-runtime-service.ts b/src/services/node-flow-runtime-service.ts
index a3f662e047..72f7667521 100644
--- a/src/services/node-flow-runtime-service.ts
+++ b/src/services/node-flow-runtime-service.ts
@@ -20,6 +20,7 @@ import { BuiltinExecutors } from "./node-flows/builtins/builtin-executors.js";
 import type { ApprovalService } from "./node-flows/approval-service.js";
 import { ApprovalRequiredError } from "./node-flows/approval-service.js";
 import type { OutboxService } from "./node-flows/outbox-service.js";
+import type { CustomNodeRuntimeService } from "./custom-nodes/custom-node-runtime-service.js";
 import type { NodeFlowFailureClassification } from "../contracts/node-flow-execution-policy-types.js";
 import { buildProviderInvocationWorkspaceOptions } from "../infrastructure/providers/cli/invocation-workspace-preparer.js";
 import type {
@@ -55,6 +56,7 @@ interface NodeFlowRuntimeDeps {
   egressPolicyService?: EgressPolicyService;
   approvalService?: ApprovalService;
   outboxService?: OutboxService;
+  customNodeRuntimeService?: CustomNodeRuntimeService;
 }
 
 interface RuntimeContext {
@@ -362,7 +364,9 @@ export class NodeFlowRuntimeService {
     node: NodeFlowNode,
     nodeRun: NodeFlowNodeRunRecord,
   ): Promise<NodeExecutionResult> {
-    if (EXTERNALLY_OBSERVABLE_NODE_TYPES.has(node.type)) {
+    const reference = node.definition ?? { type: node.type, version: 1 };
+    const definition = resolveNodeDefinition(reference.type, reference.version);
+    if (EXTERNALLY_OBSERVABLE_NODE_TYPES.has(node.type) || definition?.executionKind === "custom") {
       const invocation = this.deps.executionRepository.createExecutionInvocation({
         projectId: context.projectId,
         skipValidation: true,
@@ -375,9 +379,11 @@ export class NodeFlowRuntimeService {
         this.deps.nodeFlowRepository.updateNodeAttempt(context.currentAttemptId, { invocationId: invocation.id });
       }
       try {
-        const result = node.type === "provider_prompt"
-          ? await this.executeProviderPromptNode(context, node, invocation.id)
-          : await this.executeHttpRequestNode(context, node, invocation.id);
+        const result = definition?.executionKind === "custom"
+          ? await this.executeCustomNode(context, node, invocation.id, reference.type, reference.version)
+          : node.type === "provider_prompt"
+            ? await this.executeProviderPromptNode(context, node, invocation.id)
+            : await this.executeHttpRequestNode(context, node, invocation.id);
         this.deps.executionRepository.updateExecutionInvocation(invocation.id, {
           status: "completed",
           finishedAt: new Date().toISOString(),
@@ -419,6 +425,37 @@ export class NodeFlowRuntimeService {
     }
   }
 
+  private async executeCustomNode(
+    context: RuntimeContext,
+    node: NodeFlowNode,
+    invocationId: string,
+    nodeType: string,
+    version: number,
+  ): Promise<NodeExecutionResult> {
+    if (!this.deps.customNodeRuntimeService) throw new ValidationError("Custom node runtime service is not configured.");
+    const result = await this.deps.customNodeRuntimeService.execute({
+      projectId: context.projectId,
+      nodeType,
+      version,
+      input: this.buildNodeInput(context, node.id),
+      config: evaluateTemplates(readNodeConfig(node), context) as NodeFlowJsonObject,
+      credentialBindings: Object.fromEntries((node.credentialBindings ?? []).map((binding) => [binding.slot, binding.credentialId])),
+      workspaceId: context.runId,
+      invocationId,
+      correlationId: context.runId,
+      signal: context.options.signal,
+    });
+    if (context.currentAttemptId) {
+      this.deps.nodeFlowRepository.updateNodeAttempt(context.currentAttemptId, { artifactDigest: result.artifactDigest });
+    }
+    this.deps.executionRepository.appendExecutionInvocationMessage(invocationId, {
+      role: "assistant",
+      contentMarkdown: "Custom node container execution completed.",
+      metadata: { flowId: context.flowId, runId: context.runId, nodeId: node.id, artifactDigest: result.artifactDigest },
+    });
+    return { output: result.output };
+  }
+
   private executeSetFieldsNode(context: RuntimeContext, node: NodeFlowNode): NodeFlowJsonObject {
     const config = readNodeConfig(node);
     const base = readBoolean(config.replace) ? {} : this.firstUpstreamObject(context, node.id);
diff --git a/tests/backend/repositories/custom-node-repository.test.ts b/tests/backend/repositories/custom-node-repository.test.ts
new file mode 100644
index 0000000000..a23ab73b44
--- /dev/null
+++ b/tests/backend/repositories/custom-node-repository.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import type { CustomNodeArtifact, CustomNodeManifest, CustomNodeValidationReport } from "../../../src/contracts/custom-node-types.js";
+import { AppDbStorage } from "../../../src/repositories/app-db-storage.js";
+import { CustomNodeRepository } from "../../../src/repositories/custom-node-repository.js";
+import { ProjectManagementRepository } from "../../../src/repositories/project-management-repository.js";
+
+const manifest = (id = "safe-node"): CustomNodeManifest => ({
+  schemaVersion: 1, id, nodeType: `custom.${id}`, version: 1, name: "Safe node", description: "",
+  entrypoint: "dist/index.js", inputSchema: { type: "object" }, outputSchema: { type: "object" },
+  configurationSchema: { type: "object" }, capabilities: ["clock.read"], credentials: [],
+  resources: { cpu: 0.5, memoryMb: 128, pids: 64, timeoutMs: 30_000, maxOutputBytes: 262_144, scratchMb: 32 },
+});
+
+describe("CustomNodeRepository", () => {
+  it("enforces draft, validation, immutable artifact, and publication lifecycle", () => {
+    const storage = new AppDbStorage(":memory:");
+    const project = new ProjectManagementRepository(storage).createProject({ name: "Custom Node Test", sourceType: "local", sourceRef: "/tmp/custom-node-test" });
+    const repository = new CustomNodeRepository(storage);
+    const nodeManifest = manifest();
+    const draft = repository.createDraft(project.id, { manifest: nodeManifest, sourceRevision: "revision-1", createdBy: "test" });
+    expect(draft.status).toBe("draft");
+    repository.beginValidation(draft.id);
+    const report: CustomNodeValidationReport = { valid: true, checks: [{ name: "all", passed: true, durationMs: 1 }], issues: [], validatedAt: new Date().toISOString() };
+    const artifact: CustomNodeArtifact = {
+      digest: `sha256:${"a".repeat(64)}`, nodeId: draft.id, projectId: project.id, version: 1,
+      sourceRevision: "revision-1", buildDigest: `sha256:${"b".repeat(64)}`,
+      runtimeImageDigest: `sha256:${"c".repeat(64)}`, dependencies: [], validationReport: report,
+      createdBy: "test", invocationId: "invocation", correlationId: "correlation",
+      capabilities: ["clock.read"], manifest: nodeManifest, createdAt: new Date().toISOString(),
+    };
+    expect(repository.completeValidation(draft.id, report, artifact).status).toBe("passed");
+    const publication = repository.publish(draft.id, "publisher");
+    expect(publication).toMatchObject({ nodeType: "custom.safe-node", version: 1, artifactDigest: artifact.digest });
+    expect(repository.resolvePublished("custom.safe-node", 1)?.artifact).toEqual(artifact);
+    expect(repository.getNode(draft.id)?.status).toBe("published");
+    expect(() => repository.beginValidation(draft.id)).toThrow(/immutable/i);
+    storage.close();
+  });
+
+  it("rejects publication after failed validation", () => {
+    const storage = new AppDbStorage(":memory:");
+    const project = new ProjectManagementRepository(storage).createProject({ name: "Failed Node Test", sourceType: "local", sourceRef: "/tmp/failed-node-test" });
+    const repository = new CustomNodeRepository(storage);
+    repository.createDraft(project.id, { manifest: manifest("failed-node"), sourceRevision: "revision-1", createdBy: "test" });
+    repository.beginValidation("failed-node");
+    repository.completeValidation("failed-node", { valid: false, checks: [], issues: [{ check: "scan", code: "failed", message: "failed" }], validatedAt: new Date().toISOString() }, null);
+    expect(() => repository.publish("failed-node", "publisher")).toThrow(/passed/i);
+    storage.close();
+  });
+});
diff --git a/tests/backend/services/custom-node-services.test.ts b/tests/backend/services/custom-node-services.test.ts
new file mode 100644
index 0000000000..3443ed9751
--- /dev/null
+++ b/tests/backend/services/custom-node-services.test.ts
@@ -0,0 +1,150 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { CustomNodeArtifact, CustomNodeManifest, CustomNodeValidationReport } from "../../../src/contracts/custom-node-types.js";
+import { resolveNodeDefinition } from "../../../src/domain/node-flows/node-definition-registry.js";
+import { AppDbStorage } from "../../../src/repositories/app-db-storage.js";
+import { CustomNodeRepository } from "../../../src/repositories/custom-node-repository.js";
+import { ProjectManagementRepository } from "../../../src/repositories/project-management-repository.js";
+import { CustomNodeBuildService } from "../../../src/services/custom-nodes/custom-node-build-service.js";
+import { CustomNodeProjectService } from "../../../src/services/custom-nodes/custom-node-project-service.js";
+import { buildCustomNodeDockerRunArgs, CustomNodeRuntimeService } from "../../../src/services/custom-nodes/custom-node-runtime-service.js";
+import type { CommandResult } from "../../../src/services/cli-process-runner.js";
+
+const temporaryDirectories: string[] = [];
+const result = (stdout = "", stderr = ""): CommandResult => ({ ok: true, code: 0, stdout, stderr });
+
+async function fixture(nodeId: string): Promise<{ root: string; storage: AppDbStorage; repository: CustomNodeRepository; projectId: string; projectService: CustomNodeProjectService }> {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "code-ux-custom-node-test-"));
+  temporaryDirectories.push(root);
+  const storage = new AppDbStorage(path.join(root, "app.db"));
+  const project = new ProjectManagementRepository(storage).createProject({ name: "Custom Node Service Test", sourceType: "local", sourceRef: root });
+  const repository = new CustomNodeRepository(storage);
+  const projectService = new CustomNodeProjectService();
+  const generated = await projectService.generate({ projectRoot: root, nodeId, name: "Safe node" });
+  repository.createDraft(project.id, { manifest: generated.manifest, sourceRevision: "revision-1", createdBy: "test" });
+  return { root, storage, repository, projectId: project.id, projectService };
+}
+
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await Promise.all(temporaryDirectories.splice(0).map((directory) => fs.rm(directory, { recursive: true, force: true })));
+});
+
+describe("custom node project and build services", () => {
+  it("generates the SDK package and validates/builds/publishes a deterministic fixture through Docker", async () => {
+    const setup = await fixture("fixture-node");
+    const calls: string[][] = [];
+    const commandRunner = vi.fn(async (_command: string, args: string[]): Promise<CommandResult> => {
+      calls.push(args);
+      if (args[0] === "image") return result(`sha256:${"d".repeat(64)}\n`);
+      if (args[0] === "run") return result(JSON.stringify({ value: 1, executedAt: "2026-01-01T00:00:00.000Z" }));
+      return result();
+    });
+    const service = new CustomNodeBuildService({ repository: setup.repository, projectService: setup.projectService, commandRunner, vulnerabilityAudit: async () => ({ passed: true, details: "fixture audit passed" }) });
+    const validation = await service.validateAndBuild({ projectRoot: setup.root, nodeId: "fixture-node", creator: "test", invocationId: "invocation", correlationId: "correlation" });
+
+    expect(validation.report.valid).toBe(true);
+    expect(validation.artifact).toMatchObject({ sourceRevision: "revision-1", runtimeImageDigest: `sha256:${"d".repeat(64)}`, capabilities: ["clock.read"] });
+    expect(calls.some((args) => args[0] === "build" && args.includes("--pull=false"))).toBe(true);
+    await expect(fs.readFile(path.join(setup.root, ".code-ux", "nodes", "fixture-node", "Dockerfile"), "utf8")).resolves.toContain("RUN --network=none pnpm run typecheck");
+    expect(calls.some((args) => args[0] === "run" && args.includes("--read-only"))).toBe(true);
+    const artifact = service.publish("fixture-node", "publisher");
+    expect(resolveNodeDefinition("custom.fixture-node", 1)?.executionKind).toBe("custom");
+    expect(artifact.digest).toBe(validation.artifact?.digest);
+    await expect(fs.readFile(path.join(setup.root, ".code-ux", "nodes", "fixture-node", "src", "sdk.ts"), "utf8")).resolves.toContain("NodeExecutionContext");
+    setup.storage.close();
+  });
+
+  it.each([
+    ["host filesystem", 'import fs from "node:fs";'],
+    ["host environment", "const value = process.env.SECRET;"],
+    ["subprocess", 'import { spawn } from "node:child_process";'],
+    ["Docker", 'const socket = "/var/run/docker.sock";'],
+    ["unrestricted network", 'const response = await fetch("https://example.test");'],
+  ])("fails closed when generated code requests %s access", async (_name, attack) => {
+    const nodeId = `blocked-${temporaryDirectories.length + 10}`;
+    const setup = await fixture(nodeId);
+    await fs.writeFile(path.join(setup.root, ".code-ux", "nodes", nodeId, "src", "index.ts"), `${attack}\nexport const run = async () => ({});\n`);
+    const commandRunner = vi.fn(async (): Promise<CommandResult> => result());
+    const validation = await new CustomNodeBuildService({ repository: setup.repository, projectService: setup.projectService, commandRunner })
+      .validateAndBuild({ projectRoot: setup.root, nodeId, creator: "test", invocationId: "invocation", correlationId: "correlation" });
+    expect(validation.report.valid).toBe(false);
+    expect(validation.report.issues.some((issue) => issue.check === "prohibited-api-scan")).toBe(true);
+    expect(commandRunner).not.toHaveBeenCalled();
+    setup.storage.close();
+  });
+
+  it("rejects resource exhaustion declarations before Docker execution", async () => {
+    const setup = await fixture("resource-node");
+    const manifestPath = path.join(setup.root, ".code-ux", "nodes", "resource-node", "node.json");
+    const manifest = JSON.parse(await fs.readFile(manifestPath, "utf8")) as CustomNodeManifest;
+    manifest.resources.memoryMb = 100_000;
+    await fs.writeFile(manifestPath, JSON.stringify(manifest));
+    const commandRunner = vi.fn(async (): Promise<CommandResult> => result());
+    const validation = await new CustomNodeBuildService({ repository: setup.repository, commandRunner })
+      .validateAndBuild({ projectRoot: setup.root, nodeId: "resource-node", creator: "test", invocationId: "invocation", correlationId: "correlation" });
+    expect(validation.report.issues.some((issue) => issue.check === "resource-policy")).toBe(true);
+    expect(commandRunner).not.toHaveBeenCalled();
+    setup.storage.close();
+  });
+});
+
+describe("custom node Docker plan and runtime security", () => {
+  it("applies a non-root read-only network-none container with bounded resources and no project or Docker mounts", () => {
+    const artifact = artifactFixture("plan-node", "/immutable-image");
+    const args = buildCustomNodeDockerRunArgs({ artifact, containerName: "custom-run", seccompProfile: "/profiles/custom.json", appArmorProfile: "code-ux-custom-node" });
+    expect(args).toEqual(expect.arrayContaining(["--network", "none", "--security-opt", "no-new-privileges", "--cap-drop", "ALL", "--read-only", "--user", "65532:65532", "--pids-limit", "64", "--memory", "128m", "--cpus", "0.5"]));
+    expect(args).toContain("seccomp=/profiles/custom.json");
+    expect(args).toContain("apparmor=code-ux-custom-node");
+    expect(args.join(" ")).not.toMatch(/docker\.sock|--network host|\/workspace|\/project/);
+    expect(args.filter((arg) => arg.startsWith("type="))).toEqual([]);
+  });
+
+  it("uses the credential broker, isolates each run, and redacts canaries from outputs, logs, and diagnostics", async () => {
+    const setup = await fixture("runtime-node");
+    const artifact = artifactFixture("runtime-node", `sha256:${"e".repeat(64)}`, setup.projectId);
+    artifact.manifest.capabilities = ["credentials.read"];
+    artifact.manifest.credentials = [{ slot: "api", label: "API", required: true, allowedKinds: ["http"], requiredCapability: "read" }];
+    setup.repository.beginValidation("runtime-node");
+    setup.repository.completeValidation("runtime-node", artifact.validationReport, artifact);
+    setup.repository.publish("runtime-node", "publisher");
+    const secret = "CODEUX_SECRET_CANARY_DO_NOT_LEAK";
+    const runDirectories: string[] = [];
+    const commandRunner = vi.fn(async (_command: string, _args: string[], _cwd: string, options: { stdinFile?: string }): Promise<CommandResult> => {
+      if (!options.stdinFile) throw new Error("missing credential bundle");
+      runDirectories.push(path.dirname(options.stdinFile));
+      return result(JSON.stringify({ value: secret }), `log ${secret}`);
+    });
+    const broker = { resolveCredentialId: vi.fn(async () => ({ credentialId: "credential", value: secret, version: 1 })) };
+    const runtime = new CustomNodeRuntimeService({ repository: setup.repository, credentialBroker: broker as never, egressPolicyService: {} as never, featureEnabled: true, commandRunner });
+    const execute = () => runtime.execute({ projectId: setup.projectId, nodeType: "custom.runtime-node", version: 1, input: {}, config: {}, credentialBindings: { api: "credential" }, workspaceId: "run", invocationId: `invocation-${runDirectories.length}`, correlationId: "correlation" });
+    const first = await execute();
+    const second = await execute();
+    expect(first).toMatchObject({ output: { value: "[REDACTED]" }, logs: "log [REDACTED]", diagnostics: "{\"value\":\"[REDACTED]\"}" });
+    expect(second.output).toEqual({ value: "[REDACTED]" });
+    expect(runDirectories[0]).not.toBe(runDirectories[1]);
+    await expect(fs.access(runDirectories[0]!)).rejects.toThrow();
+    await expect(fs.access(runDirectories[1]!)).rejects.toThrow();
+    expect(broker.resolveCredentialId).toHaveBeenCalledTimes(2);
+    setup.storage.close();
+  });
+
+  it("keeps execution behind the feature and publication gates", async () => {
+    const setup = await fixture("gated-node");
+    const runtime = new CustomNodeRuntimeService({ repository: setup.repository, credentialBroker: {} as never, egressPolicyService: {} as never, featureEnabled: false });
+    await expect(runtime.execute({ projectId: setup.projectId, nodeType: "custom.gated-node", version: 1, input: {}, config: {}, credentialBindings: {}, workspaceId: "run", invocationId: "invocation", correlationId: "correlation" })).rejects.toThrow(/feature gate/i);
+    setup.storage.close();
+  });
+});
+
+function artifactFixture(nodeId: string, runtimeImageDigest: string, projectId = "project"): CustomNodeArtifact {
+  const generatedManifest: CustomNodeManifest = {
+    schemaVersion: 1, id: nodeId, nodeType: `custom.${nodeId}`, version: 1, name: "Test", description: "",
+    entrypoint: "dist/index.js", inputSchema: { type: "object" }, outputSchema: { type: "object" }, configurationSchema: { type: "object" },
+    capabilities: [], credentials: [], resources: { cpu: 0.5, memoryMb: 128, pids: 64, timeoutMs: 30_000, maxOutputBytes: 262_144, scratchMb: 32 },
+  };
+  const report: CustomNodeValidationReport = { valid: true, checks: [], issues: [], validatedAt: new Date().toISOString() };
+  return { digest: `sha256:${"a".repeat(64)}`, nodeId, projectId, version: 1, sourceRevision: "revision-1", buildDigest: `sha256:${"b".repeat(64)}`, runtimeImageDigest, dependencies: [], validationReport: report, createdBy: "test", invocationId: "invocation", correlationId: "correlation", capabilities: [], manifest: generatedManifest, createdAt: new Date().toISOString() };
+}

From aaa85a0bea92d77af3db2eb6617d4f3d57ca5c85 Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 06:11:55 +0000
Subject: [PATCH 06/25] feat(task T06): implement via codex

---
 .../docs/developer-management-actions.mdx     |  15 +
 docs-web/content/docs/developer-mcp-tools.mdx |  13 +-
 docs-web/developer/management-actions.md      |  15 +
 docs-web/developer/mcp-tools.md               |  13 +-
 docs/mcp/runtime-and-dispatch.md              |   9 +-
 docs/mcp/tools-and-contracts.md               |   8 +-
 src/api/mcp/tool-registry.ts                  |   3 +-
 src/app/dependency-factory/core-factory.ts    |   2 +-
 .../dependency-factory/dashboard-factory.ts   |  15 +-
 src/contracts/internal-management-types.ts    |  25 +-
 src/contracts/mcp-tool-definitions.ts         |  37 ++-
 src/contracts/node-flow-types.ts              |  59 ++++
 src/mcp/management-tool-handler.ts            |  27 +-
 src/mcp/management/node-flow-actions.ts       | 163 ++++++++++-
 src/repositories/custom-node-repository.ts    |  10 +
 src/repositories/node-flow-repository.ts      |  12 +-
 src/server/code-ux-server.ts                  |   4 +
 src/server/mcp-request-router.ts              |   1 +
 src/server/node-flow-routes.ts                | 102 +++++++
 src/services/agent-mcp-access.ts              |  12 +
 .../custom-node-project-service.ts            |   6 +
 src/services/node-flow-agent-skill-service.ts |  57 ++++
 src/services/node-flow-runtime-service.ts     |   6 +-
 src/services/node-flow-service.ts             | 272 ++++++++++++++++++
 .../mcp/management-node-flow-actions.test.ts  |  47 +++
 tests/backend/mcp/mcp-management.test.ts      |  28 +-
 tests/backend/server/node-flow-routes.test.ts |  10 +
 .../backend/services/agent-mcp-access.test.ts |  10 +
 .../node-flow-agent-skill-service.test.ts     |  33 +++
 .../services/node-flow-service.test.ts        |  35 +++
 30 files changed, 1006 insertions(+), 43 deletions(-)
 create mode 100644 src/services/node-flow-agent-skill-service.ts
 create mode 100644 tests/backend/services/node-flow-agent-skill-service.test.ts

diff --git a/docs-web/content/docs/developer-management-actions.mdx b/docs-web/content/docs/developer-management-actions.mdx
index aec827ebfd..8bf6fe17e6 100644
--- a/docs-web/content/docs/developer-management-actions.mdx
+++ b/docs-web/content/docs/developer-management-actions.mdx
@@ -113,6 +113,21 @@ Task create/update fields include `title`, `name`, `promptMarkdown`, `descriptio
 
 ---
 
+## `node_flows`
+
+| Action group | Approval | Behavior |
+| --- | --- | --- |
+| Catalog | – | `catalog` and `get_node_definition` return executable manifests and schemas without complete flow graphs. |
+| Drafts | – | `create_draft`, `patch_draft`, and `validate_draft` return validation, policy, credential, capability, and side-effect summaries. `patch_draft` requires `draftRevision`. |
+| Custom nodes | – | `create_custom_node`, `update_custom_node`, and `validate_custom_node` reuse the governed project/build services. |
+| Credentials | – | `request_credential` and `inspect_bindings` expose metadata and permission findings only. |
+| Review | – / ✅ | `dry_run` is side-effect free; `publish` and `rollback` require exact-payload approval; `compare_versions` returns structural summaries. |
+| Operations | – | `run`, `cancel`, `retry`, `inspect_run`, and `list_runs` enforce project ownership and publication selection. |
+
+Compatibility aliases remain for legacy list/get/create/update/delete/validate/run/attach/detach calls. Legacy create/update auto-publish for backward compatibility; governed draft actions do not. Attachments grant the agent only `run_attached_flow`, never the full management surface.
+
+---
+
 ## `scheduler`
 
 | Action | Destructive | Required payload | Description |
diff --git a/docs-web/content/docs/developer-mcp-tools.mdx b/docs-web/content/docs/developer-mcp-tools.mdx
index cde7ce28d4..785ad691b6 100644
--- a/docs-web/content/docs/developer-mcp-tools.mdx
+++ b/docs-web/content/docs/developer-mcp-tools.mdx
@@ -54,7 +54,8 @@ action-specific fields, and an optional `approval` object for destructive action
 | `manage_scheduler` | orchestration | Create and run scheduled sprints, quicksprints, messages, and node flows. |
 | `scheduler_code_ux` | orchestration | Agent-owned wakeups with restricted list/schedule/cancel actions. |
 | `manage_agents` | agents & memory | Manage agent presets and sync them to project markdown. |
-| `manage_node_flows` | agents & memory | Manage reusable node workflows, run them, and attach them as agent skills. |
+| `manage_node_flows` | agents & memory | Govern draft automation graphs, credentials, publication, versions, and runs. |
+| `run_attached_flow` | agents & memory | Run one published flow attached to the authenticated agent without exposing its graph or credentials. |
 | `manage_memory` | agents & memory | Inspect, search, promote, and re-embed short/long-term memory. |
 | `add_long_term_memory` | agents & memory | Store one canonical durable project memory and return rich confirmation-widget data. |
 | `manage_skills` | agents & memory | Manage persistent skill storages, skill markdown, and agent storage attachments. |
@@ -126,7 +127,7 @@ Clarification states are `pending`, `replied`, `expired`, and `cancelled`. Repea
 | `manage_scheduler` | `list`, `create`, `update`, `delete`, `run_due`, `schedule_sprint`, `schedule_quicksprint`, `schedule_chat`, `schedule_node_flow` |
 | `scheduler_code_ux` | `list`, `schedule_wakeup`, `cancel` |
 | `manage_agents` | `list`, `get`, `create`, `update`, `delete`, `sync` |
-| `manage_node_flows` | `list`, `get`, `create`, `update`, `delete`, `validate`, `run`, `list_runs`, `get_run`, `attach_to_agent`, `detach_from_agent` |
+| `manage_node_flows` | `catalog`, `get_node_definition`, `create_draft`, `patch_draft`, `validate_draft`, custom-node and credential actions, `dry_run`, `publish`, `compare_versions`, `rollback`, `run`, `cancel`, `retry`, `inspect_run`, plus compatibility aliases |
 | `manage_memory` | `list`, `get`, `count`, `create`, `update`, `delete`, `search`, `promote`, `get_map`, `model_status`, `start_reembed` |
 | `manage_skills` | `authoring_prompt`, `list_storages`, `get_storage`, `create_storage`, `update_storage`, `delete_storage`, `reset_storage`, `list_agent_storages`, `attach_storage`, `detach_storage`, `list_skills`, `get_skill`, `create_skill`, `update_skill`, `delete_skill`, `import_markdown`, `export_markdown` |
 | `manage_settings` | `get_system`, `get_project_override`, `resolve_project_effective`, `get_sprint_override`, `resolve_sprint_effective`, `replace_system_settings`, `patch_system_setting`, `replace_project_settings`, `patch_project_setting`, `reset_project_settings`, `replace_sprint_settings`, `patch_sprint_setting`, `reset_sprint_settings`, `export_settings_bundle`, `apply_settings_bundle` |
@@ -191,13 +192,9 @@ memory remediation, or global scheduler destructive controls.
 
 ## Node flows
 
-`manage_node_flows` exposes project node workflows through MCP. It supports graph validation, CRUD,
-runtime execution, run inspection, and flow-backed agent skill attachments.
+`manage_node_flows` exposes governed project automation authoring through MCP. Draft patches require an optimistic `draftRevision`; conflicts return expected/actual revisions without writes. Validation and dry-run responses contain policy findings, required credentials, requested capabilities, side-effect diffs, and redacted summaries. Publication and rollback require exact-payload approval. Legacy CRUD/run/attach aliases remain compatible.
 
-Create and update calls validate the structured graph before repository writes. `run` delegates to the
-node-flow runtime through `NodeFlowService.runFlow`, and `delete` requires the normal approval
-handshake. Responses mask secret-shaped graph data, inputs, and outputs before returning them to MCP
-clients.
+Attached flows appear to the owning authenticated agent only as name, description, input schema, flow id, and the `run_attached_flow` operation. Calls enforce project ownership, attachment, publication, and credential policy and record agent/conversation provenance without exposing complete graphs or credential material.
 
 Agents should build Code UX-adapted node flows rather than cloning n8n workflows one-to-one. Graphs
 should include dynamic widget schemas for editable graph inputs and node fields; callers can provide
diff --git a/docs-web/developer/management-actions.md b/docs-web/developer/management-actions.md
index 2b6a6ff6b9..4ee6316e49 100644
--- a/docs-web/developer/management-actions.md
+++ b/docs-web/developer/management-actions.md
@@ -113,6 +113,21 @@ Task create/update fields include `title`, `name`, `promptMarkdown`, `descriptio
 
 ---
 
+## `node_flows`
+
+| Action group | Approval | Behavior |
+| --- | --- | --- |
+| Catalog | – | `catalog` and `get_node_definition` return executable manifests and schemas without complete flow graphs. |
+| Drafts | – | `create_draft`, `patch_draft`, and `validate_draft` return validation, policy, credential, capability, and side-effect summaries. `patch_draft` requires `draftRevision`. |
+| Custom nodes | – | `create_custom_node`, `update_custom_node`, and `validate_custom_node` reuse the governed project/build services. |
+| Credentials | – | `request_credential` and `inspect_bindings` expose metadata and permission findings only. |
+| Review | – / ✅ | `dry_run` is side-effect free; `publish` and `rollback` require exact-payload approval; `compare_versions` returns structural summaries. |
+| Operations | – | `run`, `cancel`, `retry`, `inspect_run`, and `list_runs` enforce project ownership and publication selection. |
+
+Compatibility aliases remain for legacy list/get/create/update/delete/validate/run/attach/detach calls. Legacy create/update auto-publish for backward compatibility; governed draft actions do not. Attachments grant the agent only `run_attached_flow`, never the full management surface.
+
+---
+
 ## `scheduler`
 
 | Action | Destructive | Required payload | Description |
diff --git a/docs-web/developer/mcp-tools.md b/docs-web/developer/mcp-tools.md
index bd15393af1..7633d6ac16 100644
--- a/docs-web/developer/mcp-tools.md
+++ b/docs-web/developer/mcp-tools.md
@@ -54,7 +54,8 @@ action-specific fields, and an optional `approval` object for destructive action
 | `manage_scheduler` | orchestration | Create and run scheduled sprints, quicksprints, messages, and node flows. |
 | `scheduler_code_ux` | orchestration | Agent-owned wakeups with restricted list/schedule/cancel actions. |
 | `manage_agents` | agents & memory | Manage agent presets and sync them to project markdown. |
-| `manage_node_flows` | agents & memory | Manage reusable node workflows, run them, and attach them as agent skills. |
+| `manage_node_flows` | agents & memory | Govern draft automation graphs, credentials, publication, versions, and runs. |
+| `run_attached_flow` | agents & memory | Run one published flow attached to the authenticated agent without exposing its graph or credentials. |
 | `manage_memory` | agents & memory | Inspect, search, promote, and re-embed short/long-term memory. |
 | `add_long_term_memory` | agents & memory | Store one canonical durable project memory and return rich confirmation-widget data. |
 | `manage_skills` | agents & memory | Manage persistent skill storages, skill markdown, and agent storage attachments. |
@@ -126,7 +127,7 @@ Clarification states are `pending`, `replied`, `expired`, and `cancelled`. Repea
 | `manage_scheduler` | `list`, `create`, `update`, `delete`, `run_due`, `schedule_sprint`, `schedule_quicksprint`, `schedule_chat`, `schedule_node_flow` |
 | `scheduler_code_ux` | `list`, `schedule_wakeup`, `cancel` |
 | `manage_agents` | `list`, `get`, `create`, `update`, `delete`, `sync` |
-| `manage_node_flows` | `list`, `get`, `create`, `update`, `delete`, `validate`, `run`, `list_runs`, `get_run`, `attach_to_agent`, `detach_from_agent` |
+| `manage_node_flows` | `catalog`, `get_node_definition`, `create_draft`, `patch_draft`, `validate_draft`, custom-node and credential actions, `dry_run`, `publish`, `compare_versions`, `rollback`, `run`, `cancel`, `retry`, `inspect_run`, plus compatibility aliases |
 | `manage_memory` | `list`, `get`, `count`, `create`, `update`, `delete`, `search`, `promote`, `get_map`, `model_status`, `start_reembed` |
 | `manage_skills` | `authoring_prompt`, `list_storages`, `get_storage`, `create_storage`, `update_storage`, `delete_storage`, `reset_storage`, `list_agent_storages`, `attach_storage`, `detach_storage`, `list_skills`, `get_skill`, `create_skill`, `update_skill`, `delete_skill`, `import_markdown`, `export_markdown` |
 | `manage_settings` | `get_system`, `get_project_override`, `resolve_project_effective`, `get_sprint_override`, `resolve_sprint_effective`, `replace_system_settings`, `patch_system_setting`, `replace_project_settings`, `patch_project_setting`, `reset_project_settings`, `replace_sprint_settings`, `patch_sprint_setting`, `reset_sprint_settings`, `export_settings_bundle`, `apply_settings_bundle` |
@@ -191,13 +192,9 @@ memory remediation, or global scheduler destructive controls.
 
 ## Node flows
 
-`manage_node_flows` exposes project node workflows through MCP. It supports graph validation, CRUD,
-runtime execution, run inspection, and flow-backed agent skill attachments.
+`manage_node_flows` exposes governed project automation authoring through MCP. Draft patches require an optimistic `draftRevision`; conflicts return expected/actual revisions without writes. Validation and dry-run responses contain policy findings, required credentials, requested capabilities, side-effect diffs, and redacted summaries. Publication and rollback require exact-payload approval. Legacy CRUD/run/attach aliases remain compatible.
 
-Create and update calls validate the structured graph before repository writes. `run` delegates to the
-node-flow runtime through `NodeFlowService.runFlow`, and `delete` requires the normal approval
-handshake. Responses mask secret-shaped graph data, inputs, and outputs before returning them to MCP
-clients.
+Attached flows appear to the owning authenticated agent only as name, description, input schema, flow id, and the `run_attached_flow` operation. Calls enforce project ownership, attachment, publication, and credential policy and record agent/conversation provenance without exposing complete graphs or credential material.
 
 Agents should build Code UX-adapted node flows rather than cloning n8n workflows one-to-one. Graphs
 should include dynamic widget schemas for editable graph inputs and node fields; callers can provide
diff --git a/docs/mcp/runtime-and-dispatch.md b/docs/mcp/runtime-and-dispatch.md
index 012f15c35f..9bfd562754 100644
--- a/docs/mcp/runtime-and-dispatch.md
+++ b/docs/mcp/runtime-and-dispatch.md
@@ -143,14 +143,17 @@ Runtime behavior:
 
 ## Node Flow Tools
 
-`manage_node_flows` uses `NodeFlowService` as the MCP backend boundary. The action layer parses MCP payloads, applies optional widget schemas into the graph, masks secret-shaped response fields, and delegates graph validation, persistence, run inspection, runtime execution, and agent skill attachments to the service.
+`manage_node_flows` uses `NodeFlowService` as the MCP backend boundary. The thin action layer parses MCP payloads and delegates catalog lookup, optimistic drafts, validation/policy review, credential metadata, publication/version operations, run controls, custom-node authoring, and attachments. Governed responses use graph summaries unless a legacy project-manager `get` explicitly requests the stored flow.
 
 Runtime behavior:
 
-- `create` and `update` validate graph specs before repository writes.
+- `create_draft` and `patch_draft` append immutable versions without auto-publication; stale `draftRevision` values return structured conflicts without writes. Legacy `create` and `update` retain auto-publication compatibility.
+- `dry_run` never invokes the runtime; it reports validation, policy, credential, capability, and side-effect findings with redacted simulated output.
+- `publish` and `rollback` use the stateful exact-payload approval handshake. Runtime execution always resolves a publication.
 - `run` calls the configured node-flow runtime through `NodeFlowService.runFlow`.
+- `cancel`, `retry`, and `inspect_run` operate on project-owned durable run records.
 - `delete` uses the same stateful approval handshake as other destructive management actions.
-- `attach_to_agent` and `detach_from_agent` manage flow-backed skill attachments for agent presets; the agent still needs explicit MCP access if it should call `manage_node_flows` itself.
+- Attachments automatically expose only `run_attached_flow` to the owning agent. That operation verifies project, attachment, publication, and credential policy and records initiating agent/conversation metadata; it does not grant `manage_node_flows` or expose graphs/secrets.
 
 ## Custom MCP Defaults
 
diff --git a/docs/mcp/tools-and-contracts.md b/docs/mcp/tools-and-contracts.md
index 82ad2efa05..f802016e77 100644
--- a/docs/mcp/tools-and-contracts.md
+++ b/docs/mcp/tools-and-contracts.md
@@ -425,9 +425,11 @@ The dedicated management tools (`manage_sprints`, `manage_tasks`, `manage_quicks
 
 ## Node Flow Tools
 
-`manage_node_flows` exposes project node workflows through the project-manager MCP surface. It supports `list`, `get`, `create`, `update`, `delete`, `validate`, `run`, `list_runs`, `get_run`, `attach_to_agent`, and `detach_from_agent`.
+`manage_node_flows` is the project-manager automation-authoring surface. Governed actions are `catalog`, `get_node_definition`, `create_draft`, `patch_draft`, `validate_draft`, `create_custom_node`, `update_custom_node`, `validate_custom_node`, `request_credential`, `inspect_bindings`, `dry_run`, `publish`, `compare_versions`, `rollback`, `run`, `cancel`, `retry`, `inspect_run`, and `list_runs`. Compatibility aliases remain for `list`, `get`, `create`, `update`, `delete`, `validate`, `get_run`, `attach_to_agent`/`attach`, and `detach_from_agent`/`detach`.
 
-Node-flow management always delegates graph validation and persistence to `NodeFlowService`; `run` delegates execution through the configured node-flow runtime service. Create and update calls reject malformed graph specs before repository writes. `delete` uses the standard stateful approval handshake.
+New drafts are not executable until published. `patch_draft` requires the last observed positive integer `draftRevision`; stale revisions return a `draft_revision_conflict` containing expected and actual revisions without writing. Draft review responses are summaries rather than full graphs: they include validation issues, policy findings, credential requirements, requested capabilities, side-effect diffs, node/edge counts, and the active published version. `publish`, `rollback`, and `delete` use the exact-payload, one-use approval handshake.
+
+`dry_run` performs validation and policy simulation without executing nodes or side effects. It returns `executed: false`, redacted result metadata, and blockers such as missing or denied credential bindings. Credential actions return metadata only; decrypted credential values never cross the service or MCP response boundary. Custom-node validation reuses the governed project generator/build pipeline and returns checks, issues, capabilities, and credential slots rather than source bundles.
 
 The graph payload is the shared `NodeFlowGraph` contract:
 
@@ -459,6 +461,8 @@ Attach a flow as an agent skill:
 }
 ```
 
+An attachment also gives that authenticated agent the narrow `run_attached_flow` capability. Its catalog entry contains only `flowId`, name, description, input schema, and `operation: "run_attached_flow"`; it never includes the graph or credentials. Execution verifies project ownership, the attachment, current publication, and credential policy, then records `initiatingAgentId`, the originating conversation id when present, and `triggerType: "attached_flow"` in run audit metadata.
+
 Run a flow:
 
 ```json
diff --git a/src/api/mcp/tool-registry.ts b/src/api/mcp/tool-registry.ts
index 5d8d06b28d..b44bed9293 100644
--- a/src/api/mcp/tool-registry.ts
+++ b/src/api/mcp/tool-registry.ts
@@ -1,5 +1,5 @@
 import type { ToolName as ContractToolName } from "../../contracts/mcp-tool-definitions.js";
-import type { ManageCodeUxArgs, ManageProjectsArgs, ManageSprintsArgs, ManageTasksArgs, ManageQuicksprintsArgs, ManageSchedulerArgs, SchedulerArgs, ManageAgentsArgs, ManageNodeFlowsArgs, ManageMemoryArgs, AddLongTermMemoryArgs, ManageSkillsArgs, ManageSettingsArgs, ManagePreviewArgs, ManageCustomDashboardsArgs, ManageChatProvidersArgs, ManageTelemetryArgs, SearchKnowledgeArgs, SearchSkillsArgs, RequestClarificationArgs, ReplyToClarificationArgs } from "../../contracts/internal-management-types.js";
+import type { ManageCodeUxArgs, ManageProjectsArgs, ManageSprintsArgs, ManageTasksArgs, ManageQuicksprintsArgs, ManageSchedulerArgs, SchedulerArgs, ManageAgentsArgs, ManageNodeFlowsArgs, ManageMemoryArgs, AddLongTermMemoryArgs, ManageSkillsArgs, ManageSettingsArgs, ManagePreviewArgs, ManageCustomDashboardsArgs, ManageChatProvidersArgs, ManageTelemetryArgs, SearchKnowledgeArgs, SearchSkillsArgs, RequestClarificationArgs, ReplyToClarificationArgs, RunAttachedFlowArgs } from "../../contracts/internal-management-types.js";
 import type { PullWorkerTaskDispatchArgs, RegisterExternalWorkerEndpointArgs, UpdateWorkerTaskDispatchArgs } from "../../services/worker-task-dispatch-service.js";
 
 export interface McpToolArgsByName {
@@ -14,6 +14,7 @@ export interface McpToolArgsByName {
   scheduler_code_ux: SchedulerArgs;
   manage_agents: ManageAgentsArgs;
   manage_node_flows: ManageNodeFlowsArgs;
+  run_attached_flow: RunAttachedFlowArgs;
   manage_memory: ManageMemoryArgs;
   add_long_term_memory: AddLongTermMemoryArgs;
   manage_skills: ManageSkillsArgs;
diff --git a/src/app/dependency-factory/core-factory.ts b/src/app/dependency-factory/core-factory.ts
index 4e56765e25..6d97a2bd16 100644
--- a/src/app/dependency-factory/core-factory.ts
+++ b/src/app/dependency-factory/core-factory.ts
@@ -310,7 +310,7 @@ export function createCoreDependencies(
   const schedulerRepository = new SchedulerRepository(appDbStorage, dashboardRealtimeService);
   const skillRepository = new SkillRepository(appDbStorage);
   const nodeFlowRepository = new NodeFlowRepository(appDbStorage, dashboardRealtimeService);
-  const nodeFlowService = new NodeFlowService(nodeFlowRepository);
+  const nodeFlowService = new NodeFlowService(nodeFlowRepository, undefined, credentialBroker);
   const embeddingService = new EmbeddingService();
   const embeddingModelManager = new EmbeddingModelManager(
     embeddingService,
diff --git a/src/app/dependency-factory/dashboard-factory.ts b/src/app/dependency-factory/dashboard-factory.ts
index 32367a3a6f..629e0a49ff 100644
--- a/src/app/dependency-factory/dashboard-factory.ts
+++ b/src/app/dependency-factory/dashboard-factory.ts
@@ -41,6 +41,8 @@ import { AutomationOutboxRepository } from "../../repositories/automation-outbox
 import { AutomationWebhookTriggerRepository } from "../../repositories/automation-webhook-trigger-repository.js";
 import { CustomNodeRepository } from "../../repositories/custom-node-repository.js";
 import { CustomNodeRuntimeService } from "../../services/custom-nodes/custom-node-runtime-service.js";
+import { CustomNodeProjectService } from "../../services/custom-nodes/custom-node-project-service.js";
+import { CustomNodeBuildService } from "../../services/custom-nodes/custom-node-build-service.js";
 import { customNodeDefinitionFromArtifact } from "../../contracts/custom-node-types.js";
 import { registerCustomNodeDefinition } from "../../domain/node-flows/node-definition-registry.js";
 
@@ -243,6 +245,8 @@ export function createDashboardDependencies(
   const approvalService = new ApprovalService(approvalRepository);
   const egressPolicyService = new EgressPolicyService();
   const customNodeRepository = new CustomNodeRepository(coreDeps.appDbStorage);
+  const customNodeProjectService = new CustomNodeProjectService();
+  const customNodeBuildService = new CustomNodeBuildService({ repository: customNodeRepository, projectService: customNodeProjectService });
   for (const { artifact } of customNodeRepository.listPublications()) {
     registerCustomNodeDefinition(customNodeDefinitionFromArtifact(artifact));
   }
@@ -267,7 +271,16 @@ export function createDashboardDependencies(
   if (coreDeps.nodeFlowRepository) {
     new NodeFlowRecoveryService(coreDeps.nodeFlowRepository).recover();
   }
-  const nodeFlowService = new NodeFlowService(coreDeps.nodeFlowRepository, nodeFlowRuntimeService);
+  const nodeFlowService = new NodeFlowService(coreDeps.nodeFlowRepository, nodeFlowRuntimeService, coreDeps.credentialBroker, {
+    repository: customNodeRepository,
+    projectService: customNodeProjectService,
+    buildService: customNodeBuildService,
+    resolveProjectRoot: (projectId) => {
+      const project = coreDeps.projectManagementRepository.getProject(projectId);
+      if (!project) throw new Error(`Project not found: ${projectId}`);
+      return project.baseDir;
+    },
+  });
 
   const activityCacheService = new ActivityCacheService(
     {
diff --git a/src/contracts/internal-management-types.ts b/src/contracts/internal-management-types.ts
index e9bea58c43..7303c30b09 100644
--- a/src/contracts/internal-management-types.ts
+++ b/src/contracts/internal-management-types.ts
@@ -220,13 +220,30 @@ export interface ManageAgentsArgs {
 }
 
 export interface ManageNodeFlowsArgs {
-  action: "list" | "get" | "create" | "update" | "delete" | "validate" | "run" | "list_runs" | "get_run" | "attach_to_agent" | "detach_from_agent";
+  action:
+    | "catalog" | "get_node_definition" | "create_draft" | "patch_draft" | "validate_draft"
+    | "create_custom_node" | "update_custom_node" | "validate_custom_node"
+    | "request_credential" | "inspect_bindings" | "dry_run" | "publish" | "compare_versions"
+    | "rollback" | "run" | "cancel" | "retry" | "inspect_run" | "list_runs"
+    | "list" | "get" | "create" | "update" | "delete" | "validate" | "get_run"
+    | "attach_to_agent" | "detach_from_agent" | "attach" | "detach";
   projectId?: string;
   flowId?: string;
   runId?: string;
+  nodeType?: string;
+  nodeVersion?: number;
+  nodeId?: string;
+  slot?: string;
+  draftRevision?: number;
+  fromVersion?: number;
+  toVersion?: number;
+  version?: number;
+  publishedBy?: string;
   name?: string;
   description?: string;
   graph?: NodeFlowGraph;
+  patch?: Record<string, unknown>;
+  operations?: import("./node-flow-types.js").NodeFlowGraphPatchOperation[];
   widgets?: NodeWidgetSchema | Record<string, NodeWidgetSchema>;
   input?: NodeFlowJsonObject;
   agentPresetId?: string;
@@ -234,6 +251,12 @@ export interface ManageNodeFlowsArgs {
   approval?: ManagementApproval;
 }
 
+export interface RunAttachedFlowArgs {
+  projectId: string;
+  flowId: string;
+  input?: NodeFlowJsonObject;
+}
+
 export interface ManageMemoryArgs {
   action: "search" | "list" | "get" | "create" | "update" | "delete" | "promote" | "start_reembed" | "get_map" | "count" | "model_status" | "create_claim" | "list_claims" | "get_claim" | "update_claim" | "add_claim_evidence" | "deprecate_claim";
   projectId?: string;
diff --git a/src/contracts/mcp-tool-definitions.ts b/src/contracts/mcp-tool-definitions.ts
index d5be21c953..b5f8b2695b 100644
--- a/src/contracts/mcp-tool-definitions.ts
+++ b/src/contracts/mcp-tool-definitions.ts
@@ -390,17 +390,33 @@ export const TOOL_DEFINITIONS = [
     name: "manage_node_flows",
     runtimeRoles: ["project_manager"],
     category: "agents_memory",
-    description: "Manage Code UX node flows as reusable agent skills. Supports list, get, create, update, delete, validate, run, list_runs, get_run, attach_to_agent, and detach_from_agent. Build Code UX-adapted flows with typed graph nodes and dynamic widget schemas for editable fields; do not clone n8n workflows one-to-one. Deleting flows requires approval confirmation.",
+    description: "Govern node-flow authoring, validation, credential bindings, publication, version review, and operational runs. Legacy list/get/create/update/delete/validate/run/attach aliases remain available; publish, rollback, and delete require approval.",
     inputSchema: {
       type: "object",
       properties: {
-        action: { type: "string", enum: ["list", "get", "create", "update", "delete", "validate", "run", "list_runs", "get_run", "attach_to_agent", "detach_from_agent"], description: "The node-flow action to perform." },
+        action: { type: "string", enum: ["catalog", "get_node_definition", "create_draft", "patch_draft", "validate_draft", "create_custom_node", "update_custom_node", "validate_custom_node", "request_credential", "inspect_bindings", "dry_run", "publish", "compare_versions", "rollback", "run", "cancel", "retry", "inspect_run", "list_runs", "list", "get", "create", "update", "delete", "validate", "get_run", "attach_to_agent", "detach_from_agent", "attach", "detach"], description: "The governed node-flow action or compatibility alias to perform." },
         projectId: { type: "string", description: "Required for list, create, run, and validation of new graph specs." },
         flowId: { type: "string", description: "Required for get, update, delete, run, list_runs, attach_to_agent, and detach_from_agent." },
         runId: { type: "string", description: "Required for get_run." },
+        nodeType: { type: "string", description: "Node-definition type for get_node_definition." },
+        nodeVersion: { type: "integer", minimum: 1, description: "Optional node-definition version." },
+        nodeId: { type: "string", description: "Node id for custom-node and credential actions." },
+        slot: { type: "string", description: "Credential slot for request_credential." },
+        draftRevision: { type: "integer", minimum: 1, description: "Required optimistic revision for patch, publish, and rollback." },
+        fromVersion: { type: "integer", minimum: 1 },
+        toVersion: { type: "integer", minimum: 1 },
+        version: { type: "integer", minimum: 1, description: "Historical version used by rollback." },
+        publishedBy: { type: "string", description: "Publication audit actor; defaults to the MCP project manager identity." },
+        sourceRevision: { type: "string", description: "Immutable custom-node source revision." },
+        actor: { type: "string", description: "Custom-node audit actor." },
+        invocationId: { type: "string", description: "Custom-node validation invocation id." },
+        correlationId: { type: "string", description: "Custom-node validation correlation id." },
+        manifest: { type: "object", additionalProperties: true, description: "Complete governed custom-node manifest for update_custom_node." },
         name: { type: "string", description: "Required for create. Optional title for update." },
         description: { type: "string", description: "Optional flow or attached skill description." },
         graph: { type: "object", additionalProperties: true, description: "Structured node-flow graph. Required for create and standalone validate. Optional for update and validate existing flow." },
+        patch: { type: "object", additionalProperties: true, description: "Optimistic draft patch containing graph, operations, name, or description." },
+        operations: { type: "array", items: { type: "object", additionalProperties: true }, description: "Typed graph patch operations." },
         widgets: { type: "object", additionalProperties: true, description: "Optional dynamic widget schemas for editable graph inputs or node fields. Use a fields array for graph inputSchema or node-id keys for node widgetSchema entries." },
         input: { type: "object", additionalProperties: true, description: "Optional JSON object passed to run." },
         agentPresetId: { type: "string", description: "Required for attach_to_agent and detach_from_agent." },
@@ -415,6 +431,23 @@ export const TOOL_DEFINITIONS = [
       required: ["action"],
     },
   },
+  {
+    name: "run_attached_flow",
+    runtimeRoles: ["project_manager"],
+    audiences: ["project_manager", "worker"],
+    category: "agents_memory",
+    description: "Run one published node flow explicitly attached to the authenticated agent. The server derives agent and conversation identity and never exposes the flow graph or credential material.",
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        projectId: { type: "string", minLength: 1 },
+        flowId: { type: "string", minLength: 1 },
+        input: { type: "object", additionalProperties: true },
+      },
+      required: ["projectId", "flowId"],
+    },
+  },
   {
     name: "manage_memory",
     runtimeRoles: ["project_manager"],
diff --git a/src/contracts/node-flow-types.ts b/src/contracts/node-flow-types.ts
index d675f327d9..bce9c7ce8c 100644
--- a/src/contracts/node-flow-types.ts
+++ b/src/contracts/node-flow-types.ts
@@ -184,6 +184,65 @@ export interface UpdateNodeFlowInput {
   graph?: NodeFlowGraph;
 }
 
+export type NodeFlowGraphPatchOperation =
+  | { op: "upsert_node"; node: NodeFlowNode }
+  | { op: "remove_node"; nodeId: string }
+  | { op: "upsert_edge"; edge: NodeFlowEdge }
+  | { op: "remove_edge"; edgeId?: string; fromNodeId?: string; toNodeId?: string }
+  | { op: "set_input_schema"; inputSchema: NodeWidgetSchema | null }
+  | { op: "set_metadata"; metadata: NodeFlowJsonObject | null };
+
+export interface PatchNodeFlowDraftInput {
+  projectId: string;
+  draftRevision: number;
+  graph?: NodeFlowGraph;
+  operations?: NodeFlowGraphPatchOperation[];
+  title?: string;
+  description?: string;
+}
+
+export interface NodeFlowConcurrencyConflict {
+  code: "draft_revision_conflict";
+  flowId: string;
+  expectedDraftRevision: number;
+  actualDraftRevision: number;
+  message: string;
+}
+
+export interface NodeFlowPolicyFinding {
+  severity: "info" | "warning" | "error";
+  code: string;
+  nodeId?: string;
+  message: string;
+}
+
+export interface NodeFlowRequiredCredential {
+  nodeId: string;
+  slot: string;
+  allowedKinds: string[];
+  requiredCapabilities: string[];
+  required: boolean;
+  credentialId: string | null;
+  status: "bound" | "missing" | "denied";
+}
+
+export interface NodeFlowDraftReview {
+  flowId: string;
+  projectId: string;
+  name: string;
+  description: string;
+  draftRevision: number;
+  nodeCount: number;
+  edgeCount: number;
+  valid: boolean;
+  validationIssues: NodeFlowValidationIssue[];
+  policyFindings: NodeFlowPolicyFinding[];
+  requiredCredentials: NodeFlowRequiredCredential[];
+  requestedCapabilities: string[];
+  sideEffectDiffs: Array<{ nodeId: string; sideEffect: NodeFlowSideEffect; description: string }>;
+  publishedVersion: number | null;
+}
+
 export interface NodeFlowValidationIssue {
   field: string;
   code: string;
diff --git a/src/mcp/management-tool-handler.ts b/src/mcp/management-tool-handler.ts
index ffed6a7444..36e3870e22 100644
--- a/src/mcp/management-tool-handler.ts
+++ b/src/mcp/management-tool-handler.ts
@@ -20,10 +20,11 @@ import type {
   SearchKnowledgeArgs,
   SearchSkillsArgs,
   RequestClarificationArgs,
-  ReplyToClarificationArgs
+  ReplyToClarificationArgs,
+  RunAttachedFlowArgs,
 } from "../contracts/internal-management-types.js";
 import type { KnowledgeService } from "../services/knowledge-service.js";
-import { getCurrentMcpAgentId } from "../server/mcp-agent-context.js";
+import { getCurrentMcpAgentId, getCurrentMcpThreadId } from "../server/mcp-agent-context.js";
 import type { SprintPreviewService } from "../services/sprint-preview-service.js";
 import type { CustomDashboardRepository } from "../repositories/custom-dashboard-repository.js";
 import type { CustomDashboardValidationService } from "../services/custom-dashboard-validation-service.js";
@@ -46,6 +47,7 @@ import type {
 } from "../services/worker-task-dispatch-service.js";
 import type { SkillService } from "../services/skill-service.js";
 import type { NodeFlowService } from "../services/node-flow-service.js";
+import { NodeFlowAgentSkillService } from "../services/node-flow-agent-skill-service.js";
 import type { WorkerClarificationService } from "../services/worker-clarification-service.js";
 import type { WorkerClarificationContinuationService } from "../services/worker-clarification-continuation-service.js";
 
@@ -116,6 +118,7 @@ export class ManagementToolHandler {
   private readonly settingsActions: SettingsActions;
   private readonly agentActions: AgentActions;
   private readonly nodeFlowActions: NodeFlowActions;
+  private readonly nodeFlowAgentSkillService: NodeFlowAgentSkillService;
   private readonly memoryActions: MemoryActions;
   private readonly skillActions: SkillActions;
   private readonly previewActions: PreviewActions;
@@ -126,6 +129,7 @@ export class ManagementToolHandler {
     this.settingsActions = new SettingsActions(deps.settingsRepository);
     this.agentActions = new AgentActions(deps.agentPresetSyncService);
     this.nodeFlowActions = new NodeFlowActions(deps.nodeFlowService);
+    this.nodeFlowAgentSkillService = new NodeFlowAgentSkillService(deps.nodeFlowService);
     this.memoryActions = new MemoryActions(deps.memoryService, deps.memoryPromotionService, deps.embeddingModelManager);
     this.skillActions = new SkillActions(deps.skillService);
     this.previewActions = new PreviewActions(deps.sprintPreviewService);
@@ -239,6 +243,8 @@ export class ManagementToolHandler {
       || args.action.startsWith("replace_")
       || args.action === "remove_session"
       || args.action === "archive"
+      || args.action === "publish"
+      || args.action === "rollback"
       || args.action === "deprecate_claim";
   }
 
@@ -456,6 +462,23 @@ export class ManagementToolHandler {
     }
   }
 
+  async handleRunAttachedFlow(args: RunAttachedFlowArgs): Promise<{ content: Array<{ type: string; text: string }> }> {
+    try {
+      const agentPresetId = getCurrentMcpAgentId();
+      if (!agentPresetId) throw new Error("An authenticated agent is required to run an attached flow.");
+      const result = await this.nodeFlowAgentSkillService.runAttachedFlow({
+        projectId: args.projectId,
+        flowId: args.flowId,
+        agentPresetId,
+        conversationId: getCurrentMcpThreadId(),
+        parameters: args.input,
+      });
+      return { content: [{ type: "text", text: JSON.stringify({ result }, null, 2) }] };
+    } catch (error) {
+      return this.formatError("node_flows", "run_attached_flow", error);
+    }
+  }
+
   async handleManageMemory(args: ManageMemoryArgs): Promise<{ content: Array<{ type: string; text: string }> }> {
     try {
       const managementArgs = { domain: "memory", action: args.action, payload: args as unknown as Record<string, unknown>, approval: args.approval };
diff --git a/src/mcp/management/node-flow-actions.ts b/src/mcp/management/node-flow-actions.ts
index a35437f0b5..997806ad6c 100644
--- a/src/mcp/management/node-flow-actions.ts
+++ b/src/mcp/management/node-flow-actions.ts
@@ -13,11 +13,13 @@ import type {
   NodeWidgetSchema,
 } from "../../contracts/node-flow-types.js";
 import type { NodeFlowService } from "../../services/node-flow-service.js";
+import { getCurrentMcpAgentId } from "../../server/mcp-agent-context.js";
 import {
   managementValidationError,
   parseOptionalObject,
   parseOptionalNumber,
   parseOptionalString,
+  parseOptionalIntegerStrict,
   parseRequiredObject,
   parseRequiredString,
 } from "./payload-parsers.js";
@@ -33,6 +35,28 @@ export class NodeFlowActions {
     switch (args.action) {
       case "list":
         return this.listFlows(payload);
+      case "catalog":
+        return { result: this.nodeFlowService.catalog() };
+      case "get_node_definition":
+        return this.getNodeDefinition(payload);
+      case "create_draft":
+        return this.createDraft(payload);
+      case "patch_draft":
+        return this.patchDraft(payload);
+      case "validate_draft":
+        return this.validateDraft(payload);
+      case "request_credential":
+        return this.requestCredential(payload);
+      case "inspect_bindings":
+        return this.inspectBindings(payload);
+      case "dry_run":
+        return this.dryRun(payload);
+      case "publish":
+        return this.publishDraft(args, payload);
+      case "compare_versions":
+        return this.compareVersions(payload);
+      case "rollback":
+        return this.rollback(args, payload);
       case "get":
         return this.getFlow(payload);
       case "create":
@@ -45,19 +69,133 @@ export class NodeFlowActions {
         return this.validateFlow(payload);
       case "run":
         return await this.runFlow(payload);
+      case "cancel":
+        return this.cancelRun(payload);
+      case "retry":
+        return await this.retryRun(payload);
       case "list_runs":
         return this.listRuns(payload);
       case "get_run":
-        return this.getRun(payload);
+      case "inspect_run":
+        return this.getRun(payload, args.action === "inspect_run");
       case "attach_to_agent":
+      case "attach":
         return this.attachToAgent(payload);
       case "detach_from_agent":
+      case "detach":
         return this.detachFromAgent(payload);
+      case "create_custom_node":
+        return await this.createCustomNode(payload);
+      case "update_custom_node":
+        return await this.updateCustomNode(payload);
+      case "validate_custom_node":
+        return await this.validateCustomNode(payload);
       default:
         throw new Error(`Unknown node flow action: ${args.action}`);
     }
   }
 
+  private getNodeDefinition(payload: Record<string, unknown>): ManagementResponseEnvelope {
+    const nodeType = parseRequiredString(payload, "nodeType");
+    const version = parseOptionalIntegerStrict(payload, "nodeVersion", { min: 1 });
+    const definition = this.nodeFlowService.nodeDefinition(nodeType, version);
+    if (!definition) throw managementValidationError(`Node definition not found: ${nodeType}${version ? `@${version}` : ""}`, "nodeType");
+    return { result: { definition } };
+  }
+
+  private createDraft(payload: Record<string, unknown>): ManagementResponseEnvelope {
+    const graph = this.parseGraphWithWidgets(payload, true);
+    if (!graph) throw managementValidationError("graph object is required", "graph");
+    const validation = this.nodeFlowService.validate(graph);
+    if (!validation.valid || !validation.graph) return { result: { status: "invalid", validationIssues: validation.errors } };
+    return { result: { draft: this.nodeFlowService.createDraft(parseRequiredString(payload, "projectId"), {
+      title: parseRequiredString(payload, "name"), description: parseOptionalText(payload, "description"), graph: validation.graph,
+    }) } };
+  }
+
+  private patchDraft(payload: Record<string, unknown>): ManagementResponseEnvelope {
+    const projectId = parseRequiredString(payload, "projectId");
+    const flowId = parseRequiredString(payload, "flowId");
+    const draftRevision = requiredInteger(payload, "draftRevision");
+    const patch = parseOptionalObject<Record<string, unknown>>(payload, "patch") ?? {};
+    const graph = this.parseGraphWithWidgets(patch, false) ?? this.parseGraphWithWidgets(payload, false);
+    const operations = Array.isArray(patch.operations) ? patch.operations : Array.isArray(payload.operations) ? payload.operations : undefined;
+    return { result: this.nodeFlowService.patchDraft(flowId, {
+      projectId, draftRevision, graph,
+      operations: operations as import("../../contracts/node-flow-types.js").NodeFlowGraphPatchOperation[] | undefined,
+      title: parseOptionalString(patch, "name") ?? parseOptionalString(payload, "name"),
+      description: parseOptionalText(patch, "description") ?? parseOptionalText(payload, "description"),
+    }) };
+  }
+
+  private validateDraft(payload: Record<string, unknown>): ManagementResponseEnvelope {
+    return { result: { draft: this.nodeFlowService.validateDraft(parseRequiredString(payload, "projectId"), parseRequiredString(payload, "flowId")) } };
+  }
+
+  private requestCredential(payload: Record<string, unknown>): ManagementResponseEnvelope {
+    return { result: { request: this.nodeFlowService.requestCredential(parseRequiredString(payload, "projectId"), parseRequiredString(payload, "flowId"), parseRequiredString(payload, "nodeId"), parseRequiredString(payload, "slot")) } };
+  }
+
+  private inspectBindings(payload: Record<string, unknown>): ManagementResponseEnvelope {
+    return { result: this.nodeFlowService.inspectBindings(parseRequiredString(payload, "projectId"), parseRequiredString(payload, "flowId")) };
+  }
+
+  private dryRun(payload: Record<string, unknown>): ManagementResponseEnvelope {
+    return { result: this.nodeFlowService.dryRun(parseRequiredString(payload, "projectId"), parseRequiredString(payload, "flowId"), parseOptionalObject<NodeFlowJsonObject>(payload, "input") ?? {}) };
+  }
+
+  private publishDraft(args: ManageCodeUxArgs, payload: Record<string, unknown>): ManagementResponseEnvelope {
+    const flowId = parseRequiredString(payload, "flowId");
+    const draftRevision = requiredInteger(payload, "draftRevision");
+    if (args.approval?.confirmed !== true) return { approvalRequired: true, approvalMessage: `Publish node flow ${flowId} draft revision ${draftRevision} after reviewing validation, credentials, capabilities, and side effects.` };
+    return { result: { draft: this.nodeFlowService.publishDraft(parseRequiredString(payload, "projectId"), flowId, draftRevision, parseOptionalString(payload, "publishedBy") ?? "project-manager-mcp") } };
+  }
+
+  private compareVersions(payload: Record<string, unknown>): ManagementResponseEnvelope {
+    return { result: this.nodeFlowService.compareVersions(parseRequiredString(payload, "projectId"), parseRequiredString(payload, "flowId"), requiredInteger(payload, "fromVersion"), requiredInteger(payload, "toVersion")) };
+  }
+
+  private rollback(args: ManageCodeUxArgs, payload: Record<string, unknown>): ManagementResponseEnvelope {
+    const flowId = parseRequiredString(payload, "flowId");
+    const version = requiredInteger(payload, "version");
+    if (args.approval?.confirmed !== true) return { approvalRequired: true, approvalMessage: `Create a new draft of node flow ${flowId} from version ${version}. The current draft remains in immutable history.` };
+    return { result: { draft: this.nodeFlowService.rollback(parseRequiredString(payload, "projectId"), flowId, version, requiredInteger(payload, "draftRevision")) } };
+  }
+
+  private cancelRun(payload: Record<string, unknown>): ManagementResponseEnvelope {
+    return { result: { run: formatRun(this.nodeFlowService.cancelRun(parseRequiredString(payload, "projectId"), parseRequiredString(payload, "runId"))) } };
+  }
+
+  private async retryRun(payload: Record<string, unknown>): Promise<ManagementResponseEnvelope> {
+    return { result: formatRunSummary(await this.nodeFlowService.retryRun(parseRequiredString(payload, "projectId"), parseRequiredString(payload, "runId"))) };
+  }
+
+  private async createCustomNode(payload: Record<string, unknown>): Promise<ManagementResponseEnvelope> {
+    const node = await this.nodeFlowService.createCustomNode(parseRequiredString(payload, "projectId"), {
+      nodeId: parseRequiredString(payload, "nodeId"), name: parseRequiredString(payload, "name"),
+      description: parseOptionalText(payload, "description"), sourceRevision: parseRequiredString(payload, "sourceRevision"),
+      createdBy: parseOptionalString(payload, "actor") ?? "project-manager-mcp",
+    });
+    return { result: { node } };
+  }
+
+  private async updateCustomNode(payload: Record<string, unknown>): Promise<ManagementResponseEnvelope> {
+    const node = await this.nodeFlowService.updateCustomNode(
+      parseRequiredString(payload, "projectId"), parseRequiredString(payload, "nodeId"),
+      parseRequiredObject(payload, "manifest"), parseRequiredString(payload, "sourceRevision"),
+    );
+    return { result: { node } };
+  }
+
+  private async validateCustomNode(payload: Record<string, unknown>): Promise<ManagementResponseEnvelope> {
+    return { result: await this.nodeFlowService.validateCustomNode(
+      parseRequiredString(payload, "projectId"), parseRequiredString(payload, "nodeId"),
+      parseOptionalString(payload, "actor") ?? "project-manager-mcp",
+      parseOptionalString(payload, "invocationId") ?? `mcp-custom-node-${Date.now()}`,
+      parseOptionalString(payload, "correlationId") ?? `mcp-custom-node-${Date.now()}`,
+    ) };
+  }
+
   private listFlows(payload: Record<string, unknown>): ManagementResponseEnvelope {
     const projectId = parseRequiredString(payload, "projectId");
     const flows = this.nodeFlowService.list(projectId).flows.map(formatFlowSummary);
@@ -70,7 +208,8 @@ export class NodeFlowActions {
     this.assertProjectMatch(payload, flow);
     return {
       result: {
-        flow: formatFlow(flow),
+        flow: formatFlowForCaller(flow),
+        ...(getCurrentMcpAgentId() ? { draft: this.nodeFlowService.validateDraft(flow.projectId, flow.id) } : {}),
         agentSkills: this.nodeFlowService.listAgentSkills(flow.id),
       },
     };
@@ -92,7 +231,7 @@ export class NodeFlowActions {
       description: parseOptionalText(payload, "description"),
       graph: validation.graph,
     });
-    return { result: { flow: formatFlow(flow) } };
+    return { result: { flow: formatFlowForCaller(flow) } };
   }
 
   private updateFlow(payload: Record<string, unknown>): ManagementResponseEnvelope {
@@ -110,7 +249,7 @@ export class NodeFlowActions {
       ...(description !== undefined ? { description } : {}),
       ...(validation?.graph ? { graph: validation.graph } : {}),
     });
-    return { result: { flow: formatFlow(flow) } };
+    return { result: { flow: formatFlowForCaller(flow) } };
   }
 
   private deleteFlow(args: ManageCodeUxArgs, payload: Record<string, unknown>): ManagementResponseEnvelope {
@@ -152,16 +291,20 @@ export class NodeFlowActions {
 
   private listRuns(payload: Record<string, unknown>): ManagementResponseEnvelope {
     const flowId = parseRequiredString(payload, "flowId");
+    const projectId = parseOptionalString(payload, "projectId");
+    if (projectId) this.assertProjectMatch(payload, this.requireFlow(flowId));
     const runs = this.nodeFlowService.listRuns(flowId).runs.map(formatRun);
     return { result: { runs } };
   }
 
-  private getRun(payload: Record<string, unknown>): ManagementResponseEnvelope {
+  private getRun(payload: Record<string, unknown>, requireProject = false): ManagementResponseEnvelope {
     const runId = parseRequiredString(payload, "runId");
+    const projectId = requireProject ? parseRequiredString(payload, "projectId") : parseOptionalString(payload, "projectId");
     const run = this.nodeFlowService.getRun(runId);
     if (!run) {
       throw new Error(`Node flow run not found: ${runId}`);
     }
+    if (projectId && run.projectId !== projectId) throw managementValidationError("Node flow run does not belong to the requested project.", "projectId");
     return {
       result: {
         run: formatRun(run),
@@ -221,6 +364,12 @@ export class NodeFlowActions {
   }
 }
 
+function requiredInteger(payload: Record<string, unknown>, key: string): number {
+  const value = parseOptionalIntegerStrict(payload, key, { min: 1 });
+  if (value === undefined) throw managementValidationError(`${key} is required`, key);
+  return value;
+}
+
 function parseOptionalText(payload: Record<string, unknown>, key: string): string | undefined {
   if (!(key in payload)) {
     return undefined;
@@ -289,6 +438,10 @@ function formatFlow(flow: NodeFlowRecord): Record<string, unknown> {
   };
 }
 
+function formatFlowForCaller(flow: NodeFlowRecord): Record<string, unknown> {
+  return getCurrentMcpAgentId() ? formatFlowSummary(flow) : formatFlow(flow);
+}
+
 function formatRun(run: NodeFlowRunRecord): Record<string, unknown> {
   return {
     ...run,
diff --git a/src/repositories/custom-node-repository.ts b/src/repositories/custom-node-repository.ts
index f4d41d6ce5..3a44dd77ee 100644
--- a/src/repositories/custom-node-repository.ts
+++ b/src/repositories/custom-node-repository.ts
@@ -65,6 +65,16 @@ export class CustomNodeRepository {
       .map((row) => this.mapNode(row));
   }
 
+  updateDraft(nodeId: string, manifest: CustomNodeManifest, sourceRevision: string): CustomNodeRecord {
+    const node = this.requireNode(nodeId);
+    if (node.status === "published" || node.status === "validating") throw new ValidationError("Published or validating custom node revisions are immutable.");
+    if (manifest.id !== node.id || manifest.nodeType !== node.manifest.nodeType) throw new ValidationError("Custom node identity cannot be changed.");
+    if (!sourceRevision.trim()) throw new ValidationError("Custom node source revision is required.");
+    this.db.prepare("UPDATE custom_nodes SET status = 'draft', source_revision = ?, manifest_json = ?, validation_report_json = NULL, artifact_digest = NULL, updated_at = ? WHERE id = ?")
+      .run(sourceRevision.trim(), JSON.stringify(manifest), new Date().toISOString(), nodeId);
+    return this.requireNode(nodeId);
+  }
+
   beginValidation(nodeId: string): CustomNodeRecord {
     const node = this.requireNode(nodeId);
     if (node.status === "published") throw new ValidationError("Published custom node revisions are immutable.");
diff --git a/src/repositories/node-flow-repository.ts b/src/repositories/node-flow-repository.ts
index c3648e3606..d40fea4196 100644
--- a/src/repositories/node-flow-repository.ts
+++ b/src/repositories/node-flow-repository.ts
@@ -144,7 +144,7 @@ export class NodeFlowRepository {
     return row ? this.mapFlowRow(row) : null;
   }
 
-  createFlow(projectId: string, input: CreateNodeFlowInput): NodeFlowRecord {
+  createFlow(projectId: string, input: CreateNodeFlowInput, options: { publish?: boolean; publishedBy?: string } = {}): NodeFlowRecord {
     this.requireProject(projectId);
     const now = new Date().toISOString();
     const id = input.id?.trim() || randomUUID();
@@ -166,7 +166,9 @@ export class NodeFlowRepository {
         graphJson,
         createdAt: now,
       });
-      this.insertPublication(id, projectId, 1, graphJson, DEFAULT_NODE_FLOW_EXECUTION_POLICY, "system");
+      if (options.publish !== false) {
+        this.insertPublication(id, projectId, 1, graphJson, DEFAULT_NODE_FLOW_EXECUTION_POLICY, options.publishedBy ?? "system");
+      }
     });
 
     const created = this.requireFlow(id);
@@ -174,7 +176,7 @@ export class NodeFlowRepository {
     return created;
   }
 
-  updateFlow(flowId: string, input: UpdateNodeFlowInput): NodeFlowRecord {
+  updateFlow(flowId: string, input: UpdateNodeFlowInput, options: { publish?: boolean; publishedBy?: string } = {}): NodeFlowRecord {
     const current = this.requireFlow(flowId);
     const now = new Date().toISOString();
     const title = input.title === undefined ? current.title : this.requireTitle(input.title);
@@ -198,7 +200,9 @@ export class NodeFlowRepository {
         graphJson,
         createdAt: now,
       });
-      this.insertPublication(flowId, current.projectId, nextVersion, graphJson, DEFAULT_NODE_FLOW_EXECUTION_POLICY, "system");
+      if (options.publish !== false) {
+        this.insertPublication(flowId, current.projectId, nextVersion, graphJson, DEFAULT_NODE_FLOW_EXECUTION_POLICY, options.publishedBy ?? "system");
+      }
     });
 
     const updated = this.requireFlow(flowId);
diff --git a/src/server/code-ux-server.ts b/src/server/code-ux-server.ts
index ca7ac7b433..aa6e8e21e2 100644
--- a/src/server/code-ux-server.ts
+++ b/src/server/code-ux-server.ts
@@ -49,6 +49,7 @@ import {
   isProjectManagerClarificationAgent,
   isWorkerClarificationAgent,
   toAgentCodeUxToolAccess,
+  withAttachedFlowAccess,
   withClarificationAudienceAccess,
 } from "../services/agent-mcp-access.js";
 import { JulesSourceResolver } from "../services/jules-source-resolver.js";
@@ -525,6 +526,9 @@ export class CodeUxServer {
           : persistentSkillRetrievalEnabled
             ? toAgentCodeUxToolAccess({ codeUxEnabled: false, codeUxToolToggles: [] }, true)
             : { codeUxEnabled: false, codeUxToolToggles: [] };
+        if (this.nodeFlowService.listAgentSkillsForAgent(agent.projectId, agent.id).length > 0) {
+          resolvedAccess = withAttachedFlowAccess(resolvedAccess);
+        }
         if (workerEligible) {
           resolvedAccess = withClarificationAudienceAccess(resolvedAccess, "worker", "request_clarification");
         }
diff --git a/src/server/mcp-request-router.ts b/src/server/mcp-request-router.ts
index 8470bebd40..6b2fefe52f 100644
--- a/src/server/mcp-request-router.ts
+++ b/src/server/mcp-request-router.ts
@@ -43,6 +43,7 @@ export const registerMcpRequestHandlers = (args: McpRequestRouterArgs): void =>
     .register("scheduler_code_ux", async (input) => (await args.managementToolHandler.handleScheduler(input)) as McpToolResponse)
     .register("manage_agents", async (input) => (await args.managementToolHandler.handleManageAgents(input)) as McpToolResponse)
     .register("manage_node_flows", async (input) => (await args.managementToolHandler.handleManageNodeFlows(input)) as McpToolResponse)
+    .register("run_attached_flow", async (input) => (await args.managementToolHandler.handleRunAttachedFlow(input)) as McpToolResponse)
     .register("manage_memory", async (input) => (await args.managementToolHandler.handleManageMemory(input)) as McpToolResponse)
     .register("add_long_term_memory", async (input) => (await args.managementToolHandler.handleAddLongTermMemory(input)) as McpToolResponse)
     .register("manage_skills", async (input) => (await args.managementToolHandler.handleManageSkills(input)) as McpToolResponse)
diff --git a/src/server/node-flow-routes.ts b/src/server/node-flow-routes.ts
index 4032685d0b..f20c244148 100644
--- a/src/server/node-flow-routes.ts
+++ b/src/server/node-flow-routes.ts
@@ -19,6 +19,102 @@ function requireNodeFlowService(deps: DashboardDependencies): NonNullable<Dashbo
 }
 
 export function registerNodeFlowRoutes(app: Express, deps: DashboardDependencies): void {
+  app.get("/api/node-flow-catalog", syncRoute((_req, res) => {
+    res.json(requireNodeFlowService(deps).catalog());
+  }));
+
+  app.get("/api/node-flow-catalog/:nodeType", syncRoute((req, res) => {
+    const definition = requireNodeFlowService(deps).nodeDefinition(
+      requireTrimmedString(req.params.nodeType, "nodeType"),
+      parseOptionalInteger(req.query.version, 1, Number.MAX_SAFE_INTEGER, "version"),
+    );
+    if (!definition) throw new HttpRouteError(404, "Node definition not found.");
+    res.json(definition);
+  }));
+
+  app.post("/api/projects/:projectId/node-flow-drafts", syncRoute((req, res) => {
+    res.status(201).json(requireNodeFlowService(deps).createDraft(
+      requireTrimmedString(req.params.projectId, "projectId"), req.body as CreateNodeFlowInput,
+    ));
+  }));
+
+  app.patch("/api/node-flow-drafts/:flowId", syncRoute((req, res) => {
+    const result = requireNodeFlowService(deps).patchDraft(
+      requireTrimmedString(req.params.flowId, "flowId"), req.body,
+    );
+    res.status(result.conflict ? 409 : 200).json(result);
+  }));
+
+  app.post("/api/node-flow-drafts/:flowId/validate", syncRoute((req, res) => {
+    res.json(requireNodeFlowService(deps).validateDraft(
+      requireTrimmedString(req.body?.projectId, "projectId"), requireTrimmedString(req.params.flowId, "flowId"),
+    ));
+  }));
+
+  app.post("/api/node-flow-drafts/:flowId/dry-run", syncRoute((req, res) => {
+    res.json(requireNodeFlowService(deps).dryRun(
+      requireTrimmedString(req.body?.projectId, "projectId"), requireTrimmedString(req.params.flowId, "flowId"), req.body?.input ?? {},
+    ));
+  }));
+
+  app.get("/api/node-flow-drafts/:flowId/bindings", syncRoute((req, res) => {
+    res.json(requireNodeFlowService(deps).inspectBindings(
+      requireTrimmedString(req.query.projectId, "projectId"), requireTrimmedString(req.params.flowId, "flowId"),
+    ));
+  }));
+
+  app.post("/api/node-flow-drafts/:flowId/credential-requests", syncRoute((req, res) => {
+    res.status(201).json(requireNodeFlowService(deps).requestCredential(
+      requireTrimmedString(req.body?.projectId, "projectId"), requireTrimmedString(req.params.flowId, "flowId"),
+      requireTrimmedString(req.body?.nodeId, "nodeId"), requireTrimmedString(req.body?.slot, "slot"),
+    ));
+  }));
+
+  app.post("/api/projects/:projectId/custom-nodes", asyncRoute(async (req, res) => {
+    res.status(201).json(await requireNodeFlowService(deps).createCustomNode(requireTrimmedString(req.params.projectId, "projectId"), req.body));
+  }));
+
+  app.put("/api/projects/:projectId/custom-nodes/:nodeId", asyncRoute(async (req, res) => {
+    res.json(await requireNodeFlowService(deps).updateCustomNode(
+      requireTrimmedString(req.params.projectId, "projectId"), requireTrimmedString(req.params.nodeId, "nodeId"), req.body?.manifest, requireTrimmedString(req.body?.sourceRevision, "sourceRevision"),
+    ));
+  }));
+
+  app.post("/api/projects/:projectId/custom-nodes/:nodeId/validate", asyncRoute(async (req, res) => {
+    res.json(await requireNodeFlowService(deps).validateCustomNode(
+      requireTrimmedString(req.params.projectId, "projectId"), requireTrimmedString(req.params.nodeId, "nodeId"),
+      requireTrimmedString(req.body?.actor, "actor"), requireTrimmedString(req.body?.invocationId, "invocationId"), requireTrimmedString(req.body?.correlationId, "correlationId"),
+    ));
+  }));
+
+  app.post("/api/node-flow-drafts/:flowId/publish", syncRoute((req, res) => {
+    res.json(requireNodeFlowService(deps).publishDraft(
+      requireTrimmedString(req.body?.projectId, "projectId"), requireTrimmedString(req.params.flowId, "flowId"),
+      parseRequiredBodyInteger(req.body?.draftRevision, "draftRevision"), requireTrimmedString(req.body?.publishedBy, "publishedBy"),
+    ));
+  }));
+
+  app.get("/api/node-flows/:flowId/compare", syncRoute((req, res) => {
+    res.json(requireNodeFlowService(deps).compareVersions(
+      requireTrimmedString(req.query.projectId, "projectId"), requireTrimmedString(req.params.flowId, "flowId"),
+      parseRequiredBodyInteger(req.query.fromVersion, "fromVersion"), parseRequiredBodyInteger(req.query.toVersion, "toVersion"),
+    ));
+  }));
+
+  app.post("/api/node-flows/:flowId/rollback", syncRoute((req, res) => {
+    res.json(requireNodeFlowService(deps).rollback(
+      requireTrimmedString(req.body?.projectId, "projectId"), requireTrimmedString(req.params.flowId, "flowId"),
+      parseRequiredBodyInteger(req.body?.version, "version"), parseRequiredBodyInteger(req.body?.draftRevision, "draftRevision"),
+    ));
+  }));
+
+  app.post("/api/node-flow-runs/:runId/cancel", syncRoute((req, res) => {
+    res.json(requireNodeFlowService(deps).cancelRun(requireTrimmedString(req.body?.projectId, "projectId"), requireTrimmedString(req.params.runId, "runId")));
+  }));
+
+  app.post("/api/node-flow-runs/:runId/retry", asyncRoute(async (req, res) => {
+    res.status(201).json(await requireNodeFlowService(deps).retryRun(requireTrimmedString(req.body?.projectId, "projectId"), requireTrimmedString(req.params.runId, "runId")));
+  }));
   app.get("/api/projects/:projectId/node-flows", syncRoute((req, res) => {
     res.json(requireNodeFlowService(deps).list(requireTrimmedString(req.params.projectId, "projectId")));
   }));
@@ -158,3 +254,9 @@ export function registerNodeFlowRoutes(app: Express, deps: DashboardDependencies
     res.status(201).json({ ...configured.trigger, pathToken: configured.pathToken, secret: configured.secret });
   }));
 }
+
+function parseRequiredBodyInteger(value: unknown, label: string): number {
+  const parsed = typeof value === "string" && value.trim() ? Number(value) : value;
+  if (typeof parsed !== "number" || !Number.isInteger(parsed) || parsed < 1) throw new HttpRouteError(400, `${label} must be a positive integer.`);
+  return parsed;
+}
diff --git a/src/services/agent-mcp-access.ts b/src/services/agent-mcp-access.ts
index 920fd0d217..1dd3f1bf91 100644
--- a/src/services/agent-mcp-access.ts
+++ b/src/services/agent-mcp-access.ts
@@ -117,6 +117,18 @@ export const withClarificationAudienceAccess = (
   audienceToolNames: Array.from(new Set([...(access.audienceToolNames ?? []), toolName])),
 });
 
+/** Expose only the narrow attached-flow runner when an agent owns at least one flow attachment. */
+export const withAttachedFlowAccess = (access: AgentCodeUxToolAccess): AgentCodeUxToolAccess => {
+  const byName = new Map(access.codeUxToolToggles.map((toggle) => [toggle.name, toggle]));
+  byName.set("run_attached_flow", { name: "run_attached_flow", enabled: true, isInternal: true });
+  return {
+    ...access,
+    codeUxEnabled: true,
+    audiences: Array.from(new Set([...(access.audiences ?? []), "worker" as const])),
+    codeUxToolToggles: Array.from(byName.values()),
+  };
+};
+
 const clarificationGatewayAccess = (
   access: AgentMcpAccessConfig | null | undefined,
   toolName: Extract<ToolName, "request_clarification" | "reply_to_clarification">,
diff --git a/src/services/custom-nodes/custom-node-project-service.ts b/src/services/custom-nodes/custom-node-project-service.ts
index fb33698a2a..2aebbfde0f 100644
--- a/src/services/custom-nodes/custom-node-project-service.ts
+++ b/src/services/custom-nodes/custom-node-project-service.ts
@@ -61,6 +61,12 @@ export class CustomNodeProjectService {
     return parsed as CustomNodeManifest;
   }
 
+  async writeManifest(projectRoot: string, nodeId: string, manifest: CustomNodeManifest): Promise<void> {
+    const root = this.resolveNodeRoot(projectRoot, nodeId);
+    if (manifest.id !== nodeId || manifest.nodeType !== `custom.${nodeId}`) throw new ValidationError("Custom node manifest identity does not match its project.");
+    await fs.writeFile(path.join(root, "node.json"), `${JSON.stringify(manifest, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+  }
+
   resolveNodeRoot(projectRoot: string, nodeId: string): string {
     if (!NODE_ID_PATTERN.test(nodeId)) throw new ValidationError("Invalid custom node id.");
     const base = path.resolve(projectRoot);
diff --git a/src/services/node-flow-agent-skill-service.ts b/src/services/node-flow-agent-skill-service.ts
new file mode 100644
index 0000000000..16de46ccfa
--- /dev/null
+++ b/src/services/node-flow-agent-skill-service.ts
@@ -0,0 +1,57 @@
+import type { NodeFlowJsonObject, NodeFlowRunSummaryResponse, NodeFlowValueSchema } from "../contracts/node-flow-types.js";
+import { ValidationError, EntityNotFoundError } from "../repositories/repository-utils.js";
+import type { NodeFlowService } from "./node-flow-service.js";
+
+export interface AttachedNodeFlowCapability {
+  flowId: string;
+  name: string;
+  description: string;
+  inputSchema: NodeFlowValueSchema;
+  operation: "run_attached_flow";
+}
+
+export class NodeFlowAgentSkillService {
+  constructor(private readonly nodeFlowService: NodeFlowService) {}
+
+  listCapabilities(projectId: string, agentPresetId: string): AttachedNodeFlowCapability[] {
+    return this.nodeFlowService.listAgentSkillsForAgent(projectId, agentPresetId).map((attachment) => {
+      const flow = this.nodeFlowService.get(attachment.flowId);
+      if (!flow || flow.projectId !== projectId) {
+        throw new ValidationError("Attached node flow is outside the agent project.");
+      }
+      return {
+        flowId: flow.id,
+        name: attachment.skillName,
+        description: attachment.description,
+        inputSchema: flow.graph.schemas?.input ?? { type: "object" },
+        operation: "run_attached_flow",
+      };
+    });
+  }
+
+  async runAttachedFlow(input: {
+    projectId: string;
+    flowId: string;
+    agentPresetId: string;
+    conversationId?: string | null;
+    parameters?: NodeFlowJsonObject;
+  }): Promise<NodeFlowRunSummaryResponse> {
+    const capability = this.listCapabilities(input.projectId, input.agentPresetId)
+      .find((item) => item.flowId === input.flowId);
+    if (!capability) throw new EntityNotFoundError("Node flow is not attached to the initiating agent.");
+    const review = this.nodeFlowService.validateDraft(input.projectId, input.flowId);
+    if (review.publishedVersion === null) throw new ValidationError("Attached node flow has not been published.");
+    if (review.requiredCredentials.some((credential) => credential.status !== "bound")) {
+      throw new ValidationError("Attached node flow credential policy is not satisfied.");
+    }
+    return await this.nodeFlowService.runFlow(input.projectId, input.flowId, input.parameters ?? {}, {
+      triggerType: "attached_flow",
+      triggerPayload: {
+        initiatingAgentId: input.agentPresetId,
+        ...(input.conversationId ? { conversationId: input.conversationId } : {}),
+        operation: "run_attached_flow",
+      },
+      versionSelection: { mode: "latest_published" },
+    });
+  }
+}
diff --git a/src/services/node-flow-runtime-service.ts b/src/services/node-flow-runtime-service.ts
index 72f7667521..9a7991676b 100644
--- a/src/services/node-flow-runtime-service.ts
+++ b/src/services/node-flow-runtime-service.ts
@@ -102,6 +102,10 @@ export class NodeFlowRuntimeService {
     });
   }
 
+  requestCancellation(runId: string): NodeFlowRunRecord {
+    return this.deps.nodeFlowRepository.requestCancellation(runId);
+  }
+
   async runFlow(
     projectId: string,
     flowId: string,
@@ -187,7 +191,7 @@ export class NodeFlowRuntimeService {
       if (!node) {
         continue;
       }
-      if (options.signal?.aborted) {
+      if (options.signal?.aborted || this.deps.nodeFlowRepository.getRun(run.id)?.cancelRequestedAt) {
         terminalStatus = "cancelled";
         terminalError ??= "Node flow run was cancelled.";
         await this.persistSkippedNode(context, node, "cancelled", terminalError);
diff --git a/src/services/node-flow-service.ts b/src/services/node-flow-service.ts
index 066e300c57..753612b958 100644
--- a/src/services/node-flow-service.ts
+++ b/src/services/node-flow-service.ts
@@ -1,14 +1,25 @@
 import { EntityNotFoundError, ValidationError } from "../repositories/repository-utils.js";
 import { NodeFlowRepository } from "../repositories/node-flow-repository.js";
 import { normalizeNodeFlowGraph, validateNodeFlowGraph } from "../domain/node-flows/node-flow-validation.js";
+import { listNodeDefinitions, resolveNodeDefinition } from "../domain/node-flows/node-definition-registry.js";
+import type { CredentialBroker } from "./credentials/credential-broker.js";
+import type { CustomNodeManifest, CustomNodeRecord } from "../contracts/custom-node-types.js";
+import type { CustomNodeRepository } from "../repositories/custom-node-repository.js";
+import type { CustomNodeProjectService } from "./custom-nodes/custom-node-project-service.js";
+import type { CustomNodeBuildService } from "./custom-nodes/custom-node-build-service.js";
 import type {
   AttachNodeFlowSkillInput,
   CreateNodeFlowInput,
   NodeFlowGraph,
+  NodeFlowGraphPatchOperation,
   NodeFlowJsonObject,
   NodeFlowListResponse,
   NodeFlowNodeRunListResponse,
   NodeFlowRecord,
+  NodeFlowDraftReview,
+  NodeFlowConcurrencyConflict,
+  NodeFlowRequiredCredential,
+  PatchNodeFlowDraftInput,
   NodeFlowRunListResponse,
   NodeFlowRunRecord,
   NodeFlowRunSummaryResponse,
@@ -23,8 +34,26 @@ export class NodeFlowService {
   constructor(
     private readonly repository: NodeFlowRepository = new NodeFlowRepository(),
     private readonly runtimeService?: NodeFlowRuntimeService,
+    private readonly credentialBroker?: CredentialBroker,
+    private readonly customNodeAuthoring?: {
+      repository: CustomNodeRepository;
+      projectService: CustomNodeProjectService;
+      buildService: CustomNodeBuildService;
+      resolveProjectRoot(projectId: string): string;
+    },
   ) {}
 
+  catalog(): { nodes: Array<Record<string, unknown>> } {
+    return { nodes: listNodeDefinitions().map((definition) => definitionSummary(definition)) };
+  }
+
+  nodeDefinition(type: string, version?: number): Record<string, unknown> | null {
+    const definition = version === undefined
+      ? [...listNodeDefinitions()].filter((item) => item.type === type).sort((a, b) => b.version - a.version)[0] ?? null
+      : resolveNodeDefinition(type, version);
+    return definition ? definitionSummary(definition, true) : null;
+  }
+
   list(projectId: string): NodeFlowListResponse {
     return { flows: this.repository.listFlows(projectId) };
   }
@@ -45,6 +74,156 @@ export class NodeFlowService {
     });
   }
 
+  createDraft(projectId: string, input: CreateNodeFlowInput): NodeFlowDraftReview {
+    const title = normalizeRequiredText(input.title, "Node flow title");
+    const description = normalizeOptionalText(input.description);
+    const { graph } = normalizeNodeFlowGraph(input.graph);
+    const flow = this.repository.createFlow(projectId, { id: input.id, title, description, graph }, { publish: false });
+    return this.reviewDraft(flow);
+  }
+
+  patchDraft(flowId: string, input: PatchNodeFlowDraftInput): { draft?: NodeFlowDraftReview; conflict?: NodeFlowConcurrencyConflict } {
+    const current = this.requireOwnedFlow(flowId, input.projectId);
+    if (current.version !== input.draftRevision) {
+      return { conflict: {
+        code: "draft_revision_conflict",
+        flowId,
+        expectedDraftRevision: input.draftRevision,
+        actualDraftRevision: current.version,
+        message: "The draft changed after it was read; reload the summary and reapply the patch.",
+      } };
+    }
+    if (!input.graph && !input.operations?.length && input.title === undefined && input.description === undefined) {
+      throw new ValidationError("A graph patch, title, or description is required.");
+    }
+    const graph = input.graph ?? applyGraphPatch(current.graph, input.operations ?? []);
+    const validation = validateNodeFlowGraph(graph);
+    if (!validation.valid || !validation.graph) {
+      return { draft: this.reviewDraft({ ...current, graph }, validation) };
+    }
+    const updated = this.repository.updateFlow(flowId, {
+      ...(input.title !== undefined ? { title: input.title } : {}),
+      ...(input.description !== undefined ? { description: input.description } : {}),
+      graph: validation.graph,
+    }, { publish: false });
+    return { draft: this.reviewDraft(updated, validation) };
+  }
+
+  validateDraft(projectId: string, flowId: string): NodeFlowDraftReview {
+    return this.reviewDraft(this.requireOwnedFlow(flowId, projectId));
+  }
+
+  inspectBindings(projectId: string, flowId: string): Pick<NodeFlowDraftReview, "requiredCredentials" | "requestedCapabilities" | "policyFindings"> {
+    const review = this.reviewDraft(this.requireOwnedFlow(flowId, projectId));
+    return {
+      requiredCredentials: review.requiredCredentials,
+      requestedCapabilities: review.requestedCapabilities,
+      policyFindings: review.policyFindings,
+    };
+  }
+
+  requestCredential(projectId: string, flowId: string, nodeId: string, slot: string): Record<string, unknown> {
+    const review = this.reviewDraft(this.requireOwnedFlow(flowId, projectId));
+    const requirement = review.requiredCredentials.find((item) => item.nodeId === nodeId && item.slot === slot);
+    if (!requirement) throw new ValidationError(`Credential slot is not declared: ${nodeId}.${slot}`);
+    return { projectId, flowId, ...requirement, requestStatus: requirement.status === "bound" ? "already_bound" : "requested" };
+  }
+
+  async createCustomNode(projectId: string, input: { nodeId: string; name: string; description?: string; sourceRevision: string; createdBy: string }): Promise<CustomNodeRecord> {
+    const authoring = this.requireCustomNodeAuthoring();
+    const generated = await authoring.projectService.generate({
+      projectRoot: authoring.resolveProjectRoot(projectId), nodeId: input.nodeId, name: input.name, description: input.description,
+    });
+    return authoring.repository.createDraft(projectId, {
+      manifest: generated.manifest, sourceRevision: normalizeRequiredText(input.sourceRevision, "sourceRevision"), createdBy: normalizeRequiredText(input.createdBy, "createdBy"),
+    });
+  }
+
+  async updateCustomNode(projectId: string, nodeId: string, manifest: CustomNodeManifest, sourceRevision: string): Promise<CustomNodeRecord> {
+    const authoring = this.requireCustomNodeAuthoring();
+    const current = authoring.repository.getNode(nodeId);
+    if (!current || current.projectId !== projectId) throw new EntityNotFoundError(`Custom node not found: ${nodeId}`);
+    await authoring.projectService.writeManifest(authoring.resolveProjectRoot(projectId), nodeId, manifest);
+    return authoring.repository.updateDraft(nodeId, manifest, sourceRevision);
+  }
+
+  async validateCustomNode(projectId: string, nodeId: string, actor: string, invocationId: string, correlationId: string): Promise<Record<string, unknown>> {
+    const authoring = this.requireCustomNodeAuthoring();
+    const current = authoring.repository.getNode(nodeId);
+    if (!current || current.projectId !== projectId) throw new EntityNotFoundError(`Custom node not found: ${nodeId}`);
+    const result = await authoring.buildService.validateAndBuild({ projectRoot: authoring.resolveProjectRoot(projectId), nodeId, creator: actor, invocationId, correlationId });
+    return { nodeId, status: result.report.valid ? "passed" : "failed", validationIssues: result.report.issues, checks: result.report.checks, requestedCapabilities: current.manifest.capabilities, requiredCredentials: current.manifest.credentials };
+  }
+
+  dryRun(projectId: string, flowId: string, input: Record<string, unknown> = {}): Record<string, unknown> {
+    normalizeJsonObject(input, "input");
+    const review = this.reviewDraft(this.requireOwnedFlow(flowId, projectId));
+    const missingCredentials = review.requiredCredentials.filter((item) => item.status !== "bound");
+    return {
+      status: review.valid && missingCredentials.length === 0 ? "ready" : "blocked",
+      draftRevision: review.draftRevision,
+      validationIssues: review.validationIssues,
+      policyFindings: review.policyFindings,
+      requiredCredentials: review.requiredCredentials,
+      requestedCapabilities: review.requestedCapabilities,
+      sideEffectDiffs: review.sideEffectDiffs,
+      result: { executed: false, inputKeys: Object.keys(input).sort(), output: null },
+    };
+  }
+
+  publishDraft(projectId: string, flowId: string, draftRevision: number, publishedBy: string): NodeFlowDraftReview {
+    const flow = this.requireOwnedFlow(flowId, projectId);
+    if (flow.version !== draftRevision) throw new ValidationError(`Draft revision conflict: expected ${draftRevision}, actual ${flow.version}.`);
+    const review = this.reviewDraft(flow);
+    if (!review.valid) throw new ValidationError("Only a valid draft can be published.");
+    if (review.requiredCredentials.some((item) => item.status !== "bound")) {
+      throw new ValidationError("All required credentials must be bound before publication.");
+    }
+    this.repository.publishVersion(flowId, draftRevision, undefined, normalizeRequiredText(publishedBy, "publishedBy"));
+    return this.reviewDraft(flow);
+  }
+
+  compareVersions(projectId: string, flowId: string, fromVersion: number, toVersion: number): Record<string, unknown> {
+    this.requireOwnedFlow(flowId, projectId);
+    const from = this.repository.getVersion(flowId, fromVersion);
+    const to = this.repository.getVersion(flowId, toVersion);
+    if (!from || !to) throw new EntityNotFoundError("One or both node flow versions were not found.");
+    return {
+      flowId, fromVersion, toVersion,
+      nodeCount: { from: from.graph.nodes.length, to: to.graph.nodes.length },
+      edgeCount: { from: from.graph.edges.length, to: to.graph.edges.length },
+      addedNodeIds: to.graph.nodes.map((node) => node.id).filter((id) => !from.graph.nodes.some((node) => node.id === id)),
+      removedNodeIds: from.graph.nodes.map((node) => node.id).filter((id) => !to.graph.nodes.some((node) => node.id === id)),
+      sideEffectDiffs: reviewSideEffects(to.graph).filter((item) => !reviewSideEffects(from.graph).some((before) => before.nodeId === item.nodeId && before.sideEffect === item.sideEffect)),
+    };
+  }
+
+  rollback(projectId: string, flowId: string, version: number, draftRevision: number): NodeFlowDraftReview {
+    const current = this.requireOwnedFlow(flowId, projectId);
+    if (current.version !== draftRevision) throw new ValidationError(`Draft revision conflict: expected ${draftRevision}, actual ${current.version}.`);
+    const target = this.repository.getVersion(flowId, version);
+    if (!target) throw new EntityNotFoundError(`Node flow version not found: ${flowId}@${version}`);
+    return this.reviewDraft(this.repository.updateFlow(flowId, {
+      title: target.title, description: target.description, graph: target.graph,
+    }, { publish: false }));
+  }
+
+  cancelRun(projectId: string, runId: string): NodeFlowRunRecord {
+    const run = this.requireOwnedRun(runId, projectId);
+    if (["succeeded", "failed", "cancelled"].includes(run.status)) throw new ValidationError(`Run ${runId} is already terminal.`);
+    return this.runtimeService?.requestCancellation(runId) ?? this.repository.requestCancellation(runId);
+  }
+
+  async retryRun(projectId: string, runId: string): Promise<NodeFlowRunSummaryResponse> {
+    const run = this.requireOwnedRun(runId, projectId);
+    if (!["failed", "cancelled", "attention_required"].includes(run.status)) throw new ValidationError("Only failed, cancelled, or attention-required runs can be retried.");
+    return await this.runFlow(projectId, run.flowId, run.input ?? {}, {
+      triggerType: "retry",
+      triggerPayload: { retriedRunId: run.id },
+      versionSelection: { mode: "pinned", version: run.version },
+    });
+  }
+
   update(flowId: string, input: UpdateNodeFlowInput): NodeFlowRecord {
     const update: UpdateNodeFlowInput = {};
     if (input.title !== undefined) {
@@ -127,6 +306,99 @@ export class NodeFlowService {
       options,
     );
   }
+
+  private requireOwnedFlow(flowId: string, projectId: string): NodeFlowRecord {
+    const flow = this.repository.getFlow(flowId);
+    if (!flow) throw new EntityNotFoundError(`Node flow not found: ${flowId}`);
+    if (flow.projectId !== projectId) throw new ValidationError("Node flow does not belong to the requested project.");
+    return flow;
+  }
+
+  private requireOwnedRun(runId: string, projectId: string): NodeFlowRunRecord {
+    const run = this.repository.getRun(runId);
+    if (!run) throw new EntityNotFoundError(`Node flow run not found: ${runId}`);
+    if (run.projectId !== projectId) throw new ValidationError("Node flow run does not belong to the requested project.");
+    return run;
+  }
+
+  private reviewDraft(flow: NodeFlowRecord, validation = validateNodeFlowGraph(flow.graph)): NodeFlowDraftReview {
+    const credentialMetadata = this.credentialBroker?.list(flow.projectId) ?? [];
+    const requiredCredentials: NodeFlowRequiredCredential[] = flow.graph.nodes.flatMap((node) => {
+      const definition = node.definition ? resolveNodeDefinition(node.definition.type, node.definition.version) : undefined;
+      return (definition?.credentials ?? []).filter((slot) => slot.required || node.credentialBindings?.some((binding) => binding.slot === slot.slot)).map((slot) => {
+        const credentialId = node.credentialBindings?.find((binding) => binding.slot === slot.slot)?.credentialId ?? null;
+        const credential = credentialMetadata.find((item) => item.id === credentialId);
+        const requiredCapabilities = ["read"];
+        const allowed = credential && credential.status === "active"
+          && slot.allowedKinds.includes(credential.kind)
+          && requiredCapabilities.every((capability) => credential.capabilities.includes(capability));
+        const status: NodeFlowRequiredCredential["status"] = credentialId ? (allowed ? "bound" : "denied") : "missing";
+        return { nodeId: node.id, slot: slot.slot, allowedKinds: [...slot.allowedKinds], requiredCapabilities, required: slot.required, credentialId, status };
+      });
+    });
+    const requestedCapabilities = [...new Set(flow.graph.nodes.flatMap((node) => node.capabilities ?? []))].sort();
+    const policyFindings = reviewPolicy(flow.graph, requiredCredentials);
+    return {
+      flowId: flow.id, projectId: flow.projectId, name: flow.title, description: flow.description,
+      draftRevision: flow.version, nodeCount: flow.graph.nodes.length, edgeCount: flow.graph.edges.length,
+      valid: validation.valid && !policyFindings.some((finding) => finding.severity === "error"),
+      validationIssues: validation.errors, policyFindings, requiredCredentials, requestedCapabilities,
+      sideEffectDiffs: reviewSideEffects(flow.graph),
+      publishedVersion: this.repository.getPublication(flow.id)?.version ?? null,
+    };
+  }
+
+  private requireCustomNodeAuthoring(): NonNullable<NodeFlowService["customNodeAuthoring"]> {
+    if (!this.customNodeAuthoring) throw new ValidationError("Custom-node authoring is not configured.");
+    return this.customNodeAuthoring;
+  }
+}
+
+function definitionSummary(definition: ReturnType<typeof listNodeDefinitions>[number], includeSchema = false): Record<string, unknown> {
+  return {
+    type: definition.type, version: definition.version, executable: definition.executable,
+    executionKind: definition.executionKind, label: definition.ui.label, description: definition.ui.description,
+    category: definition.ui.category, credentials: definition.credentials, capabilities: definition.capabilities,
+    sideEffect: definition.sideEffect, ports: definition.ports,
+    ...(includeSchema ? { configurationSchema: definition.configurationSchema, widgetSchema: definition.ui.widgetSchema, defaultPolicy: definition.defaultPolicy } : {}),
+  };
+}
+
+function applyGraphPatch(graph: NodeFlowGraph, operations: NodeFlowGraphPatchOperation[]): NodeFlowGraph {
+  let next: NodeFlowGraph = { ...graph, nodes: [...graph.nodes], edges: [...graph.edges] };
+  for (const operation of operations) {
+    if (operation.op === "upsert_node") next.nodes = [...next.nodes.filter((node) => node.id !== operation.node.id), operation.node];
+    else if (operation.op === "remove_node") {
+      next.nodes = next.nodes.filter((node) => node.id !== operation.nodeId);
+      next.edges = next.edges.filter((edge) => edge.fromNodeId !== operation.nodeId && edge.toNodeId !== operation.nodeId);
+    } else if (operation.op === "upsert_edge") {
+      const edgeKey = operation.edge.id ?? `${operation.edge.fromNodeId}:${operation.edge.toNodeId}:${operation.edge.fromHandle ?? ""}:${operation.edge.toHandle ?? ""}`;
+      next.edges = [...next.edges.filter((edge) => (edge.id ?? `${edge.fromNodeId}:${edge.toNodeId}:${edge.fromHandle ?? ""}:${edge.toHandle ?? ""}`) !== edgeKey), operation.edge];
+    } else if (operation.op === "remove_edge") next.edges = next.edges.filter((edge) => operation.edgeId ? edge.id !== operation.edgeId : !(edge.fromNodeId === operation.fromNodeId && edge.toNodeId === operation.toNodeId));
+    else if (operation.op === "set_input_schema") next = { ...next, inputSchema: operation.inputSchema ?? undefined };
+    else if (operation.op === "set_metadata") next = { ...next, metadata: operation.metadata ?? undefined };
+  }
+  return next;
+}
+
+function reviewSideEffects(graph: NodeFlowGraph): NodeFlowDraftReview["sideEffectDiffs"] {
+  return graph.nodes.flatMap((node) => {
+    const definition = node.definition ? resolveNodeDefinition(node.definition.type, node.definition.version) : undefined;
+    const sideEffect = node.sideEffect ?? definition?.sideEffect ?? "none";
+    return sideEffect === "none" ? [] : [{ nodeId: node.id, sideEffect, description: `${node.title} may perform a ${sideEffect} side effect.` }];
+  });
+}
+
+function reviewPolicy(graph: NodeFlowGraph, credentials: NodeFlowDraftReview["requiredCredentials"]): NodeFlowDraftReview["policyFindings"] {
+  const findings: NodeFlowDraftReview["policyFindings"] = credentials.filter((item) => item.status === "denied" || (item.required && item.status === "missing")).map((item) => ({
+    severity: "error", code: item.status === "missing" ? "missing_credential" : "credential_permission_denied", nodeId: item.nodeId,
+    message: `${item.nodeId}.${item.slot} requires an approved credential binding.`,
+  }));
+  for (const node of graph.nodes) {
+    const definition = node.definition ? resolveNodeDefinition(node.definition.type, node.definition.version) : undefined;
+    if ((node.sideEffect ?? definition?.sideEffect) === "external") findings.push({ severity: "warning", code: "external_side_effect", nodeId: node.id, message: "External side effects require publication review." });
+  }
+  return findings;
 }
 
 function normalizeRequiredText(value: string | undefined, label: string): string {
diff --git a/tests/backend/mcp/management-node-flow-actions.test.ts b/tests/backend/mcp/management-node-flow-actions.test.ts
index dbd69abd52..f6292447e7 100644
--- a/tests/backend/mcp/management-node-flow-actions.test.ts
+++ b/tests/backend/mcp/management-node-flow-actions.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
 import { ManagementToolHandler } from "../../../src/mcp/management-tool-handler.js";
 import type { NodeFlowGraph, NodeFlowRecord } from "../../../src/contracts/node-flow-types.js";
+import { runWithMcpAgentContext } from "../../../src/server/mcp-agent-context.js";
 
 const validGraph: NodeFlowGraph = {
   nodes: [
@@ -205,4 +206,50 @@ describe("manage_node_flows", () => {
       visible: "ok",
     });
   });
+
+  it("returns governed draft conflicts and structured dry-run findings", async () => {
+    const nodeFlowService = {
+      patchDraft: vi.fn(() => ({ conflict: { code: "draft_revision_conflict", expectedDraftRevision: 1, actualDraftRevision: 2 } })),
+      dryRun: vi.fn(() => ({ status: "blocked", validationIssues: [], policyFindings: [{ code: "missing_credential" }], requiredCredentials: [{ status: "missing" }], result: { executed: false } })),
+    };
+    const handler = createHandler(nodeFlowService);
+    const conflict = parseResponse(await handler.handleManageNodeFlows({ action: "patch_draft", projectId: "project-1", flowId: "flow-1", draftRevision: 1, operations: [{ op: "set_metadata", metadata: {} }] }));
+    const dryRun = parseResponse(await handler.handleManageNodeFlows({ action: "dry_run", projectId: "project-1", flowId: "flow-1", input: { token: "never-returned" } }));
+    expect(conflict.result.conflict).toMatchObject({ code: "draft_revision_conflict", actualDraftRevision: 2 });
+    expect(dryRun.result).toMatchObject({ status: "blocked", result: { executed: false } });
+  });
+
+  it("requires exact approval for publish and rollback", async () => {
+    const nodeFlowService = { publishDraft: vi.fn(() => ({ draftRevision: 2 })), rollback: vi.fn(() => ({ draftRevision: 3 })) };
+    const handler = createHandler(nodeFlowService);
+    const publishArgs = { action: "publish" as const, projectId: "project-1", flowId: "flow-1", draftRevision: 2, approval: { confirmed: true } };
+    expect(parseResponse(await handler.handleManageNodeFlows(publishArgs)).approvalRequired).toBe(true);
+    expect(parseResponse(await handler.handleManageNodeFlows(publishArgs)).result.draft.draftRevision).toBe(2);
+    const rollbackArgs = { action: "rollback" as const, projectId: "project-1", flowId: "flow-1", draftRevision: 2, version: 1, approval: { confirmed: true } };
+    expect(parseResponse(await handler.handleManageNodeFlows(rollbackArgs)).approvalRequired).toBe(true);
+    expect(parseResponse(await handler.handleManageNodeFlows(rollbackArgs)).result.draft.draftRevision).toBe(3);
+  });
+
+  it("validates required optimistic and operational fields", async () => {
+    const handler = createHandler({});
+    const patch = await handler.handleManageNodeFlows({ action: "patch_draft", projectId: "project-1", flowId: "flow-1" });
+    const cancel = await handler.handleManageNodeFlows({ action: "cancel", projectId: "project-1" });
+    expect(parseResponse(patch).result).toMatchObject({ errorType: "validation", field: "draftRevision" });
+    expect(parseResponse(cancel).result).toMatchObject({ errorType: "validation", field: "runId" });
+  });
+
+  it("executes an attached flow with authenticated agent and conversation metadata", async () => {
+    const runFlow = vi.fn(async () => ({ run: { id: "run-1" }, nodeRuns: [], output: { ok: true } }));
+    const handler = createHandler({
+      listAgentSkillsForAgent: () => [{ flowId: "flow-1", skillName: "Review", description: "" }],
+      get: () => ({ id: "flow-1", projectId: "project-1", graph: { nodes: [], edges: [] } }),
+      validateDraft: () => ({ publishedVersion: 1, requiredCredentials: [] }),
+      runFlow,
+    });
+    const response = await runWithMcpAgentContext("agent-1", "thread-1", () => handler.handleRunAttachedFlow({ projectId: "project-1", flowId: "flow-1", input: { prompt: "review" } }));
+    expect(parseResponse(response).result.run.id).toBe("run-1");
+    expect(runFlow).toHaveBeenCalledWith("project-1", "flow-1", { prompt: "review" }, expect.objectContaining({
+      triggerPayload: expect.objectContaining({ initiatingAgentId: "agent-1", conversationId: "thread-1" }),
+    }));
+  });
 });
diff --git a/tests/backend/mcp/mcp-management.test.ts b/tests/backend/mcp/mcp-management.test.ts
index c2e63f6c59..b342f42e97 100644
--- a/tests/backend/mcp/mcp-management.test.ts
+++ b/tests/backend/mcp/mcp-management.test.ts
@@ -546,25 +546,45 @@ describe("ManagementToolHandler", () => {
     const properties = schema?.properties ?? {};
 
     expect(properties.action?.enum).toEqual([
+      "catalog",
+      "get_node_definition",
+      "create_draft",
+      "patch_draft",
+      "validate_draft",
+      "create_custom_node",
+      "update_custom_node",
+      "validate_custom_node",
+      "request_credential",
+      "inspect_bindings",
+      "dry_run",
+      "publish",
+      "compare_versions",
+      "rollback",
+      "run",
+      "cancel",
+      "retry",
+      "inspect_run",
+      "list_runs",
       "list",
       "get",
       "create",
       "update",
       "delete",
       "validate",
-      "run",
-      "list_runs",
       "get_run",
       "attach_to_agent",
       "detach_from_agent",
+      "attach",
+      "detach",
     ]);
     expect(properties.graph).toMatchObject({ type: "object" });
     expect(properties.widgets).toMatchObject({ type: "object" });
     expect(properties.input).toMatchObject({ type: "object" });
     expect(properties.agentPresetId).toMatchObject({ type: "string" });
     expect(properties.skillAlias).toMatchObject({ type: "string" });
-    expect(tool?.description).toContain("Code UX-adapted flows");
-    expect(tool?.description).toContain("dynamic widget schemas");
+    expect(properties.draftRevision).toMatchObject({ type: "integer", minimum: 1 });
+    expect(properties.operations).toMatchObject({ type: "array" });
+    expect(tool?.description).toContain("Govern node-flow authoring");
   });
 
   it("exposes the dedicated long-term-memory MCP schema", () => {
diff --git a/tests/backend/server/node-flow-routes.test.ts b/tests/backend/server/node-flow-routes.test.ts
index 662fa498a1..f7a7a05f45 100644
--- a/tests/backend/server/node-flow-routes.test.ts
+++ b/tests/backend/server/node-flow-routes.test.ts
@@ -141,4 +141,14 @@ describe("node flow routes", () => {
       versionSelection: { mode: "latest_published" },
     });
   });
+
+  it("returns HTTP 409 for optimistic draft conflicts", async () => {
+    const nodeFlowService = { patchDraft: vi.fn(() => ({ conflict: { code: "draft_revision_conflict", expectedDraftRevision: 1, actualDraftRevision: 2 } })) };
+    const app = express();
+    app.use(express.json());
+    registerNodeFlowRoutes(app, { nodeFlowService } as any);
+    const response = await request(app).patch("/api/node-flow-drafts/flow-1").send({ projectId: "project-1", draftRevision: 1, operations: [] });
+    expect(response.status).toBe(409);
+    expect(response.body.conflict).toMatchObject({ code: "draft_revision_conflict", actualDraftRevision: 2 });
+  });
 });
diff --git a/tests/backend/services/agent-mcp-access.test.ts b/tests/backend/services/agent-mcp-access.test.ts
index fe6c7d278e..1258b8c3a6 100644
--- a/tests/backend/services/agent-mcp-access.test.ts
+++ b/tests/backend/services/agent-mcp-access.test.ts
@@ -13,6 +13,7 @@ import {
   projectManagerClarificationAgentMcpAccess,
   toAgentCodeUxToolAccess,
   workerClarificationAgentMcpAccess,
+  withAttachedFlowAccess,
 } from "../../../src/services/agent-mcp-access.js";
 import type { CustomMcpServer, McpToolToggle } from "../../../src/contracts/app-types.js";
 import type { McpConnectionInfo } from "../../../src/contracts/mcp-connection-types.js";
@@ -56,6 +57,15 @@ describe("sanitizeAgentMcpAccess", () => {
 });
 
 describe("agent MCP defaults", () => {
+  it("grants only the narrow attached-flow operation for flow-backed capabilities", () => {
+    const access = withAttachedFlowAccess({ codeUxEnabled: false, codeUxToolToggles: [] });
+    expect(access.codeUxEnabled).toBe(true);
+    expect(access.audiences).toContain("worker");
+    expect(access.codeUxToolToggles.filter((toggle) => toggle.enabled)).toEqual([
+      { name: "run_attached_flow", enabled: true, isInternal: true },
+    ]);
+  });
+
   it("recognizes assigned, manual, and worker-pool coding agents without admitting planning, QA, or unrelated agents", () => {
     const settings = {
       ...DEFAULT_DASHBOARD_SETTINGS,
diff --git a/tests/backend/services/node-flow-agent-skill-service.test.ts b/tests/backend/services/node-flow-agent-skill-service.test.ts
new file mode 100644
index 0000000000..4ae189f4a3
--- /dev/null
+++ b/tests/backend/services/node-flow-agent-skill-service.test.ts
@@ -0,0 +1,33 @@
+import { describe, expect, it, vi } from "vitest";
+import { NodeFlowAgentSkillService } from "../../../src/services/node-flow-agent-skill-service.js";
+
+describe("NodeFlowAgentSkillService", () => {
+  it("advertises only narrow capability metadata and records initiating context", async () => {
+    const runFlow = vi.fn(async () => ({ run: { id: "run-1" }, nodeRuns: [], output: { ok: true } }));
+    const nodeFlowService = {
+      listAgentSkillsForAgent: vi.fn(() => [{ flowId: "flow-1", skillName: "Review", description: "Review input" }]),
+      get: vi.fn(() => ({ id: "flow-1", projectId: "project-1", graph: { nodes: [], edges: [], schemas: { input: { type: "object", properties: { prompt: { type: "string" } } } } } })),
+      validateDraft: vi.fn(() => ({ publishedVersion: 2, requiredCredentials: [] })),
+      runFlow,
+    };
+    const service = new NodeFlowAgentSkillService(nodeFlowService as never);
+
+    expect(service.listCapabilities("project-1", "agent-1")).toEqual([{
+      flowId: "flow-1", name: "Review", description: "Review input",
+      inputSchema: { type: "object", properties: { prompt: { type: "string" } } }, operation: "run_attached_flow",
+    }]);
+    await service.runAttachedFlow({ projectId: "project-1", flowId: "flow-1", agentPresetId: "agent-1", conversationId: "thread-1", parameters: { prompt: "safe" } });
+    expect(runFlow).toHaveBeenCalledWith("project-1", "flow-1", { prompt: "safe" }, expect.objectContaining({
+      triggerType: "attached_flow",
+      triggerPayload: { initiatingAgentId: "agent-1", conversationId: "thread-1", operation: "run_attached_flow" },
+    }));
+    expect(JSON.stringify(service.listCapabilities("project-1", "agent-1"))).not.toContain("credential");
+  });
+
+  it("rejects unattached, unpublished, and credential-blocked flows", async () => {
+    const base = { get: vi.fn(() => ({ id: "flow-1", projectId: "project-1", graph: { nodes: [], edges: [] } })), runFlow: vi.fn() };
+    await expect(new NodeFlowAgentSkillService({ ...base, listAgentSkillsForAgent: () => [] } as never).runAttachedFlow({ projectId: "project-1", flowId: "flow-1", agentPresetId: "agent-1" })).rejects.toThrow(/not attached/i);
+    await expect(new NodeFlowAgentSkillService({ ...base, listAgentSkillsForAgent: () => [{ flowId: "flow-1", skillName: "x", description: "" }], validateDraft: () => ({ publishedVersion: null, requiredCredentials: [] }) } as never).runAttachedFlow({ projectId: "project-1", flowId: "flow-1", agentPresetId: "agent-1" })).rejects.toThrow(/not been published/i);
+    await expect(new NodeFlowAgentSkillService({ ...base, listAgentSkillsForAgent: () => [{ flowId: "flow-1", skillName: "x", description: "" }], validateDraft: () => ({ publishedVersion: 1, requiredCredentials: [{ status: "missing" }] }) } as never).runAttachedFlow({ projectId: "project-1", flowId: "flow-1", agentPresetId: "agent-1" })).rejects.toThrow(/credential policy/i);
+  });
+});
diff --git a/tests/backend/services/node-flow-service.test.ts b/tests/backend/services/node-flow-service.test.ts
index 1560a2d47b..c893c86983 100644
--- a/tests/backend/services/node-flow-service.test.ts
+++ b/tests/backend/services/node-flow-service.test.ts
@@ -90,4 +90,39 @@ describe("NodeFlowService", () => {
       expect.objectContaining({ code: "invalid_edge_endpoint" }),
     ]));
   });
+
+  it("applies optimistic draft patches without overwriting conflicting edits", async () => {
+    const { dir, projectRepository, service } = await createService();
+    const project = projectRepository.createProject({ name: "Draft Project", sourceType: "local", sourceRef: dir });
+    const draft = service.createDraft(project.id, { title: "Draft", graph: validGraph() });
+
+    const updated = service.patchDraft(draft.flowId, {
+      projectId: project.id,
+      draftRevision: draft.draftRevision,
+      operations: [{ op: "set_metadata", metadata: { purpose: "review" } }],
+    });
+    const conflict = service.patchDraft(draft.flowId, {
+      projectId: project.id,
+      draftRevision: draft.draftRevision,
+      operations: [{ op: "set_metadata", metadata: { purpose: "overwrite" } }],
+    });
+
+    expect(updated.draft?.draftRevision).toBe(2);
+    expect(conflict.conflict).toMatchObject({ code: "draft_revision_conflict", expectedDraftRevision: 1, actualDraftRevision: 2 });
+    expect(service.get(draft.flowId)?.graph.metadata).toEqual({ purpose: "review" });
+  });
+
+  it("publishes reviewed drafts and creates rollback drafts without replacing history", async () => {
+    const { dir, projectRepository, service } = await createService();
+    const project = projectRepository.createProject({ name: "Publish Project", sourceType: "local", sourceRef: dir });
+    const draft = service.createDraft(project.id, { title: "Draft", graph: validGraph() });
+    expect(draft.publishedVersion).toBeNull();
+    const published = service.publishDraft(project.id, draft.flowId, 1, "reviewer");
+    expect(published.publishedVersion).toBe(1);
+    const second = service.patchDraft(draft.flowId, { projectId: project.id, draftRevision: 1, title: "Second" });
+    const rollback = service.rollback(project.id, draft.flowId, 1, second.draft!.draftRevision);
+    expect(rollback.draftRevision).toBe(3);
+    expect(rollback.name).toBe("Draft");
+    expect(service.compareVersions(project.id, draft.flowId, 1, 3)).toMatchObject({ fromVersion: 1, toVersion: 3 });
+  });
 });

From c68c5014a361c7226767e1d0741e2c376a8d4bbe Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 06:33:12 +0000
Subject: [PATCH 07/25] feat(task T07): implement via codex

---
 dashboard/src/v2/NodesPage.tsx                | 478 +++++-------------
 .../v2/components/nodes/NodeFlowInspector.tsx |  39 +-
 .../components/nodes/NodeGovernancePanel.tsx  |  30 ++
 .../src/v2/components/nodes/NodePalette.tsx   | 127 ++---
 .../v2/components/nodes/NodeRunDebugger.tsx   |  17 +
 .../src/v2/lib/dashboard-feature-flags.ts     |  13 +-
 dashboard/src/v2/lib/node-flow-api.ts         | 111 ++++
 dashboard/src/v2/types.ts                     |  16 +
 docs/dashboard/feature-flags.md               |   4 +-
 docs/dashboard/node-flows.md                  |  96 +---
 docs/dashboard/nodes-canvas.md                |  80 +--
 .../lib/dashboard-feature-flags.test.ts       |   3 +-
 tests/dashboard/v2/node-flow-page.test.tsx    |  47 +-
 tests/dashboard/v2/nodes-inspector.test.tsx   |  18 +-
 tests/dashboard/v2/nodes-page.test.tsx        | 202 ++------
 15 files changed, 451 insertions(+), 830 deletions(-)
 create mode 100644 dashboard/src/v2/components/nodes/NodeGovernancePanel.tsx
 create mode 100644 dashboard/src/v2/components/nodes/NodeRunDebugger.tsx

diff --git a/dashboard/src/v2/NodesPage.tsx b/dashboard/src/v2/NodesPage.tsx
index fe086346c6..f550fa51fc 100644
--- a/dashboard/src/v2/NodesPage.tsx
+++ b/dashboard/src/v2/NodesPage.tsx
@@ -1,374 +1,134 @@
 import type { FunctionComponent } from "preact";
-import { useCallback, useEffect, useMemo, useState } from "preact/hooks";
-import {
-  AlertTriangle,
-  CheckCircle2,
-  ClipboardList,
-  Download,
-  FileJson,
-  RefreshCcw,
-  RotateCcw,
-  Upload,
-  Workflow,
-} from "lucide-preact";
+import { useCallback, useEffect, useMemo, useRef, useState } from "preact/hooks";
+import { AlertTriangle, Plus, Save, Workflow } from "lucide-preact";
 import { PageContainer } from "./components/layout/PageContainer.js";
 import { PageHeader } from "./components/layout/PageHeader.js";
-import { NodeCanvas } from "./components/nodes/NodeCanvas.js";
-import { NodeInspector } from "./components/nodes/NodeInspector.js";
-import { NodePalette } from "./components/nodes/NodePalette.js";
-import { NodeValidationPanel } from "./components/nodes/NodeValidationPanel.js";
+import { EmptyState } from "./components/ui/EmptyState.js";
 import { Button } from "./components/ui/Button.js";
-import type {
-  NodeCanvasConfigValue,
-  NodeCanvasEdge,
-  NodeCanvasGraph,
-  NodeCanvasNode,
-  NodesCanvasAction,
-} from "./lib/nodes-canvas-state.js";
-import {
-  createInitialNodeCanvasGraph,
-  nodesCanvasReducer,
-  serializeNodeCanvasGraph,
-  validateNodeCanvasGraph,
-} from "./lib/nodes-canvas-state.js";
+import { NodeFlowLibrary } from "./components/nodes/NodeFlowLibrary.js";
+import { NodeFlowCanvas } from "./components/nodes/NodeFlowCanvas.js";
+import { NodeFlowInspector } from "./components/nodes/NodeFlowInspector.js";
+import { NodePalette } from "./components/nodes/NodePalette.js";
+import { NodeGovernancePanel } from "./components/nodes/NodeGovernancePanel.js";
+import { NodeRunDebugger } from "./components/nodes/NodeRunDebugger.js";
+import { useProjectData } from "./context/project-data.js";
+import type { NodeDefinitionManifest, NodeFlowDraftReview, NodeFlowGraph, NodeFlowNode, NodeFlowNodeAttemptRecord, NodeFlowNodeRunRecord, NodeFlowRecord, NodeFlowRunRecord } from "./types.js";
+import { createDefaultNodeFlowGraph, isNodeFlowDirty, updateNodeInGraph } from "./lib/node-flow-view-models.js";
+import { deserializeNodeCanvasGraphWithMigration, toCanonicalNodeFlowGraph } from "./lib/nodes-canvas-state.js";
 import {
-  applyNodeCanvasAgentCommand,
-  buildNodeCanvasAgentSummary,
-} from "./lib/nodes-agent-surface.js";
+  cancelNodeFlowRun, compareNodeFlowVersions, createNodeFlowDraft, deleteNodeFlow, dryRunNodeFlowDraft,
+  fetchNodeDefinition, fetchNodeFlow, fetchNodeFlowAttempts, fetchNodeFlowCatalog, fetchNodeFlowNodeRuns,
+  fetchNodeFlowRuns, fetchNodeFlows, patchNodeFlowDraft, publishNodeFlowDraft, requestNodeFlowCredential,
+  retryNodeFlowRun, rollbackNodeFlow, runNodeFlow, validateNodeFlowDraft,
+  type NodeDefinitionSummary, type NodeFlowDryRunResponse, type NodeFlowVersionDiff,
+} from "./lib/node-flow-api.js";
 
 export const NODES_CANVAS_STORAGE_KEY = "codeux:nodes-canvas:v1";
-
-type FeedbackTone = "success" | "error" | "info" | "warning";
-
-interface FeedbackState {
-  tone: FeedbackTone;
-  message: string;
-}
-
-const panelClass = "rounded-[var(--radius-panel)] border border-black/[0.06] bg-white/70 p-4 shadow-[var(--elevation-soft)] dark:border-white/[0.06] dark:bg-white/[0.035]";
-
-const toneClasses: Record<FeedbackTone, string> = {
-  success: "border-status-green/20 bg-status-green/[0.08] text-slate-700 dark:text-slate-200",
-  error: "border-status-red/25 bg-status-red/[0.08] text-slate-700 dark:text-slate-200",
-  info: "border-signal-500/20 bg-signal-500/[0.08] text-slate-700 dark:text-slate-200",
-  warning: "border-amber-500/25 bg-amber-500/[0.08] text-slate-700 dark:text-slate-200",
-};
-
-const loadPersistedGraph = (): NodeCanvasGraph => {
-  if (typeof window === "undefined") {
-    return createInitialNodeCanvasGraph();
-  }
-
-  const persisted = window.localStorage.getItem(NODES_CANVAS_STORAGE_KEY);
-  if (!persisted) {
-    return createInitialNodeCanvasGraph();
-  }
-
-  const result = applyNodeCanvasAgentCommand(createInitialNodeCanvasGraph(), {
-    command: "replace_graph",
-    serializedGraph: persisted,
-  });
-
-  return result.issues.some((issue) => issue.field === "serializedGraph")
-    ? createInitialNodeCanvasGraph()
-    : result.graph;
-};
-
-const selectedNodeFromGraph = (graph: NodeCanvasGraph): NodeCanvasNode | null => {
-  const selectedId = graph.selection.nodeIds[0];
-  return selectedId ? graph.nodes.find((node) => node.id === selectedId) ?? null : null;
-};
-
-const selectedEdgeFromGraph = (graph: NodeCanvasGraph): NodeCanvasEdge | null => {
-  const selectedId = graph.selection.edgeIds[0];
-  return selectedId ? graph.edges.find((edge) => edge.id === selectedId) ?? null : null;
-};
-
-const updateNodePatch = (
-  graph: NodeCanvasGraph,
-  nodeId: string,
-  patch: Partial<Pick<NodeCanvasNode, "description" | "label" | "metadata">>,
-): NodeCanvasGraph => {
-  let nextGraph = graph;
-  if (patch.label !== undefined) {
-    nextGraph = nodesCanvasReducer(nextGraph, { type: "update_node_label", nodeId, label: patch.label });
-  }
-
-  if (patch.description !== undefined || patch.metadata !== undefined) {
-    nextGraph = nodesCanvasReducer(nextGraph, {
-      type: "replace_graph",
-      graph: {
-        ...nextGraph,
-        nodes: nextGraph.nodes.map((node) => node.id === nodeId
-          ? {
-              ...node,
-              ...(patch.description !== undefined ? { description: patch.description } : {}),
-              ...(patch.metadata !== undefined ? { metadata: { ...node.metadata, ...patch.metadata } } : {}),
-            }
-          : node),
-      },
-    });
-  }
-
-  return nextGraph;
-};
-
-const formatSummaryJson = (graph: NodeCanvasGraph): string => (
-  JSON.stringify(buildNodeCanvasAgentSummary(graph), null, 2)
-);
+const migrationMarker = (projectId: string): string => `codeux:nodes-canvas:imported:${projectId}`;
+const errorMessage = (error: unknown): string => error instanceof Error ? error.message : "The node-flow request failed.";
 
 export const NodesPage: FunctionComponent = () => {
-  const [graph, setGraph] = useState<NodeCanvasGraph>(() => loadPersistedGraph());
-  const [exchangeJson, setExchangeJson] = useState(() => serializeNodeCanvasGraph(graph));
-  const [feedback, setFeedback] = useState<FeedbackState>({
-    tone: "info",
-    message: "Canvas restored from local browser storage.",
-  });
-  const [enabledNodeIds, setEnabledNodeIds] = useState<Set<string>>(() => new Set(graph.nodes.map((node) => node.id)));
-
-  const validationIssues = useMemo(() => validateNodeCanvasGraph(graph), [graph]);
-  const summary = useMemo(() => buildNodeCanvasAgentSummary(graph), [graph]);
-  const selectedNode = useMemo(() => selectedNodeFromGraph(graph), [graph]);
-  const selectedEdge = useMemo(() => selectedEdgeFromGraph(graph), [graph]);
-  const serializedGraph = useMemo(() => serializeNodeCanvasGraph(graph), [graph]);
-  const summaryJson = useMemo(() => formatSummaryJson(graph), [graph]);
-
-  useEffect(() => {
-    if (typeof window === "undefined") {
-      return;
-    }
-    window.localStorage.setItem(NODES_CANVAS_STORAGE_KEY, serializedGraph);
-  }, [serializedGraph]);
-
-  const dispatch = useCallback((action: NodesCanvasAction): void => {
-    setGraph((current) => nodesCanvasReducer(current, action));
+  const { selectedProject, loading: projectLoading } = useProjectData();
+  const projectId = selectedProject?.id ?? null;
+  const projectRef = useRef(projectId); projectRef.current = projectId;
+  const [flows, setFlows] = useState<NodeFlowRecord[]>([]);
+  const [catalog, setCatalog] = useState<NodeDefinitionSummary[]>([]);
+  const [selectedFlowId, setSelectedFlowId] = useState<string | null>(null);
+  const [record, setRecord] = useState<NodeFlowRecord | null>(null);
+  const [title, setTitle] = useState("");
+  const [description, setDescription] = useState("");
+  const [graph, setGraph] = useState<NodeFlowGraph>(createDefaultNodeFlowGraph);
+  const [selectedNodeId, setSelectedNodeId] = useState<string | null>(null);
+  const [definitions, setDefinitions] = useState<Record<string, NodeDefinitionManifest>>({});
+  const [review, setReview] = useState<NodeFlowDraftReview | null>(null);
+  const [dryRun, setDryRun] = useState<NodeFlowDryRunResponse | null>(null);
+  const [diff, setDiff] = useState<NodeFlowVersionDiff | null>(null);
+  const [runs, setRuns] = useState<NodeFlowRunRecord[]>([]);
+  const [selectedRunId, setSelectedRunId] = useState<string | null>(null);
+  const [nodeRuns, setNodeRuns] = useState<NodeFlowNodeRunRecord[]>([]);
+  const [attempts, setAttempts] = useState<NodeFlowNodeAttemptRecord[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [notice, setNotice] = useState<string | null>(null);
+
+  const selectedNode = useMemo(() => graph.nodes.find((node) => node.id === selectedNodeId) ?? null, [graph.nodes, selectedNodeId]);
+  const selectedDefinition = selectedNode?.definition ? definitions[`${selectedNode.definition.type}@${selectedNode.definition.version}`] ?? null : null;
+  const dirty = isNodeFlowDirty(record, title, description, graph);
+
+  const applyRecord = useCallback((flow: NodeFlowRecord): void => {
+    setRecord(flow); setSelectedFlowId(flow.id); setTitle(flow.title); setDescription(flow.description); setGraph(flow.graph);
+    setSelectedNodeId(flow.graph.nodes[0]?.id ?? null); setReview(null); setDryRun(null); setDiff(null);
   }, []);
 
-  const handleExport = (): void => {
-    setExchangeJson(serializedGraph);
-    setFeedback({
-      tone: validationIssues.length === 0 ? "success" : "warning",
-      message: `Exported ${summary.nodeCount} nodes and ${summary.edgeCount} edges as deterministic JSON.`,
-    });
-  };
-
-  const handleImport = (): void => {
-    const result = applyNodeCanvasAgentCommand(graph, {
-      command: "replace_graph",
-      serializedGraph: exchangeJson,
-    });
-    const importIssues = result.issues.filter((issue) => issue.entityId.startsWith("command[0]"));
-    if (importIssues.length > 0) {
-      setFeedback({ tone: "error", message: importIssues[0]?.message ?? "Import failed." });
-      return;
-    }
-
-    setGraph(result.graph);
-    setEnabledNodeIds(new Set(result.graph.nodes.map((node) => node.id)));
-    const nextIssueCount = validateNodeCanvasGraph(result.graph).length;
-    setFeedback({
-      tone: nextIssueCount === 0 ? "success" : "warning",
-      message: nextIssueCount === 0
-        ? "Imported graph JSON and saved it locally."
-        : `Imported graph JSON with ${nextIssueCount} validation issue${nextIssueCount === 1 ? "" : "s"}.`,
-    });
-  };
-
-  const handleReset = (): void => {
-    const nextGraph = createInitialNodeCanvasGraph();
-    setGraph(nextGraph);
-    setExchangeJson(serializeNodeCanvasGraph(nextGraph));
-    setEnabledNodeIds(new Set(nextGraph.nodes.map((node) => node.id)));
-    setFeedback({ tone: "info", message: "Canvas reset to the starter workflow." });
-  };
-
-  const handleClear = (): void => {
-    setGraph({ nodes: [], edges: [], selection: { nodeIds: [], edgeIds: [] } });
-    setEnabledNodeIds(new Set());
-    setFeedback({ tone: "info", message: "Canvas cleared. Add a node from the palette to start again." });
-  };
-
-  const handleNodeChange = (
-    nodeId: string,
-    patch: Partial<Pick<NodeCanvasNode, "description" | "label" | "metadata">>,
-  ): void => {
-    setGraph((current) => updateNodePatch(current, nodeId, patch));
-  };
-
-  const handleNodeConfigChange = (nodeId: string, fieldId: string, value: NodeCanvasConfigValue): void => {
-    dispatch({ type: "update_node_config", nodeId, fieldId, value });
-  };
-
-  const handleNodeEnabledChange = (nodeId: string, enabled: boolean): void => {
-    setEnabledNodeIds((current) => {
-      const next = new Set(current);
-      if (enabled) {
-        next.add(nodeId);
-      } else {
-        next.delete(nodeId);
+  const loadLibrary = useCallback(async (nextProjectId: string, signal?: AbortSignal): Promise<void> => {
+    setLoading(true); setError(null);
+    try {
+      const [library, registry] = await Promise.all([fetchNodeFlows(nextProjectId, signal), fetchNodeFlowCatalog(signal)]);
+      if (projectRef.current !== nextProjectId) return;
+      let nextFlows = library.flows;
+      const legacy = typeof window !== "undefined" ? window.localStorage.getItem(NODES_CANVAS_STORAGE_KEY) : null;
+      if (legacy && !window.localStorage.getItem(migrationMarker(nextProjectId))) {
+        const importedGraph = toCanonicalNodeFlowGraph(deserializeNodeCanvasGraphWithMigration(legacy).graph);
+        const imported = await createNodeFlowDraft(nextProjectId, { title: "Imported Nodes Canvas", description: "One-time import from the legacy browser canvas.", graph: importedGraph });
+        window.localStorage.setItem(migrationMarker(nextProjectId), imported.flowId);
+        window.localStorage.removeItem(NODES_CANVAS_STORAGE_KEY);
+        nextFlows = (await fetchNodeFlows(nextProjectId, signal)).flows;
+        setNotice("Legacy canvas imported once into this project's backend flow library.");
       }
-      return next;
-    });
-    setFeedback({ tone: "info", message: `${enabled ? "Enabled" : "Disabled"} ${nodeId} for this editing session.` });
-  };
-
-  const selectNode = (nodeId: string, append = false): void => dispatch({ type: "select_node", nodeId, append });
-  const selectEdge = (edgeId: string, append = false): void => dispatch({ type: "select_edge", edgeId, append });
-
-  const statusIcon = validationIssues.length === 0 ? CheckCircle2 : AlertTriangle;
-  const StatusIcon = statusIcon;
-
-  return (
-    <PageContainer
-      aria-labelledby="nodes-canvas-title"
-      className="gap-5"
-      padding="workbench"
-    >
-      <PageHeader
-        icon={Workflow}
-        eyebrow="Nodes"
-        title={<span id="nodes-canvas-title">Nodes Canvas</span>}
-        subtitle="Compose local workflow graphs with typed nodes, reducer-backed edits, validation feedback, and JSON exchange for agents."
-        actions={(
-          <>
-            <Button type="button" size="sm" variant="secondary" icon={Download} onClick={handleExport}>
-              Export JSON
-            </Button>
-            <Button type="button" size="sm" variant="secondary" icon={Upload} onClick={handleImport}>
-              Import JSON
-            </Button>
-            <Button type="button" size="sm" variant="ghost" icon={RefreshCcw} onClick={handleClear}>
-              Clear
-            </Button>
-            <Button type="button" size="sm" variant="ghost" icon={RotateCcw} onClick={handleReset}>
-              Reset
-            </Button>
-          </>
-        )}
-      />
-
-      <section
-        aria-label="Node canvas status"
-        className={`${panelClass} flex flex-col gap-3 lg:flex-row lg:items-center lg:justify-between`}
-      >
-        <div className="flex min-w-0 items-start gap-3">
-          <div className="mt-0.5 flex h-9 w-9 shrink-0 items-center justify-center rounded-[var(--radius-ui)] bg-slate-900/[0.06] text-slate-600 dark:bg-white/[0.08] dark:text-slate-200">
-            <StatusIcon className={validationIssues.length === 0 ? "h-4 w-4 text-status-green" : "h-4 w-4 text-status-red"} aria-hidden="true" />
-          </div>
-          <div className="min-w-0">
-            <p className="text-sm font-bold text-slate-900 dark:text-white">
-              {validationIssues.length === 0 ? "Graph is structurally valid" : `${validationIssues.length} validation issue${validationIssues.length === 1 ? "" : "s"}`}
-            </p>
-            <p className="mt-1 text-sm text-slate-500 dark:text-slate-400">
-              {summary.nodeCount} nodes, {summary.edgeCount} edges, {summary.selectedNodeIds.length + summary.selectedEdgeIds.length} selected. Saved locally under <code>{NODES_CANVAS_STORAGE_KEY}</code>.
-            </p>
-          </div>
-        </div>
-        <p
-          role="status"
-          aria-live="polite"
-          className={`rounded-[var(--radius-ui)] border px-3 py-2 text-sm ${toneClasses[feedback.tone]}`}
-        >
-          {feedback.message}
-        </p>
-      </section>
+      setCatalog(registry.nodes); setFlows(nextFlows);
+      const preferred = nextFlows.find((flow) => flow.id === selectedFlowId) ?? nextFlows[0] ?? null;
+      if (preferred) {
+        applyRecord(preferred);
+        setReview(await validateNodeFlowDraft(nextProjectId, preferred.id));
+      } else { setRecord(null); setSelectedFlowId(null); setReview(null); }
+    } catch (requestError) { if (!signal?.aborted) setError(errorMessage(requestError)); }
+    finally { if (!signal?.aborted && projectRef.current === nextProjectId) setLoading(false); }
+  }, [applyRecord, selectedFlowId]);
 
-      <div className="grid min-h-0 gap-4 xl:grid-cols-[300px_minmax(0,1fr)_380px]">
-        <NodePalette
-          onCreateNode={(action) => {
-            dispatch(action);
-            setFeedback({ tone: "success", message: `Added ${action.kind} node.` });
-          }}
-        />
-
-        <div className="flex min-w-0 flex-col gap-4">
-          <NodeCanvas
-            graph={graph}
-            validationIssues={validationIssues}
-            onSelectNode={selectNode}
-            onSelectEdge={selectEdge}
-            onClearSelection={() => dispatch({ type: "clear_selection" })}
-            onDeleteNode={(nodeId) => dispatch({ type: "delete_node", nodeId })}
-            onDeleteEdge={(edgeId) => dispatch({ type: "delete_edge", edgeId })}
-            onMoveNode={(nodeId, position) => dispatch({ type: "move_node", nodeId, position })}
-          />
-          {graph.nodes.length === 0 ? (
-            <div className={`${panelClass} flex items-center gap-3 text-sm text-slate-500 dark:text-slate-400`} role="status">
-              <FileJson className="h-4 w-4 shrink-0 text-signal-500" aria-hidden="true" />
-              The canvas is empty. Palette actions and valid imported JSON can rebuild it.
-            </div>
-          ) : null}
-          <NodeValidationPanel
-            graph={graph}
-            onSelectNode={(nodeId) => selectNode(nodeId)}
-            onSelectEdge={(edgeId) => selectEdge(edgeId)}
-            onFocusNode={(nodeId) => {
-              selectNode(nodeId);
-              setFeedback({ tone: "info", message: `Selected node ${nodeId}.` });
-            }}
-            onFocusEdge={(edgeId) => {
-              selectEdge(edgeId);
-              setFeedback({ tone: "info", message: `Selected edge ${edgeId}.` });
-            }}
-          />
-        </div>
-
-        <div className="flex min-w-0 flex-col gap-4">
-          <NodeInspector
-            graph={graph}
-            selectedNode={selectedNode}
-            selectedEdge={selectedEdge}
-            selectedNodeEnabled={selectedNode ? enabledNodeIds.has(selectedNode.id) : true}
-            validationIssues={validationIssues}
-            onNodeChange={handleNodeChange}
-            onNodeConfigChange={handleNodeConfigChange}
-            onNodeEnabledChange={handleNodeEnabledChange}
-            onSelectNode={(nodeId) => selectNode(nodeId)}
-            onSelectEdge={(edgeId) => selectEdge(edgeId)}
-          />
-
-          <section className={`${panelClass} flex flex-col gap-3`} aria-labelledby="nodes-json-heading">
-            <div className="flex items-start justify-between gap-3">
-              <div>
-                <p className="text-[10px] font-bold uppercase tracking-[0.18em] text-signal-600 dark:text-signal-400">Exchange</p>
-                <h2 id="nodes-json-heading" className="text-base font-bold text-slate-900 dark:text-white">Graph JSON</h2>
-              </div>
-              <ClipboardList className="h-4 w-4 text-slate-400" aria-hidden="true" />
-            </div>
-            <label className="text-sm font-medium text-slate-700 dark:text-slate-300" htmlFor="nodes-graph-json">
-              Import or exported graph
-            </label>
-            <textarea
-              id="nodes-graph-json"
-              className="min-h-56 w-full resize-y rounded-[var(--radius-ui)] border border-[color:var(--border-hairline)] bg-[var(--fill-muted)] px-3 py-2 font-mono text-xs leading-relaxed text-slate-700 outline-none transition focus-visible:ring-2 focus-visible:ring-[var(--accent-focus-ring)] dark:text-slate-200"
-              spellcheck={false}
-              value={exchangeJson}
-              onInput={(event) => setExchangeJson(event.currentTarget.value)}
-            />
-            <div className="flex flex-wrap gap-2">
-              <Button type="button" size="sm" variant="secondary" icon={Download} onClick={handleExport}>
-                Export
-              </Button>
-              <Button type="button" size="sm" variant="signal" icon={Upload} onClick={handleImport}>
-                Import
-              </Button>
-            </div>
-          </section>
+  useEffect(() => {
+    setFlows([]); setRecord(null); setSelectedFlowId(null); setRuns([]); setError(null); setNotice(null);
+    if (!projectId) return;
+    const controller = new AbortController(); void loadLibrary(projectId, controller.signal); return () => controller.abort();
+  }, [projectId]);
 
-          <section className={`${panelClass} flex flex-col gap-3`} aria-labelledby="nodes-agent-heading">
-            <div>
-              <p className="text-[10px] font-bold uppercase tracking-[0.18em] text-signal-600 dark:text-signal-400">Agent surface</p>
-              <h2 id="nodes-agent-heading" className="text-base font-bold text-slate-900 dark:text-white">Command metadata</h2>
-            </div>
-            <p className="text-sm leading-relaxed text-slate-500 dark:text-slate-400">
-              Agents can use add_node, patch_node, connect_ports, delete_entities, select_entities, and replace_graph commands against this graph contract.
-            </p>
-            <pre className="max-h-72 overflow-auto rounded-[var(--radius-ui)] border border-black/[0.06] bg-slate-950 p-3 text-xs leading-relaxed text-slate-100 dark:border-white/[0.08]">
-              {summaryJson}
-            </pre>
-          </section>
-        </div>
-      </div>
-    </PageContainer>
-  );
+  useEffect(() => {
+    if (!selectedNode?.definition) return;
+    const key = `${selectedNode.definition.type}@${selectedNode.definition.version}`;
+    if (definitions[key]) return;
+    void fetchNodeDefinition(selectedNode.definition.type, selectedNode.definition.version).then((definition) => setDefinitions((current) => ({ ...current, [key]: definition }))).catch((requestError) => setError(errorMessage(requestError)));
+  }, [selectedNode?.definition?.type, selectedNode?.definition?.version]);
+
+  const refreshRuns = useCallback(async (): Promise<void> => {
+    if (!record) return;
+    const response = await fetchNodeFlowRuns(record.id); setRuns(response.runs); setSelectedRunId((current) => current ?? response.runs[0]?.id ?? null);
+  }, [record]);
+  useEffect(() => { setRuns([]); setSelectedRunId(null); if (record) void refreshRuns().catch((requestError) => setError(errorMessage(requestError))); }, [record?.id]);
+  useEffect(() => { if (!selectedRunId) { setNodeRuns([]); setAttempts([]); return; } const controller = new AbortController(); void Promise.all([fetchNodeFlowNodeRuns(selectedRunId, controller.signal), fetchNodeFlowAttempts(selectedRunId, controller.signal)]).then(([nodes, history]) => { setNodeRuns(nodes.nodeRuns); setAttempts(history.attempts); }).catch((requestError) => { if (!controller.signal.aborted) setError(errorMessage(requestError)); }); return () => controller.abort(); }, [selectedRunId]);
+
+  const act = async (action: () => Promise<void>): Promise<void> => { setBusy(true); setError(null); setNotice(null); try { await action(); } catch (requestError) { setError(errorMessage(requestError)); } finally { setBusy(false); } };
+  const selectFlow = (flowId: string): void => { const flow = flows.find((item) => item.id === flowId); if (!flow || !projectId) return; applyRecord(flow); void validateNodeFlowDraft(projectId, flow.id).then(setReview).catch((requestError) => setError(errorMessage(requestError))); };
+  const createFlow = (): void => { if (!projectId) return; void act(async () => { const created = await createNodeFlowDraft(projectId, { title: "Untitled automation", description: "", graph: createDefaultNodeFlowGraph() }); const flow = await fetchNodeFlow(created.flowId); setFlows((current) => [flow, ...current]); applyRecord(flow); setReview(created); setNotice("Draft created in the selected project."); }); };
+  const save = (): void => { if (!projectId || !record) return; void act(async () => { const result = await patchNodeFlowDraft(record.id, { projectId, draftRevision: record.version, title, description, graph }); if (result.conflict) { setError(`${result.conflict.message} Current revision is ${result.conflict.actualDraftRevision}.`); return; } const saved = await fetchNodeFlow(record.id); setFlows((current) => current.map((item) => item.id === saved.id ? saved : item)); applyRecord(saved); setReview(result.draft ?? null); setNotice("Draft saved to the canonical flow repository."); }); };
+  const addNode = (summary: NodeDefinitionSummary): void => { void act(async () => { const definition = await fetchNodeDefinition(summary.type, summary.version); setDefinitions((current) => ({ ...current, [`${definition.type}@${definition.version}`]: definition })); let suffix = 1; while (graph.nodes.some((node) => node.id === `${definition.type}-${suffix}`)) suffix += 1; const node: NodeFlowNode = { id: `${definition.type}-${suffix}`, type: definition.type, title: definition.ui.label, description: definition.ui.description, definition: { type: definition.type, version: definition.version }, ports: definition.ports, widgetSchema: definition.ui.widgetSchema, data: {}, capabilities: definition.capabilities, sideEffect: definition.sideEffect, policy: definition.defaultPolicy, credentialBindings: [], position: { x: 80 + graph.nodes.length * 260, y: 100 } }; setGraph((current) => ({ ...current, nodes: [...current.nodes, node] })); setSelectedNodeId(node.id); }); };
+  const validate = (): void => { if (!projectId || !record) return; void act(async () => setReview(await validateNodeFlowDraft(projectId, record.id))); };
+  const runDry = (): void => { if (!projectId || !record) return; void act(async () => setDryRun(await dryRunNodeFlowDraft(projectId, record.id))); };
+  const publish = (): void => { if (!projectId || !record || !review) return; void act(async () => { setReview(await publishNodeFlowDraft(projectId, record.id, review.draftRevision)); setNotice("Draft published after governed review."); }); };
+  const compare = (): void => { if (!projectId || !record || !review?.publishedVersion) return; const publishedVersion = review.publishedVersion; void act(async () => setDiff(await compareNodeFlowVersions(projectId, record.id, publishedVersion, record.version))); };
+  const rollback = (): void => { if (!projectId || !record || !review?.publishedVersion) return; void act(async () => { const next = await rollbackNodeFlow(projectId, record.id, review.publishedVersion!, record.version); const flow = await fetchNodeFlow(record.id); applyRecord(flow); setReview(next); }); };
+  const run = (): void => { if (!projectId || !record) return; void act(async () => { const result = await runNodeFlow(record.id, { projectId, input: {} }); setRuns((current) => [result.run, ...current]); setSelectedRunId(result.run.id); setNodeRuns(result.nodeRuns); setAttempts(result.attempts ?? []); }); };
+
+  if (projectLoading) return <PageContainer><div role="status" className="p-10 text-sm text-slate-500">Loading project workspace…</div></PageContainer>;
+  if (!selectedProject) return <PageContainer><PageHeader icon={Workflow} eyebrow="Nodes" title="Automation workspace" subtitle="Select a project to load its governed node-flow library." /><EmptyState icon={<Workflow className="h-7 w-7" />} title="Select a project" description="Flows, credentials, publications, and run history are always scoped to a project." /></PageContainer>;
+  return <PageContainer className="gap-5" padding="workbench" aria-labelledby="nodes-workspace-title">
+    <PageHeader icon={Workflow} eyebrow={selectedProject.name} title={<span id="nodes-workspace-title">Automation workspace</span>} subtitle="Build from the governed registry, review policy and permissions, publish immutable versions, and debug redacted runs." actions={<><Button size="sm" icon={Plus} onClick={createFlow} disabled={busy}>New draft</Button><Button size="sm" variant="secondary" icon={Save} onClick={save} disabled={busy || !record || !dirty}>Save draft</Button><Button size="sm" variant="secondary" onClick={run} disabled={busy || !record || !review?.publishedVersion}>Run published</Button></>} />
+    {error ? <div role="alert" className="rounded-xl border border-status-red/25 bg-status-red/[0.07] p-3 text-sm text-status-red"><AlertTriangle className="mr-2 inline h-4 w-4" aria-hidden="true" />{error}<button type="button" className="ml-3 underline" onClick={() => void loadLibrary(selectedProject.id)}>Retry</button></div> : null}
+    {notice ? <div role="status" className="rounded-xl border border-status-green/20 bg-status-green/[0.06] p-3 text-sm text-slate-700 dark:text-slate-200">{notice}</div> : null}
+    <div className="flex min-w-0 flex-col gap-4 xl:flex-row"><NodeFlowLibrary flows={flows} selectedFlowId={selectedFlowId} loading={loading} onSelect={selectFlow} onCreate={createFlow} onDelete={(id) => void act(async () => { await deleteNodeFlow(id); await loadLibrary(selectedProject.id); })} />
+      <div className="min-w-0 flex-1">{record ? <div className="mb-3 grid gap-3 sm:grid-cols-2"><label className="text-xs font-bold uppercase text-slate-500">Flow name<input className="mt-1 w-full rounded-xl border border-black/[0.08] bg-white/70 px-3 py-2 text-sm normal-case dark:border-white/[0.08] dark:bg-white/[0.04]" value={title} onInput={(event) => setTitle(event.currentTarget.value)} /></label><label className="text-xs font-bold uppercase text-slate-500">Description<input className="mt-1 w-full rounded-xl border border-black/[0.08] bg-white/70 px-3 py-2 text-sm normal-case dark:border-white/[0.08] dark:bg-white/[0.04]" value={description} onInput={(event) => setDescription(event.currentTarget.value)} /></label></div> : null}{record ? <NodeFlowCanvas graph={graph} selectedNodeId={selectedNodeId} onSelectNode={setSelectedNodeId} onMoveNode={(id, position) => setGraph((current) => updateNodeInGraph(current, id, { position }))} /> : <EmptyState icon={<Workflow className="h-7 w-7" />} title="No flows in this project" description="Create a draft to start from the canonical backend workspace." primaryAction={<Button onClick={createFlow}>Create draft</Button>} />}</div>
+      <NodePalette definitions={catalog} loading={loading} disabled={!record || busy} onCreateNode={addNode} />
+      {record ? <NodeFlowInspector selectedNode={selectedNode} definition={selectedDefinition} validation={review ? { valid: review.valid, errors: review.validationIssues } : null} requiredCredentials={review?.requiredCredentials.filter((item) => item.nodeId === selectedNode?.id) ?? []} agents={[]} attachments={[]} attachAgentId="" onAttachAgentIdChange={() => undefined} onAttachAgent={() => undefined} onDetachAgent={() => undefined} onNodeChange={(id, update) => setGraph((current) => updateNodeInGraph(current, id, update))} onRequestCredential={(nodeId, slot) => { if (projectId && record) void act(async () => { await requestNodeFlowCredential(projectId, record.id, nodeId, slot); setNotice("Credential binding request recorded; secret material remains outside the graph."); }); }} /> : null}
+    </div>
+    {record ? <><NodeGovernancePanel review={review} dryRun={dryRun} diff={diff} busy={busy} onValidate={validate} onDryRun={runDry} onCompare={compare} onPublish={publish} onRollback={rollback} /><NodeRunDebugger runs={runs} selectedRunId={selectedRunId} nodeRuns={nodeRuns} attempts={attempts} busy={busy} onSelectRun={setSelectedRunId} onRefresh={() => void act(refreshRuns)} onCancel={() => { const active = runs.find((item) => item.id === selectedRunId); if (projectId && active) void act(async () => { await cancelNodeFlowRun(projectId, active.id); await refreshRuns(); }); }} onRetry={() => { const active = runs.find((item) => item.id === selectedRunId); if (projectId && active) void act(async () => { const result = await retryNodeFlowRun(projectId, active.id); setRuns((current) => [result.run, ...current]); setSelectedRunId(result.run.id); }); }} /></> : null}
+  </PageContainer>;
 };
diff --git a/dashboard/src/v2/components/nodes/NodeFlowInspector.tsx b/dashboard/src/v2/components/nodes/NodeFlowInspector.tsx
index cd1ec791f5..2c12419d5c 100644
--- a/dashboard/src/v2/components/nodes/NodeFlowInspector.tsx
+++ b/dashboard/src/v2/components/nodes/NodeFlowInspector.tsx
@@ -7,6 +7,8 @@ import type {
   NodeFlowNode,
   NodeFlowSkillAttachment,
   NodeFlowValidationResponse,
+  NodeDefinitionManifest,
+  NodeFlowRequiredCredential,
 } from "../../types.js";
 import {
   applyWidgetDefaults,
@@ -25,6 +27,9 @@ interface NodeFlowInspectorProps {
   onAttachAgent: () => void;
   onDetachAgent: (agentPresetId: string) => void;
   onNodeChange: (nodeId: string, update: Partial<NodeFlowNode>) => void;
+  definition?: NodeDefinitionManifest | null;
+  requiredCredentials?: NodeFlowRequiredCredential[];
+  onRequestCredential?: (nodeId: string, slot: string) => void;
 }
 
 const inputClass = "w-full rounded-xl border border-black/[0.08] bg-white/75 px-3 py-2 text-sm text-slate-800 shadow-sm outline-none transition focus:border-signal-500/50 focus:ring-2 focus:ring-signal-500/20 dark:border-white/[0.08] dark:bg-white/[0.04] dark:text-slate-100";
@@ -40,6 +45,9 @@ export const NodeFlowInspector: FunctionComponent<NodeFlowInspectorProps> = ({
   onAttachAgent,
   onDetachAgent,
   onNodeChange,
+  definition = null,
+  requiredCredentials = [],
+  onRequestCredential,
 }) => {
   const messagesByField = buildValidationMessagesByField(validation);
 
@@ -51,7 +59,8 @@ export const NodeFlowInspector: FunctionComponent<NodeFlowInspectorProps> = ({
     );
   }
 
-  const data = applyWidgetDefaults(selectedNode.widgetSchema, selectedNode.data);
+  const widgetSchema = definition?.ui.widgetSchema ?? selectedNode.widgetSchema;
+  const data = applyWidgetDefaults(widgetSchema, selectedNode.data);
 
   const updateDataField = (fieldId: string, value: NodeFlowJsonValue): void => {
     onNodeChange(selectedNode.id, {
@@ -79,14 +88,11 @@ export const NodeFlowInspector: FunctionComponent<NodeFlowInspectorProps> = ({
             onInput={(event) => onNodeChange(selectedNode.id, { title: event.currentTarget.value })}
           />
         </label>
-        <label className="flex flex-col gap-1.5 text-xs font-bold uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">
-          Type
-          <input
-            className={inputClass}
-            value={selectedNode.type}
-            onInput={(event) => onNodeChange(selectedNode.id, { type: event.currentTarget.value })}
-          />
-        </label>
+        <div className="rounded-xl border border-black/[0.06] bg-white/55 p-3 text-xs text-slate-500 dark:border-white/[0.06] dark:bg-white/[0.03]">
+          <p className="font-bold text-slate-800 dark:text-slate-100">{definition?.ui.label ?? selectedNode.type} · v{definition?.version ?? selectedNode.definition?.version ?? 1}</p>
+          <p className="mt-1">{definition?.ports.length ?? selectedNode.ports?.length ?? 0} typed ports · {definition?.sideEffect ?? selectedNode.sideEffect ?? "none"} side effects</p>
+          {(definition?.capabilities ?? selectedNode.capabilities ?? []).length ? <p className="mt-1 break-words">Capabilities: {(definition?.capabilities ?? selectedNode.capabilities ?? []).join(", ")}</p> : null}
+        </div>
         <label className="flex flex-col gap-1.5 text-xs font-bold uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">
           Description
           <textarea
@@ -99,12 +105,12 @@ export const NodeFlowInspector: FunctionComponent<NodeFlowInspectorProps> = ({
 
       <section className="flex flex-col gap-4 border-t border-black/[0.06] pt-4 dark:border-white/[0.06]" aria-labelledby="node-widgets-heading">
         <h3 id="node-widgets-heading" className="text-xs font-bold uppercase tracking-[0.16em] text-slate-500 dark:text-slate-400">Widgets</h3>
-        {(selectedNode.widgetSchema?.fields.length ?? 0) === 0 ? (
+        {(widgetSchema?.fields.length ?? 0) === 0 ? (
           <p className="rounded-xl border border-black/[0.06] bg-white/55 px-3 py-3 text-sm text-slate-500 dark:border-white/[0.06] dark:bg-white/[0.03]">
             No widgets configured for this node.
           </p>
         ) : (
-          selectedNode.widgetSchema!.fields.map((field) => (
+          widgetSchema!.fields.map((field) => (
             <NodeWidgetField
               key={field.id}
               field={field}
@@ -116,6 +122,17 @@ export const NodeFlowInspector: FunctionComponent<NodeFlowInspectorProps> = ({
         )}
       </section>
 
+      <section className="flex flex-col gap-3 border-t border-black/[0.06] pt-4 dark:border-white/[0.06]" aria-labelledby="node-credentials-heading">
+        <h3 id="node-credentials-heading" className="text-xs font-bold uppercase tracking-[0.16em] text-slate-500 dark:text-slate-400">Credential bindings</h3>
+        {requiredCredentials.length === 0 ? <p className="text-xs text-slate-500">This node does not request credentials.</p> : requiredCredentials.map((credential) => (
+          <div key={credential.slot} className="rounded-xl border border-black/[0.06] bg-white/60 p-3 dark:border-white/[0.06] dark:bg-white/[0.03]">
+            <div className="flex items-center justify-between gap-3"><span className="text-sm font-bold text-slate-800 dark:text-slate-100">{credential.slot}</span><span className={`text-[10px] font-bold uppercase ${credential.status === "bound" ? "text-status-green" : "text-status-red"}`}>{credential.status}</span></div>
+            <p className="mt-1 text-xs text-slate-500">{credential.allowedKinds.join(", ")} · secret value never displayed</p>
+            {credential.status !== "bound" && onRequestCredential ? <button type="button" className="mt-2 rounded-lg border border-signal-500/30 px-2.5 py-1.5 text-xs font-bold text-signal-600 focus:outline-none focus-visible:ring-2 focus-visible:ring-signal-500/40" onClick={() => onRequestCredential(selectedNode.id, credential.slot)}>Request binding</button> : null}
+          </div>
+        ))}
+      </section>
+
       <section className="flex flex-col gap-3 border-t border-black/[0.06] pt-4 dark:border-white/[0.06]" aria-labelledby="node-agent-attachments-heading">
         <h3 id="node-agent-attachments-heading" className="text-xs font-bold uppercase tracking-[0.16em] text-slate-500 dark:text-slate-400">Agent Attachments</h3>
         <div className="flex gap-2">
diff --git a/dashboard/src/v2/components/nodes/NodeGovernancePanel.tsx b/dashboard/src/v2/components/nodes/NodeGovernancePanel.tsx
new file mode 100644
index 0000000000..e9777d9aa8
--- /dev/null
+++ b/dashboard/src/v2/components/nodes/NodeGovernancePanel.tsx
@@ -0,0 +1,30 @@
+import type { FunctionComponent } from "preact";
+import { CheckCircle2, FlaskConical, GitCompare, RotateCcw, ShieldAlert, UploadCloud } from "lucide-preact";
+import type { NodeFlowDraftReview } from "../../types.js";
+import type { NodeFlowDryRunResponse, NodeFlowVersionDiff } from "../../lib/node-flow-api.js";
+import { Button } from "../ui/Button.js";
+
+interface NodeGovernancePanelProps {
+  review: NodeFlowDraftReview | null;
+  dryRun: NodeFlowDryRunResponse | null;
+  diff: NodeFlowVersionDiff | null;
+  busy?: boolean;
+  onValidate: () => void;
+  onDryRun: () => void;
+  onCompare: () => void;
+  onPublish: () => void;
+  onRollback: () => void;
+}
+
+export const NodeGovernancePanel: FunctionComponent<NodeGovernancePanelProps> = ({ review, dryRun, diff, busy, onValidate, onDryRun, onCompare, onPublish, onRollback }) => (
+  <section className="rounded-[var(--radius-panel)] border border-black/[0.06] bg-white/70 p-4 shadow-[var(--elevation-soft)] dark:border-white/[0.06] dark:bg-white/[0.035]" aria-labelledby="governance-heading">
+    <div className="flex flex-wrap items-start justify-between gap-3"><div><p className="text-[10px] font-bold uppercase tracking-[0.18em] text-signal-600 dark:text-signal-400">T06 control plane</p><h2 id="governance-heading" className="text-base font-bold text-slate-900 dark:text-white">Validation, policy & publication</h2></div><div className="flex flex-wrap gap-2"><Button size="sm" variant="secondary" icon={CheckCircle2} onClick={onValidate} disabled={busy}>Validate</Button><Button size="sm" variant="secondary" icon={FlaskConical} onClick={onDryRun} disabled={busy}>Dry run</Button><Button size="sm" variant="secondary" icon={GitCompare} onClick={onCompare} disabled={busy || !review?.publishedVersion}>Compare</Button><Button size="sm" variant="ghost" icon={RotateCcw} onClick={onRollback} disabled={busy || !review?.publishedVersion}>Rollback</Button><Button size="sm" icon={UploadCloud} onClick={onPublish} disabled={busy || !review?.valid}>Publish</Button></div></div>
+    {!review ? <p role="status" className="mt-4 text-sm text-slate-500">Validate the draft to load its governed review.</p> : <div className="mt-4 grid gap-3 lg:grid-cols-3">
+      <div className="rounded-xl border border-black/[0.06] p-3 dark:border-white/[0.06]"><p className="text-xs font-bold uppercase text-slate-400">Revision</p><p className="mt-1 text-sm font-bold text-slate-900 dark:text-white">Draft r{review.draftRevision} · {review.publishedVersion ? `published v${review.publishedVersion}` : "unpublished"}</p><p className="mt-2 text-xs text-slate-500">{review.nodeCount} nodes · {review.edgeCount} edges</p></div>
+      <div className="rounded-xl border border-black/[0.06] p-3 dark:border-white/[0.06]"><p className="text-xs font-bold uppercase text-slate-400">Permissions</p><p className="mt-1 text-sm text-slate-700 dark:text-slate-200">{review.requestedCapabilities.length ? review.requestedCapabilities.join(", ") : "No capabilities requested"}</p>{review.sideEffectDiffs.map((item) => <p key={item.nodeId} className="mt-1 text-xs text-amber-600">{item.description}</p>)}</div>
+      <div className="rounded-xl border border-black/[0.06] p-3 dark:border-white/[0.06]"><p className="text-xs font-bold uppercase text-slate-400">Policy</p>{review.policyFindings.length ? review.policyFindings.map((finding) => <p key={`${finding.code}-${finding.nodeId ?? "graph"}`} className={`mt-1 text-xs ${finding.severity === "error" ? "text-status-red" : "text-amber-600"}`}><ShieldAlert className="mr-1 inline h-3 w-3" aria-hidden="true" />{finding.message}</p>) : <p className="mt-1 text-sm text-status-green">No policy findings</p>}</div>
+    </div>}
+    {dryRun ? <div role="status" className={`mt-3 rounded-xl border p-3 text-sm ${dryRun.status === "ready" ? "border-status-green/20 bg-status-green/[0.06]" : "border-amber-500/25 bg-amber-500/[0.06]"}`}><strong>Dry run {dryRun.status}.</strong> No nodes executed; reviewed {dryRun.result.inputKeys.length} input keys.</div> : null}
+    {diff ? <div className="mt-3 rounded-xl border border-black/[0.06] p-3 text-sm dark:border-white/[0.06]" aria-label="Publication diff"><strong>Graph diff v{diff.fromVersion} → v{diff.toVersion}:</strong> {diff.addedNodeIds.length} added, {diff.removedNodeIds.length} removed; nodes {diff.nodeCount.from} → {diff.nodeCount.to}. Permission/side-effect changes: {diff.sideEffectDiffs.length}.</div> : null}
+  </section>
+);
diff --git a/dashboard/src/v2/components/nodes/NodePalette.tsx b/dashboard/src/v2/components/nodes/NodePalette.tsx
index 1c1183b033..7a19743ce9 100644
--- a/dashboard/src/v2/components/nodes/NodePalette.tsx
+++ b/dashboard/src/v2/components/nodes/NodePalette.tsx
@@ -1,100 +1,43 @@
 import type { FunctionComponent } from "preact";
-import { GitBranch, Play, Plus, Route, Send, Split } from "lucide-preact";
-import type {
-  NodeCanvasNodeKind,
-  NodeCanvasNodeMetadata,
-  NodesCanvasAction,
-} from "../../lib/nodes-canvas-state.js";
-import { Button } from "../ui/Button.js";
-import { Tooltip } from "../ui/Tooltip.js";
-
-export type NodePaletteCreateNodeInput = Extract<NodesCanvasAction, { type: "add_node" }>;
-
-interface NodePaletteTemplate {
-  kind: NodeCanvasNodeKind;
-  label: string;
-  description: string;
-  metadata?: NodeCanvasNodeMetadata;
-  Icon: typeof Play;
-}
+import { Box, LockKeyhole, Plus } from "lucide-preact";
+import type { NodeDefinitionSummary } from "../../lib/node-flow-api.js";
 
 interface NodePaletteProps {
+  definitions: NodeDefinitionSummary[];
   disabled?: boolean;
-  onCreateNode: (input: NodePaletteCreateNodeInput) => void;
+  loading?: boolean;
+  onCreateNode: (definition: NodeDefinitionSummary) => void;
 }
 
-const NODE_TEMPLATES: readonly NodePaletteTemplate[] = [
-  {
-    kind: "trigger",
-    label: "Trigger",
-    description: "Start a graph from a manual or scheduled event.",
-    Icon: Play,
-  },
-  {
-    kind: "agent",
-    label: "Agent",
-    description: "Route work to a planning, implementation, review, or QA agent.",
-    metadata: { agentIntent: "implement" },
-    Icon: Route,
-  },
-  {
-    kind: "task",
-    label: "Task",
-    description: "Draft the concrete work item an agent should execute.",
-    metadata: { taskIntent: "feature" },
-    Icon: GitBranch,
-  },
-  {
-    kind: "condition",
-    label: "Condition",
-    description: "Branch the workflow based on checks or review state.",
-    Icon: Split,
-  },
-  {
-    kind: "output",
-    label: "Output",
-    description: "Collect the final workflow result for runs and agents.",
-    Icon: Send,
-  },
-];
-
-export const NodePalette: FunctionComponent<NodePaletteProps> = ({ disabled = false, onCreateNode }) => (
-  <aside
-    className="flex min-w-0 flex-col gap-3 rounded-[var(--radius-panel)] border border-black/[0.06] bg-white/70 p-4 shadow-[var(--elevation-soft)] dark:border-white/[0.06] dark:bg-white/[0.035] xl:w-[300px] xl:shrink-0"
-    aria-labelledby="node-palette-heading"
-  >
-    <div className="flex items-center justify-between gap-3">
-      <div>
-        <p className="text-[10px] font-bold uppercase tracking-[0.18em] text-signal-600 dark:text-signal-400">Palette</p>
-        <h2 id="node-palette-heading" className="text-base font-bold text-slate-900 dark:text-white">Add nodes</h2>
+export const NodePalette: FunctionComponent<NodePaletteProps> = ({ definitions, disabled = false, loading = false, onCreateNode }) => {
+  const categories = new Map<string, NodeDefinitionSummary[]>();
+  for (const definition of definitions) {
+    categories.set(definition.category, [...(categories.get(definition.category) ?? []), definition]);
+  }
+  return (
+    <aside className="flex min-w-0 flex-col gap-3 rounded-[var(--radius-panel)] border border-black/[0.06] bg-white/70 p-4 shadow-[var(--elevation-soft)] dark:border-white/[0.06] dark:bg-white/[0.035] xl:w-[300px] xl:shrink-0" aria-labelledby="node-palette-heading">
+      <div className="flex items-center justify-between gap-3">
+        <div><p className="text-[10px] font-bold uppercase tracking-[0.18em] text-signal-600 dark:text-signal-400">T01 registry</p><h2 id="node-palette-heading" className="text-base font-bold text-slate-900 dark:text-white">Node catalog</h2></div>
+        <Plus className="h-4 w-4 text-slate-400" aria-hidden="true" />
       </div>
-      <Plus className="h-4 w-4 text-slate-400" aria-hidden="true" />
-    </div>
-    <div className="grid gap-2" aria-label="Node templates">
-      {NODE_TEMPLATES.map(({ kind, label, description, metadata, Icon }) => (
-        <Tooltip key={kind} content={description} position="right">
-          <Button
-            type="button"
-            aria-label={`Add ${label} node`}
-            variant="secondary"
-            size="md"
-            icon={Icon}
-            disabled={disabled}
-            className="w-full justify-start text-left"
-            onClick={() => onCreateNode({
-              type: "add_node",
-              kind,
-              label: `${label} Node`,
-              ...(metadata ? { metadata } : {}),
-            })}
-          >
-            <span className="flex min-w-0 flex-col items-start">
-              <span className="truncate text-sm">{label}</span>
-              <span className="line-clamp-2 text-xs font-medium text-slate-500 dark:text-slate-400">{description}</span>
-            </span>
-          </Button>
-        </Tooltip>
+      {loading ? <p role="status" className="text-sm text-slate-500">Loading node definitions…</p> : null}
+      {!loading && definitions.length === 0 ? <p role="status" className="text-sm text-slate-500">No governed node definitions are available.</p> : null}
+      {[...categories.entries()].map(([category, entries]) => (
+        <section key={category} aria-labelledby={`node-category-${category}`}>
+          <h3 id={`node-category-${category}`} className="mb-2 text-[10px] font-bold uppercase tracking-[0.16em] text-slate-400">{category}</h3>
+          <div className="grid gap-2">
+            {entries.map((definition) => (
+              <button key={`${definition.type}@${definition.version}`} type="button" disabled={disabled || !definition.executable} onClick={() => onCreateNode(definition)} className="rounded-xl border border-black/[0.07] bg-white/70 p-3 text-left transition hover:border-signal-500/35 focus:outline-none focus-visible:ring-2 focus-visible:ring-signal-500/40 disabled:cursor-not-allowed disabled:opacity-55 dark:border-white/[0.07] dark:bg-white/[0.03]" aria-label={`Add ${definition.label} node`}>
+                <span className="flex items-center gap-2 text-sm font-bold text-slate-900 dark:text-white"><Box className="h-4 w-4 text-signal-500" aria-hidden="true" />{definition.label}<span className="ml-auto text-[10px] text-slate-400">v{definition.version}</span></span>
+                <span className="mt-1 block text-xs leading-relaxed text-slate-500">{definition.description}</span>
+                <span className="mt-2 flex flex-wrap gap-1.5 text-[10px] font-bold uppercase tracking-[0.1em] text-slate-400">
+                  <span>{definition.executionKind}</span><span>{definition.sideEffect}</span>{definition.credentials.length ? <span className="inline-flex items-center gap-1"><LockKeyhole className="h-3 w-3" aria-hidden="true" />credential</span> : null}{!definition.executable ? <span>Unavailable</span> : null}
+                </span>
+              </button>
+            ))}
+          </div>
+        </section>
       ))}
-    </div>
-  </aside>
-);
+    </aside>
+  );
+};
diff --git a/dashboard/src/v2/components/nodes/NodeRunDebugger.tsx b/dashboard/src/v2/components/nodes/NodeRunDebugger.tsx
new file mode 100644
index 0000000000..af284a8cff
--- /dev/null
+++ b/dashboard/src/v2/components/nodes/NodeRunDebugger.tsx
@@ -0,0 +1,17 @@
+import type { FunctionComponent } from "preact";
+import { Ban, CalendarClock, ExternalLink, RefreshCw, RotateCw } from "lucide-preact";
+import type { NodeFlowNodeAttemptRecord, NodeFlowNodeRunRecord, NodeFlowRunRecord } from "../../types.js";
+import { redactNodeFlowSecrets } from "../../lib/node-flow-view-models.js";
+import { Button } from "../ui/Button.js";
+
+interface NodeRunDebuggerProps { runs: NodeFlowRunRecord[]; selectedRunId: string | null; nodeRuns: NodeFlowNodeRunRecord[]; attempts: NodeFlowNodeAttemptRecord[]; busy?: boolean; onSelectRun: (id: string) => void; onRefresh: () => void; onCancel: () => void; onRetry: () => void; }
+const terminal = new Set(["succeeded", "failed", "cancelled"]);
+const duration = (start: string | null, end: string | null): string => start ? `${Math.max(0, new Date(end ?? Date.now()).getTime() - new Date(start).getTime())} ms` : "Not started";
+export const NodeRunDebugger: FunctionComponent<NodeRunDebuggerProps> = ({ runs, selectedRunId, nodeRuns, attempts, busy, onSelectRun, onRefresh, onCancel, onRetry }) => {
+  const run = runs.find((item) => item.id === selectedRunId) ?? runs[0] ?? null;
+  return <section className="rounded-[var(--radius-panel)] border border-black/[0.06] bg-white/70 p-4 shadow-[var(--elevation-soft)] dark:border-white/[0.06] dark:bg-white/[0.035]" aria-labelledby="debugger-heading">
+    <div className="flex flex-wrap items-start justify-between gap-3"><div><p className="text-[10px] font-bold uppercase tracking-[0.18em] text-signal-600 dark:text-signal-400">Redacted operations</p><h2 id="debugger-heading" className="text-base font-bold text-slate-900 dark:text-white">Run debugger</h2></div><div className="flex gap-2"><a href="/scheduler" className="inline-flex items-center gap-2 rounded-xl border border-black/[0.08] px-3 py-2 text-sm font-bold text-slate-600 focus:outline-none focus-visible:ring-2 focus-visible:ring-signal-500/40 dark:border-white/[0.08] dark:text-slate-300"><CalendarClock className="h-4 w-4" aria-hidden="true" />Schedule</a><Button size="sm" variant="secondary" icon={RefreshCw} onClick={onRefresh} disabled={busy}>Refresh</Button></div></div>
+    <div className="mt-4 grid gap-4 lg:grid-cols-[16rem_minmax(0,1fr)]"><div className="flex max-h-80 flex-col gap-2 overflow-auto">{runs.length ? runs.map((item) => <button key={item.id} type="button" onClick={() => onSelectRun(item.id)} aria-current={run?.id === item.id ? "true" : undefined} className="rounded-xl border border-black/[0.06] p-3 text-left focus:outline-none focus-visible:ring-2 focus-visible:ring-signal-500/40 dark:border-white/[0.06]"><span className="block text-xs font-bold uppercase text-slate-500">{item.status} · v{item.version}</span><span className="mt-1 block truncate font-mono text-[11px] text-slate-400">{item.id}</span></button>) : <p role="status" className="text-sm text-slate-500">No persisted runs.</p>}</div>
+      <div className="min-w-0">{run ? <><div className="flex flex-wrap gap-2"><Button size="sm" variant="secondary" icon={Ban} onClick={onCancel} disabled={busy || terminal.has(run.status)}>Cancel</Button><Button size="sm" variant="secondary" icon={RotateCw} onClick={onRetry} disabled={busy || !["failed", "cancelled", "attention_required"].includes(run.status)}>Safe retry</Button></div><p className="mt-3 text-xs text-slate-500">Timing: {duration(run.startedAt, run.finishedAt)} · trigger {run.triggerType}</p><div className="mt-3 grid gap-2">{nodeRuns.map((nodeRun) => <div key={nodeRun.id} className="rounded-xl border border-black/[0.06] p-3 dark:border-white/[0.06]"><p className="text-sm font-bold text-slate-800 dark:text-slate-100">{nodeRun.nodeId} · {nodeRun.status} · {duration(nodeRun.startedAt, nodeRun.finishedAt)}</p>{nodeRun.executionInvocationId ? <a className="mt-1 inline-flex items-center gap-1 text-xs text-signal-600" href={`/?invocation=${encodeURIComponent(nodeRun.executionInvocationId)}`}>Invocation {nodeRun.executionInvocationId}<ExternalLink className="h-3 w-3" aria-hidden="true" /></a> : null}{attempts.filter((attempt) => attempt.nodeRunId === nodeRun.id).map((attempt) => <p key={attempt.id} className="mt-1 text-xs text-slate-500">Attempt {attempt.attemptNumber}: {attempt.status}{attempt.failureClassification ? ` · ${attempt.failureClassification}` : ""}{attempt.retryDecision ? ` · ${attempt.retryDecision}` : ""}</p>)}</div>)}</div><pre className="mt-3 max-h-72 overflow-auto rounded-xl bg-slate-950 p-3 text-xs text-slate-100">{JSON.stringify(redactNodeFlowSecrets(run.output ?? run.input ?? {}), null, 2)}</pre></> : <p className="text-sm text-slate-500">Select a run to inspect its graph state and attempts.</p>}</div></div>
+  </section>;
+};
diff --git a/dashboard/src/v2/lib/dashboard-feature-flags.ts b/dashboard/src/v2/lib/dashboard-feature-flags.ts
index f8f2d96378..3e27e6550f 100644
--- a/dashboard/src/v2/lib/dashboard-feature-flags.ts
+++ b/dashboard/src/v2/lib/dashboard-feature-flags.ts
@@ -9,6 +9,7 @@ export type DashboardFeatureFlagValues = Partial<Record<DashboardFeatureId, unkn
 export interface DashboardFeatureFlagSource {
   devMode?: boolean;
   values?: DashboardFeatureFlagValues;
+  prerequisites?: Partial<Record<"nodeFlowBackend" | "automationSecurity", unknown>>;
 }
 
 export const DASHBOARD_FEATURE_ENV_KEYS: Record<DashboardFeatureId, string> = {
@@ -48,6 +49,10 @@ const readDashboardFeatureFlagSource = (): DashboardFeatureFlagSource => {
       nodes: env[DASHBOARD_FEATURE_ENV_KEYS.nodes],
       "custom-dashboards": env[DASHBOARD_FEATURE_ENV_KEYS["custom-dashboards"]],
     },
+    prerequisites: {
+      nodeFlowBackend: env.VITE_CODEUX_NODE_FLOW_BACKEND,
+      automationSecurity: env.VITE_CODEUX_AUTOMATION_SECURITY,
+    },
   };
 };
 
@@ -67,7 +72,13 @@ export const resolveDashboardFeatureFlags = (
 
   return DASHBOARD_FEATURE_IDS.reduce<DashboardFeatureFlagMap>((flags, feature) => {
     const explicitValue = parseDashboardFeatureFlagValue(source.values?.[feature]);
-    flags[feature] = explicitValue ?? false;
+    if (feature === "nodes") {
+      const backendReady = parseDashboardFeatureFlagValue(source.prerequisites?.nodeFlowBackend) === true;
+      const securityReady = parseDashboardFeatureFlagValue(source.prerequisites?.automationSecurity) === true;
+      flags[feature] = explicitValue === true && backendReady && securityReady;
+    } else {
+      flags[feature] = explicitValue ?? false;
+    }
     return flags;
   }, {} as DashboardFeatureFlagMap);
 };
diff --git a/dashboard/src/v2/lib/node-flow-api.ts b/dashboard/src/v2/lib/node-flow-api.ts
index 7a590862fa..633ef161de 100644
--- a/dashboard/src/v2/lib/node-flow-api.ts
+++ b/dashboard/src/v2/lib/node-flow-api.ts
@@ -10,6 +10,11 @@ import type {
   NodeFlowSkillAttachment,
   NodeFlowValidationResponse,
   NodeFlowJsonObject,
+  NodeDefinitionManifest,
+  NodeFlowDraftReview,
+  NodeFlowConcurrencyConflict,
+  NodeFlowNodeAttemptRecord,
+  PatchNodeFlowDraftInput,
   UpdateNodeFlowInput,
 } from "../types.js";
 import { fetchJson } from "../../lib/api/fetch-json.js";
@@ -20,6 +25,112 @@ export interface RunNodeFlowInput {
   triggerPayload?: NodeFlowJsonObject;
 }
 
+export interface NodeFlowCatalogResponse {
+  nodes: NodeDefinitionSummary[];
+}
+
+export interface NodeDefinitionSummary {
+  type: string;
+  version: number;
+  executable: boolean;
+  executionKind: NodeDefinitionManifest["executionKind"];
+  label: string;
+  description: string;
+  category: string;
+  credentials: NodeDefinitionManifest["credentials"];
+  capabilities: string[];
+  sideEffect: NodeDefinitionManifest["sideEffect"];
+  ports: NodeDefinitionManifest["ports"];
+}
+
+export interface PatchNodeFlowDraftResponse {
+  draft?: NodeFlowDraftReview;
+  conflict?: NodeFlowConcurrencyConflict;
+}
+
+export interface NodeFlowDryRunResponse {
+  status: "ready" | "blocked";
+  draftRevision: number;
+  validationIssues: NodeFlowDraftReview["validationIssues"];
+  policyFindings: NodeFlowDraftReview["policyFindings"];
+  requiredCredentials: NodeFlowDraftReview["requiredCredentials"];
+  requestedCapabilities: string[];
+  sideEffectDiffs: NodeFlowDraftReview["sideEffectDiffs"];
+  result: { executed: false; inputKeys: string[]; output: null };
+}
+
+export interface NodeFlowVersionDiff {
+  flowId: string;
+  fromVersion: number;
+  toVersion: number;
+  nodeCount: { from: number; to: number };
+  edgeCount: { from: number; to: number };
+  addedNodeIds: string[];
+  removedNodeIds: string[];
+  sideEffectDiffs: NodeFlowDraftReview["sideEffectDiffs"];
+}
+
+export const fetchNodeFlowCatalog = async (signal?: AbortSignal): Promise<NodeFlowCatalogResponse> =>
+  fetchJson<NodeFlowCatalogResponse>("/api/node-flow-catalog", { signal });
+
+export const fetchNodeDefinition = async (type: string, version?: number, signal?: AbortSignal): Promise<NodeDefinitionManifest> => {
+  const query = version === undefined ? "" : `?version=${encodeURIComponent(String(version))}`;
+  return fetchJson<NodeDefinitionManifest>(`/api/node-flow-catalog/${encodeURIComponent(type)}${query}`, { signal });
+};
+
+export const createNodeFlowDraft = async (projectId: string, input: CreateNodeFlowInput): Promise<NodeFlowDraftReview> =>
+  fetchJson<NodeFlowDraftReview>(`/api/projects/${encodeURIComponent(projectId)}/node-flow-drafts`, {
+    method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(input),
+  });
+
+export const patchNodeFlowDraft = async (flowId: string, input: PatchNodeFlowDraftInput): Promise<PatchNodeFlowDraftResponse> =>
+  fetchJson<PatchNodeFlowDraftResponse>(`/api/node-flow-drafts/${encodeURIComponent(flowId)}`, {
+    method: "PATCH", headers: { "Content-Type": "application/json" }, body: JSON.stringify(input),
+  });
+
+export const validateNodeFlowDraft = async (projectId: string, flowId: string): Promise<NodeFlowDraftReview> =>
+  fetchJson<NodeFlowDraftReview>(`/api/node-flow-drafts/${encodeURIComponent(flowId)}/validate`, {
+    method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ projectId }),
+  });
+
+export const dryRunNodeFlowDraft = async (projectId: string, flowId: string, input: NodeFlowJsonObject = {}): Promise<NodeFlowDryRunResponse> =>
+  fetchJson<NodeFlowDryRunResponse>(`/api/node-flow-drafts/${encodeURIComponent(flowId)}/dry-run`, {
+    method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ projectId, input }),
+  });
+
+export const requestNodeFlowCredential = async (projectId: string, flowId: string, nodeId: string, slot: string): Promise<Record<string, unknown>> =>
+  fetchJson<Record<string, unknown>>(`/api/node-flow-drafts/${encodeURIComponent(flowId)}/credential-requests`, {
+    method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ projectId, nodeId, slot }),
+  });
+
+export const publishNodeFlowDraft = async (projectId: string, flowId: string, draftRevision: number): Promise<NodeFlowDraftReview> =>
+  fetchJson<NodeFlowDraftReview>(`/api/node-flow-drafts/${encodeURIComponent(flowId)}/publish`, {
+    method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ projectId, draftRevision, publishedBy: "dashboard" }),
+  });
+
+export const compareNodeFlowVersions = async (projectId: string, flowId: string, fromVersion: number, toVersion: number): Promise<NodeFlowVersionDiff> => {
+  const query = new URLSearchParams({ projectId, fromVersion: String(fromVersion), toVersion: String(toVersion) });
+  return fetchJson<NodeFlowVersionDiff>(`/api/node-flows/${encodeURIComponent(flowId)}/compare?${query.toString()}`);
+};
+
+export const rollbackNodeFlow = async (projectId: string, flowId: string, version: number, draftRevision: number): Promise<NodeFlowDraftReview> =>
+  fetchJson<NodeFlowDraftReview>(`/api/node-flows/${encodeURIComponent(flowId)}/rollback`, {
+    method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ projectId, version, draftRevision }),
+  });
+
+export const cancelNodeFlowRun = async (projectId: string, runId: string): Promise<NodeFlowRunRecord> =>
+  fetchJson<NodeFlowRunRecord>(`/api/node-flow-runs/${encodeURIComponent(runId)}/cancel`, {
+    method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ projectId }),
+  });
+
+export const retryNodeFlowRun = async (projectId: string, runId: string): Promise<NodeFlowRunSummaryResponse> =>
+  fetchJson<NodeFlowRunSummaryResponse>(`/api/node-flow-runs/${encodeURIComponent(runId)}/retry`, {
+    method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ projectId }),
+  });
+
+export const fetchNodeFlowAttempts = async (runId: string, signal?: AbortSignal): Promise<{ attempts: NodeFlowNodeAttemptRecord[] }> =>
+  fetchJson<{ attempts: NodeFlowNodeAttemptRecord[] }>(`/api/node-flow-runs/${encodeURIComponent(runId)}/attempts`, { signal });
+
 export const fetchNodeFlows = async (
   projectId: string,
   signal?: AbortSignal,
diff --git a/dashboard/src/v2/types.ts b/dashboard/src/v2/types.ts
index 762584c006..739712b32e 100644
--- a/dashboard/src/v2/types.ts
+++ b/dashboard/src/v2/types.ts
@@ -139,6 +139,13 @@ import type {
   NodeFlowNodeRunListResponse,
   NodeFlowNodeRunRecord,
   NodeFlowNodeRunStatus,
+  NodeFlowNodeAttemptRecord,
+  NodeFlowDraftReview,
+  NodeFlowConcurrencyConflict,
+  NodeFlowRequiredCredential,
+  NodeFlowPolicyFinding,
+  PatchNodeFlowDraftInput,
+  NodeFlowPublicationRecord,
   NodeFlowRecord,
   NodeFlowRunListResponse,
   NodeFlowRunRecord,
@@ -154,6 +161,7 @@ import type {
   NodeWidgetSelectOption,
   UpdateNodeFlowInput,
 } from "../../../src/contracts/node-flow-types.js";
+import type { NodeDefinitionManifest } from "../../../src/contracts/node-definition-types.js";
 import type {
   CreateCustomDashboardDraftInput,
   CreateCustomDashboardRevisionInput,
@@ -483,6 +491,13 @@ export type {
   NodeFlowNodeRunListResponse,
   NodeFlowNodeRunRecord,
   NodeFlowNodeRunStatus,
+  NodeFlowNodeAttemptRecord,
+  NodeFlowDraftReview,
+  NodeFlowConcurrencyConflict,
+  NodeFlowRequiredCredential,
+  NodeFlowPolicyFinding,
+  PatchNodeFlowDraftInput,
+  NodeFlowPublicationRecord,
   NodeFlowRecord,
   NodeFlowRunListResponse,
   NodeFlowRunRecord,
@@ -497,6 +512,7 @@ export type {
   NodeWidgetSchema,
   NodeWidgetSelectOption,
   UpdateNodeFlowInput,
+  NodeDefinitionManifest,
 };
 
 export type { SprintReviewSummary };
diff --git a/docs/dashboard/feature-flags.md b/docs/dashboard/feature-flags.md
index e79384693e..50bfefa59e 100644
--- a/docs/dashboard/feature-flags.md
+++ b/docs/dashboard/feature-flags.md
@@ -14,10 +14,10 @@ Supported values are `true`, `1`, `yes`, `on`, `enabled`, `false`, `0`, `no`, `o
 
 | Feature | Env variable | Development default | Production default | Scope |
 | --- | --- | --- | --- | --- |
-| `nodes` | `VITE_CODEUX_FEATURE_NODES` | enabled | disabled | Hides the unfinished `/nodes` surface from route registration, shared navigation, route prefetch, and the guided dashboard tour. |
+| `nodes` | `VITE_CODEUX_FEATURE_NODES` | enabled | disabled | Requires `VITE_CODEUX_NODE_FLOW_BACKEND` and `VITE_CODEUX_AUTOMATION_SECURITY` to also be enabled in production. |
 | `custom-dashboards` | `VITE_CODEUX_FEATURE_CUSTOM_DASHBOARDS` | enabled | disabled | Hides the unfinished `/custom-dashboards` surface from route registration, shared navigation, route prefetch, and the guided dashboard tour. |
 
-When a feature is disabled in a production build, its page module remains in source for local development and tests, but the route is not added to the TanStack route tree. Direct navigation falls through to the dashboard not-found route.
+When Nodes or either production prerequisite is disabled, its route is omitted from the route tree, navigation, and route prefetch. Development keeps the surface reachable for local integration testing.
 
 ## Adding a Flag
 
diff --git a/docs/dashboard/node-flows.md b/docs/dashboard/node-flows.md
index 3c78d9d122..69701d85ac 100644
--- a/docs/dashboard/node-flows.md
+++ b/docs/dashboard/node-flows.md
@@ -1,97 +1,25 @@
 # Node Flows Dashboard
 
-The **Nodes** page (`/nodes`) is the dashboard surface for creating, editing, validating, running, scheduling, and attaching project node flows. It is project-scoped: no project means no flow library, no agent attachments, and no run history.
+The **Nodes** page (`/nodes`) is the project-scoped authoring and operations surface for canonical node flows. No selected project means no flow library, credentials, publications, or run history are requested.
 
-For the shorter page contract, see [Nodes](./nodes.md). For persistence and runtime details, see [Node Flows](../architecture/node-flows.md).
+## Library and drafts
 
-## Flow Library
+The library loads through `GET /api/projects/:projectId/node-flows`. Drafts are created through `POST /api/projects/:projectId/node-flow-drafts` and saved through revision-checked `PATCH /api/node-flow-drafts/:flowId`. A stale revision produces a visible conflict and never overwrites newer work.
 
-When a project is selected, the page loads saved flows from `GET /api/projects/:projectId/node-flows`. The library shows the current flow title, description, version, node count, edge count, and update recency. Selecting a flow opens a local draft for the canvas and inspector.
+The former browser canvas is eligible for one project-specific import. After a successful backend draft creation, its graph value is removed and a migration marker prevents duplicates. Browser storage is never used for ongoing persistence.
 
-Create and update operations write through the node-flow HTTP routes and increment the saved version on update. Deleting a flow removes the current flow, versions, attachments, and run rows through database cascade behavior.
+## Registry and credentials
 
-## Canvas Editing
+`GET /api/node-flow-catalog` is the T01 source for palette entries, typed ports, widget schemas, execution availability, capabilities, side effects, policies, and credential requirements. Selecting a definition loads its full versioned manifest. Graphs reference a definition version and do not contain custom-node source.
 
-The editor manages the draft graph in the dashboard before saving:
+The inspector displays credential slots as bound, missing, or denied and can request a binding. It displays credential metadata only; secret values never enter the graph or dashboard output.
 
-- nodes have stable ids, titles, types, positions, and JSON `data`
-- edges connect `fromNodeId` to `toNodeId`
-- node selection is keyboard-focusable and labeled for assistive technology
-- pointer movement edits node positions without adding a graph-rendering dependency
-- unsaved draft state is shown separately from validation state
+## Governance and publication
 
-Editable node-canvas work that has not yet been persisted through the node-flow API should use the pure state helpers in `dashboard/src/v2/lib/nodes-canvas-state.ts`. That module defines typed canvas nodes, input and output ports, port-connected edges, config fields, selection state, reducer actions, deterministic layout, JSON serialization recovery, and the starter trigger -> agent -> task -> condition -> output graph. It is UI-free so canvas, inspector, and import surfaces can share one deterministic graph foundation.
+T06 draft endpoints provide structural validation, policy findings, requested permissions, side-effect review, dry runs, immutable publication, version comparison, and rollback. Dry runs never execute nodes. Only a valid draft with satisfied required credentials can publish, and only published versions execute.
 
-Autonomous graph editing should use `dashboard/src/v2/lib/nodes-agent-surface.ts` instead of driving the UI. The agent surface accepts structured JSON commands for `add_node`, `patch_node`, `connect_ports`, `delete_entities`, `select_entities`, and `replace_graph`; applies them through the reducer; returns graph validation issues; and exposes deterministic summary and diff helpers for review loops.
+## Run debugger and scheduling
 
-The `/nodes` side-panel components use that same state contract without owning global state. `NodePalette`
-emits typed `add_node` actions for trigger, agent, task, condition, and output templates. `NodeInspector`
-renders node and edge selection details, controlled edits for label, description, metadata intents, config
-fields, and enabled state, plus `NodePortList` wiring hints. `NodeValidationPanel` runs
-`validateNodeCanvasGraph`, groups issues by affected entity, and exposes select/focus callbacks for the
-canvas shell.
+The debugger reads persisted runs, node runs, and attempt history. It overlays node state, shows retry reasons and decisions, links invocation ids, reports timing, supports cancellation and safe retry, and redacts secret-shaped values before rendering. Scheduling is entered through `/scheduler`; scheduler execution also resolves published versions.
 
-The canvas is intentionally Code UX-specific. It should not present imported n8n workflows as if every external node type can run locally.
-
-## Dynamic Widget Inspector
-
-The inspector renders each selected node's `widgetSchema` fields and writes values into the node's JSON data:
-
-| Widget type | Dashboard behavior |
-| --- | --- |
-| `text` / `textarea` | Plain string input. |
-| `number` | Finite numeric input, respecting optional min/max/step where present. |
-| `boolean` | Toggle or checkbox-style boolean control. |
-| `select` | Choice from declared options. |
-| `json` | JSON value parsed before save or run input submission. |
-| `secretRef` | Reference string only, not a raw secret value. |
-| `keyValue` | Object with string values. |
-
-Graph-level `inputSchema` describes manual and scheduled run input. Per-node widget schemas describe editable node configuration. Secret-bearing values should be represented as stable references that runtime services resolve elsewhere, not as inline credentials.
-
-## Validation States
-
-Validation posts the draft graph to `POST /api/node-flows/:flowId/validate`. The backend returns `valid`, `errors` with `field`, `code`, and `message`, and a normalized `graph` plus `executionOrder` when valid.
-
-The page surfaces field-level issues without saving. A graph can be structurally valid and still contain node types that the runtime cannot execute; runtime-supported node types are documented in [Node Flows](../architecture/node-flows.md#runtime).
-
-## Manual Run Panel
-
-The run panel accepts JSON object input and calls `POST /api/node-flows/:flowId/run` with `projectId`, `input`, and optional trigger metadata. Blank input is treated as `{}`. Invalid JSON is rejected before submission.
-
-Run history is read through:
-
-- `GET /api/node-flows/:flowId/runs`
-- `GET /api/node-flow-runs/:runId`
-- `GET /api/node-flow-runs/:runId/node-runs`
-
-The panel displays flow status, node status, linked execution invocation ids when present, error messages, and redacted JSON output. Secret-shaped keys are masked before display.
-
-## Agent Attachment
-
-The inspector can attach the selected flow to project agent presets through:
-
-- `GET /api/node-flows/:flowId/agent-skills`
-- `POST /api/node-flows/:flowId/agent-skills`
-- `DELETE /api/node-flows/:flowId/agent-skills`
-
-Attachment exposes the flow as a repeatable agent skill with a skill name and description. Detaching removes only the binding for that agent; it does not delete the flow or its run history.
-
-## Scheduling
-
-Operators can schedule a saved node flow from the Scheduler page. The scheduler form selects a project-owned flow and accepts optional JSON object input. Recurrence, pause/resume, failure status, and due-run behavior follow the scheduler contract in [Scheduler](./scheduler.md#node-flow-schedules).
-
-## Responsive And Accessibility Expectations
-
-Nodes must stay usable on desktop and mobile:
-
-- the library, canvas, inspector, run panel, and attachment controls must reflow without overlapping text or controls
-- selection, validation, save, run, attach, detach, pause, and destructive actions must be keyboard reachable
-- icon-only controls need accessible labels
-- validation and run errors must be text, not color-only
-- focus order should follow library -> canvas -> inspector -> run/attachment panels
-- JSON editors and textareas should preserve visible labels and error messages on small screens
-
-## Graph v2 boundary
-
-The dashboard edits the shared Graph v2 contract rather than owning a second execution model. A graph is executable only when every node resolves to `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, or `output`. Planning palette concepts are not runtime handlers.
+The layout stacks on small screens, preserves keyboard-visible focus, labels loading/error/empty states, and bounds long histories and JSON output with scrolling.
diff --git a/docs/dashboard/nodes-canvas.md b/docs/dashboard/nodes-canvas.md
index 7d44194533..6d906e6db2 100644
--- a/docs/dashboard/nodes-canvas.md
+++ b/docs/dashboard/nodes-canvas.md
@@ -1,79 +1,17 @@
-# Nodes Canvas
+# Nodes Automation Workspace
 
-The **Nodes Canvas** page (`/nodes`) is a browser-local workspace for drafting Code UX workflow graphs. It composes the in-house node canvas, palette, inspector, validation panel, and agent command helpers without calling backend APIs or writing to the database.
+The **Nodes** page (`/nodes`) is a project-scoped automation workspace backed by the canonical node-flow repository. Browser storage is not a workflow database and edits are never auto-saved locally.
 
-This page is a draft and exchange surface. It does not synchronize graphs to projects, execute n8n workflows, or run node flows through the Code UX runtime.
+## Legacy canvas import
 
-## Local persistence
+On the first load for a selected project, the dashboard checks the former `codeux:nodes-canvas:v1` key. When present, it normalizes the payload to Graph v2, creates an **Imported Nodes Canvas** backend draft, records a project-specific migration marker, and removes the legacy graph value. A failed import leaves the value available for retry. The marker prevents duplicates.
 
-The page saves the current graph to browser `localStorage` under:
+## Governed editing
 
-```text
-codeux:nodes-canvas:v1
-```
+The T01 registry supplies executable state, typed ports, widget schemas, capabilities, credential slots, side-effect classification, and default policy. The graph stores only a type/version reference and configuration; it never stores custom source or credential values.
 
-The stored value is the deterministic JSON produced by `serializeNodeCanvasGraph`. Reloading `/nodes` restores that graph when it can be parsed through the same canvas contract. Malformed persisted data falls back to the starter graph.
+Draft saves use `draftRevision`. A concurrent update returns a visible conflict. Validation, policy findings, credential status, dry runs, publication, version comparison, and rollback use the T06 draft APIs.
 
-The enabled switch in the inspector is an editing-session flag only. It is not part of the persisted graph contract.
+## Operations
 
-## Node types
-
-The palette creates five node templates:
-
-| Type | Purpose |
-| --- | --- |
-| `trigger` | Starts the graph from a manual or scheduled event source. |
-| `agent` | Routes downstream work to a planning, implementation, review, or QA agent intent. |
-| `task` | Captures a concrete task prompt and task intent. |
-| `condition` | Branches based on an expression such as a validation result. |
-| `output` | Collects the final graph result. |
-
-Each node has stable input and output ports, editable labels and descriptions, typed config fields, metadata intents where applicable, and a fixed canvas position.
-
-## Validation behavior
-
-The page runs `validateNodeCanvasGraph` after every graph change. Validation is local and structural. It checks for:
-
-- duplicate node ids
-- missing edge source or target nodes
-- missing edge source or target ports
-- self-connections
-- input/output direction mismatches
-- incompatible port types
-- empty required labels or config values
-- invalid agent or task intent metadata
-
-The status strip reports the current issue count. The validation panel groups issues by affected node or edge and exposes select/focus actions so operators can move directly to the problem entity. Validation errors do not prevent export; invalid imported graphs can be loaded when the JSON shape is valid so users can repair them on the canvas.
-
-## Import and export format
-
-`Export JSON` writes the current serialized graph into the exchange textarea. The JSON contains:
-
-- `nodes`: node ids, kinds, labels, descriptions, positions, ports, config fields, and metadata
-- `edges`: edge ids plus source and target node/port endpoints
-- `selection`: selected node and edge ids
-
-`Import JSON` routes the textarea content through the agent helper `replace_graph` command. Invalid JSON leaves the current graph unchanged and reports a live error. Valid JSON is normalized before it replaces the canvas and is immediately revalidated.
-
-## Agent command surface
-
-Agents should use `dashboard/src/v2/lib/nodes-agent-surface.ts` instead of driving the UI. The supported command names are:
-
-- `add_node`
-- `patch_node`
-- `connect_ports`
-- `delete_entities`
-- `select_entities`
-- `replace_graph`
-
-The page displays the deterministic `buildNodeCanvasAgentSummary` output so agents can inspect node counts, edge counts, selected ids, ports, config values, and validation blockers in a command-friendly shape. Import uses the same command path, so autonomous graph changes and human JSON exchange share reducer-backed normalization and validation.
-
-## Empty, reset, and no-selection states
-
-`Clear` replaces the graph with an empty canvas. The canvas and inspector show empty/no-selection states, while the palette remains available for recovery. `Reset` restores the starter trigger -> agent -> task -> condition -> output graph and refreshes the exchange JSON.
-
-The page uses responsive grid columns that collapse into a single column at smaller widths so the palette, canvas, inspector, validation panel, and JSON exchange controls remain reachable without overlapping.
-
-## Graph v2 migration
-
-Serialization writes `schemaVersion: 2`. Importing a legacy browser v1 value deterministically normalizes it and retains the untouched snapshot separately. Trigger, agent, task, condition, and output palette entries are planning concepts; executable definitions are limited to `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output`.
+Only published versions run. The debugger shows redacted run output, graph and node states, attempts, retry classifications and decisions, invocation links, timing, cancellation, and safe retry controls. Scheduling is entered through the Scheduler page.
diff --git a/tests/dashboard/lib/dashboard-feature-flags.test.ts b/tests/dashboard/lib/dashboard-feature-flags.test.ts
index 473b809394..8898fe080b 100644
--- a/tests/dashboard/lib/dashboard-feature-flags.test.ts
+++ b/tests/dashboard/lib/dashboard-feature-flags.test.ts
@@ -59,7 +59,8 @@ describe("dashboard feature flags", () => {
   });
 
   it("honors explicit values outside development mode", () => {
-    expect(resolveDashboardFeatureFlags({ devMode: false, values: { nodes: "true", "custom-dashboards": "enabled" } })).toEqual({ nodes: true, "custom-dashboards": true });
+    expect(resolveDashboardFeatureFlags({ devMode: false, values: { nodes: "true", "custom-dashboards": "enabled" }, prerequisites: { nodeFlowBackend: "enabled", automationSecurity: "enabled" } })).toEqual({ nodes: true, "custom-dashboards": true });
+    expect(resolveDashboardFeatureFlags({ devMode: false, values: { nodes: "true" }, prerequisites: { nodeFlowBackend: "enabled", automationSecurity: "off" } }).nodes).toBe(false);
     expect(resolveDashboardFeatureFlags({ devMode: false, values: { nodes: "false", "custom-dashboards": "off" } })).toEqual({ nodes: false, "custom-dashboards": false });
   });
 
diff --git a/tests/dashboard/v2/node-flow-page.test.tsx b/tests/dashboard/v2/node-flow-page.test.tsx
index ee77f4088c..1a7b412960 100644
--- a/tests/dashboard/v2/node-flow-page.test.tsx
+++ b/tests/dashboard/v2/node-flow-page.test.tsx
@@ -5,45 +5,18 @@ import { cleanup, render, screen } from "@testing-library/preact";
 import "@testing-library/jest-dom/vitest";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { NodesPage } from "../../../dashboard/src/v2/NodesPage.js";
+import { ProjectDataContext } from "../../../dashboard/src/v2/context/project-data.js";
 
-vi.mock("../../../dashboard/src/v2/hooks/use-reduced-motion.js", () => ({
-  useReducedMotion: () => true,
-  useResolvedMotionDuration: <T,>(duration: T): T => duration,
-}));
+vi.mock("../../../dashboard/src/v2/hooks/use-reduced-motion.js", () => ({ useReducedMotion: () => true, useResolvedMotionDuration: <T,>(value: T): T => value }));
+vi.mock("../../../dashboard/src/v2/lib/motion/index.js", () => ({ useInteractionTokens: () => ({ controlFeedback: { duration: "0ms", ease: "linear" }, enterExit: { duration: "0ms", ease: "linear" }, selectionMovement: { duration: "0ms", ease: "linear" } }), useGsapInteractionTokens: () => ({ controlFeedback: { duration: 0, ease: "linear" }, enterExit: { duration: 0, ease: "linear" }, inlineValidation: { duration: 0, ease: "linear" }, selectionMovement: { duration: 0, ease: "linear" } }) }));
 
-vi.mock("../../../dashboard/src/v2/lib/motion/index.js", () => ({
-  useInteractionTokens: () => ({
-    controlFeedback: { duration: "0ms", ease: "linear" },
-    enterExit: { duration: "0ms", ease: "linear" },
-    selectionMovement: { duration: "0ms", ease: "linear" },
-  }),
-  useGsapInteractionTokens: () => ({
-    controlFeedback: { duration: 0, ease: "linear" },
-    enterExit: { duration: 0, ease: "linear" },
-    inlineValidation: { duration: 0, ease: "linear" },
-    selectionMovement: { duration: 0, ease: "linear" },
-  }),
-}));
+afterEach(cleanup);
 
-class TestResizeObserver {
-  observe(): void {}
-  unobserve(): void {}
-  disconnect(): void {}
-}
-
-globalThis.ResizeObserver = TestResizeObserver;
-
-afterEach(() => {
-  cleanup();
-  window.localStorage.clear();
-});
-
-describe("NodesPage legacy node-flow route coverage", () => {
-  it("renders the local nodes canvas instead of backend-backed flow management", () => {
-    render(<NodesPage />);
-
-    expect(screen.getByRole("heading", { name: "Nodes Canvas" })).toBeInTheDocument();
-    expect(screen.getByText(/Compose local workflow graphs/i)).toBeInTheDocument();
-    expect(screen.getByRole("application", { name: "Node canvas" })).toBeInTheDocument();
+describe("NodesPage project boundary", () => {
+  it("requires a selected project before loading governed flows", () => {
+    render(<ProjectDataContext.Provider value={{ projects: [], selectedProjectId: null, selectedProject: null, loading: false, error: null, refreshProjects: async () => undefined, selectProject: async () => undefined, createProject: async () => { throw new Error("unused"); }, updateProject: async () => { throw new Error("unused"); }, deleteProject: async () => undefined }}><NodesPage /></ProjectDataContext.Provider>);
+    expect(screen.getByRole("heading", { name: "Automation workspace" })).toBeInTheDocument();
+    expect(screen.getByText("Select a project")).toBeInTheDocument();
+    expect(screen.queryByText("Node catalog")).not.toBeInTheDocument();
   });
 });
diff --git a/tests/dashboard/v2/nodes-inspector.test.tsx b/tests/dashboard/v2/nodes-inspector.test.tsx
index 61331b9470..61ca404121 100644
--- a/tests/dashboard/v2/nodes-inspector.test.tsx
+++ b/tests/dashboard/v2/nodes-inspector.test.tsx
@@ -49,26 +49,16 @@ const renderInspector = (node: NodeCanvasNode | null, graph = createInitialNodeC
 };
 
 describe("nodes inspector panels", () => {
-  it("emits typed add-node actions from the palette", async () => {
+  it("emits governed registry definitions from the palette", async () => {
     const user = userEvent.setup();
     const onCreateNode = vi.fn();
 
-    render(<NodePalette onCreateNode={onCreateNode} />);
+    const definitions = [{ type: "output", version: 1, executable: true, executionKind: "local" as const, label: "Output", description: "Return output", category: "Core", credentials: [], capabilities: [], sideEffect: "none" as const, ports: [] }];
+    render(<NodePalette definitions={definitions} onCreateNode={onCreateNode} />);
 
-    await user.click(screen.getByRole("button", { name: "Add Agent node" }));
     await user.click(screen.getByRole("button", { name: "Add Output node" }));
 
-    expect(onCreateNode).toHaveBeenNthCalledWith(1, {
-      type: "add_node",
-      kind: "agent",
-      label: "Agent Node",
-      metadata: { agentIntent: "implement" },
-    });
-    expect(onCreateNode).toHaveBeenNthCalledWith(2, {
-      type: "add_node",
-      kind: "output",
-      label: "Output Node",
-    });
+    expect(onCreateNode).toHaveBeenCalledWith(definitions[0]);
   });
 
   it("renders an accessible empty-selection state", () => {
diff --git a/tests/dashboard/v2/nodes-page.test.tsx b/tests/dashboard/v2/nodes-page.test.tsx
index 033fff2ea3..f3c48eb3e8 100644
--- a/tests/dashboard/v2/nodes-page.test.tsx
+++ b/tests/dashboard/v2/nodes-page.test.tsx
@@ -1,165 +1,51 @@
 /** @vitest-environment jsdom */
 /** @jsx h */
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-import { h, type ComponentChildren } from "preact";
-import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/preact";
+import { h } from "preact";
+import { cleanup, render, screen, waitFor } from "@testing-library/preact";
 import userEvent from "@testing-library/user-event";
 import "@testing-library/jest-dom/vitest";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import {
-  NODES_CANVAS_STORAGE_KEY,
-  NodesPage,
-} from "../../../dashboard/src/v2/NodesPage.js";
-import {
-  ALL_NAVIGATION_ITEMS,
-  isRouteNavigationItem,
-} from "../../../dashboard/src/v2/lib/navigation-items.js";
-
-vi.mock("../../../dashboard/src/v2/hooks/use-reduced-motion.js", () => ({
-  useReducedMotion: () => true,
-  useResolvedMotionDuration: <T,>(duration: T): T => duration,
-}));
-
-vi.mock("../../../dashboard/src/v2/lib/motion/index.js", () => ({
-  useAnimatedActiveIndicator: () => ({ style: {} }),
-  useGsapInteractionTokens: () => ({
-    controlFeedback: { duration: 0, ease: "linear" },
-    enterExit: { duration: 0, ease: "linear" },
-    inlineValidation: { duration: 0, ease: "linear" },
-    selectionMovement: { duration: 0, ease: "linear" },
-  }),
-  useInteractionTokens: () => ({
-    controlFeedback: { duration: "0ms", ease: "linear" },
-    enterExit: { duration: "0ms", ease: "linear" },
-    selectionMovement: { duration: "0ms", ease: "linear" },
-  }),
-}));
-
-vi.mock("../../../dashboard/src/v2/components/ui/Tooltip.js", () => ({
-  Tooltip: ({ children }: { children: ComponentChildren }) => <>{children}</>,
-}));
-
-class TestResizeObserver {
-  observe(): void {}
-  unobserve(): void {}
-  disconnect(): void {}
-}
-
-globalThis.ResizeObserver = TestResizeObserver;
-HTMLElement.prototype.setPointerCapture = vi.fn();
-HTMLElement.prototype.releasePointerCapture = vi.fn();
-
-const mainSource = readFileSync(join(process.cwd(), "dashboard/src/main.tsx"), "utf8");
-const prefetchSource = readFileSync(join(process.cwd(), "dashboard/src/v2/router/route-prefetch.ts"), "utf8");
-
-describe("NodesPage", () => {
-  beforeEach(() => {
-    window.localStorage.clear();
-  });
-
-  afterEach(() => {
-    cleanup();
-    window.localStorage.clear();
-    vi.clearAllMocks();
-  });
-
-  it("renders the composed local canvas workspace", () => {
-    render(<NodesPage />);
-
-    expect(screen.getByRole("heading", { name: "Nodes Canvas" })).toBeInTheDocument();
-    expect(screen.getByRole("application", { name: "Node canvas" })).toBeInTheDocument();
-    expect(screen.getByRole("heading", { name: "Add nodes" })).toBeInTheDocument();
-    expect(screen.getByRole("heading", { name: "Project Trigger" })).toBeInTheDocument();
-    expect(screen.getByRole("heading", { name: "Ready to wire" })).toBeInTheDocument();
-    expect(screen.getByRole("heading", { name: "Graph JSON" })).toBeInTheDocument();
-    expect(screen.getByRole("heading", { name: "Command metadata" })).toBeInTheDocument();
-    expect(screen.getByText(/codeux:nodes-canvas:v1/i)).toBeInTheDocument();
-  });
-
-  it("exercises node selection and inspector editing through reducer-backed state", async () => {
-    const user = userEvent.setup();
-    render(<NodesPage />);
-
-    await user.click(screen.getByRole("button", { name: /Task Draft task node/i }));
-    expect(screen.getByRole("heading", { name: "Task Draft" })).toBeInTheDocument();
-
-    fireEvent.input(screen.getByLabelText("Label"), { target: { value: "Implementation Task" } });
-
-    expect(screen.getByRole("heading", { name: "Implementation Task" })).toBeInTheDocument();
-    expect(screen.getByRole("button", { name: /Implementation Task task node/i })).toBeInTheDocument();
-  });
-
-  it("persists graph changes to localStorage and restores them on the next render", async () => {
-    const { unmount } = render(<NodesPage />);
-
-    fireEvent.input(screen.getByLabelText("Label"), { target: { value: "Manual Launch" } });
-
-    await waitFor(() => {
-      expect(window.localStorage.getItem(NODES_CANVAS_STORAGE_KEY)).toContain("Manual Launch");
-    });
-
-    unmount();
-    cleanup();
-    render(<NodesPage />);
-
-    expect(screen.getByDisplayValue("Manual Launch")).toBeInTheDocument();
-    expect(screen.getByRole("button", { name: /Manual Launch trigger node/i })).toBeInTheDocument();
-  });
-
-  it("handles invalid import JSON without replacing the current graph", async () => {
-    const user = userEvent.setup();
-    render(<NodesPage />);
-
-    fireEvent.input(screen.getByLabelText("Import or exported graph"), { target: { value: "not-json" } });
-    await user.click(screen.getByRole("button", { name: /^Import$/i }));
-
-    expect(screen.getByText("Serialized graph must be valid JSON.")).toBeInTheDocument();
-    expect(screen.getByRole("button", { name: /Project Trigger trigger node/i })).toBeInTheDocument();
-  });
-
-  it("supports clear and reset states without losing palette recovery", async () => {
-    const user = userEvent.setup();
-    render(<NodesPage />);
-
-    await user.click(screen.getByRole("button", { name: "Clear" }));
-    expect(screen.getByRole("region", { name: "Empty node canvas" })).toBeInTheDocument();
-    expect(screen.getByRole("heading", { name: "Nothing selected" })).toBeInTheDocument();
-
-    await user.click(screen.getByRole("button", { name: "Add Agent node" }));
-    expect(screen.getByRole("button", { name: /Agent Node agent node/i })).toBeInTheDocument();
-
-    await user.click(screen.getByRole("button", { name: "Reset" }));
-    expect(screen.getByRole("button", { name: /Project Trigger trigger node/i })).toBeInTheDocument();
-  });
-
-  it("feature-gates unfinished route registration and prefetch while keeping shared metadata", () => {
-    expect(mainSource).toContain('import("./v2/NodesPage.js")');
-    expect(mainSource).toContain('path: "/nodes"');
-    expect(mainSource).toContain('...(nodesFeatureEnabled ? [nodesRoute] : [])');
-    expect(prefetchSource).toContain('"/nodes": { importer: () => import("../NodesPage.js"), feature: "nodes" }');
-    expect(prefetchSource).toContain("canPrefetchRoute(path)");
-    expect(mainSource).toContain('import("./v2/CustomDashboardsPage.js")');
-    expect(mainSource).toContain('path: "/custom-dashboards"');
-    expect(mainSource).toContain('...(customDashboardsFeatureEnabled ? [customDashboardsRoute] : [])');
-    expect(prefetchSource).toContain('"/custom-dashboards": { importer: () => import("../CustomDashboardsPage.js"), feature: "custom-dashboards" }');
-
-    const navItem = ALL_NAVIGATION_ITEMS.find((item) => item.id === "nodes");
-    expect(navItem).toBeDefined();
-    expect(navItem && isRouteNavigationItem(navItem)).toBe(true);
-    if (navItem && isRouteNavigationItem(navItem)) {
-      expect(navItem.path).toBe("/nodes");
-      expect(navItem.group).toBe("workspace");
-      expect(navItem.dockSection).toBe("right");
-    }
-
-    const customDashboardsNavItem = ALL_NAVIGATION_ITEMS.find((item) => item.id === "custom-dashboards");
-    expect(customDashboardsNavItem).toBeDefined();
-    expect(customDashboardsNavItem && isRouteNavigationItem(customDashboardsNavItem)).toBe(true);
-    if (customDashboardsNavItem && isRouteNavigationItem(customDashboardsNavItem)) {
-      expect(customDashboardsNavItem.path).toBe("/custom-dashboards");
-      expect(customDashboardsNavItem.group).toBe("workspace");
-      expect(customDashboardsNavItem.dockSection).toBe("right");
-    }
+import { NODES_CANVAS_STORAGE_KEY, NodesPage } from "../../../dashboard/src/v2/NodesPage.js";
+import { ProjectDataContext } from "../../../dashboard/src/v2/context/project-data.js";
+
+const api = vi.hoisted(() => ({ fetchNodeFlows: vi.fn(), fetchNodeFlowCatalog: vi.fn(), createNodeFlowDraft: vi.fn(), fetchNodeFlow: vi.fn(), fetchNodeFlowRuns: vi.fn(), fetchNodeFlowNodeRuns: vi.fn(), fetchNodeFlowAttempts: vi.fn(), patchNodeFlowDraft: vi.fn(), fetchNodeDefinition: vi.fn(), validateNodeFlowDraft: vi.fn(), deleteNodeFlow: vi.fn() }));
+vi.mock("../../../dashboard/src/v2/lib/node-flow-api.js", async (original) => ({ ...(await original()), ...api }));
+vi.mock("../../../dashboard/src/v2/hooks/use-reduced-motion.js", () => ({ useReducedMotion: () => true, useResolvedMotionDuration: <T,>(value: T): T => value }));
+
+const flow = { id: "flow-1", projectId: "project-1", title: "Release automation", description: "Governed", graph: { schemaVersion: 2 as const, nodes: [{ id: "input-1", type: "input", title: "Input", definition: { type: "input", version: 1 }, position: { x: 40, y: 40 } }], edges: [] }, version: 2, createdAt: "2026-01-01T00:00:00.000Z", updatedAt: "2026-01-01T00:00:00.000Z" };
+const context = { projects: [{ id: "project-1", name: "Test project" }], selectedProjectId: "project-1", selectedProject: { id: "project-1", name: "Test project" }, loading: false, error: null, refreshProjects: async () => undefined, selectProject: async () => undefined, createProject: async () => { throw new Error("unused"); }, updateProject: async () => { throw new Error("unused"); }, deleteProject: async () => undefined };
+
+describe("NodesPage governed workspace", () => {
+  const review = { flowId: "flow-1", projectId: "project-1", name: "Release automation", description: "Governed", draftRevision: 2, nodeCount: 1, edgeCount: 0, valid: true, validationIssues: [], policyFindings: [], requiredCredentials: [], requestedCapabilities: [], sideEffectDiffs: [], publishedVersion: 1 };
+  beforeEach(() => { api.validateNodeFlowDraft.mockResolvedValue(review); });
+  beforeEach(() => { window.localStorage.clear(); api.fetchNodeFlows.mockResolvedValue({ flows: [flow] }); api.fetchNodeFlowCatalog.mockResolvedValue({ nodes: [{ type: "input", version: 1, executable: true, executionKind: "local", label: "Input", description: "Input", category: "Core", credentials: [], capabilities: [], sideEffect: "none", ports: [] }] }); api.fetchNodeFlowRuns.mockResolvedValue({ runs: [] }); api.fetchNodeFlowNodeRuns.mockResolvedValue({ nodeRuns: [] }); api.fetchNodeFlowAttempts.mockResolvedValue({ attempts: [] }); api.fetchNodeDefinition.mockResolvedValue({ type: "input", version: 1, executable: true, executionKind: "local", configurationSchema: { type: "object" }, ui: { label: "Input", description: "Input", category: "Core", widgetSchema: { fields: [] } }, ports: [], credentials: [], capabilities: [], sideEffect: "none", defaultPolicy: {}, documentation: "", deprecation: { deprecated: false } }); });
+  afterEach(() => { cleanup(); vi.clearAllMocks(); });
+
+  it("loads a project flow library and registry-backed editor", async () => {
+    render(<ProjectDataContext.Provider value={context as never}><NodesPage /></ProjectDataContext.Provider>);
+    expect(await screen.findByRole("heading", { name: "Automation workspace" })).toBeInTheDocument();
+    expect(await screen.findByText("Release automation")).toBeInTheDocument();
+    expect(screen.getByRole("heading", { name: "Node catalog" })).toBeInTheDocument();
+    expect(screen.getByText("Run debugger")).toBeInTheDocument();
+    expect(api.fetchNodeFlows).toHaveBeenCalledWith("project-1", expect.any(AbortSignal));
+  });
+
+  it("imports legacy localStorage once and removes it as a source of truth", async () => {
+    window.localStorage.setItem(NODES_CANVAS_STORAGE_KEY, JSON.stringify({ schemaVersion: 2, nodes: [{ id: "input-1", type: "input", title: "Input", position: { x: 1, y: 1 } }], edges: [] }));
+    api.createNodeFlowDraft.mockResolvedValue({ flowId: "imported", draftRevision: 1 });
+    api.fetchNodeFlows.mockResolvedValueOnce({ flows: [] }).mockResolvedValueOnce({ flows: [flow] });
+    render(<ProjectDataContext.Provider value={context as never}><NodesPage /></ProjectDataContext.Provider>);
+    await waitFor(() => expect(api.createNodeFlowDraft).toHaveBeenCalledTimes(1));
+    expect(window.localStorage.getItem(NODES_CANVAS_STORAGE_KEY)).toBeNull();
+    expect(window.localStorage.getItem("codeux:nodes-canvas:imported:project-1")).toBe("imported");
+  });
+
+  it("surfaces optimistic save conflicts", async () => {
+    const user = userEvent.setup(); api.patchNodeFlowDraft.mockResolvedValue({ conflict: { message: "The draft changed after it was read; reload the summary and reapply the patch.", actualDraftRevision: 3 } });
+    render(<ProjectDataContext.Provider value={context as never}><NodesPage /></ProjectDataContext.Provider>);
+    await screen.findByText("Release automation");
+    await user.type(screen.getAllByLabelText("Description")[0]!, " changed");
+    await user.click(screen.getByRole("button", { name: "Save draft" }));
+    expect(await screen.findByRole("alert")).toHaveTextContent("Current revision is 3");
   });
 });

From baa834eaf0515512c59329e522f10445f00f3375 Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 07:09:28 +0000
Subject: [PATCH 08/25] feat(task T08): implement via codex

---
 .../node-flow-durable-execution.md            |   2 +
 docs-web/architecture/system-overview.md      |   2 +
 ...chitecture-node-flow-durable-execution.mdx |   2 +
 .../docs/architecture-system-overview.mdx     |   2 +
 docs-web/content/docs/operations-runbook.mdx  |  12 +
 .../docs/operations-security-hardening.mdx    |   9 +
 .../content/docs/operations-server-mode.mdx   |  27 +++
 docs-web/content/docs/registry.ts             |  27 +++
 docs-web/operations/runbook.md                |  12 +
 docs-web/operations/security-hardening.md     |   9 +
 docs-web/operations/server-mode.md            |  27 +++
 .../routes/docs.operations-runbook.lazy.tsx   |  11 +
 ...ocs.operations-security-hardening.lazy.tsx |  11 +
 .../docs.operations-server-mode.lazy.tsx      |  11 +
 docs/SUMMARY.md                               |   2 +-
 .../node-flow-durable-execution.md            |   6 +
 docs/architecture/system-overview.md          |   8 +
 docs/index.md                                 |   2 +-
 docs/operations/runbook.md                    |  15 ++
 docs/operations/security-hardening.md         |  10 +
 docs/operations/server-mode.md                |  41 +++-
 src/app/dependency-factory/core-factory.ts    |  34 ++-
 .../dependency-factory/dashboard-factory.ts   |  13 +-
 .../lifecycle/dashboard-lifecycle-service.ts  |  12 +
 src/contracts/headless-security-types.ts      |  84 +++++++
 .../automation-credential-repository.ts       |   5 +
 src/repositories/db/app-db-migrations.ts      |  22 ++
 src/server/code-ux-server.ts                  |  17 ++
 src/server/dashboard-middleware.ts            |  73 ++++++
 src/server/dashboard-route-registration.ts    |   2 +
 src/server/dashboard-server.ts                |  25 +-
 src/server/headless-operations-routes.ts      |  40 ++++
 .../automation-audit-export-service.ts        | 146 ++++++++++++
 src/services/automation-slo-service.ts        |  39 ++++
 src/services/credentials/credential-broker.ts |   7 +-
 .../distributed-node-flow-runner-service.ts   |  52 +++++
 src/services/headless-auth-service.ts         | 214 ++++++++++++++++++
 .../headless-operational-readiness-service.ts |  70 ++++++
 src/services/node-flow-runtime-service.ts     |   6 +
 src/services/node-flows/approval-service.ts   |  12 +-
 src/services/node-flows/outbox-service.ts     |  11 +-
 src/worker/index.ts                           |   1 +
 src/worker/worker-config.ts                   |   4 +
 .../server/headless-dashboard-auth.test.ts    |  85 +++++++
 .../credentialed-automation-e2e.test.ts       | 186 +++++++++++++++
 .../headless-automation-operations.test.ts    | 135 +++++++++++
 tests/backend/worker/worker-config.test.ts    |  10 +
 .../fixtures/headless-automation-records.json |  22 ++
 48 files changed, 1556 insertions(+), 19 deletions(-)
 create mode 100644 docs-web/content/docs/operations-runbook.mdx
 create mode 100644 docs-web/content/docs/operations-security-hardening.mdx
 create mode 100644 docs-web/content/docs/operations-server-mode.mdx
 create mode 100644 docs-web/operations/runbook.md
 create mode 100644 docs-web/operations/security-hardening.md
 create mode 100644 docs-web/operations/server-mode.md
 create mode 100644 docs-web/routes/docs.operations-runbook.lazy.tsx
 create mode 100644 docs-web/routes/docs.operations-security-hardening.lazy.tsx
 create mode 100644 docs-web/routes/docs.operations-server-mode.lazy.tsx
 create mode 100644 src/contracts/headless-security-types.ts
 create mode 100644 src/server/headless-operations-routes.ts
 create mode 100644 src/services/automation-audit-export-service.ts
 create mode 100644 src/services/automation-slo-service.ts
 create mode 100644 src/services/distributed-node-flow-runner-service.ts
 create mode 100644 src/services/headless-auth-service.ts
 create mode 100644 src/services/headless-operational-readiness-service.ts
 create mode 100644 tests/backend/server/headless-dashboard-auth.test.ts
 create mode 100644 tests/backend/services/credentialed-automation-e2e.test.ts
 create mode 100644 tests/backend/services/headless-automation-operations.test.ts
 create mode 100644 tests/e2e/fixtures/headless-automation-records.json

diff --git a/docs-web/architecture/node-flow-durable-execution.md b/docs-web/architecture/node-flow-durable-execution.md
index e5bc80f167..4d5eb01e34 100644
--- a/docs-web/architecture/node-flow-durable-execution.md
+++ b/docs-web/architecture/node-flow-durable-execution.md
@@ -2,6 +2,8 @@
 
 Node flows execute immutable published snapshots. A run explicitly pins a published version or follows the latest published version; later edits cannot change a pinned run.
 
+Distributed runners are authenticated service principals with `automation_runner` and explicit project scope. Queue claims use a database compare-and-set lease, and heartbeats renew only for the current owner. Outbox idempotency combines publication, run, node, and logical item, so restart reconstruction returns prior sent rows instead of duplicating external effects. Unknown outcomes require attention; approvals, attempts, credential access, and delivery emit redacted correlation audit records.
+
 Runs are durably queued and leased with bounded global and project concurrency. Node attempts retain attempt number, executor and invocation identity, artifact digest, redacted payloads, credential ids, failure class, and retry decision. Retryable failures use bounded exponential backoff and jitter, while cancellation and timeout signals propagate to provider and HTTP work.
 
 On restart, expired pre-invocation work is safely requeued. Work with an external invocation and an unknown outcome moves to `attention_required` and is never silently replayed. Credential values are resolved only for the active node and are not retained in run history or diagnostics.
diff --git a/docs-web/architecture/system-overview.md b/docs-web/architecture/system-overview.md
index 52d2f3b7fe..b560abe473 100644
--- a/docs-web/architecture/system-overview.md
+++ b/docs-web/architecture/system-overview.md
@@ -2,6 +2,8 @@
 
 Code UX is a single Node process that hosts multiple cooperating services. This page describes that process model, the major services, and how data flows through them.
 
+Authenticated headless automation is composed from a fail-closed principal/role boundary, key/audit/runner readiness, durable redacted audit export, SLO sampling, and project-scoped runner lease ownership. The dashboard API enforces these controls before route handlers; startup verifies recovery keys before binding listeners when encrypted data exists.
+
 ## Process topology
 
 ```
diff --git a/docs-web/content/docs/architecture-node-flow-durable-execution.mdx b/docs-web/content/docs/architecture-node-flow-durable-execution.mdx
index e5bc80f167..4d5eb01e34 100644
--- a/docs-web/content/docs/architecture-node-flow-durable-execution.mdx
+++ b/docs-web/content/docs/architecture-node-flow-durable-execution.mdx
@@ -2,6 +2,8 @@
 
 Node flows execute immutable published snapshots. A run explicitly pins a published version or follows the latest published version; later edits cannot change a pinned run.
 
+Distributed runners are authenticated service principals with `automation_runner` and explicit project scope. Queue claims use a database compare-and-set lease, and heartbeats renew only for the current owner. Outbox idempotency combines publication, run, node, and logical item, so restart reconstruction returns prior sent rows instead of duplicating external effects. Unknown outcomes require attention; approvals, attempts, credential access, and delivery emit redacted correlation audit records.
+
 Runs are durably queued and leased with bounded global and project concurrency. Node attempts retain attempt number, executor and invocation identity, artifact digest, redacted payloads, credential ids, failure class, and retry decision. Retryable failures use bounded exponential backoff and jitter, while cancellation and timeout signals propagate to provider and HTTP work.
 
 On restart, expired pre-invocation work is safely requeued. Work with an external invocation and an unknown outcome moves to `attention_required` and is never silently replayed. Credential values are resolved only for the active node and are not retained in run history or diagnostics.
diff --git a/docs-web/content/docs/architecture-system-overview.mdx b/docs-web/content/docs/architecture-system-overview.mdx
index 34bf1f73c2..b338b393e3 100644
--- a/docs-web/content/docs/architecture-system-overview.mdx
+++ b/docs-web/content/docs/architecture-system-overview.mdx
@@ -2,6 +2,8 @@
 
 Code UX is a single Node process that hosts multiple cooperating services. This page describes that process model, the major services, and how data flows through them.
 
+Authenticated headless automation is composed from a fail-closed principal/role boundary, key/audit/runner readiness, durable redacted audit export, SLO sampling, and project-scoped runner lease ownership. The dashboard API enforces these controls before route handlers; startup verifies recovery keys before binding listeners when encrypted data exists.
+
 ## Process topology
 
 ```
diff --git a/docs-web/content/docs/operations-runbook.mdx b/docs-web/content/docs/operations-runbook.mdx
new file mode 100644
index 0000000000..c70652c530
--- /dev/null
+++ b/docs-web/content/docs/operations-runbook.mdx
@@ -0,0 +1,12 @@
+# Authenticated Automation Runbook
+
+Run recovery drills only against the approved local test project and mocked job/email providers.
+
+1. Verify a viewer can read its project and receives `403` for another project; correlate both requests in audit export.
+2. Stop the key provider with encrypted rows present. `/health` stays live, `/ready` returns `503`, and a new process refuses startup.
+3. Process the 20-record fixture, approve selected drafts, and restart after outbox enqueue. Sent idempotency keys must not invoke the provider twice; unknown outcomes require attention.
+4. Rotate the external credential and confirm the binding resolves its next version; revoke it and confirm access is denied without secret canaries in exports, logs, prompts, traces, or diagnostics.
+5. Publish a later automation, then draft/publish the earlier immutable version. Existing runs remain pinned and new runs select the rollback publication.
+6. Restore SQLite/WAL plus key versions in isolation. Keep runners disabled until readiness, audit continuity, lease ownership, approvals, and outbox counts match the backup manifest.
+
+Record database integrity, key ids/versions (never key material), last audit id, lease/outbox counts, and rollback publication. A drill passes only with 20 processed fixtures, the expected selected delivery count, no duplicate provider/idempotency ids, and no secret canary.
diff --git a/docs-web/content/docs/operations-security-hardening.mdx b/docs-web/content/docs/operations-security-hardening.mdx
new file mode 100644
index 0000000000..1393677792
--- /dev/null
+++ b/docs-web/content/docs/operations-security-hardening.mdx
@@ -0,0 +1,9 @@
+# Headless Security Hardening
+
+Remote dashboard/API access requires a service-token or trusted OIDC reverse-proxy boundary, TLS, project-scoped roles, and request correlation. A non-loopback `DASHBOARD_HOST` does not make credential routes public: callers still need `credential_admin`, project membership, and `CODE_UX_REMOTE_CREDENTIAL_MANAGEMENT=true`.
+
+The proxy must remove client-supplied identity headers and inject its own principal, roles, projects, HTTPS protocol, and backend shared secret. Service identity configuration stores only SHA-256 bearer digests. Give runners `automation_runner` and only the projects they lease; split author, publisher, approver/runner, credential administrator, and viewer identities where separation is required.
+
+Encrypted credential data has no plaintext fallback. Missing mounted/KMS/Vault key versions fail startup and `/ready`; `/health` remains useful for liveness. Backups are incomplete without the referenced key versions. Audit export is recursively secret-redacted but still restricted operational data.
+
+See [Authenticated Headless Server Mode](/docs/operations-server-mode) for deployment, recovery, rotation, SLOs, and limitations.
diff --git a/docs-web/content/docs/operations-server-mode.mdx b/docs-web/content/docs/operations-server-mode.mdx
new file mode 100644
index 0000000000..f4ec240e0e
--- /dev/null
+++ b/docs-web/content/docs/operations-server-mode.mdx
@@ -0,0 +1,27 @@
+# Authenticated Headless Server Mode
+
+Code UX separates MCP bearer access from the authenticated dashboard administrative API. Remote dashboard/API deployments must use digest-backed service identities or terminate OIDC at a trusted reverse proxy; loopback desktop operation remains a trusted local boundary.
+
+## Identity and authorization
+
+Set `CODE_UX_DASHBOARD_AUTH_MODE=service_token` and provide `CODE_UX_SERVICE_IDENTITIES_JSON` entries containing `id`, `displayName`, SHA-256 `tokenSha256`, `roles`, explicit `projectIds`, and `enabled`. Workers send the bearer through `CODE_UX_WORKER_AUTH_TOKEN` and may assert the matching identity with `CODE_UX_WORKER_SERVICE_ID`.
+
+Alternatively, set `CODE_UX_DASHBOARD_AUTH_MODE=trusted_proxy`, configure `CODE_UX_TRUSTED_PROXY_SECRET`, terminate/validate OIDC at the proxy, strip client identity headers, and inject trusted principal, role, and project headers. Authenticated remote traffic requires TLS (`X-Forwarded-Proto: https`) unless insecure HTTP is explicitly enabled for an isolated test.
+
+Roles are `credential_admin`, `automation_author`, `automation_publisher`, `automation_runner`, and `viewer`. Credential routes additionally require `CODE_UX_REMOTE_CREDENTIAL_MANAGEMENT=true`; enabling it without a healthy secure key provider makes readiness fail. Host/origin checks, no-store responses, and administrative rate limits remain active.
+
+## Probes, audit, and SLOs
+
+`/health` is liveness. `/ready` also checks credential-key recovery, the audit store, and distributed-runner identities and returns `503` when required components are unavailable. If encrypted credential rows exist and their key cannot be recovered, startup aborts before listeners bind.
+
+Authenticated operators can use `/api/admin/readiness`, `/api/admin/audit/export` (redacted NDJSON), and `/api/admin/metrics/slo`. Audit covers management calls, credential access, runs, attempts, approvals, and outbox delivery with correlation ids.
+
+Baseline alerts: readiness not ready for five minutes, management 5xx above 1% or p95 above one second for ten minutes, repeated lease expiry, credential-denial spikes, outbox failure backlog, or any secret/audit check failure. Target zero unauthorized project grants, secret disclosures, and duplicate side effects.
+
+## Backup and recovery
+
+Back up SQLite with WAL consistency, settings, project `.code-ux/` state, and every referenced external key version. Restore keys before databases, keep runner admission disabled, require `/ready`, then reconcile leases, approvals, audit continuity, and outbox counts. Never back up plaintext service tokens beside their digests.
+
+Rotate service identities by overlapping new/old digests until runners authenticate with the new token. Rotate credential values through the broker so graph bindings retain ids and resolve the next version. Retain old KMS/Vault versions until envelope rewrap and restore drills pass.
+
+Rollback creates and publishes a new draft from an earlier immutable version; in-flight runs stay pinned. Recovery requeues only known-safe pre-invocation work and leaves uncertain external outcomes for attention. OIDC validation and Vault/KMS client integration remain deployment-host responsibilities, and MCP bearer authority remains broader than dashboard roles.
diff --git a/docs-web/content/docs/registry.ts b/docs-web/content/docs/registry.ts
index 23b762da50..6bf849a8b0 100644
--- a/docs-web/content/docs/registry.ts
+++ b/docs-web/content/docs/registry.ts
@@ -104,6 +104,9 @@ export type DocsSlug =
   | 'architecture-configuration-resolution'
   | 'architecture-security'
   | 'operations-credential-security'
+  | 'operations-runbook'
+  | 'operations-security-hardening'
+  | 'operations-server-mode'
   | 'settings-google-drive-mount'
   | 'user-dashboard-custom-dashboards'
   | 'architecture-custom-dashboard-foundation'
@@ -833,6 +836,27 @@ export const docsRegistry: Record<DocsSlug, DocsRegistryEntry> = {
     title: "Automation Credential Security",
     description: "Code UX resolves canonical node credential IDs and named project binding keys through the credential broker. Stored values are not exposed to nodes, dashboard reads, MCP payloads, agent context, run inspection records...",
   },
+  'operations-runbook': {
+    id: 'operations-runbook',
+    path: '/docs/operations-runbook',
+    section: 'User Guide',
+    title: "Authenticated Automation Runbook",
+    description: "Run recovery drills only against the approved local test project and mocked job/email providers.",
+  },
+  'operations-security-hardening': {
+    id: 'operations-security-hardening',
+    path: '/docs/operations-security-hardening',
+    section: 'User Guide',
+    title: "Headless Security Hardening",
+    description: "Remote dashboard/API access requires a service-token or trusted OIDC reverse-proxy boundary, TLS, project-scoped roles, and request correlation. A non-loopback DASHBOARD_HOST does not make credential routes public: ca...",
+  },
+  'operations-server-mode': {
+    id: 'operations-server-mode',
+    path: '/docs/operations-server-mode',
+    section: 'User Guide',
+    title: "Authenticated Headless Server Mode",
+    description: "Code UX separates MCP bearer access from the authenticated dashboard administrative API. Remote dashboard/API deployments must use digest-backed service identities or terminate OIDC at a trusted reverse proxy; loopbac...",
+  },
   'settings-google-drive-mount': {
     id: 'settings-google-drive-mount',
     path: '/docs/settings-google-drive-mount',
@@ -1021,6 +1045,9 @@ export const orderedDocs: DocsRegistryEntry[] = [
   docsRegistry['architecture-configuration-resolution'],
   docsRegistry['architecture-security'],
   docsRegistry['operations-credential-security'],
+  docsRegistry['operations-runbook'],
+  docsRegistry['operations-security-hardening'],
+  docsRegistry['operations-server-mode'],
   docsRegistry['settings-google-drive-mount'],
   docsRegistry['user-dashboard-custom-dashboards'],
   docsRegistry['architecture-custom-dashboard-foundation'],
diff --git a/docs-web/operations/runbook.md b/docs-web/operations/runbook.md
new file mode 100644
index 0000000000..c70652c530
--- /dev/null
+++ b/docs-web/operations/runbook.md
@@ -0,0 +1,12 @@
+# Authenticated Automation Runbook
+
+Run recovery drills only against the approved local test project and mocked job/email providers.
+
+1. Verify a viewer can read its project and receives `403` for another project; correlate both requests in audit export.
+2. Stop the key provider with encrypted rows present. `/health` stays live, `/ready` returns `503`, and a new process refuses startup.
+3. Process the 20-record fixture, approve selected drafts, and restart after outbox enqueue. Sent idempotency keys must not invoke the provider twice; unknown outcomes require attention.
+4. Rotate the external credential and confirm the binding resolves its next version; revoke it and confirm access is denied without secret canaries in exports, logs, prompts, traces, or diagnostics.
+5. Publish a later automation, then draft/publish the earlier immutable version. Existing runs remain pinned and new runs select the rollback publication.
+6. Restore SQLite/WAL plus key versions in isolation. Keep runners disabled until readiness, audit continuity, lease ownership, approvals, and outbox counts match the backup manifest.
+
+Record database integrity, key ids/versions (never key material), last audit id, lease/outbox counts, and rollback publication. A drill passes only with 20 processed fixtures, the expected selected delivery count, no duplicate provider/idempotency ids, and no secret canary.
diff --git a/docs-web/operations/security-hardening.md b/docs-web/operations/security-hardening.md
new file mode 100644
index 0000000000..724eee4e9e
--- /dev/null
+++ b/docs-web/operations/security-hardening.md
@@ -0,0 +1,9 @@
+# Headless Security Hardening
+
+Remote dashboard/API access requires a service-token or trusted OIDC reverse-proxy boundary, TLS, project-scoped roles, and request correlation. A non-loopback `DASHBOARD_HOST` does not make credential routes public: callers still need `credential_admin`, project membership, and `CODE_UX_REMOTE_CREDENTIAL_MANAGEMENT=true`.
+
+The proxy must remove client-supplied identity headers and inject its own principal, roles, projects, HTTPS protocol, and backend shared secret. Service identity configuration stores only SHA-256 bearer digests. Give runners `automation_runner` and only the projects they lease; split author, publisher, approver/runner, credential administrator, and viewer identities where separation is required.
+
+Encrypted credential data has no plaintext fallback. Missing mounted/KMS/Vault key versions fail startup and `/ready`; `/health` remains useful for liveness. Backups are incomplete without the referenced key versions. Audit export is recursively secret-redacted but still restricted operational data.
+
+See [Authenticated Headless Server Mode](./server-mode.md) for deployment, recovery, rotation, SLOs, and limitations.
diff --git a/docs-web/operations/server-mode.md b/docs-web/operations/server-mode.md
new file mode 100644
index 0000000000..f4ec240e0e
--- /dev/null
+++ b/docs-web/operations/server-mode.md
@@ -0,0 +1,27 @@
+# Authenticated Headless Server Mode
+
+Code UX separates MCP bearer access from the authenticated dashboard administrative API. Remote dashboard/API deployments must use digest-backed service identities or terminate OIDC at a trusted reverse proxy; loopback desktop operation remains a trusted local boundary.
+
+## Identity and authorization
+
+Set `CODE_UX_DASHBOARD_AUTH_MODE=service_token` and provide `CODE_UX_SERVICE_IDENTITIES_JSON` entries containing `id`, `displayName`, SHA-256 `tokenSha256`, `roles`, explicit `projectIds`, and `enabled`. Workers send the bearer through `CODE_UX_WORKER_AUTH_TOKEN` and may assert the matching identity with `CODE_UX_WORKER_SERVICE_ID`.
+
+Alternatively, set `CODE_UX_DASHBOARD_AUTH_MODE=trusted_proxy`, configure `CODE_UX_TRUSTED_PROXY_SECRET`, terminate/validate OIDC at the proxy, strip client identity headers, and inject trusted principal, role, and project headers. Authenticated remote traffic requires TLS (`X-Forwarded-Proto: https`) unless insecure HTTP is explicitly enabled for an isolated test.
+
+Roles are `credential_admin`, `automation_author`, `automation_publisher`, `automation_runner`, and `viewer`. Credential routes additionally require `CODE_UX_REMOTE_CREDENTIAL_MANAGEMENT=true`; enabling it without a healthy secure key provider makes readiness fail. Host/origin checks, no-store responses, and administrative rate limits remain active.
+
+## Probes, audit, and SLOs
+
+`/health` is liveness. `/ready` also checks credential-key recovery, the audit store, and distributed-runner identities and returns `503` when required components are unavailable. If encrypted credential rows exist and their key cannot be recovered, startup aborts before listeners bind.
+
+Authenticated operators can use `/api/admin/readiness`, `/api/admin/audit/export` (redacted NDJSON), and `/api/admin/metrics/slo`. Audit covers management calls, credential access, runs, attempts, approvals, and outbox delivery with correlation ids.
+
+Baseline alerts: readiness not ready for five minutes, management 5xx above 1% or p95 above one second for ten minutes, repeated lease expiry, credential-denial spikes, outbox failure backlog, or any secret/audit check failure. Target zero unauthorized project grants, secret disclosures, and duplicate side effects.
+
+## Backup and recovery
+
+Back up SQLite with WAL consistency, settings, project `.code-ux/` state, and every referenced external key version. Restore keys before databases, keep runner admission disabled, require `/ready`, then reconcile leases, approvals, audit continuity, and outbox counts. Never back up plaintext service tokens beside their digests.
+
+Rotate service identities by overlapping new/old digests until runners authenticate with the new token. Rotate credential values through the broker so graph bindings retain ids and resolve the next version. Retain old KMS/Vault versions until envelope rewrap and restore drills pass.
+
+Rollback creates and publishes a new draft from an earlier immutable version; in-flight runs stay pinned. Recovery requeues only known-safe pre-invocation work and leaves uncertain external outcomes for attention. OIDC validation and Vault/KMS client integration remain deployment-host responsibilities, and MCP bearer authority remains broader than dashboard roles.
diff --git a/docs-web/routes/docs.operations-runbook.lazy.tsx b/docs-web/routes/docs.operations-runbook.lazy.tsx
new file mode 100644
index 0000000000..bf199a327f
--- /dev/null
+++ b/docs-web/routes/docs.operations-runbook.lazy.tsx
@@ -0,0 +1,11 @@
+import { createLazyFileRoute } from '@tanstack/react-router'
+import OperationsRunbookContent from '../content/docs/operations-runbook.mdx'
+import { DocsPage } from '../components/docs/DocsPage'
+
+export const Route = createLazyFileRoute('/docs/operations-runbook')({
+  component: () => (
+    <DocsPage id="operations-runbook">
+      <OperationsRunbookContent />
+    </DocsPage>
+  )
+})
diff --git a/docs-web/routes/docs.operations-security-hardening.lazy.tsx b/docs-web/routes/docs.operations-security-hardening.lazy.tsx
new file mode 100644
index 0000000000..2c3f166d2d
--- /dev/null
+++ b/docs-web/routes/docs.operations-security-hardening.lazy.tsx
@@ -0,0 +1,11 @@
+import { createLazyFileRoute } from '@tanstack/react-router'
+import OperationsSecurityHardeningContent from '../content/docs/operations-security-hardening.mdx'
+import { DocsPage } from '../components/docs/DocsPage'
+
+export const Route = createLazyFileRoute('/docs/operations-security-hardening')({
+  component: () => (
+    <DocsPage id="operations-security-hardening">
+      <OperationsSecurityHardeningContent />
+    </DocsPage>
+  )
+})
diff --git a/docs-web/routes/docs.operations-server-mode.lazy.tsx b/docs-web/routes/docs.operations-server-mode.lazy.tsx
new file mode 100644
index 0000000000..dce2ef3730
--- /dev/null
+++ b/docs-web/routes/docs.operations-server-mode.lazy.tsx
@@ -0,0 +1,11 @@
+import { createLazyFileRoute } from '@tanstack/react-router'
+import OperationsServerModeContent from '../content/docs/operations-server-mode.mdx'
+import { DocsPage } from '../components/docs/DocsPage'
+
+export const Route = createLazyFileRoute('/docs/operations-server-mode')({
+  component: () => (
+    <DocsPage id="operations-server-mode">
+      <OperationsServerModeContent />
+    </DocsPage>
+  )
+})
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 1d7a3c0e6f..a6c74b9e57 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -106,7 +106,7 @@
   - [Mockup Sprint Pentest Scenarios](./development/mockup-sprint-pentest-scenarios.md)
   - [Documentation Standards](./development/documentation-standards.md)
 - [Operations Runbook](./operations/runbook.md)
-- [Secure Headless Server Mode](./operations/server-mode.md)
+- [Secure Headless Server Mode](./operations/server-mode.md) (authenticated automation operations)
 - [Security Hardening](./operations/security-hardening.md)
 - [Automation Credential Security](./operations/credential-security.md)
 - [Logging and Correlation IDs](./operations/logging-and-correlation.md)
diff --git a/docs/architecture/node-flow-durable-execution.md b/docs/architecture/node-flow-durable-execution.md
index 334447c9de..6bdd4ba290 100644
--- a/docs/architecture/node-flow-durable-execution.md
+++ b/docs/architecture/node-flow-durable-execution.md
@@ -13,3 +13,9 @@ Every node execution creates a numbered attempt with executor identity, optional
 Startup recovery scans queued and waiting work plus running work with expired leases. A pre-invocation attempt can be requeued safely without inserting a duplicate attempt. An expired attempt with an invocation id has an unknown externally observable outcome and moves to `attention_required`; Code UX does not silently replay it. Approval- and retry-waiting runs retain their durable state until their prerequisite becomes actionable.
 
 The relevant tables are `node_flow_publications`, `node_flow_runs`, `node_flow_node_runs`, and `node_flow_node_attempts`. Attempt history is available at `GET /api/node-flow-runs/:runId/attempts` and contains only redacted payloads and credential identifiers.
+
+## Distributed ownership and side effects
+
+Authenticated runners claim through a service principal with `automation_runner` and explicit project membership. The database update from queued/retry-waiting to running is the ownership compare-and-set; heartbeats renew only when both run id and lease owner match. A second runner therefore cannot acquire an active lease.
+
+External email-style effects use `automation_outbox`. The idempotency key is derived from publication, run, node, and logical item, so reconstructing services after restart returns an existing sent row rather than invoking the provider twice. Known failures may be retried; unknown outcomes become `attention_required`. Approval decisions and deliveries are durable and produce redacted correlation audit records alongside run and attempt events.
diff --git a/docs/architecture/system-overview.md b/docs/architecture/system-overview.md
index aa79f415b6..f29106b51b 100644
--- a/docs/architecture/system-overview.md
+++ b/docs/architecture/system-overview.md
@@ -74,6 +74,14 @@ Code UX is a container-first multi-provider runtime with an integrated dashboard
 - `src/shared/logging/logger.ts`
 - `src/shared/logging/correlation-id.ts`
 
+### 9. Authenticated headless automation boundary
+
+- `src/services/headless-auth-service.ts` resolves local, trusted-proxy, or digest-backed service principals and applies role/project authorization before dashboard administrative routes.
+- `src/services/headless-operational-readiness-service.ts` combines encrypted-data key recovery, durable audit storage, and runner identity checks. The server asserts key recovery before binding listeners.
+- `src/services/automation-audit-export-service.ts` persists correlation-linked, recursively redacted audit rows and exports bounded NDJSON.
+- `src/services/distributed-node-flow-runner-service.ts` grants compare-and-set leases only to project-scoped `automation_runner` service principals.
+- `src/services/automation-slo-service.ts` publishes bounded management latency/error and delivery baselines.
+
 ## Runtime Architecture Diagram
 
 ```mermaid
diff --git a/docs/index.md b/docs/index.md
index 7c8f643b42..46669c2146 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -104,7 +104,7 @@ Use this page as the main entrypoint.
 3. [Custom Dashboard MCP Contract](./mcp/tools-and-contracts.md#custom-dashboard-management)
 4. [MCP Issue Importer Contract](./mcp/tools-and-contracts.md#manage_sprints-import_issues)
 5. [MCP Runtime and Dispatch](./mcp/runtime-and-dispatch.md)
-6. [Secure Headless Server Mode](./operations/server-mode.md)
+6. [Secure Headless Server Mode](./operations/server-mode.md) — dashboard/API identities, key readiness, audit, recovery, and SLOs
 7. [Operations Runbook](./operations/runbook.md)
 8. [Security Hardening](./operations/security-hardening.md)
 9. [Automation Credential Security](./operations/credential-security.md)
diff --git a/docs/operations/runbook.md b/docs/operations/runbook.md
index c227e7f470..7db7afc293 100644
--- a/docs/operations/runbook.md
+++ b/docs/operations/runbook.md
@@ -1,5 +1,20 @@
 # Operations Runbook
 
+## Authenticated automation recovery drills
+
+Run these drills against the approved local test project with mocked job/email boundaries only:
+
+1. Send an authenticated read using a viewer identity, then verify a different project returns `403` with the same correlation id visible in redacted audit export.
+2. Stop the key provider while encrypted rows exist. `/health` must remain live, `/ready` must return `503`, and a fresh process must refuse startup. Restore the exact key version before retrying.
+3. Start a 20-record fixture run, approve selected drafts, and restart after durable outbox enqueue. Recovery may reclaim expired pre-invocation work; it must not repeat a `sent` idempotency key. Unknown provider outcomes require attention instead of replay.
+4. Rotate the externally configured credential and verify the unchanged binding resolves the next credential version. Revoke it and verify new resolution is denied without secret text in logs, attempts, graph export, prompts, or diagnostics.
+5. Publish a second automation version, then roll back by drafting/publishing the earlier immutable version. Existing runs stay pinned; new runs select the rollback publication.
+6. Restore the SQLite/WAL snapshot and key-provider state into isolation. Keep runner admission disabled until `/ready`, audit continuity, approval rows, leases, and outbox counts match the backup manifest.
+
+Record the backup timestamp, database integrity result, key ids/versions (never key material), last audit id, active lease count, outbox status counts, and rollback publication id. A drill passes only with 20 processed fixture records, the expected selected-message count, no duplicate provider ids/idempotency keys, and no secret canary in any exported artifact.
+
+Alert response starts by disabling runner identities, preserving the database/WAL and audit export, and checking `/api/admin/readiness` plus `/api/admin/metrics/slo`. Do not delete attention-required attempts or manually mark uncertain outbox rows sent; reconcile them with the mocked/provider idempotency record first.
+
 This runbook covers day-to-day operation and incident handling for the MCP server and dashboard.
 
 ## Normal Startup Procedure
diff --git a/docs/operations/security-hardening.md b/docs/operations/security-hardening.md
index 73bf59f142..856ce8dd6a 100644
--- a/docs/operations/security-hardening.md
+++ b/docs/operations/security-hardening.md
@@ -1,5 +1,15 @@
 # Security Hardening
 
+## Headless identity boundary
+
+Remote dashboard/API access must use either digest-backed service identities or an OIDC-capable trusted reverse proxy as documented in [Secure Headless Server Mode](./server-mode.md). Never expose credential management by setting only `DASHBOARD_HOST`; it also requires the `credential_admin` role, project scope, TLS, and `CODE_UX_REMOTE_CREDENTIAL_MANAGEMENT=true`.
+
+Treat trusted identity headers as credentials: the proxy must remove inbound copies, inject its own values, authenticate to the loopback backend with `CODE_UX_TRUSTED_PROXY_SECRET`, and emit `X-Forwarded-Proto: https`. Keep `/health` and `/ready` free of authorization headers. Keep webhook and chat-provider ingress secrets separate from dashboard identities.
+
+Service identity JSON stores only SHA-256 token digests. Give automation runners only `automation_runner` plus the exact project ids they lease. Split authoring, publishing, approval/running, credential administration, and viewing identities where operational separation matters. Audit export is secret-redacted but still security-sensitive operational data; restrict and retain it according to incident policy.
+
+Encrypted credential rows make key recovery a startup invariant. Backups are incomplete without the referenced KMS/Vault versions or owner-only mounted key. A missing key must produce `/ready` 503 and startup failure, never metadata-only success or an unencrypted fallback.
+
 This page documents the concrete security posture of Code UX. Code UX operates as a single-user trusted process designed for local development or isolated execution. It explicitly does not feature multi-tenant RBAC, full authentication for standard UI flows, or protection from hostile users with existing network access to the application.
 
 ## Dependency Audit Enforcement
diff --git a/docs/operations/server-mode.md b/docs/operations/server-mode.md
index 8994db6cf2..37f1b271b5 100644
--- a/docs/operations/server-mode.md
+++ b/docs/operations/server-mode.md
@@ -12,7 +12,28 @@ Server mode is different from ordinary `--headless` mode:
 
 ## Threat Model
 
-Server mode is still a single-user trusted Code UX runtime. Any authenticated MCP client can inspect and mutate projects, settings, sprints, tasks, memory, and execution state exposed through enabled MCP tools. It is not a multi-tenant service and does not implement per-user RBAC.
+MCP bearer access remains a runtime-wide control-plane identity. The dashboard administrative API has a separate authenticated-headless boundary with project-scoped roles; do not treat an MCP bearer as a dashboard service identity.
+
+## Authenticated Dashboard API
+
+Remote dashboard/API operation is fail-closed. Setting a non-loopback `DASHBOARD_HOST` without an explicit authentication mode defaults the API to `service_token`, so unconfigured callers receive `401`/`403` instead of inheriting desktop access. Loopback desktop mode remains `local`.
+
+Choose one boundary:
+
+- `CODE_UX_DASHBOARD_AUTH_MODE=service_token`: define `CODE_UX_SERVICE_IDENTITIES_JSON` as an array of identities with `id`, `displayName`, a lowercase SHA-256 `tokenSha256`, `roles`, `projectIds`, and `enabled`. Workers may send the matching id with `--service-identity-id` or `CODE_UX_WORKER_SERVICE_ID`; the bearer remains in `CODE_UX_WORKER_AUTH_TOKEN`.
+- `CODE_UX_DASHBOARD_AUTH_MODE=trusted_proxy`: terminate OIDC at a trusted proxy, set `CODE_UX_TRUSTED_PROXY_SECRET`, and have the proxy overwrite `X-Code-UX-Proxy-Secret`, `X-Code-UX-Principal-Id`, `X-Code-UX-Roles`, `X-Code-UX-Project-Ids`, and optional name/kind headers. Never forward client-supplied copies.
+
+Roles are `credential_admin`, `automation_author`, `automation_publisher`, `automation_runner`, and `viewer`. Project ids are explicit; `*` is an operator-only all-project grant. Credential routes additionally require `CODE_UX_REMOTE_CREDENTIAL_MANAGEMENT=true`. Enabling that flag without a healthy secure key provider makes readiness fail.
+
+TLS is assumed at the reverse proxy. Authenticated remote requests must arrive with HTTPS or a trusted `X-Forwarded-Proto: https`; `CODE_UX_ALLOW_INSECURE_HTTP=true` is limited to isolated test networks. Same-origin browser checks, no-store headers, host validation, and a 600-request/minute administrative API limiter remain active. Webhook and provider-ingress endpoints retain their dedicated authentication schemes.
+
+Example identity generation (the JSON stores only the digest):
+
+```bash
+token="$(openssl rand -base64 48 | tr -d '\n')"
+digest="$(printf '%s' "$token" | sha256sum | cut -d' ' -f1)"
+# Put $token in the runner secret manager and $digest in CODE_UX_SERVICE_IDENTITIES_JSON.
+```
 
 Use server mode when:
 
@@ -82,6 +103,24 @@ Use `/ready` for runtime readiness. It reports whether the Code UX runtime finis
 
 Do not include `Authorization` headers in probe logs. The probe endpoints do not require bearer credentials.
 
+`/ready` also reports `credentialKey`, `auditStore`, and `distributedRunner`. `/health` remains live during a key-provider outage, while `/ready` returns `503`. Startup aborts before dashboard or MCP binding when encrypted credential rows exist but their key provider cannot recover the wrapping key. Select a provider with `CODE_UX_CREDENTIAL_KEY_PROVIDER=mounted-key-file|vault|kms`; mounted files use `CODE_UX_CREDENTIAL_KEY_FILE` and owner-only permissions. Vault/KMS modes require their host adapter to be configured and healthy.
+
+Authenticated operators can inspect `/api/admin/readiness`, export redacted NDJSON from `/api/admin/audit/export`, and sample `/api/admin/metrics/slo`. Audit rows include the correlation id, principal, project, action, outcome, and redacted metadata for management requests, credential access, runs, attempts, approvals, and outbox delivery.
+
+## Backup, Restore, Rotation, And Rollback
+
+Back up `~/.code-ux/app.db` with a SQLite-aware snapshot that includes/checkpoints WAL state, the settings database, project `.code-ux/` directories, and the external key-provider versions needed by every encrypted envelope. Never place plaintext service tokens or root keys in the database backup. Restore into an isolated host, restore keys first, run `/ready`, then enable runners.
+
+Rotate service tokens by adding the new digest, deploying the new runner secret, observing successful authenticated calls, and disabling the old identity entry. Rotate credential values through the credential rotation API; existing graph bindings keep the credential id and resolve the new version. Retain old KMS/Vault key versions until every envelope has been rewrapped and a restore drill succeeds.
+
+To roll back an automation, create a new draft from the earlier immutable version, review it, and publish it. In-flight runs remain pinned to their original publication. Stop runner admission before database recovery; after restore, startup recovery requeues only known-safe work and leaves unknown external outcomes in `attention_required`.
+
+## Baseline SLOs And Alerts
+
+Initial operator baselines are 99.9% authenticated management availability, p95 management latency below 500 ms, zero unauthorized project grants, zero secret disclosure, and zero duplicate outbox side effects. Alert when readiness is not ready for 5 minutes, management 5xx rate exceeds 1% for 10 minutes, p95 exceeds 1 second for 10 minutes, leases repeatedly expire, denied credential access spikes, outbox failures remain pending for 5 minutes, or any audit/secret scanning check fails.
+
+Local mode is intentionally a trusted loopback desktop boundary. Authenticated headless mode adds API RBAC, project scope, key readiness, durable audit, and service identities, but it is not a general multi-tenant identity platform: OIDC token validation belongs at the trusted proxy, Vault/KMS require host adapters, and MCP bearer authority remains broader than dashboard roles.
+
 ## Client Connections
 
 MCP HTTP clients connect to the configured path with `Authorization: Bearer <token>`. The first JSON-RPC request on a new Streamable HTTP session must be `initialize`; the server returns an `mcp-session-id` header that the client echoes on later calls.
diff --git a/src/app/dependency-factory/core-factory.ts b/src/app/dependency-factory/core-factory.ts
index 6d97a2bd16..c2f7322ae4 100644
--- a/src/app/dependency-factory/core-factory.ts
+++ b/src/app/dependency-factory/core-factory.ts
@@ -73,7 +73,13 @@ import { AutomationWebhookTriggerRepository } from "../../repositories/automatio
 import { CredentialBroker } from "../../services/credentials/credential-broker.js";
 import { MountedKeyFileProvider } from "../../infrastructure/security/mounted-key-file-provider.js";
 import { EncryptedSqliteSecretStore } from "../../infrastructure/security/encrypted-sqlite-secret-store.js";
+import { KmsKeyProviderAdapter, VaultKeyProviderAdapter } from "../../infrastructure/security/external-key-provider-adapters.js";
 import { getProcessCredentialKeyProvider } from "../../services/credentials/key-provider-registry.js";
+import type { KeyProvider } from "../../services/credentials/key-provider.js";
+import { HeadlessAuthService, loadHeadlessSecurityConfiguration } from "../../services/headless-auth-service.js";
+import { AutomationAuditExportService } from "../../services/automation-audit-export-service.js";
+import { HeadlessOperationalReadinessService } from "../../services/headless-operational-readiness-service.js";
+import { AutomationSloService } from "../../services/automation-slo-service.js";
 
 export interface CoreDependencies {
   providerRunner: IProviderRunner;
@@ -138,6 +144,10 @@ export interface CoreDependencies {
   automationOutboxRepository: AutomationOutboxRepository;
   automationWebhookTriggerRepository: AutomationWebhookTriggerRepository;
   credentialBroker: CredentialBroker;
+  headlessAuthService: HeadlessAuthService;
+  automationAuditService: AutomationAuditExportService;
+  headlessReadinessService: HeadlessOperationalReadinessService;
+  automationSloService: AutomationSloService;
 }
 
 export function createCoreDependencies(
@@ -197,13 +207,29 @@ export function createCoreDependencies(
   const automationApprovalRepository = new AutomationApprovalRepository(appDbStorage);
   const automationOutboxRepository = new AutomationOutboxRepository(appDbStorage);
   const automationWebhookTriggerRepository = new AutomationWebhookTriggerRepository(appDbStorage);
-  const credentialKeyProvider = getProcessCredentialKeyProvider()
-    ?? new MountedKeyFileProvider(process.env.CODE_UX_CREDENTIAL_KEY_FILE);
+  const securityConfiguration = loadHeadlessSecurityConfiguration();
+  const configuredKeyProvider = (): KeyProvider => {
+    const provider = process.env.CODE_UX_CREDENTIAL_KEY_PROVIDER?.trim().toLowerCase();
+    if (provider === "vault") return new VaultKeyProviderAdapter();
+    if (provider === "kms") return new KmsKeyProviderAdapter();
+    return new MountedKeyFileProvider(process.env.CODE_UX_CREDENTIAL_KEY_FILE);
+  };
+  const credentialKeyProvider = getProcessCredentialKeyProvider() ?? configuredKeyProvider();
+  const automationAuditService = new AutomationAuditExportService(appDbStorage);
   const credentialBroker = new CredentialBroker(
     automationCredentialRepository,
     new EncryptedSqliteSecretStore(automationCredentialRepository, credentialKeyProvider),
     credentialKeyProvider,
+    automationAuditService,
   );
+  const headlessAuthService = new HeadlessAuthService(securityConfiguration);
+  const automationSloService = new AutomationSloService();
+  const headlessReadinessService = new HeadlessOperationalReadinessService({
+    credentialRepository: automationCredentialRepository,
+    keyProvider: credentialKeyProvider,
+    auditService: automationAuditService,
+    security: securityConfiguration,
+  });
   const dashboardRealtimeEventRepository = new DashboardRealtimeEventRepository(appDbStorage);
   const dashboardRealtimeService = new DashboardRealtimeService(
     dashboardRealtimeEventRepository,
@@ -420,5 +446,9 @@ export function createCoreDependencies(
     automationOutboxRepository,
     automationWebhookTriggerRepository,
     credentialBroker,
+    headlessAuthService,
+    automationAuditService,
+    headlessReadinessService,
+    automationSloService,
   };
 }
diff --git a/src/app/dependency-factory/dashboard-factory.ts b/src/app/dependency-factory/dashboard-factory.ts
index 629e0a49ff..0a6c971945 100644
--- a/src/app/dependency-factory/dashboard-factory.ts
+++ b/src/app/dependency-factory/dashboard-factory.ts
@@ -48,6 +48,10 @@ import { registerCustomNodeDefinition } from "../../domain/node-flows/node-defin
 
 export interface DashboardDependencies {
   credentialBroker: CoreDependencies["credentialBroker"];
+  headlessAuthService: CoreDependencies["headlessAuthService"];
+  automationAuditService: CoreDependencies["automationAuditService"];
+  headlessReadinessService: CoreDependencies["headlessReadinessService"];
+  automationSloService: CoreDependencies["automationSloService"];
   chatThreadRuntimeService: ChatThreadRuntimeService;
   chatProviderRepository: CoreDependencies["chatProviderRepository"];
   chatProviderIngressService: ChatProviderIngressService;
@@ -242,7 +246,7 @@ export function createDashboardDependencies(
     ?? new AutomationOutboxRepository(coreDeps.appDbStorage);
   const webhookTriggerRepository = coreDeps.automationWebhookTriggerRepository
     ?? new AutomationWebhookTriggerRepository(coreDeps.appDbStorage);
-  const approvalService = new ApprovalService(approvalRepository);
+  const approvalService = new ApprovalService(approvalRepository, coreDeps.automationAuditService);
   const egressPolicyService = new EgressPolicyService();
   const customNodeRepository = new CustomNodeRepository(coreDeps.appDbStorage);
   const customNodeProjectService = new CustomNodeProjectService();
@@ -265,7 +269,8 @@ export function createDashboardDependencies(
     egressPolicyService,
     customNodeRuntimeService,
     approvalService,
-    outboxService: new OutboxService(outboxRepository, new MockSideEffectProvider()),
+    outboxService: new OutboxService(outboxRepository, new MockSideEffectProvider(), coreDeps.automationAuditService),
+    auditService: coreDeps.automationAuditService,
     getDashboardSettings: (projectId) => resolveDashboardSettings({ projectId }),
   });
   if (coreDeps.nodeFlowRepository) {
@@ -602,6 +607,10 @@ export function createDashboardDependencies(
 
   return {
     credentialBroker: coreDeps.credentialBroker,
+    headlessAuthService: coreDeps.headlessAuthService,
+    automationAuditService: coreDeps.automationAuditService,
+    headlessReadinessService: coreDeps.headlessReadinessService,
+    automationSloService: coreDeps.automationSloService,
     chatProviderRepository,
     chatThreadRuntimeService,
     chatProviderIngressService,
diff --git a/src/app/lifecycle/dashboard-lifecycle-service.ts b/src/app/lifecycle/dashboard-lifecycle-service.ts
index f7876bb181..0b8dbccf67 100644
--- a/src/app/lifecycle/dashboard-lifecycle-service.ts
+++ b/src/app/lifecycle/dashboard-lifecycle-service.ts
@@ -62,6 +62,10 @@ import type { SpeechTranscriptionService } from "../../services/speech-transcrip
 import type { SpeechSynthesisService } from "../../services/speech-synthesis-service.js";
 import type { SpeechModelManager } from "../../services/speech-model-manager.js";
 import type { NodeFlowService } from "../../services/node-flow-service.js";
+import type { HeadlessAuthService } from "../../services/headless-auth-service.js";
+import type { AutomationAuditExportService } from "../../services/automation-audit-export-service.js";
+import type { HeadlessOperationalReadinessService } from "../../services/headless-operational-readiness-service.js";
+import type { AutomationSloService } from "../../services/automation-slo-service.js";
 import type { MemoryService } from "../../services/memory-service.js";
 import type { KnowledgeService } from "../../services/knowledge-service.js";
 import type { MemoryPromotionService } from "../../services/memory-promotion-service.js";
@@ -139,6 +143,10 @@ export interface BootDashboardDeps {
   speechModelManager: SpeechModelManager;
   chatProviderOutboundService?: ChatProviderOutboundService;
   nodeFlowService?: NodeFlowService;
+  headlessAuthService: HeadlessAuthService;
+  automationAuditService: AutomationAuditExportService;
+  headlessReadinessService: HeadlessOperationalReadinessService;
+  automationSloService: AutomationSloService;
   customDashboardRepository?: CustomDashboardRepository;
   customDashboardValidationService?: CustomDashboardValidationService;
   skillService: SkillService;
@@ -494,6 +502,10 @@ export async function bootDashboard(deps: BootDashboardDeps): Promise<DashboardS
     speechSynthesisService: deps.speechSynthesisService,
     speechModelManager: deps.speechModelManager,
     nodeFlowService: deps.nodeFlowService,
+    headlessAuthService: deps.headlessAuthService,
+    automationAuditService: deps.automationAuditService,
+    headlessReadinessService: deps.headlessReadinessService,
+    automationSloService: deps.automationSloService,
     customDashboardRepository: deps.customDashboardRepository,
     customDashboardValidationService: deps.customDashboardValidationService,
     skillService: deps.skillService,
diff --git a/src/contracts/headless-security-types.ts b/src/contracts/headless-security-types.ts
new file mode 100644
index 0000000000..39a860504f
--- /dev/null
+++ b/src/contracts/headless-security-types.ts
@@ -0,0 +1,84 @@
+export const CODE_UX_ROLES = [
+  "credential_admin",
+  "automation_author",
+  "automation_publisher",
+  "automation_runner",
+  "viewer",
+] as const;
+
+export type CodeUxRole = typeof CODE_UX_ROLES[number];
+export type PrincipalKind = "user" | "service" | "local_desktop";
+
+export interface CodeUxPrincipal {
+  id: string;
+  displayName: string;
+  kind: PrincipalKind;
+  roles: CodeUxRole[];
+  /** An empty array means the principal has no project access. */
+  projectIds: string[];
+  authenticatedAt: string;
+  authenticationMethod: "local" | "trusted_proxy" | "service_token";
+}
+
+export interface RunnerServiceIdentity {
+  id: string;
+  displayName: string;
+  tokenSha256: string;
+  roles: CodeUxRole[];
+  projectIds: string[];
+  enabled: boolean;
+}
+
+export type HeadlessAuthMode = "local" | "trusted_proxy" | "service_token";
+
+export interface HeadlessSecurityConfiguration {
+  mode: HeadlessAuthMode;
+  trustedProxySecret?: string;
+  serviceIdentities: RunnerServiceIdentity[];
+  allowInsecureHttp: boolean;
+  remoteCredentialManagement: boolean;
+}
+
+export type AuditOutcome = "succeeded" | "denied" | "failed";
+
+export interface AutomationAuditRecord {
+  id: string;
+  occurredAt: string;
+  correlationId: string;
+  principalId: string;
+  principalKind: PrincipalKind;
+  action: string;
+  resourceType: string;
+  resourceId: string | null;
+  projectId: string | null;
+  outcome: AuditOutcome;
+  metadata: Record<string, unknown>;
+}
+
+export type OperationalReadinessComponentStatus = "ready" | "not_ready" | "not_required";
+
+export interface OperationalReadinessComponent {
+  status: OperationalReadinessComponentStatus;
+  reason?: string;
+  provider?: string;
+}
+
+export interface HeadlessOperationalReadiness {
+  status: "READY" | "NOT_READY";
+  checkedAt: string;
+  components: {
+    credentialKey: OperationalReadinessComponent;
+    auditStore: OperationalReadinessComponent;
+    distributedRunner: OperationalReadinessComponent;
+  };
+}
+
+export interface AutomationSloSnapshot {
+  windowStartedAt: string;
+  sampledAt: string;
+  managementRequestCount: number;
+  managementErrorRate: number;
+  managementLatencyP95Ms: number;
+  runAttemptCount: number;
+  outboxDeliveryErrorRate: number;
+}
diff --git a/src/repositories/automation-credential-repository.ts b/src/repositories/automation-credential-repository.ts
index a37f1d0b56..1048e8f4f7 100644
--- a/src/repositories/automation-credential-repository.ts
+++ b/src/repositories/automation-credential-repository.ts
@@ -17,6 +17,11 @@ export class AutomationCredentialRepository {
     if (!this.db.prepare("SELECT id FROM projects WHERE id = ?").get(projectId)) throw new EntityNotFoundError(`Project not found: ${projectId}`);
   }
 
+  countEncryptedSecrets(): number {
+    const row = this.db.prepare("SELECT COUNT(*) AS count FROM automation_credential_secrets").get() as { count?: number | bigint } | undefined;
+    return Number(row?.count ?? 0);
+  }
+
   list(projectId: string): AutomationCredentialMetadata[] {
     this.requireProject(projectId);
     const rows = this.db.prepare(`SELECT c.*, EXISTS(SELECT 1 FROM automation_credential_secrets s WHERE s.credential_id=c.id) AS configured FROM automation_credentials c WHERE c.project_id = ? OR (c.scope = 'global' AND EXISTS (SELECT 1 FROM json_each(c.allowed_project_ids_json) WHERE value = ?)) ORDER BY c.updated_at DESC`).all(projectId, projectId) as CredentialRow[];
diff --git a/src/repositories/db/app-db-migrations.ts b/src/repositories/db/app-db-migrations.ts
index a83425e514..f557b4dc10 100644
--- a/src/repositories/db/app-db-migrations.ts
+++ b/src/repositories/db/app-db-migrations.ts
@@ -596,6 +596,27 @@ export function ensureAutomationCredentialTables(db: DatabaseAdapter): void {
   ensureIndex(db, "idx_automation_credential_rotations_credential", "automation_credential_rotations", "credential_id, rotated_at DESC");
 }
 
+export function ensureAutomationAuditTables(db: DatabaseAdapter): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS automation_audit_records (
+      id TEXT PRIMARY KEY,
+      occurred_at TEXT NOT NULL,
+      correlation_id TEXT NOT NULL,
+      principal_id TEXT NOT NULL,
+      principal_kind TEXT NOT NULL,
+      action TEXT NOT NULL,
+      resource_type TEXT NOT NULL,
+      resource_id TEXT,
+      project_id TEXT,
+      outcome TEXT NOT NULL,
+      metadata_json TEXT NOT NULL DEFAULT '{}'
+    )
+  `);
+  ensureIndex(db, "idx_automation_audit_occurred", "automation_audit_records", "occurred_at DESC, id DESC");
+  ensureIndex(db, "idx_automation_audit_project", "automation_audit_records", "project_id, occurred_at DESC");
+  ensureIndex(db, "idx_automation_audit_principal", "automation_audit_records", "principal_id, occurred_at DESC");
+}
+
 export function ensureCustomNodeTables(db: DatabaseAdapter): void {
   db.exec(`
     CREATE TABLE IF NOT EXISTS custom_nodes (
@@ -882,6 +903,7 @@ export function runMigrations(db: DatabaseAdapter): void {
   migratePersistedNodeFlowGraphs(db);
   ensureCustomDashboardTables(db);
   ensureAutomationCredentialTables(db);
+  ensureAutomationAuditTables(db);
   ensureCustomNodeTables(db);
 
   ensureColumn(db, "projects", "initialization_mode", "TEXT NOT NULL DEFAULT 'existing'");
diff --git a/src/server/code-ux-server.ts b/src/server/code-ux-server.ts
index aa6e8e21e2..a74226faa4 100644
--- a/src/server/code-ux-server.ts
+++ b/src/server/code-ux-server.ts
@@ -100,6 +100,10 @@ import { disposeCommandSpawner, shutdownGitHelperPool } from "../shared/subproce
 import { LocalMcpCliConfigService } from "../services/local-mcp-cli-config-service.js";
 import type { McpConnectionInfo } from "../contracts/mcp-connection-types.js";
 import type { ChatProviderIngressService } from "../services/chat-provider-ingress-service.js";
+import type { HeadlessAuthService } from "../services/headless-auth-service.js";
+import type { AutomationAuditExportService } from "../services/automation-audit-export-service.js";
+import type { HeadlessOperationalReadinessService } from "../services/headless-operational-readiness-service.js";
+import type { AutomationSloService } from "../services/automation-slo-service.js";
 import { ProjectInitializationStateService } from "../services/project-initialization-state-service.js";
 
 function detectMergeConflictMessage(message: string | null | undefined): boolean {
@@ -229,6 +233,10 @@ export class CodeUxServer {
   private closePromise: Promise<void> | null = null;
   private readonly mcpApprovalTracker = new McpApprovalTracker();
   private readonly localMcpCliConfigService = new LocalMcpCliConfigService();
+  private readonly headlessAuthService: HeadlessAuthService;
+  private readonly automationAuditService: AutomationAuditExportService;
+  private readonly headlessReadinessService: HeadlessOperationalReadinessService;
+  private readonly automationSloService: AutomationSloService;
   private readonly signalHandler: () => void;
   private runtimeProcessLockRelease: RuntimeProcessLockRelease | null = null;
 
@@ -277,6 +285,10 @@ export class CodeUxServer {
     this.sessionTracking = deps.sessionTracking;
     this.cliWorkflowService = deps.cliWorkflowService;
     this.managementToolHandler = deps.managementToolHandler;
+    this.headlessAuthService = deps.headlessAuthService;
+    this.automationAuditService = deps.automationAuditService;
+    this.headlessReadinessService = deps.headlessReadinessService;
+    this.automationSloService = deps.automationSloService;
 
     this.activityCacheService = deps.activityCacheService;
     this.taskRerunService = deps.taskRerunService;
@@ -1379,6 +1391,7 @@ export class CodeUxServer {
   }
 
   private async runInternal(): Promise<void> {
+    await this.headlessReadinessService.assertStartupReady();
     await bootSettings({
       runtimeContext: this.runtimeContext,
       projectRoot: this.projectRoot,
@@ -1433,6 +1446,10 @@ export class CodeUxServer {
         projectSetupService: this.projectSetupService,
         schedulerService: this.schedulerService,
         nodeFlowService: this.nodeFlowService,
+        headlessAuthService: this.headlessAuthService,
+        automationAuditService: this.automationAuditService,
+        headlessReadinessService: this.headlessReadinessService,
+        automationSloService: this.automationSloService,
         customDashboardRepository: this.customDashboardRepository,
         customDashboardValidationService: this.customDashboardValidationService,
         skillService: this.skillService,
diff --git a/src/server/dashboard-middleware.ts b/src/server/dashboard-middleware.ts
index feb8bac243..67eac754bd 100644
--- a/src/server/dashboard-middleware.ts
+++ b/src/server/dashboard-middleware.ts
@@ -13,6 +13,8 @@ import {
 import { createPreviewHostMiddleware } from "./preview-host-middleware.js";
 import { parsePreviewSessionIdFromHost } from "./preview-host-utils.js";
 import { createHttpRateLimiter } from "../shared/http/rate-limit.js";
+import { getCorrelationId } from "../shared/logging/correlation-id.js";
+import { HeadlessAuthenticationError, HeadlessAuthService } from "../services/headless-auth-service.js";
 import type { DashboardServerOptions } from "./dashboard-server.js";
 import {
   DASHBOARD_DEFAULT_JSON_BODY_LIMIT,
@@ -54,6 +56,72 @@ export const applyDashboardPreRouteMiddleware = (
     }
     next();
   });
+
+  const authService = options.headlessAuthService ?? new HeadlessAuthService();
+  app.use("/api", createHttpRateLimiter({
+    windowMs: 60_000,
+    max: 600,
+    onLimited: (req) => dashboardLogger.warn("Dashboard API request rate limit exceeded", {
+      logPurpose: "security",
+      method: req.method,
+      path: req.path,
+    }),
+  }));
+  app.use("/api", (req, res, next) => {
+    if (req.path.startsWith("/webhooks/") || req.path.includes("/ingress/")) {
+      next();
+      return;
+    }
+    const startedAt = Date.now();
+    try {
+      const principal = authService.authenticate(req);
+      authService.authorize(req, principal);
+      res.locals.codeUxPrincipal = principal;
+      res.on("finish", () => {
+        options.automationSloService?.observeManagementRequest(Date.now() - startedAt, res.statusCode);
+        options.automationAuditService?.record({
+          correlationId: getCorrelationId() ?? String(res.getHeader("x-correlation-id") ?? "unknown"),
+          principal,
+          action: `${req.method} ${req.path}`,
+          resourceType: "dashboard_api",
+          projectId: extractProjectId(req.path),
+          outcome: res.statusCode < 400 ? "succeeded" : res.statusCode === 401 || res.statusCode === 403 ? "denied" : "failed",
+          metadata: { statusCode: res.statusCode, durationMs: Date.now() - startedAt },
+        });
+      });
+      next();
+    } catch (error) {
+      const authenticationError = error instanceof HeadlessAuthenticationError
+        ? error
+        : new HeadlessAuthenticationError("Authentication configuration is invalid.", 403);
+      dashboardLogger.warn("Dashboard API access denied", {
+        logPurpose: "security",
+        method: req.method,
+        path: req.path,
+        statusCode: authenticationError.statusCode,
+        reason: authenticationError.message,
+      });
+      options.automationSloService?.observeManagementRequest(Date.now() - startedAt, authenticationError.statusCode);
+      options.automationAuditService?.record({
+        correlationId: getCorrelationId() ?? String(res.getHeader("x-correlation-id") ?? "unknown"),
+        principal: {
+          id: "unauthenticated",
+          displayName: "Unauthenticated request",
+          kind: "user",
+          roles: [],
+          projectIds: [],
+          authenticatedAt: new Date().toISOString(),
+          authenticationMethod: "service_token",
+        },
+        action: `${req.method} ${req.path}`,
+        resourceType: "dashboard_api",
+        projectId: extractProjectId(req.path),
+        outcome: "denied",
+        metadata: { statusCode: authenticationError.statusCode, reason: authenticationError.message },
+      });
+      res.status(authenticationError.statusCode).json({ error: authenticationError.message });
+    }
+  });
   app.use((req, res, next) => {
     const startedAt = Date.now();
     res.on("finish", () => {
@@ -116,6 +184,11 @@ export const applyDashboardPreRouteMiddleware = (
   app.use(createDashboardJsonBodyErrorHandler(dashboardLogger));
 };
 
+function extractProjectId(pathname: string): string | null {
+  const match = pathname.match(/^\/projects\/([^/]+)/);
+  return match?.[1] ? decodeURIComponent(match[1]) : null;
+}
+
 function captureRawJsonBody(req: IncomingMessage, _res: unknown, buf: Buffer): void {
   (req as IncomingMessage & { rawBody?: string }).rawBody = buf.toString("utf8");
 }
diff --git a/src/server/dashboard-route-registration.ts b/src/server/dashboard-route-registration.ts
index aea5368746..3a4745b8f0 100644
--- a/src/server/dashboard-route-registration.ts
+++ b/src/server/dashboard-route-registration.ts
@@ -29,6 +29,7 @@ import { registerUpdateStatusRoutes } from "./update-status-routes.js";
 import { registerMemoryRoutes } from "./memory-routes.js";
 import { registerKnowledgeRoutes } from "./knowledge-routes.js";
 import { registerDocsWebRoutes } from "./docs-web-routes.js";
+import { registerHeadlessOperationsRoutes } from "./headless-operations-routes.js";
 import { registerAutomationCredentialRoutes } from "./automation-credential-routes.js";
 import { registerChatProviderRoutes } from "./chat-provider-routes.js";
 import { registerChatProviderIngressRoutes } from "./chat-provider-ingress-routes.js";
@@ -137,6 +138,7 @@ const registerSystemIntegrationRouteGroup = (app: Express, deps: DashboardDepend
   registerGitProviderRoutes(app, deps);
   registerUpdateStatusRoutes(app, deps);
   registerDocsWebRoutes(app);
+  registerHeadlessOperationsRoutes(app, deps);
 };
 
 const registerSpeechRouteGroup = (app: Express, deps: DashboardDependencies): void => {
diff --git a/src/server/dashboard-server.ts b/src/server/dashboard-server.ts
index 720b41f26b..2525cb484f 100644
--- a/src/server/dashboard-server.ts
+++ b/src/server/dashboard-server.ts
@@ -144,6 +144,10 @@ import type { SkillService } from "../services/skill-service.js";
 import type { CredentialBroker } from "../services/credentials/credential-broker.js";
 import type { ApprovalService } from "../services/node-flows/approval-service.js";
 import type { AutomationWebhookTriggerRepository } from "../repositories/automation-webhook-trigger-repository.js";
+import type { HeadlessAuthService } from "../services/headless-auth-service.js";
+import type { AutomationAuditExportService } from "../services/automation-audit-export-service.js";
+import type { HeadlessOperationalReadinessService } from "../services/headless-operational-readiness-service.js";
+import type { AutomationSloService } from "../services/automation-slo-service.js";
 import type { ManagedRuntimeService } from "../services/managed-runtime-service.js";
 import type { ProviderToolManager } from "../services/provider-tool-manager.js";
 import {
@@ -195,6 +199,10 @@ export interface DashboardServerOptions {
   customDashboardValidationService?: CustomDashboardValidationService;
   skillService?: SkillService;
   credentialBroker?: CredentialBroker;
+  headlessAuthService?: HeadlessAuthService;
+  automationAuditService?: AutomationAuditExportService;
+  headlessReadinessService?: HeadlessOperationalReadinessService;
+  automationSloService?: AutomationSloService;
   managedRuntimeService?: ManagedRuntimeService;
   providerToolManager?: ProviderToolManager;
   playwrightBrowserManager?: PlaywrightBrowserManager;
@@ -417,12 +425,20 @@ export const configureDashboardApp = (options: DashboardServerOptions): Logger =
     }
   });
 
-  app.get("/ready", (req, res) => {
+  app.get("/ready", async (req, res) => {
     const ready = isReady ? isReady() : { status: "READY" as const };
-    if (ready.status === "READY" || ready.status === "UP") {
-      res.json(ready);
+    const operational = options.headlessReadinessService
+      ? await options.headlessReadinessService.refresh()
+      : null;
+    const response = operational
+      ? { ...operational, runtime: ready }
+      : ready;
+    const isRuntimeReady = ready.status === "READY" || ready.status === "UP";
+    const isOperationallyReady = operational === null || operational.status === "READY";
+    if (isRuntimeReady && isOperationallyReady) {
+      res.json(response);
     } else {
-      res.status(503).json(ready);
+      res.status(503).json(response);
     }
   });
 
@@ -528,6 +544,7 @@ export const setupDashboardServer = async (options: DashboardServerOptions): Pro
     port,
     getSprintPreviewSession,
   } = options;
+  await options.headlessReadinessService?.assertStartupReady();
   const dashboardLogger = configureDashboardApp(options);
   if (process.env.NODE_ENV !== "test") {
     const runtime = options.managedRuntimeService ?? managedRuntimeService;
diff --git a/src/server/headless-operations-routes.ts b/src/server/headless-operations-routes.ts
new file mode 100644
index 0000000000..a400b4edb3
--- /dev/null
+++ b/src/server/headless-operations-routes.ts
@@ -0,0 +1,40 @@
+import type { Express } from "express";
+import type { DashboardDependencies } from "./dashboard-server.js";
+import { asyncRoute } from "./route-utils.js";
+
+export function registerHeadlessOperationsRoutes(app: Express, deps: DashboardDependencies): void {
+  if (deps.automationAuditService) {
+    app.get("/api/admin/audit/export", (req, res) => {
+      const projectId = typeof req.query.projectId === "string" ? req.query.projectId.trim() || undefined : undefined;
+      const since = typeof req.query.since === "string" ? req.query.since.trim() || undefined : undefined;
+      const limitValue = typeof req.query.limit === "string" ? Number.parseInt(req.query.limit, 10) : undefined;
+      const principalProjectIds = Array.isArray(res.locals.codeUxPrincipal?.projectIds)
+        ? res.locals.codeUxPrincipal.projectIds as string[]
+        : [];
+      if (!projectId && !principalProjectIds.includes("*")) {
+        res.status(403).json({ error: "A projectId is required for project-scoped audit export." });
+        return;
+      }
+      if (projectId && !principalProjectIds.includes("*") && !principalProjectIds.includes(projectId)) {
+        res.status(403).json({ error: "The authenticated principal is not authorized for this project." });
+        return;
+      }
+      res.type("application/x-ndjson").send(deps.automationAuditService!.exportNdjson({
+        projectId,
+        since,
+        limit: Number.isFinite(limitValue) ? limitValue : undefined,
+      }));
+    });
+  }
+  if (deps.headlessReadinessService) {
+    app.get("/api/admin/readiness", asyncRoute(async (_req, res) => {
+      const readiness = await deps.headlessReadinessService!.refresh();
+      res.status(readiness.status === "READY" ? 200 : 503).json(readiness);
+    }));
+  }
+  if (deps.automationSloService) {
+    app.get("/api/admin/metrics/slo", (_req, res) => {
+      res.json(deps.automationSloService!.snapshot());
+    });
+  }
+}
diff --git a/src/services/automation-audit-export-service.ts b/src/services/automation-audit-export-service.ts
new file mode 100644
index 0000000000..a575dbe8cc
--- /dev/null
+++ b/src/services/automation-audit-export-service.ts
@@ -0,0 +1,146 @@
+import { randomUUID } from "node:crypto";
+import type {
+  AutomationAuditRecord,
+  AuditOutcome,
+  CodeUxPrincipal,
+} from "../contracts/headless-security-types.js";
+import type { AppDbStorage } from "../repositories/app-db-storage.js";
+import type { DatabaseAdapter } from "../repositories/db/database-adapter.js";
+import { redactMetadata } from "../shared/security/redaction.js";
+import { getCorrelationId, generateCorrelationId } from "../shared/logging/correlation-id.js";
+
+interface AuditRow {
+  id: string;
+  occurred_at: string;
+  correlation_id: string;
+  principal_id: string;
+  principal_kind: AutomationAuditRecord["principalKind"];
+  action: string;
+  resource_type: string;
+  resource_id: string | null;
+  project_id: string | null;
+  outcome: AuditOutcome;
+  metadata_json: string;
+}
+
+export interface RecordAutomationAuditInput {
+  correlationId: string;
+  principal: CodeUxPrincipal;
+  action: string;
+  resourceType: string;
+  resourceId?: string | null;
+  projectId?: string | null;
+  outcome: AuditOutcome;
+  metadata?: Record<string, unknown>;
+}
+
+export class AutomationAuditExportService {
+  private readonly db: DatabaseAdapter;
+
+  constructor(storage: AppDbStorage) {
+    this.db = storage.getDatabase();
+  }
+
+  health(): boolean {
+    try {
+      this.db.prepare("SELECT 1 FROM automation_audit_records LIMIT 1").get();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  record(input: RecordAutomationAuditInput): AutomationAuditRecord {
+    const record: AutomationAuditRecord = {
+      id: randomUUID(),
+      occurredAt: new Date().toISOString(),
+      correlationId: input.correlationId,
+      principalId: input.principal.id,
+      principalKind: input.principal.kind,
+      action: input.action,
+      resourceType: input.resourceType,
+      resourceId: input.resourceId ?? null,
+      projectId: input.projectId ?? null,
+      outcome: input.outcome,
+      metadata: redactMetadata(input.metadata ?? {}) as Record<string, unknown>,
+    };
+    this.db.prepare(`
+      INSERT INTO automation_audit_records (
+        id, occurred_at, correlation_id, principal_id, principal_kind, action,
+        resource_type, resource_id, project_id, outcome, metadata_json
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      record.id,
+      record.occurredAt,
+      record.correlationId,
+      record.principalId,
+      record.principalKind,
+      record.action,
+      record.resourceType,
+      record.resourceId,
+      record.projectId,
+      record.outcome,
+      JSON.stringify(record.metadata),
+    );
+    return record;
+  }
+
+  recordSystem(input: Omit<RecordAutomationAuditInput, "correlationId" | "principal"> & { principalId?: string }): AutomationAuditRecord {
+    return this.record({
+      ...input,
+      correlationId: getCorrelationId() ?? generateCorrelationId(),
+      principal: {
+        id: input.principalId ?? "code-ux-runtime",
+        displayName: "Code UX runtime",
+        kind: "service",
+        roles: ["automation_runner"],
+        projectIds: input.projectId ? [input.projectId] : [],
+        authenticatedAt: new Date().toISOString(),
+        authenticationMethod: "service_token",
+      },
+    });
+  }
+
+  list(input: { projectId?: string; since?: string; limit?: number } = {}): AutomationAuditRecord[] {
+    const clauses: string[] = [];
+    const parameters: Array<string | number> = [];
+    if (input.projectId) {
+      clauses.push("project_id = ?");
+      parameters.push(input.projectId);
+    }
+    if (input.since) {
+      clauses.push("occurred_at >= ?");
+      parameters.push(input.since);
+    }
+    const limit = Math.min(10_000, Math.max(1, input.limit ?? 1_000));
+    parameters.push(limit);
+    const rows = this.db.prepare(`
+      SELECT * FROM automation_audit_records
+      ${clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : ""}
+      ORDER BY occurred_at ASC, id ASC
+      LIMIT ?
+    `).all(...parameters) as AuditRow[];
+    return rows.map((row) => this.map(row));
+  }
+
+  exportNdjson(input: { projectId?: string; since?: string; limit?: number } = {}): string {
+    const lines = this.list(input).map((record) => JSON.stringify(record));
+    return lines.length > 0 ? `${lines.join("\n")}\n` : "";
+  }
+
+  private map(row: AuditRow): AutomationAuditRecord {
+    return {
+      id: row.id,
+      occurredAt: row.occurred_at,
+      correlationId: row.correlation_id,
+      principalId: row.principal_id,
+      principalKind: row.principal_kind,
+      action: row.action,
+      resourceType: row.resource_type,
+      resourceId: row.resource_id,
+      projectId: row.project_id,
+      outcome: row.outcome,
+      metadata: JSON.parse(row.metadata_json) as Record<string, unknown>,
+    };
+  }
+}
diff --git a/src/services/automation-slo-service.ts b/src/services/automation-slo-service.ts
new file mode 100644
index 0000000000..7075973fd8
--- /dev/null
+++ b/src/services/automation-slo-service.ts
@@ -0,0 +1,39 @@
+import type { AutomationSloSnapshot } from "../contracts/headless-security-types.js";
+
+export class AutomationSloService {
+  private readonly windowStartedAt = new Date().toISOString();
+  private readonly managementLatencies: number[] = [];
+  private managementErrors = 0;
+  private runAttempts = 0;
+  private outboxDeliveries = 0;
+  private outboxDeliveryErrors = 0;
+
+  observeManagementRequest(durationMs: number, statusCode: number): void {
+    this.managementLatencies.push(Math.max(0, durationMs));
+    if (this.managementLatencies.length > 10_000) this.managementLatencies.shift();
+    if (statusCode >= 500) this.managementErrors += 1;
+  }
+
+  observeRunAttempt(): void {
+    this.runAttempts += 1;
+  }
+
+  observeOutboxDelivery(succeeded: boolean): void {
+    this.outboxDeliveries += 1;
+    if (!succeeded) this.outboxDeliveryErrors += 1;
+  }
+
+  snapshot(): AutomationSloSnapshot {
+    const sorted = [...this.managementLatencies].sort((left, right) => left - right);
+    const p95Index = sorted.length === 0 ? 0 : Math.ceil(sorted.length * 0.95) - 1;
+    return {
+      windowStartedAt: this.windowStartedAt,
+      sampledAt: new Date().toISOString(),
+      managementRequestCount: sorted.length,
+      managementErrorRate: sorted.length === 0 ? 0 : this.managementErrors / sorted.length,
+      managementLatencyP95Ms: sorted[p95Index] ?? 0,
+      runAttemptCount: this.runAttempts,
+      outboxDeliveryErrorRate: this.outboxDeliveries === 0 ? 0 : this.outboxDeliveryErrors / this.outboxDeliveries,
+    };
+  }
+}
diff --git a/src/services/credentials/credential-broker.ts b/src/services/credentials/credential-broker.ts
index 992262a547..1614c0640b 100644
--- a/src/services/credentials/credential-broker.ts
+++ b/src/services/credentials/credential-broker.ts
@@ -3,13 +3,14 @@ import type { AutomationCredentialMetadata, CreateAutomationCredentialInput, Cre
 import type { AutomationCredentialRepository } from "../../repositories/automation-credential-repository.js";
 import type { KeyProvider } from "./key-provider.js";
 import type { SecretStore } from "./secret-store.js";
+import type { AutomationAuditExportService } from "../automation-audit-export-service.js";
 
 export class CredentialAccessDeniedError extends Error {
   constructor(message: string) { super(message); this.name = "CredentialAccessDeniedError"; }
 }
 
 export class CredentialBroker {
-  constructor(private readonly repository: AutomationCredentialRepository, private readonly secretStore: SecretStore, private readonly keyProvider: KeyProvider) {}
+  constructor(private readonly repository: AutomationCredentialRepository, private readonly secretStore: SecretStore, private readonly keyProvider: KeyProvider, private readonly auditService?: AutomationAuditExportService) {}
 
   health(): Promise<CredentialBackendHealth> { return this.keyProvider.health(); }
   list(projectId: string): AutomationCredentialMetadata[] { return this.repository.list(projectId); }
@@ -63,6 +64,7 @@ export class CredentialBroker {
     try {
       const secret=await this.secretStore.get(this.context(credential)); const value=secret.toString("utf8"); secret.fill(0);
       this.repository.recordAccess({credentialId:credential.id,projectId:request.projectId,bindingKey:request.bindingKey,capability:request.capability,operation:"resolve",outcome:"granted",reason:null});
+      this.auditService?.recordSystem({ action: "credential.access", resourceType: "automation_credential", resourceId: credential.id, projectId: request.projectId, outcome: "succeeded", metadata: { bindingKey: request.bindingKey, capability: request.capability, credentialVersion: credential.version } });
       return {credentialId:credential.id,value,version:credential.version};
     } catch { return this.deny(request,credential.id,"Credential backend is unavailable or authentication failed."); }
   }
@@ -76,6 +78,7 @@ export class CredentialBroker {
     try {
       const secret=await this.secretStore.get(this.context(credential)); const value=secret.toString("utf8"); secret.fill(0);
       this.repository.recordAccess({credentialId:credential.id,projectId:request.projectId,bindingKey:request.bindingKey,capability:request.capability,operation:"resolve",outcome:"granted",reason:null});
+      this.auditService?.recordSystem({ action: "credential.access", resourceType: "automation_credential", resourceId: credential.id, projectId: request.projectId, outcome: "succeeded", metadata: { bindingKey: request.bindingKey, capability: request.capability, credentialVersion: credential.version } });
       return {credentialId:credential.id,value,version:credential.version};
     } catch { return this.deny(request,credential.id,"Credential backend is unavailable or authentication failed."); }
   }
@@ -84,5 +87,5 @@ export class CredentialBroker {
   private context(credential:AutomationCredentialMetadata){ return {credentialId:credential.id,projectId:credential.projectId ?? "global",workspaceId:credential.projectId ?? "global"}; }
   private canAccess(credential:AutomationCredentialMetadata,projectId:string):boolean{return credential.scope === "project" ? credential.projectId === projectId : credential.allowedProjectIds.includes(projectId);}
   private requireAccessible(projectId:string,credentialId:string):AutomationCredentialMetadata{this.repository.requireProject(projectId);const credential=this.repository.get(credentialId);if(!credential||!this.canAccess(credential,projectId))throw new CredentialAccessDeniedError("Credential is not available to this project.");return credential;}
-  private deny(request:CredentialResolutionRequest,credentialId:string|null,reason:string):never{this.repository.recordAccess({credentialId,projectId:request.projectId,bindingKey:request.bindingKey,capability:request.capability,operation:"resolve",outcome:"denied",reason});throw new CredentialAccessDeniedError(reason);}
+  private deny(request:CredentialResolutionRequest,credentialId:string|null,reason:string):never{this.repository.recordAccess({credentialId,projectId:request.projectId,bindingKey:request.bindingKey,capability:request.capability,operation:"resolve",outcome:"denied",reason});this.auditService?.recordSystem({action:"credential.access",resourceType:"automation_credential",resourceId:credentialId,projectId:request.projectId,outcome:"denied",metadata:{bindingKey:request.bindingKey,capability:request.capability,reason}});throw new CredentialAccessDeniedError(reason);}
 }
diff --git a/src/services/distributed-node-flow-runner-service.ts b/src/services/distributed-node-flow-runner-service.ts
new file mode 100644
index 0000000000..7ec621c63b
--- /dev/null
+++ b/src/services/distributed-node-flow-runner-service.ts
@@ -0,0 +1,52 @@
+import type { CodeUxPrincipal } from "../contracts/headless-security-types.js";
+import type { NodeFlowRunRecord } from "../contracts/node-flow-types.js";
+import type { NodeFlowRepository } from "../repositories/node-flow-repository.js";
+import { NodeFlowQueueService, NodeFlowQuotaExceededError } from "./node-flows/node-flow-queue-service.js";
+
+export class DistributedRunnerAuthorizationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "DistributedRunnerAuthorizationError";
+  }
+}
+
+/**
+ * Owns the narrow distributed-runner lease boundary. Execution remains in the
+ * node-flow runtime; this service only grants project-scoped, compare-and-set
+ * leases to authenticated runner identities.
+ */
+export class DistributedNodeFlowRunnerService {
+  private readonly queue: NodeFlowQueueService;
+
+  constructor(private readonly repository: NodeFlowRepository) {
+    this.queue = new NodeFlowQueueService(repository);
+  }
+
+  claimNext(principal: CodeUxPrincipal): NodeFlowRunRecord | null {
+    this.requireRunner(principal);
+    const candidates = this.repository.listRecoverableRuns().filter((run) =>
+      (run.status === "queued" || run.status === "retry_waiting")
+      && (principal.projectIds.includes("*") || principal.projectIds.includes(run.projectId))
+    );
+    for (const run of candidates) {
+      try {
+        return this.queue.claim(run, principal.id);
+      } catch (error) {
+        if (error instanceof NodeFlowQuotaExceededError) return null;
+        // Another runner may have won the compare-and-set lease; try the next row.
+      }
+    }
+    return null;
+  }
+
+  heartbeat(principal: CodeUxPrincipal, runId: string, leaseDurationMs: number): boolean {
+    this.requireRunner(principal);
+    return this.repository.heartbeatRun(runId, principal.id, leaseDurationMs);
+  }
+
+  private requireRunner(principal: CodeUxPrincipal): void {
+    if (principal.kind !== "service" || !principal.roles.includes("automation_runner")) {
+      throw new DistributedRunnerAuthorizationError("A service principal with automation_runner is required.");
+    }
+  }
+}
diff --git a/src/services/headless-auth-service.ts b/src/services/headless-auth-service.ts
new file mode 100644
index 0000000000..ab68fa4d9e
--- /dev/null
+++ b/src/services/headless-auth-service.ts
@@ -0,0 +1,214 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import type { Request } from "express";
+import {
+  CODE_UX_ROLES,
+  type CodeUxPrincipal,
+  type CodeUxRole,
+  type HeadlessAuthMode,
+  type HeadlessSecurityConfiguration,
+  type RunnerServiceIdentity,
+} from "../contracts/headless-security-types.js";
+
+const MUTATING_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+const ROLE_SET = new Set<string>(CODE_UX_ROLES);
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+
+export class HeadlessAuthenticationError extends Error {
+  constructor(message: string, readonly statusCode: 401 | 403 = 401) {
+    super(message);
+    this.name = "HeadlessAuthenticationError";
+  }
+}
+
+function stringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? [...new Set(value.filter((item): item is string => typeof item === "string").map((item) => item.trim()).filter(Boolean))]
+    : [];
+}
+
+function roles(value: unknown): CodeUxRole[] {
+  return stringArray(value).filter((role): role is CodeUxRole => ROLE_SET.has(role));
+}
+
+function parseServiceIdentities(raw: string | undefined): RunnerServiceIdentity[] {
+  if (!raw?.trim()) return [];
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error("CODE_UX_SERVICE_IDENTITIES_JSON must contain valid JSON.");
+  }
+  if (!Array.isArray(parsed)) throw new Error("CODE_UX_SERVICE_IDENTITIES_JSON must be an array.");
+  return parsed.map((entry, index) => {
+    if (!entry || typeof entry !== "object") throw new Error(`Service identity ${index} must be an object.`);
+    const value = entry as Record<string, unknown>;
+    const id = typeof value.id === "string" ? value.id.trim() : "";
+    const tokenSha256 = typeof value.tokenSha256 === "string" ? value.tokenSha256.trim().toLowerCase() : "";
+    const parsedRoles = roles(value.roles);
+    if (!id || !/^[a-f\d]{64}$/.test(tokenSha256) || parsedRoles.length === 0) {
+      throw new Error(`Service identity ${index} requires id, a SHA-256 token digest, and at least one valid role.`);
+    }
+    return {
+      id,
+      displayName: typeof value.displayName === "string" && value.displayName.trim() ? value.displayName.trim() : id,
+      tokenSha256,
+      roles: parsedRoles,
+      projectIds: stringArray(value.projectIds),
+      enabled: value.enabled !== false,
+    };
+  });
+}
+
+function configuredDashboardIsRemote(): boolean {
+  const value = process.env.DASHBOARD_HOST?.trim();
+  if (!value) return false;
+  try {
+    const url = new URL(value.includes("://") ? value : `http://${value}`);
+    return !LOCAL_HOSTS.has(url.hostname.toLowerCase());
+  } catch {
+    return true;
+  }
+}
+
+export function loadHeadlessSecurityConfiguration(): HeadlessSecurityConfiguration {
+  const configuredMode = process.env.CODE_UX_DASHBOARD_AUTH_MODE?.trim().toLowerCase();
+  const mode: HeadlessAuthMode = configuredMode === "trusted_proxy" || configuredMode === "service_token" || configuredMode === "local"
+    ? configuredMode
+    : configuredDashboardIsRemote() ? "service_token" : "local";
+  return {
+    mode,
+    trustedProxySecret: process.env.CODE_UX_TRUSTED_PROXY_SECRET?.trim() || undefined,
+    serviceIdentities: parseServiceIdentities(process.env.CODE_UX_SERVICE_IDENTITIES_JSON),
+    allowInsecureHttp: process.env.CODE_UX_ALLOW_INSECURE_HTTP === "true",
+    remoteCredentialManagement: process.env.CODE_UX_REMOTE_CREDENTIAL_MANAGEMENT === "true",
+  };
+}
+
+function singleHeader(req: Request, name: string): string | null {
+  const value = req.headers[name];
+  return typeof value === "string" && value.trim() && !value.includes(",") ? value.trim() : null;
+}
+
+function constantTimeHexEqual(left: string, right: string): boolean {
+  if (!/^[a-f\d]{64}$/.test(left) || !/^[a-f\d]{64}$/.test(right)) return false;
+  return timingSafeEqual(Buffer.from(left, "hex"), Buffer.from(right, "hex"));
+}
+
+function projectIdFromRequest(req: Request): string | null {
+  const routeId = req.params?.projectId;
+  if (typeof routeId === "string" && routeId.trim()) return routeId.trim();
+  const match = req.path.match(/^\/(?:api\/)?projects\/([^/]+)/);
+  if (match?.[1]) return decodeURIComponent(match[1]);
+  const bodyProjectId = req.body && typeof req.body === "object" && typeof (req.body as Record<string, unknown>).projectId === "string"
+    ? String((req.body as Record<string, unknown>).projectId).trim()
+    : "";
+  return bodyProjectId || null;
+}
+
+export function requiredRoleForDashboardRequest(req: Request): CodeUxRole {
+  if (req.path.startsWith("/admin/") || req.path.startsWith("/api/admin/")) return "credential_admin";
+  if (req.path.startsWith("/api/credentials") || /\/credentials(?:\/|$)/.test(req.path)) return "credential_admin";
+  if (/\/node-flows?\//.test(req.path) || req.path.includes("/node-flows")) {
+    if (/\/(publish|rollback)(?:\/|$)/.test(req.path)) return "automation_publisher";
+    if (/\/(run|retry|cancel|approve|approvals)(?:\/|$)/.test(req.path)) return "automation_runner";
+    return MUTATING_METHODS.has(req.method) ? "automation_author" : "viewer";
+  }
+  return MUTATING_METHODS.has(req.method) ? "automation_author" : "viewer";
+}
+
+export class HeadlessAuthService {
+  constructor(readonly configuration: HeadlessSecurityConfiguration = loadHeadlessSecurityConfiguration()) {
+    if (configuration.mode === "trusted_proxy" && !configuration.trustedProxySecret) {
+      throw new Error("Trusted-proxy dashboard authentication requires CODE_UX_TRUSTED_PROXY_SECRET.");
+    }
+  }
+
+  authenticate(req: Request): CodeUxPrincipal {
+    if (this.configuration.mode === "local") {
+      return {
+        id: "local-desktop",
+        displayName: "Local desktop operator",
+        kind: "local_desktop",
+        roles: [...CODE_UX_ROLES],
+        projectIds: ["*"],
+        authenticatedAt: new Date().toISOString(),
+        authenticationMethod: "local",
+      };
+    }
+    this.requireTlsBoundary(req);
+    return this.configuration.mode === "trusted_proxy"
+      ? this.authenticateTrustedProxy(req)
+      : this.authenticateServiceToken(req);
+  }
+
+  authorize(req: Request, principal: CodeUxPrincipal): void {
+    const requiredRole = requiredRoleForDashboardRequest(req);
+    if (!principal.roles.includes(requiredRole)) {
+      throw new HeadlessAuthenticationError(`Role ${requiredRole} is required.`, 403);
+    }
+    const projectId = projectIdFromRequest(req);
+    if (projectId && !principal.projectIds.includes("*") && !principal.projectIds.includes(projectId)) {
+      throw new HeadlessAuthenticationError("The authenticated principal is not authorized for this project.", 403);
+    }
+    if (
+      this.configuration.mode !== "local"
+      && requiredRole === "credential_admin"
+      && !this.configuration.remoteCredentialManagement
+    ) {
+      throw new HeadlessAuthenticationError("Remote credential management is disabled.", 403);
+    }
+  }
+
+  private authenticateServiceToken(req: Request): CodeUxPrincipal {
+    const authorization = singleHeader(req, "authorization");
+    const match = authorization?.match(/^Bearer\s+([^\s]+)$/i);
+    if (!match) throw new HeadlessAuthenticationError("Bearer authentication is required.");
+    const digest = createHash("sha256").update(match[1], "utf8").digest("hex");
+    const identity = this.configuration.serviceIdentities.find((candidate) =>
+      candidate.enabled && constantTimeHexEqual(candidate.tokenSha256, digest)
+    );
+    if (!identity) throw new HeadlessAuthenticationError("Bearer authentication failed.");
+    const assertedIdentityId = singleHeader(req, "x-code-ux-service-id");
+    if (assertedIdentityId && assertedIdentityId !== identity.id) {
+      throw new HeadlessAuthenticationError("Bearer identity assertion does not match the authenticated service.");
+    }
+    return {
+      id: identity.id,
+      displayName: identity.displayName,
+      kind: "service",
+      roles: identity.roles,
+      projectIds: identity.projectIds,
+      authenticatedAt: new Date().toISOString(),
+      authenticationMethod: "service_token",
+    };
+  }
+
+  private authenticateTrustedProxy(req: Request): CodeUxPrincipal {
+    const suppliedSecret = singleHeader(req, "x-code-ux-proxy-secret");
+    const expected = this.configuration.trustedProxySecret ?? "";
+    const suppliedDigest = createHash("sha256").update(suppliedSecret ?? "", "utf8").digest("hex");
+    const expectedDigest = createHash("sha256").update(expected, "utf8").digest("hex");
+    if (!suppliedSecret || !constantTimeHexEqual(suppliedDigest, expectedDigest)) {
+      throw new HeadlessAuthenticationError("Trusted proxy authentication failed.");
+    }
+    const id = singleHeader(req, "x-code-ux-principal-id");
+    const parsedRoles = roles(singleHeader(req, "x-code-ux-roles")?.split(/\s+/));
+    if (!id || parsedRoles.length === 0) throw new HeadlessAuthenticationError("Trusted proxy identity headers are incomplete.");
+    return {
+      id,
+      displayName: singleHeader(req, "x-code-ux-principal-name") ?? id,
+      kind: singleHeader(req, "x-code-ux-principal-kind") === "service" ? "service" : "user",
+      roles: parsedRoles,
+      projectIds: stringArray(singleHeader(req, "x-code-ux-project-ids")?.split(/\s+/)),
+      authenticatedAt: new Date().toISOString(),
+      authenticationMethod: "trusted_proxy",
+    };
+  }
+
+  private requireTlsBoundary(req: Request): void {
+    if (this.configuration.allowInsecureHttp) return;
+    const forwardedProto = singleHeader(req, "x-forwarded-proto");
+    if (req.secure || forwardedProto === "https") return;
+    throw new HeadlessAuthenticationError("Authenticated remote access requires TLS termination.", 403);
+  }
+}
diff --git a/src/services/headless-operational-readiness-service.ts b/src/services/headless-operational-readiness-service.ts
new file mode 100644
index 0000000000..7f48f171be
--- /dev/null
+++ b/src/services/headless-operational-readiness-service.ts
@@ -0,0 +1,70 @@
+import type { HeadlessOperationalReadiness } from "../contracts/headless-security-types.js";
+import type { AutomationCredentialRepository } from "../repositories/automation-credential-repository.js";
+import type { AutomationAuditExportService } from "./automation-audit-export-service.js";
+import type { KeyProvider } from "./credentials/key-provider.js";
+import type { HeadlessSecurityConfiguration } from "../contracts/headless-security-types.js";
+
+export class HeadlessOperationalReadinessService {
+  private current: HeadlessOperationalReadiness = {
+    status: "NOT_READY",
+    checkedAt: new Date(0).toISOString(),
+    components: {
+      credentialKey: { status: "not_ready", reason: "Credential key readiness has not been checked." },
+      auditStore: { status: "not_ready", reason: "Audit store readiness has not been checked." },
+      distributedRunner: { status: "not_ready", reason: "Runner identity readiness has not been checked." },
+    },
+  };
+
+  constructor(private readonly dependencies: {
+    credentialRepository: AutomationCredentialRepository;
+    keyProvider: KeyProvider;
+    auditService: AutomationAuditExportService;
+    security: HeadlessSecurityConfiguration;
+  }) {}
+
+  snapshot(): HeadlessOperationalReadiness {
+    return structuredClone(this.current);
+  }
+
+  async refresh(): Promise<HeadlessOperationalReadiness> {
+    const encryptedSecretCount = this.dependencies.credentialRepository.countEncryptedSecrets();
+    const keyRequired = encryptedSecretCount > 0 || this.dependencies.security.remoteCredentialManagement;
+    const keyHealth = await this.dependencies.keyProvider.health();
+    const credentialKey = keyRequired
+      ? keyHealth.available && keyHealth.secure
+        ? { status: "ready" as const, provider: keyHealth.provider }
+        : {
+            status: "not_ready" as const,
+            provider: keyHealth.provider,
+            reason: keyHealth.reason ?? "The configured credential key provider is unavailable.",
+          }
+      : { status: "not_required" as const, provider: keyHealth.provider };
+    const auditStore = this.dependencies.auditService.health()
+      ? { status: "ready" as const }
+      : { status: "not_ready" as const, reason: "The durable audit store is unavailable." };
+    const distributedRunner = this.dependencies.security.mode === "local"
+      ? { status: "not_required" as const }
+      : this.dependencies.security.serviceIdentities.some((identity) =>
+          identity.enabled && identity.roles.includes("automation_runner") && identity.projectIds.length > 0
+        )
+        ? { status: "ready" as const }
+        : { status: "not_ready" as const, reason: "No enabled, project-scoped service identity is configured." };
+    const ready = credentialKey.status !== "not_ready"
+      && auditStore.status !== "not_ready"
+      && distributedRunner.status !== "not_ready";
+    this.current = {
+      status: ready ? "READY" : "NOT_READY",
+      checkedAt: new Date().toISOString(),
+      components: { credentialKey, auditStore, distributedRunner },
+    };
+    return this.snapshot();
+  }
+
+  async assertStartupReady(): Promise<void> {
+    const status = await this.refresh();
+    const encryptedSecretCount = this.dependencies.credentialRepository.countEncryptedSecrets();
+    if (encryptedSecretCount > 0 && status.components.credentialKey.status !== "ready") {
+      throw new Error(`Encrypted credential data exists but key recovery is unavailable: ${status.components.credentialKey.reason ?? "unknown reason"}`);
+    }
+  }
+}
diff --git a/src/services/node-flow-runtime-service.ts b/src/services/node-flow-runtime-service.ts
index 9a7991676b..c36615e7e6 100644
--- a/src/services/node-flow-runtime-service.ts
+++ b/src/services/node-flow-runtime-service.ts
@@ -21,6 +21,7 @@ import type { ApprovalService } from "./node-flows/approval-service.js";
 import { ApprovalRequiredError } from "./node-flows/approval-service.js";
 import type { OutboxService } from "./node-flows/outbox-service.js";
 import type { CustomNodeRuntimeService } from "./custom-nodes/custom-node-runtime-service.js";
+import type { AutomationAuditExportService } from "./automation-audit-export-service.js";
 import type { NodeFlowFailureClassification } from "../contracts/node-flow-execution-policy-types.js";
 import { buildProviderInvocationWorkspaceOptions } from "../infrastructure/providers/cli/invocation-workspace-preparer.js";
 import type {
@@ -57,6 +58,7 @@ interface NodeFlowRuntimeDeps {
   approvalService?: ApprovalService;
   outboxService?: OutboxService;
   customNodeRuntimeService?: CustomNodeRuntimeService;
+  auditService?: AutomationAuditExportService;
 }
 
 interface RuntimeContext {
@@ -156,6 +158,7 @@ export class NodeFlowRuntimeService {
       input: sanitizedInput,
       startedAt: null,
     });
+    this.deps.auditService?.recordSystem({ action: "automation.run.started", resourceType: "node_flow_run", resourceId: run.id, projectId, outcome: "succeeded", metadata: { flowId: flow.id, publicationId: publication.id, version: publication.version, triggerType: options.triggerType ?? "manual" } });
     const executorId = options.executorId?.trim() || `node-flow-runtime:${process.pid}:${randomUUID()}`;
     const claimedRun = new NodeFlowQueueService(this.deps.nodeFlowRepository).claim(run, executorId);
     const leaseService = new NodeFlowLeaseService(this.deps.nodeFlowRepository);
@@ -249,6 +252,7 @@ export class NodeFlowRuntimeService {
         context.outputs.set(node.id, result.output);
         if (result.selectedPorts) context.selectedPorts.set(node.id, new Set(result.selectedPorts));
         attemptService.succeed(attempt, maskSecrets(result.output), result.invocationId);
+        this.deps.auditService?.recordSystem({ action: "automation.attempt.succeeded", resourceType: "node_flow_attempt", resourceId: attempt.id, projectId, outcome: "succeeded", metadata: { runId: run.id, flowId: flow.id, nodeId: node.id, attemptNumber } });
         this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, {
           status: "succeeded",
           executionInvocationId: result.invocationId ?? nodeRun.executionInvocationId,
@@ -261,6 +265,7 @@ export class NodeFlowRuntimeService {
         clearTimeout(timeout); options.signal?.removeEventListener("abort", parentAbort); context.options = previousOptions;
         const message = error instanceof Error ? error.message : String(error);
         const classification = classifyFailure(error, options.signal?.aborted === true, timeoutController.signal.aborted);
+        this.deps.auditService?.recordSystem({ action: "automation.attempt.failed", resourceType: "node_flow_attempt", resourceId: attempt.id, projectId, outcome: "failed", metadata: { runId: run.id, flowId: flow.id, nodeId: node.id, attemptNumber, classification } });
         if (error instanceof ApprovalRequiredError) {
           attemptService.fail(attempt, "permanent", message, false);
           this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, {
@@ -343,6 +348,7 @@ export class NodeFlowRuntimeService {
         status: terminalStatus,
       },
     });
+    this.deps.auditService?.recordSystem({ action: "automation.run.finished", resourceType: "node_flow_run", resourceId: run.id, projectId, outcome: terminalStatus === "succeeded" ? "succeeded" : "failed", metadata: { flowId: flow.id, publicationId: publication.id, status: terminalStatus } });
 
     clearInterval(heartbeatTimer);
     return {
diff --git a/src/services/node-flows/approval-service.ts b/src/services/node-flows/approval-service.ts
index 4391688f35..da353c9d48 100644
--- a/src/services/node-flows/approval-service.ts
+++ b/src/services/node-flows/approval-service.ts
@@ -1,6 +1,7 @@
 import { ValidationError } from "../../repositories/repository-utils.js";
 import { AutomationApprovalRepository, type AutomationApprovalRecord } from "../../repositories/automation-approval-repository.js";
 import type { NodeFlowJsonObject } from "../../contracts/node-flow-types.js";
+import type { AutomationAuditExportService } from "../automation-audit-export-service.js";
 
 export class ApprovalRequiredError extends Error {
   constructor(public readonly approval: AutomationApprovalRecord) {
@@ -10,7 +11,7 @@ export class ApprovalRequiredError extends Error {
 }
 
 export class ApprovalService {
-  constructor(private readonly repository: AutomationApprovalRepository) {}
+  constructor(private readonly repository: AutomationApprovalRepository, private readonly auditService?: AutomationAuditExportService) {}
 
   requireApproval(input: {
     projectId: string; flowId: string; runId: string; nodeId: string;
@@ -21,6 +22,7 @@ export class ApprovalService {
     const approval = this.repository.getForItem(input.runId, input.nodeId, logicalItem)
       ?? this.repository.request({ ...input, logicalItem });
     if (approval.status === "approved") return approval;
+    this.auditService?.recordSystem({ action: "approval.requested", resourceType: "automation_approval", resourceId: approval.id, projectId: approval.projectId, outcome: "succeeded", metadata: { flowId: approval.flowId, runId: approval.runId, nodeId: approval.nodeId, logicalItem: approval.logicalItem } });
     if (approval.status === "rejected" || approval.status === "expired") {
       throw new ValidationError(`Approval ${approval.id} is ${approval.status}.`);
     }
@@ -28,10 +30,14 @@ export class ApprovalService {
   }
 
   approve(id: string, decidedBy: string, decision: NodeFlowJsonObject = {}): AutomationApprovalRecord {
-    return this.repository.decide(id, { status: "approved", decidedBy, decision });
+    const approval = this.repository.decide(id, { status: "approved", decidedBy, decision });
+    this.auditService?.recordSystem({ action: "approval.approved", resourceType: "automation_approval", resourceId: approval.id, projectId: approval.projectId, outcome: "succeeded", principalId: decidedBy, metadata: { flowId: approval.flowId, runId: approval.runId, nodeId: approval.nodeId } });
+    return approval;
   }
   reject(id: string, decidedBy: string, decision: NodeFlowJsonObject = {}): AutomationApprovalRecord {
-    return this.repository.decide(id, { status: "rejected", decidedBy, decision });
+    const approval = this.repository.decide(id, { status: "rejected", decidedBy, decision });
+    this.auditService?.recordSystem({ action: "approval.rejected", resourceType: "automation_approval", resourceId: approval.id, projectId: approval.projectId, outcome: "succeeded", principalId: decidedBy, metadata: { flowId: approval.flowId, runId: approval.runId, nodeId: approval.nodeId } });
+    return approval;
   }
   listForRun(runId: string): AutomationApprovalRecord[] { return this.repository.listForRun(runId); }
 }
diff --git a/src/services/node-flows/outbox-service.ts b/src/services/node-flows/outbox-service.ts
index 8c1bfef991..f825e234ac 100644
--- a/src/services/node-flows/outbox-service.ts
+++ b/src/services/node-flows/outbox-service.ts
@@ -1,11 +1,12 @@
 import { AutomationOutboxRepository, type AutomationOutboxRecord } from "../../repositories/automation-outbox-repository.js";
 import type { NodeFlowJsonObject } from "../../contracts/node-flow-types.js";
+import type { AutomationAuditExportService } from "../automation-audit-export-service.js";
 
 export interface SideEffectProviderResult { providerMessageId: string }
 export interface SideEffectProvider { send(effectType: string, payload: NodeFlowJsonObject, idempotencyKey: string): Promise<SideEffectProviderResult> }
 
 export class OutboxService {
-  constructor(private readonly repository: AutomationOutboxRepository, private readonly provider: SideEffectProvider) {
+  constructor(private readonly repository: AutomationOutboxRepository, private readonly provider: SideEffectProvider, private readonly auditService?: AutomationAuditExportService) {
     this.repository.recoverSending();
   }
 
@@ -19,10 +20,14 @@ export class OutboxService {
     if (!claimed) return this.repository.get(record.id)!;
     try {
       const result = await this.provider.send(claimed.effectType, claimed.payload, claimed.idempotencyKey);
-      return this.repository.markSent(claimed.id, result.providerMessageId);
+      const sent = this.repository.markSent(claimed.id, result.providerMessageId);
+      this.auditService?.recordSystem({ action: "outbox.delivered", resourceType: "automation_outbox", resourceId: claimed.id, projectId: claimed.projectId, outcome: "succeeded", metadata: { runId: claimed.runId, nodeId: claimed.nodeId, effectType: claimed.effectType, idempotencyKey: claimed.idempotencyKey } });
+      return sent;
     } catch (error) {
       const unknownOutcome = error instanceof UnknownSideEffectOutcomeError;
-      return this.repository.markFailed(claimed.id, error instanceof Error ? error.message : String(error), unknownOutcome);
+      const failed = this.repository.markFailed(claimed.id, error instanceof Error ? error.message : String(error), unknownOutcome);
+      this.auditService?.recordSystem({ action: "outbox.delivery", resourceType: "automation_outbox", resourceId: claimed.id, projectId: claimed.projectId, outcome: "failed", metadata: { runId: claimed.runId, nodeId: claimed.nodeId, effectType: claimed.effectType, unknownOutcome } });
+      return failed;
     }
   }
 }
diff --git a/src/worker/index.ts b/src/worker/index.ts
index c88de58aee..14fd6448fe 100644
--- a/src/worker/index.ts
+++ b/src/worker/index.ts
@@ -524,6 +524,7 @@ async function createRemoteControlPlaneClient(config: WorkerConfig): Promise<Wor
       requestInit: {
         headers: {
           Authorization: `Bearer ${config.controlPlaneAuthToken}`,
+          ...(config.serviceIdentityId ? { "X-Code-UX-Service-Id": config.serviceIdentityId } : {}),
         },
       },
     },
diff --git a/src/worker/worker-config.ts b/src/worker/worker-config.ts
index e568ba23d3..18714e11f0 100644
--- a/src/worker/worker-config.ts
+++ b/src/worker/worker-config.ts
@@ -15,6 +15,7 @@ export interface WorkerConfig {
   sessionPollIntervalMs: number;
   controlPlaneUrl?: string;
   controlPlaneAuthToken?: string;
+  serviceIdentityId?: string;
   serverCommand: string;
   serverArgs: string[];
   serverCwd?: string;
@@ -104,6 +105,9 @@ export function loadWorkerConfig(argv: string[] = process.argv): WorkerConfig {
       || process.env.MCP_HTTP_AUTH_TOKEN?.trim()
       || process.env.MCP_HTTPS_AUTH_TOKEN?.trim()
       || undefined,
+    serviceIdentityId: parseStringFlag(argv, "--service-identity-id")?.trim()
+      || process.env.CODE_UX_WORKER_SERVICE_ID?.trim()
+      || undefined,
     serverCommand: parseStringFlag(argv, "--server-command")?.trim() || defaultServer.command,
     serverArgs: serverArgs.length > 0 ? serverArgs : defaultServer.args,
     serverCwd: parseStringFlag(argv, "--server-cwd")?.trim() || undefined,
diff --git a/tests/backend/server/headless-dashboard-auth.test.ts b/tests/backend/server/headless-dashboard-auth.test.ts
new file mode 100644
index 0000000000..3d6d460c62
--- /dev/null
+++ b/tests/backend/server/headless-dashboard-auth.test.ts
@@ -0,0 +1,85 @@
+import { createHash } from "node:crypto";
+import express from "express";
+import request from "supertest";
+import { describe, expect, it } from "vitest";
+import { applyDashboardPreRouteMiddleware } from "../../../src/server/dashboard-middleware.js";
+import type { DashboardServerOptions } from "../../../src/server/dashboard-server.js";
+import { configureDashboardApp } from "../../../src/server/dashboard-server.js";
+import type { HeadlessOperationalReadinessService } from "../../../src/services/headless-operational-readiness-service.js";
+import { HeadlessAuthService } from "../../../src/services/headless-auth-service.js";
+import { createLogger } from "../../../src/shared/logging/logger.js";
+
+describe("headless dashboard API authentication", () => {
+  const token = "headless-dashboard-fixture-token";
+  const authService = new HeadlessAuthService({
+    mode: "service_token",
+    serviceIdentities: [{
+      id: "author",
+      displayName: "Automation author",
+      tokenSha256: createHash("sha256").update(token).digest("hex"),
+      roles: ["automation_author", "automation_runner", "viewer"],
+      projectIds: ["project-one"],
+      enabled: true,
+    }],
+    allowInsecureHttp: false,
+    remoteCredentialManagement: false,
+  });
+
+  function app() {
+    const application = express();
+    applyDashboardPreRouteMiddleware(application, {
+      headlessAuthService: authService,
+    } as DashboardServerOptions, createLogger({ level: "error" }));
+    application.get("/api/projects/:projectId/node-flows", (req, res) => res.json({ projectId: req.params.projectId }));
+    application.get("/api/projects/:projectId/credentials", (_req, res) => res.json({ secret: "must-not-run" }));
+    return application;
+  }
+
+  it("rejects missing identity, insecure transport, unauthorized projects, and disabled credential administration", async () => {
+    await request(app()).get("/api/projects/project-one/node-flows").set("Host", "localhost").expect(403);
+    await request(app()).get("/api/projects/project-one/node-flows")
+      .set("Host", "localhost").set("Authorization", `Bearer ${token}`).expect(403, /TLS/);
+    await request(app()).get("/api/projects/project-two/node-flows")
+      .set("Host", "localhost").set("X-Forwarded-Proto", "https").set("Authorization", `Bearer ${token}`).expect(403, /not authorized/);
+    await request(app()).get("/api/projects/project-one/credentials")
+      .set("Host", "localhost").set("X-Forwarded-Proto", "https").set("Authorization", `Bearer ${token}`).expect(403, /credential_admin/);
+  });
+
+  it("accepts an authorized TLS request and returns a correlation id", async () => {
+    const response = await request(app()).get("/api/projects/project-one/node-flows")
+      .set("Host", "localhost")
+      .set("X-Forwarded-Proto", "https")
+      .set("Authorization", `Bearer ${token}`)
+      .expect(200);
+    expect(response.body).toEqual({ projectId: "project-one" });
+    expect(response.headers["x-correlation-id"]).toMatch(/^[a-f\d-]+$/i);
+  });
+
+  it("keeps health live while key-backed readiness fails closed", async () => {
+    const application = express();
+    const readiness = {
+      refresh: async () => ({
+        status: "NOT_READY",
+        checkedAt: new Date().toISOString(),
+        components: {
+          credentialKey: { status: "not_ready", provider: "vault", reason: "vault unavailable" },
+          auditStore: { status: "ready" },
+          distributedRunner: { status: "ready" },
+        },
+      }),
+    } as unknown as HeadlessOperationalReadinessService;
+    configureDashboardApp({
+      app: application,
+      dashboardDir: "/nonexistent",
+      liveActivityCacheMs: 1_000,
+      port: 0,
+      headlessReadinessService: readiness,
+      headlessAuthService: new HeadlessAuthService({ mode: "local", serviceIdentities: [], allowInsecureHttp: true, remoteCredentialManagement: false }),
+      isHealthy: () => ({ status: "UP" }),
+      isReady: () => ({ status: "READY" }),
+    } as DashboardServerOptions);
+    await request(application).get("/health").set("Host", "localhost").expect(200, { status: "UP" });
+    const response = await request(application).get("/ready").set("Host", "localhost").expect(503);
+    expect(response.body).toMatchObject({ status: "NOT_READY", components: { credentialKey: { provider: "vault" } } });
+  });
+});
diff --git a/tests/backend/services/credentialed-automation-e2e.test.ts b/tests/backend/services/credentialed-automation-e2e.test.ts
new file mode 100644
index 0000000000..02fd313144
--- /dev/null
+++ b/tests/backend/services/credentialed-automation-e2e.test.ts
@@ -0,0 +1,186 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { AppDbStorage } from "../../../src/repositories/app-db-storage.js";
+import { ProjectManagementRepository } from "../../../src/repositories/project-management-repository.js";
+import { AutomationCredentialRepository } from "../../../src/repositories/automation-credential-repository.js";
+import { AutomationApprovalRepository } from "../../../src/repositories/automation-approval-repository.js";
+import { AutomationOutboxRepository } from "../../../src/repositories/automation-outbox-repository.js";
+import { CustomNodeRepository } from "../../../src/repositories/custom-node-repository.js";
+import { NodeFlowRepository } from "../../../src/repositories/node-flow-repository.js";
+import { EncryptedSqliteSecretStore } from "../../../src/infrastructure/security/encrypted-sqlite-secret-store.js";
+import { CredentialBroker } from "../../../src/services/credentials/credential-broker.js";
+import type { KeyProvider } from "../../../src/services/credentials/key-provider.js";
+import { AutomationAuditExportService } from "../../../src/services/automation-audit-export-service.js";
+import { CustomNodeProjectService } from "../../../src/services/custom-nodes/custom-node-project-service.js";
+import { CustomNodeBuildService } from "../../../src/services/custom-nodes/custom-node-build-service.js";
+import { NodeFlowService } from "../../../src/services/node-flow-service.js";
+import { ApprovalRequiredError, ApprovalService } from "../../../src/services/node-flows/approval-service.js";
+import { MockSideEffectProvider, OutboxService, type SideEffectProvider } from "../../../src/services/node-flows/outbox-service.js";
+import type { CommandResult } from "../../../src/services/cli-process-runner.js";
+
+interface JobFixture { id: string; name: string; selected: boolean }
+const temporaryDirectories: string[] = [];
+
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await Promise.all(temporaryDirectories.splice(0).map((directory) => fs.rm(directory, { recursive: true, force: true })));
+});
+
+const commandResult = (stdout = "", stderr = ""): CommandResult => ({ ok: true, code: 0, stdout, stderr });
+
+describe("credentialed automation authoring-to-execution", () => {
+  it("processes exactly 20 mocked records with restart-safe delivery, rotation, and rollback", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "code-ux-credentialed-e2e-"));
+    temporaryDirectories.push(root);
+    const storage = new AppDbStorage(path.join(root, "app.db"));
+    const project = new ProjectManagementRepository(storage).createProject({
+      name: "Approved local test project",
+      sourceType: "local",
+      sourceRef: root,
+    });
+    const audit = new AutomationAuditExportService(storage);
+    const key = Buffer.alloc(32, 7);
+    const keyProvider: KeyProvider = {
+      providerName: "mock-kms",
+      health: async () => ({ available: true, secure: true, provider: "mock-kms", keyId: "fixture-key", keyVersion: 1 }),
+      getActiveKey: async () => ({ key: Buffer.from(key), keyId: "fixture-key", version: 1 }),
+      getKey: async () => ({ key: Buffer.from(key), keyId: "fixture-key", version: 1 }),
+    };
+    const credentialRepository = new AutomationCredentialRepository(storage);
+    const broker = new CredentialBroker(
+      credentialRepository,
+      new EncryptedSqliteSecretStore(credentialRepository, keyProvider),
+      keyProvider,
+      audit,
+    );
+
+    // Credential values are configured outside the graph/agent authoring path.
+    const credential = await broker.create(project.id, {
+      name: "Mock jobs and email API",
+      kind: "http",
+      value: "E2E_SECRET_CANARY",
+      capabilities: ["read", "write"],
+    });
+    broker.bind(project.id, credential.id, "jobs-api", ["read"]);
+
+    // The mocked command boundary proves generation + isolated validation/build without Docker/network access.
+    const customNodeRepository = new CustomNodeRepository(storage);
+    const customNodeProjectService = new CustomNodeProjectService();
+    const commandRunner = vi.fn(async (_command: string, args: string[]): Promise<CommandResult> => {
+      if (args[0] === "image") return commandResult(`sha256:${"d".repeat(64)}\n`);
+      if (args[0] === "run") return commandResult(JSON.stringify({ value: 1, executedAt: "2026-01-01T00:00:00.000Z" }));
+      return commandResult();
+    });
+    const customNodeBuildService = new CustomNodeBuildService({
+      repository: customNodeRepository,
+      projectService: customNodeProjectService,
+      commandRunner,
+      vulnerabilityAudit: async () => ({ passed: true, details: "mock audit passed" }),
+    });
+    const flowRepository = new NodeFlowRepository(storage);
+    const flowService = new NodeFlowService(flowRepository, undefined, broker, {
+      repository: customNodeRepository,
+      projectService: customNodeProjectService,
+      buildService: customNodeBuildService,
+      resolveProjectRoot: () => root,
+    });
+    await flowService.createCustomNode(project.id, {
+      nodeId: "fixture-record-selector",
+      name: "Fixture record selector",
+      sourceRevision: "fixture-r1",
+      createdBy: "author-agent",
+    });
+    const validation = await flowService.validateCustomNode(project.id, "fixture-record-selector", "author-agent", "invocation-build", "correlation-build");
+    expect(validation).toMatchObject({ status: "passed" });
+
+    const firstDraft = flowService.createDraft(project.id, {
+      title: "Mocked candidate outreach",
+      graph: { nodes: [{ id: "output-v1", type: "output", title: "Output v1", data: { release: "v1" } }], edges: [] },
+    });
+    flowService.publishDraft(project.id, firstDraft.flowId, firstDraft.draftRevision, "publisher-service");
+    const patched = flowService.patchDraft(firstDraft.flowId, {
+      projectId: project.id,
+      draftRevision: firstDraft.draftRevision,
+      graph: { nodes: [{ id: "output-v2", type: "output", title: "Output v2", data: { release: "v2" } }], edges: [] },
+    }).draft!;
+    flowService.publishDraft(project.id, firstDraft.flowId, patched.draftRevision, "publisher-service");
+    const publicationV2 = flowRepository.getPublication(firstDraft.flowId)!;
+
+    const fixturePath = path.resolve("tests/e2e/fixtures/headless-automation-records.json");
+    const jobApi = { list: vi.fn(async (): Promise<JobFixture[]> => JSON.parse(await fs.readFile(fixturePath, "utf8")) as JobFixture[]) };
+    const records = await jobApi.list();
+    expect(records).toHaveLength(20);
+    const selected = records.filter((record) => record.selected);
+    const drafts = selected.map((record) => ({ to: `${record.id}@example.test`, subject: "Fixture follow-up", body: `Hello ${record.name}` }));
+    expect(drafts).toHaveLength(5);
+
+    const run = flowRepository.createRun({
+      projectId: project.id,
+      flowId: firstDraft.flowId,
+      version: publicationV2.version,
+      publicationId: publicationV2.id,
+      policy: publicationV2.policy,
+      status: "queued",
+      input: { recordCount: records.length },
+    });
+    const approvalService = new ApprovalService(new AutomationApprovalRepository(storage), audit);
+    const provider = new MockSideEffectProvider();
+    const firstOutbox = new OutboxService(new AutomationOutboxRepository(storage), provider, audit);
+    for (const [index, draft] of drafts.entries()) {
+      const logicalItem = selected[index]!.id;
+      try {
+        approvalService.requireApproval({ projectId: project.id, flowId: firstDraft.flowId, runId: run.id, nodeId: "send", logicalItem, request: draft });
+      } catch (error) {
+        expect(error).toBeInstanceOf(ApprovalRequiredError);
+        approvalService.approve((error as ApprovalRequiredError).approval.id, "approver-service");
+      }
+      approvalService.requireApproval({ projectId: project.id, flowId: firstDraft.flowId, runId: run.id, nodeId: "send", logicalItem, request: draft });
+      await firstOutbox.dispatch({ projectId: project.id, flowId: firstDraft.flowId, publicationId: publicationV2.id, runId: run.id, nodeId: "send", logicalItem, effectType: "email", payload: draft });
+    }
+    expect(provider.sends).toHaveLength(5);
+
+    // A new service instance models process restart. Re-dispatch uses the durable idempotency key and sends nothing twice.
+    const restartedProvider = new MockSideEffectProvider();
+    const restartedOutbox = new OutboxService(new AutomationOutboxRepository(storage), restartedProvider, audit);
+    for (const [index, draft] of drafts.entries()) {
+      await restartedOutbox.dispatch({ projectId: project.id, flowId: firstDraft.flowId, publicationId: publicationV2.id, runId: run.id, nodeId: "send", logicalItem: selected[index]!.id, effectType: "email", payload: draft });
+    }
+    expect(restartedProvider.sends).toHaveLength(0);
+    expect(new AutomationOutboxRepository(storage).listForRun(run.id).filter((item) => item.status === "sent")).toHaveLength(5);
+
+    await broker.rotate(project.id, credential.id, "ROTATED_SECRET_CANARY");
+    const rotated = await broker.resolve({ projectId: project.id, bindingKey: "jobs-api", capability: "read", workspaceId: "run-after-rotation" });
+    expect(rotated).toMatchObject({ credentialId: credential.id, version: 2 });
+    expect(rotated.value).toBe("ROTATED_SECRET_CANARY");
+    broker.revoke(project.id, credential.id);
+    await expect(broker.resolve({ projectId: project.id, bindingKey: "jobs-api", capability: "read", workspaceId: "revoked" })).rejects.toThrow(/not active/i);
+
+    const unavailableProvider: SideEffectProvider = { send: vi.fn(async () => { throw new Error("mock email provider unavailable"); }) };
+    const failed = await new OutboxService(new AutomationOutboxRepository(storage), unavailableProvider, audit).dispatch({
+      projectId: project.id, flowId: firstDraft.flowId, publicationId: publicationV2.id, runId: run.id,
+      nodeId: "send", logicalItem: "provider-unavailable", effectType: "email", payload: { to: "nobody@example.test" },
+    });
+    expect(failed).toMatchObject({ status: "failed" });
+
+    const rolledBack = flowService.rollback(project.id, firstDraft.flowId, 1, patched.draftRevision);
+    flowService.publishDraft(project.id, firstDraft.flowId, rolledBack.draftRevision, "publisher-service");
+    expect(flowRepository.getPublication(firstDraft.flowId)?.graph.nodes[0]?.id).toBe("output-v1");
+
+    const exportedState = JSON.stringify({
+      credential: broker.list(project.id),
+      validation,
+      graph: flowRepository.getFlow(firstDraft.flowId)?.graph,
+      audit: audit.list({ projectId: project.id }),
+      drafts,
+      diagnostics: { processed: records.length, delivered: provider.sends.length },
+    });
+    expect(exportedState).not.toContain("E2E_SECRET_CANARY");
+    expect(exportedState).not.toContain("ROTATED_SECRET_CANARY");
+    expect(exportedState).not.toMatch(/Bearer\s+/i);
+    expect(jobApi.list).toHaveBeenCalledTimes(1);
+    expect(commandRunner).toHaveBeenCalled();
+    storage.close();
+  });
+});
diff --git a/tests/backend/services/headless-automation-operations.test.ts b/tests/backend/services/headless-automation-operations.test.ts
new file mode 100644
index 0000000000..b0bfbe8f65
--- /dev/null
+++ b/tests/backend/services/headless-automation-operations.test.ts
@@ -0,0 +1,135 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { Request } from "express";
+import { AppDbStorage } from "../../../src/repositories/app-db-storage.js";
+import { ProjectManagementRepository } from "../../../src/repositories/project-management-repository.js";
+import { NodeFlowRepository } from "../../../src/repositories/node-flow-repository.js";
+import { AutomationCredentialRepository } from "../../../src/repositories/automation-credential-repository.js";
+import { AutomationAuditExportService } from "../../../src/services/automation-audit-export-service.js";
+import { HeadlessAuthService } from "../../../src/services/headless-auth-service.js";
+import { HeadlessOperationalReadinessService } from "../../../src/services/headless-operational-readiness-service.js";
+import { DistributedNodeFlowRunnerService } from "../../../src/services/distributed-node-flow-runner-service.js";
+import type { CodeUxPrincipal, HeadlessSecurityConfiguration } from "../../../src/contracts/headless-security-types.js";
+import type { KeyProvider } from "../../../src/services/credentials/key-provider.js";
+
+const temporaryDirectories: string[] = [];
+
+async function storageFixture(): Promise<{ directory: string; storage: AppDbStorage }> {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "code-ux-headless-"));
+  temporaryDirectories.push(directory);
+  return { directory, storage: new AppDbStorage(path.join(directory, "app.db")) };
+}
+
+afterEach(async () => {
+  vi.unstubAllEnvs();
+  await Promise.all(temporaryDirectories.splice(0).map((directory) => fs.rm(directory, { recursive: true, force: true })));
+});
+
+function request(pathname: string, headers: Record<string, string> = {}, method = "GET"): Request {
+  return { path: pathname, method, headers, secure: headers["x-forwarded-proto"] === "https", body: {} } as unknown as Request;
+}
+
+const runnerPrincipal: CodeUxPrincipal = {
+  id: "runner-one",
+  displayName: "Runner one",
+  kind: "service",
+  roles: ["automation_runner"],
+  projectIds: [],
+  authenticatedAt: new Date().toISOString(),
+  authenticationMethod: "service_token",
+};
+
+describe("authenticated headless automation operations", () => {
+  it("authenticates service identities and enforces roles, projects, TLS, and the credential feature gate", () => {
+    const token = "fixture-service-token";
+    const configuration: HeadlessSecurityConfiguration = {
+      mode: "service_token",
+      serviceIdentities: [{
+        id: "runner-one",
+        displayName: "Runner one",
+        tokenSha256: createHash("sha256").update(token).digest("hex"),
+        roles: ["automation_runner", "viewer"],
+        projectIds: ["project-allowed"],
+        enabled: true,
+      }],
+      allowInsecureHttp: false,
+      remoteCredentialManagement: false,
+    };
+    const service = new HeadlessAuthService(configuration);
+    const headers = { authorization: `Bearer ${token}`, "x-forwarded-proto": "https", "x-code-ux-service-id": "runner-one" };
+    const principal = service.authenticate(request("/projects/project-allowed/node-flows/flow/run", headers, "POST"));
+    expect(() => service.authorize(request("/projects/project-allowed/node-flows/flow/run", headers, "POST"), principal)).not.toThrow();
+    expect(() => service.authorize(request("/projects/project-denied/node-flows/flow/run", headers, "POST"), principal)).toThrow(/not authorized/i);
+    expect(() => service.authorize(request("/projects/project-allowed/credentials", headers), principal)).toThrow(/credential_admin/i);
+    expect(() => service.authenticate(request("/projects/project-allowed/node-flows", { authorization: `Bearer ${token}` }))).toThrow(/TLS/i);
+    expect(() => service.authenticate(request("/projects/project-allowed/node-flows", { ...headers, "x-code-ux-service-id": "other" }))).toThrow(/identity assertion/i);
+  });
+
+  it("persists redacted correlation audit records and exports restart-safe NDJSON", async () => {
+    vi.stubEnv("VITEST_IN_MEMORY_DB", "false");
+    const { directory, storage } = await storageFixture();
+    const service = new AutomationAuditExportService(storage);
+    service.recordSystem({
+      action: "automation.build",
+      resourceType: "custom_node",
+      resourceId: "node-one",
+      projectId: "project-one",
+      outcome: "succeeded",
+      metadata: { authorization: "Bearer must-not-leak", nested: { apiKey: "must-not-leak" } },
+    });
+    storage.close();
+
+    const reopened = new AppDbStorage(path.join(directory, "app.db"));
+    const exported = new AutomationAuditExportService(reopened).exportNdjson({ projectId: "project-one" });
+    expect(exported).toContain("automation.build");
+    expect(exported).not.toContain("must-not-leak");
+    expect(exported).toContain("[REDACTED]");
+    reopened.close();
+  });
+
+  it("fails key readiness closed only when encrypted data requires recovery", async () => {
+    const unavailableKeyProvider: KeyProvider = {
+      providerName: "vault",
+      health: async () => ({ available: false, secure: true, provider: "vault", keyId: null, keyVersion: null, reason: "vault unavailable" }),
+      getActiveKey: async () => { throw new Error("unavailable"); },
+      getKey: async () => { throw new Error("unavailable"); },
+    };
+    const auditService = { health: () => true } as unknown as AutomationAuditExportService;
+    const optional = new HeadlessOperationalReadinessService({
+      credentialRepository: { countEncryptedSecrets: () => 0 } as unknown as AutomationCredentialRepository,
+      keyProvider: unavailableKeyProvider,
+      auditService,
+      security: { mode: "local", serviceIdentities: [], allowInsecureHttp: true, remoteCredentialManagement: false },
+    });
+    await expect(optional.refresh()).resolves.toMatchObject({ status: "READY", components: { credentialKey: { status: "not_required" } } });
+
+    const required = new HeadlessOperationalReadinessService({
+      credentialRepository: { countEncryptedSecrets: () => 1 } as unknown as AutomationCredentialRepository,
+      keyProvider: unavailableKeyProvider,
+      auditService,
+      security: { mode: "local", serviceIdentities: [], allowInsecureHttp: true, remoteCredentialManagement: false },
+    });
+    await expect(required.assertStartupReady()).rejects.toThrow(/encrypted credential data exists/i);
+    expect(required.snapshot()).toMatchObject({ status: "NOT_READY", components: { credentialKey: { provider: "vault" } } });
+  });
+
+  it("grants a queued run to exactly one authorized project-scoped runner", async () => {
+    const { directory, storage } = await storageFixture();
+    const project = new ProjectManagementRepository(storage).createProject({ name: "Approved local test project", sourceType: "local", sourceRef: directory });
+    const repository = new NodeFlowRepository(storage);
+    const flow = repository.createFlow(project.id, { title: "Distributed", graph: { nodes: [{ id: "output", type: "output", title: "Output" }], edges: [] } });
+    const publication = repository.getPublication(flow.id)!;
+    const run = repository.createRun({ projectId: project.id, flowId: flow.id, version: publication.version, publicationId: publication.id, policy: publication.policy, status: "queued" });
+    const principal = { ...runnerPrincipal, projectIds: [project.id] };
+    const first = new DistributedNodeFlowRunnerService(repository).claimNext(principal);
+    const second = new DistributedNodeFlowRunnerService(repository).claimNext(principal);
+    expect(first).toMatchObject({ id: run.id, leaseOwner: principal.id, status: "running" });
+    expect(second).toBeNull();
+    expect(new DistributedNodeFlowRunnerService(repository).heartbeat(principal, run.id, 30_000)).toBe(true);
+    expect(() => new DistributedNodeFlowRunnerService(repository).claimNext({ ...principal, kind: "user" })).toThrow(/service principal/i);
+    storage.close();
+  });
+});
diff --git a/tests/backend/worker/worker-config.test.ts b/tests/backend/worker/worker-config.test.ts
index 48bca12c0d..c8886b9b0e 100644
--- a/tests/backend/worker/worker-config.test.ts
+++ b/tests/backend/worker/worker-config.test.ts
@@ -7,6 +7,7 @@ beforeEach(() => {
   vi.stubEnv("MCP_HTTP_SERVER_URL", undefined);
   vi.stubEnv("MCP_HTTP_AUTH_TOKEN", undefined);
   vi.stubEnv("MCP_HTTPS_AUTH_TOKEN", undefined);
+  vi.stubEnv("CODE_UX_WORKER_SERVICE_ID", undefined);
 });
 
 afterEach(() => {
@@ -24,6 +25,7 @@ describe("loadWorkerConfig", () => {
     expect(config.serverArgs).toContain("worker-host");
     expect(config.controlPlaneUrl).toBeUndefined();
     expect(config.controlPlaneAuthToken).toBeUndefined();
+    expect(config.serviceIdentityId).toBeUndefined();
   });
 
   it("parses explicit worker flags", () => {
@@ -94,6 +96,14 @@ describe("loadWorkerConfig", () => {
     expect(config.controlPlaneAuthToken).toBe("worker-env-token");
   });
 
+  it("loads a runner service identity without exposing it as the bearer token", () => {
+    vi.stubEnv("CODE_UX_WORKER_SERVICE_ID", "runner-prod-1");
+    vi.stubEnv("CODE_UX_WORKER_AUTH_TOKEN", "service-token");
+    const config = loadWorkerConfig(["node", "worker.js"]);
+    expect(config.serviceIdentityId).toBe("runner-prod-1");
+    expect(config.controlPlaneAuthToken).toBe("service-token");
+  });
+
   it("keeps explicit auth token flags ahead of environment fallbacks", () => {
     vi.stubEnv("CODE_UX_WORKER_AUTH_TOKEN", "worker-env-token");
     vi.stubEnv("MCP_HTTP_AUTH_TOKEN", "mcp-env-token");
diff --git a/tests/e2e/fixtures/headless-automation-records.json b/tests/e2e/fixtures/headless-automation-records.json
new file mode 100644
index 0000000000..2bfd4aa9f1
--- /dev/null
+++ b/tests/e2e/fixtures/headless-automation-records.json
@@ -0,0 +1,22 @@
+[
+  { "id": "job-01", "name": "Candidate 01", "selected": true },
+  { "id": "job-02", "name": "Candidate 02", "selected": true },
+  { "id": "job-03", "name": "Candidate 03", "selected": true },
+  { "id": "job-04", "name": "Candidate 04", "selected": true },
+  { "id": "job-05", "name": "Candidate 05", "selected": true },
+  { "id": "job-06", "name": "Candidate 06", "selected": false },
+  { "id": "job-07", "name": "Candidate 07", "selected": false },
+  { "id": "job-08", "name": "Candidate 08", "selected": false },
+  { "id": "job-09", "name": "Candidate 09", "selected": false },
+  { "id": "job-10", "name": "Candidate 10", "selected": false },
+  { "id": "job-11", "name": "Candidate 11", "selected": false },
+  { "id": "job-12", "name": "Candidate 12", "selected": false },
+  { "id": "job-13", "name": "Candidate 13", "selected": false },
+  { "id": "job-14", "name": "Candidate 14", "selected": false },
+  { "id": "job-15", "name": "Candidate 15", "selected": false },
+  { "id": "job-16", "name": "Candidate 16", "selected": false },
+  { "id": "job-17", "name": "Candidate 17", "selected": false },
+  { "id": "job-18", "name": "Candidate 18", "selected": false },
+  { "id": "job-19", "name": "Candidate 19", "selected": false },
+  { "id": "job-20", "name": "Candidate 20", "selected": false }
+]

From f61d4dcdb13e1dd0e16615f4530a384169fb55e9 Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 07:16:32 +0000
Subject: [PATCH 09/25] fix(ci): resolve failing checks on
 task/feature-codux-21-t08-codex-6bcd6902-mrhf9zca

---
 .../headless-operational-readiness-service.ts | 22 +++++++++++--------
 .../headless-automation-operations.test.ts    |  5 ++++-
 2 files changed, 17 insertions(+), 10 deletions(-)

diff --git a/src/services/headless-operational-readiness-service.ts b/src/services/headless-operational-readiness-service.ts
index 7f48f171be..c0a204a2d9 100644
--- a/src/services/headless-operational-readiness-service.ts
+++ b/src/services/headless-operational-readiness-service.ts
@@ -29,16 +29,9 @@ export class HeadlessOperationalReadinessService {
   async refresh(): Promise<HeadlessOperationalReadiness> {
     const encryptedSecretCount = this.dependencies.credentialRepository.countEncryptedSecrets();
     const keyRequired = encryptedSecretCount > 0 || this.dependencies.security.remoteCredentialManagement;
-    const keyHealth = await this.dependencies.keyProvider.health();
     const credentialKey = keyRequired
-      ? keyHealth.available && keyHealth.secure
-        ? { status: "ready" as const, provider: keyHealth.provider }
-        : {
-            status: "not_ready" as const,
-            provider: keyHealth.provider,
-            reason: keyHealth.reason ?? "The configured credential key provider is unavailable.",
-          }
-      : { status: "not_required" as const, provider: keyHealth.provider };
+      ? await this.checkRequiredCredentialKey()
+      : { status: "not_required" as const, provider: this.dependencies.keyProvider.providerName };
     const auditStore = this.dependencies.auditService.health()
       ? { status: "ready" as const }
       : { status: "not_ready" as const, reason: "The durable audit store is unavailable." };
@@ -60,6 +53,17 @@ export class HeadlessOperationalReadinessService {
     return this.snapshot();
   }
 
+  private async checkRequiredCredentialKey(): Promise<HeadlessOperationalReadiness["components"]["credentialKey"]> {
+    const keyHealth = await this.dependencies.keyProvider.health();
+    return keyHealth.available && keyHealth.secure
+      ? { status: "ready", provider: keyHealth.provider }
+      : {
+          status: "not_ready",
+          provider: keyHealth.provider,
+          reason: keyHealth.reason ?? "The configured credential key provider is unavailable.",
+        };
+  }
+
   async assertStartupReady(): Promise<void> {
     const status = await this.refresh();
     const encryptedSecretCount = this.dependencies.credentialRepository.countEncryptedSecrets();
diff --git a/tests/backend/services/headless-automation-operations.test.ts b/tests/backend/services/headless-automation-operations.test.ts
index b0bfbe8f65..92b7160291 100644
--- a/tests/backend/services/headless-automation-operations.test.ts
+++ b/tests/backend/services/headless-automation-operations.test.ts
@@ -91,9 +91,10 @@ describe("authenticated headless automation operations", () => {
   });
 
   it("fails key readiness closed only when encrypted data requires recovery", async () => {
+    const health = vi.fn(async () => ({ available: false, secure: true, provider: "vault", keyId: null, keyVersion: null, reason: "vault unavailable" }));
     const unavailableKeyProvider: KeyProvider = {
       providerName: "vault",
-      health: async () => ({ available: false, secure: true, provider: "vault", keyId: null, keyVersion: null, reason: "vault unavailable" }),
+      health,
       getActiveKey: async () => { throw new Error("unavailable"); },
       getKey: async () => { throw new Error("unavailable"); },
     };
@@ -105,6 +106,7 @@ describe("authenticated headless automation operations", () => {
       security: { mode: "local", serviceIdentities: [], allowInsecureHttp: true, remoteCredentialManagement: false },
     });
     await expect(optional.refresh()).resolves.toMatchObject({ status: "READY", components: { credentialKey: { status: "not_required" } } });
+    expect(health).not.toHaveBeenCalled();
 
     const required = new HeadlessOperationalReadinessService({
       credentialRepository: { countEncryptedSecrets: () => 1 } as unknown as AutomationCredentialRepository,
@@ -113,6 +115,7 @@ describe("authenticated headless automation operations", () => {
       security: { mode: "local", serviceIdentities: [], allowInsecureHttp: true, remoteCredentialManagement: false },
     });
     await expect(required.assertStartupReady()).rejects.toThrow(/encrypted credential data exists/i);
+    expect(health).toHaveBeenCalledTimes(1);
     expect(required.snapshot()).toMatchObject({ status: "NOT_READY", components: { credentialKey: { provider: "vault" } } });
   });
 

From df9779c88b1c08cd305515a453f96ec04c59cc64 Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 07:43:56 +0000
Subject: [PATCH 10/25] feat(task T13): implement via codex

---
 docs-web/content/docs/operations-runbook.mdx  |   8 +
 docs-web/operations/runbook.md                |   8 +
 docs/operations/runbook.md                    |   8 +
 package.json                                  |   1 +
 .../credentialed-automation-e2e.test.ts       | 377 ++++++++++++++----
 5 files changed, 317 insertions(+), 85 deletions(-)

diff --git a/docs-web/content/docs/operations-runbook.mdx b/docs-web/content/docs/operations-runbook.mdx
index c70652c530..5fac8c0917 100644
--- a/docs-web/content/docs/operations-runbook.mdx
+++ b/docs-web/content/docs/operations-runbook.mdx
@@ -2,6 +2,12 @@
 
 Run recovery drills only against the approved local test project and mocked job/email providers.
 
+Run the complete offline drill with one command. It uses a temporary SQLite database, the checked-in 20-record fixture, authenticated in-process HTTP routes, and mocked custom-node/job/email boundaries. It does not dispatch a sprint, invoke a live provider, start Docker, or require network access.
+
+```bash
+pnpm run test:e2e:credentialed-automation
+```
+
 1. Verify a viewer can read its project and receives `403` for another project; correlate both requests in audit export.
 2. Stop the key provider with encrypted rows present. `/health` stays live, `/ready` returns `503`, and a new process refuses startup.
 3. Process the 20-record fixture, approve selected drafts, and restart after outbox enqueue. Sent idempotency keys must not invoke the provider twice; unknown outcomes require attention.
@@ -10,3 +16,5 @@ Run recovery drills only against the approved local test project and mocked job/
 6. Restore SQLite/WAL plus key versions in isolation. Keep runners disabled until readiness, audit continuity, lease ownership, approvals, and outbox counts match the backup manifest.
 
 Record database integrity, key ids/versions (never key material), last audit id, lease/outbox counts, and rollback publication. A drill passes only with 20 processed fixtures, the expected selected delivery count, no duplicate provider/idempotency ids, and no secret canary.
+
+The executable drill additionally asserts five approved and delivered messages, one provider idempotency key per message, expired pre-invocation lease recovery after reopening the database, credential version 2 after rotation, pinned version 2 versus the latest rollback publication, authenticated route failures, unavailable mocked providers, and zero canary disclosure in responses, logs, audit export, or diagnostics.
diff --git a/docs-web/operations/runbook.md b/docs-web/operations/runbook.md
index c70652c530..5fac8c0917 100644
--- a/docs-web/operations/runbook.md
+++ b/docs-web/operations/runbook.md
@@ -2,6 +2,12 @@
 
 Run recovery drills only against the approved local test project and mocked job/email providers.
 
+Run the complete offline drill with one command. It uses a temporary SQLite database, the checked-in 20-record fixture, authenticated in-process HTTP routes, and mocked custom-node/job/email boundaries. It does not dispatch a sprint, invoke a live provider, start Docker, or require network access.
+
+```bash
+pnpm run test:e2e:credentialed-automation
+```
+
 1. Verify a viewer can read its project and receives `403` for another project; correlate both requests in audit export.
 2. Stop the key provider with encrypted rows present. `/health` stays live, `/ready` returns `503`, and a new process refuses startup.
 3. Process the 20-record fixture, approve selected drafts, and restart after outbox enqueue. Sent idempotency keys must not invoke the provider twice; unknown outcomes require attention.
@@ -10,3 +16,5 @@ Run recovery drills only against the approved local test project and mocked job/
 6. Restore SQLite/WAL plus key versions in isolation. Keep runners disabled until readiness, audit continuity, lease ownership, approvals, and outbox counts match the backup manifest.
 
 Record database integrity, key ids/versions (never key material), last audit id, lease/outbox counts, and rollback publication. A drill passes only with 20 processed fixtures, the expected selected delivery count, no duplicate provider/idempotency ids, and no secret canary.
+
+The executable drill additionally asserts five approved and delivered messages, one provider idempotency key per message, expired pre-invocation lease recovery after reopening the database, credential version 2 after rotation, pinned version 2 versus the latest rollback publication, authenticated route failures, unavailable mocked providers, and zero canary disclosure in responses, logs, audit export, or diagnostics.
diff --git a/docs/operations/runbook.md b/docs/operations/runbook.md
index 7db7afc293..fe685c5dcf 100644
--- a/docs/operations/runbook.md
+++ b/docs/operations/runbook.md
@@ -4,6 +4,12 @@
 
 Run these drills against the approved local test project with mocked job/email boundaries only:
 
+Run the complete offline drill with one command. It uses a temporary SQLite database, the checked-in 20-record fixture, authenticated in-process HTTP routes, and mocked custom-node/job/email boundaries; it does not dispatch a sprint, invoke a live provider, start Docker, or require network access.
+
+```bash
+pnpm run test:e2e:credentialed-automation
+```
+
 1. Send an authenticated read using a viewer identity, then verify a different project returns `403` with the same correlation id visible in redacted audit export.
 2. Stop the key provider while encrypted rows exist. `/health` must remain live, `/ready` must return `503`, and a fresh process must refuse startup. Restore the exact key version before retrying.
 3. Start a 20-record fixture run, approve selected drafts, and restart after durable outbox enqueue. Recovery may reclaim expired pre-invocation work; it must not repeat a `sent` idempotency key. Unknown provider outcomes require attention instead of replay.
@@ -11,6 +17,8 @@ Run these drills against the approved local test project with mocked job/email b
 5. Publish a second automation version, then roll back by drafting/publishing the earlier immutable version. Existing runs stay pinned; new runs select the rollback publication.
 6. Restore the SQLite/WAL snapshot and key-provider state into isolation. Keep runner admission disabled until `/ready`, audit continuity, approval rows, leases, and outbox counts match the backup manifest.
 
+The executable drill asserts authenticated authoring and custom-node validation/publication, 20 processed records, five approved and delivered messages, one provider idempotency key per message, expired pre-invocation lease recovery after a real database reopen, credential version 2 after rotation, pinned version 2 versus the latest rollback publication, liveness/readiness behavior, authorization failures, unavailable mocked providers, and zero secret-canary disclosure in responses, logs, audit export, or diagnostics.
+
 Record the backup timestamp, database integrity result, key ids/versions (never key material), last audit id, active lease count, outbox status counts, and rollback publication id. A drill passes only with 20 processed fixture records, the expected selected-message count, no duplicate provider ids/idempotency keys, and no secret canary in any exported artifact.
 
 Alert response starts by disabling runner identities, preserving the database/WAL and audit export, and checking `/api/admin/readiness` plus `/api/admin/metrics/slo`. Do not delete attention-required attempts or manually mark uncertain outbox rows sent; reconcile them with the mocked/provider idempotency record first.
diff --git a/package.json b/package.json
index 07820a9650..d16cf4aa2d 100644
--- a/package.json
+++ b/package.json
@@ -58,6 +58,7 @@
     "test:backend": "vitest run tests/backend",
     "test:dashboard": "vitest run tests/dashboard",
     "test:e2e": "node scripts/e2e/run-playwright.mjs",
+    "test:e2e:credentialed-automation": "vitest run tests/backend/services/credentialed-automation-e2e.test.ts",
     "test:e2e:mockup-sprint-pentest": "node scripts/e2e/run-mockup-sprint-pentest.mjs",
     "test:orchestration:rapid": "vitest run tests/backend/services/virtual-worker-service.test.ts tests/backend/infrastructure/providers/cli/provider-runner.test.ts tests/backend/services/provider-routing.test.ts tests/backend/sprint/watch-loop-core.test.ts tests/backend/domain/sprint/ci/feature-pr-gate.test.ts tests/backend/infrastructure/git/local-merge.test.ts",
     "test:orchestration:ci-dag": "pnpm run build && pnpm run test:orchestration:ci-dag:run",
diff --git a/tests/backend/services/credentialed-automation-e2e.test.ts b/tests/backend/services/credentialed-automation-e2e.test.ts
index 02fd313144..98a5563e11 100644
--- a/tests/backend/services/credentialed-automation-e2e.test.ts
+++ b/tests/backend/services/credentialed-automation-e2e.test.ts
@@ -1,71 +1,160 @@
+import { createHash } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
+import express, { type Express } from "express";
+import request, { type SuperTest, type Test } from "supertest";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import type { NodeFlowJsonObject } from "../../../src/contracts/node-flow-types.js";
+import type { HeadlessSecurityConfiguration } from "../../../src/contracts/headless-security-types.js";
+import { EncryptedSqliteSecretStore } from "../../../src/infrastructure/security/encrypted-sqlite-secret-store.js";
 import { AppDbStorage } from "../../../src/repositories/app-db-storage.js";
-import { ProjectManagementRepository } from "../../../src/repositories/project-management-repository.js";
-import { AutomationCredentialRepository } from "../../../src/repositories/automation-credential-repository.js";
 import { AutomationApprovalRepository } from "../../../src/repositories/automation-approval-repository.js";
+import { AutomationCredentialRepository } from "../../../src/repositories/automation-credential-repository.js";
 import { AutomationOutboxRepository } from "../../../src/repositories/automation-outbox-repository.js";
 import { CustomNodeRepository } from "../../../src/repositories/custom-node-repository.js";
 import { NodeFlowRepository } from "../../../src/repositories/node-flow-repository.js";
-import { EncryptedSqliteSecretStore } from "../../../src/infrastructure/security/encrypted-sqlite-secret-store.js";
+import { ProjectManagementRepository } from "../../../src/repositories/project-management-repository.js";
+import { applyDashboardPreRouteMiddleware } from "../../../src/server/dashboard-middleware.js";
+import type { DashboardDependencies, DashboardServerOptions } from "../../../src/server/dashboard-server.js";
+import { registerHeadlessOperationsRoutes } from "../../../src/server/headless-operations-routes.js";
+import { registerNodeFlowRoutes } from "../../../src/server/node-flow-routes.js";
+import { AutomationAuditExportService } from "../../../src/services/automation-audit-export-service.js";
+import type { CommandResult } from "../../../src/services/cli-process-runner.js";
 import { CredentialBroker } from "../../../src/services/credentials/credential-broker.js";
 import type { KeyProvider } from "../../../src/services/credentials/key-provider.js";
-import { AutomationAuditExportService } from "../../../src/services/automation-audit-export-service.js";
-import { CustomNodeProjectService } from "../../../src/services/custom-nodes/custom-node-project-service.js";
 import { CustomNodeBuildService } from "../../../src/services/custom-nodes/custom-node-build-service.js";
+import { CustomNodeProjectService } from "../../../src/services/custom-nodes/custom-node-project-service.js";
+import { HeadlessAuthService } from "../../../src/services/headless-auth-service.js";
+import { HeadlessOperationalReadinessService } from "../../../src/services/headless-operational-readiness-service.js";
 import { NodeFlowService } from "../../../src/services/node-flow-service.js";
 import { ApprovalRequiredError, ApprovalService } from "../../../src/services/node-flows/approval-service.js";
+import { NodeFlowPublicationService } from "../../../src/services/node-flows/node-flow-publication-service.js";
+import { NodeFlowQueueService } from "../../../src/services/node-flows/node-flow-queue-service.js";
+import { NodeFlowRecoveryService } from "../../../src/services/node-flows/node-flow-recovery-service.js";
 import { MockSideEffectProvider, OutboxService, type SideEffectProvider } from "../../../src/services/node-flows/outbox-service.js";
-import type { CommandResult } from "../../../src/services/cli-process-runner.js";
+import { createLogger, type Logger } from "../../../src/shared/logging/logger.js";
 
 interface JobFixture { id: string; name: string; selected: boolean }
+
+const EXPECTED_RECORD_COUNT = 20;
+const EXPECTED_SELECTED_MESSAGE_COUNT = 5;
+const FIRST_SECRET_CANARY = "E2E_SECRET_CANARY";
+const ROTATED_SECRET_CANARY = "ROTATED_SECRET_CANARY";
+const SERVICE_TOKEN = "headless-automation-drill-token";
 const temporaryDirectories: string[] = [];
 
 afterEach(async () => {
   vi.restoreAllMocks();
+  vi.unstubAllEnvs();
   await Promise.all(temporaryDirectories.splice(0).map((directory) => fs.rm(directory, { recursive: true, force: true })));
 });
 
 const commandResult = (stdout = "", stderr = ""): CommandResult => ({ ok: true, code: 0, stdout, stderr });
 
+function authenticated(agent: SuperTest<Test>, token = SERVICE_TOKEN): Test {
+  return agent
+    .set("Host", "localhost")
+    .set("X-Forwarded-Proto", "https")
+    .set("X-Code-UX-Service-Id", "automation-drill")
+    .set("Authorization", `Bearer ${token}`);
+}
+
+function createHeadlessApp(input: {
+  nodeFlowService: NodeFlowService;
+  approvalService: ApprovalService;
+  auditService: AutomationAuditExportService;
+  readinessService: HeadlessOperationalReadinessService;
+  security: HeadlessSecurityConfiguration;
+  logger: Logger;
+}): Express {
+  const app = express();
+  const authService = new HeadlessAuthService(input.security);
+  applyDashboardPreRouteMiddleware(app, {
+    headlessAuthService: authService,
+    automationAuditService: input.auditService,
+  } as DashboardServerOptions, input.logger);
+  app.get("/health", (_req, res) => res.json({ status: "UP" }));
+  app.get("/ready", async (_req, res) => {
+    const readiness = await input.readinessService.refresh();
+    res.status(readiness.status === "READY" ? 200 : 503).json(readiness);
+  });
+  const dependencies = {
+    nodeFlowService: input.nodeFlowService,
+    approvalService: input.approvalService,
+    automationAuditService: input.auditService,
+    headlessReadinessService: input.readinessService,
+  } as DashboardDependencies;
+  registerNodeFlowRoutes(app, dependencies);
+  registerHeadlessOperationsRoutes(app, dependencies);
+  return app;
+}
+
 describe("credentialed automation authoring-to-execution", () => {
-  it("processes exactly 20 mocked records with restart-safe delivery, rotation, and rollback", async () => {
+  it("runs the complete mocked drill with authenticated authoring, restart recovery, rotation, and rollback", async () => {
+    vi.stubEnv("VITEST_IN_MEMORY_DB", "false");
     const root = await fs.mkdtemp(path.join(os.tmpdir(), "code-ux-credentialed-e2e-"));
     temporaryDirectories.push(root);
-    const storage = new AppDbStorage(path.join(root, "app.db"));
+    const databasePath = path.join(root, "app.db");
+    let storage = new AppDbStorage(databasePath);
     const project = new ProjectManagementRepository(storage).createProject({
       name: "Approved local test project",
       sourceType: "local",
       sourceRef: root,
     });
-    const audit = new AutomationAuditExportService(storage);
+    let keyAvailable = true;
     const key = Buffer.alloc(32, 7);
     const keyProvider: KeyProvider = {
       providerName: "mock-kms",
-      health: async () => ({ available: true, secure: true, provider: "mock-kms", keyId: "fixture-key", keyVersion: 1 }),
+      health: async () => ({
+        available: keyAvailable,
+        secure: true,
+        provider: "mock-kms",
+        keyId: keyAvailable ? "fixture-key" : null,
+        keyVersion: keyAvailable ? 1 : null,
+        reason: keyAvailable ? undefined : "mock key provider unavailable",
+      }),
       getActiveKey: async () => ({ key: Buffer.from(key), keyId: "fixture-key", version: 1 }),
       getKey: async () => ({ key: Buffer.from(key), keyId: "fixture-key", version: 1 }),
     };
-    const credentialRepository = new AutomationCredentialRepository(storage);
-    const broker = new CredentialBroker(
+    const security: HeadlessSecurityConfiguration = {
+      mode: "service_token",
+      serviceIdentities: [{
+        id: "automation-drill",
+        displayName: "Automation drill fixture",
+        tokenSha256: createHash("sha256").update(SERVICE_TOKEN).digest("hex"),
+        roles: ["credential_admin", "automation_author", "automation_publisher", "automation_runner", "viewer"],
+        projectIds: [project.id],
+        enabled: true,
+      }],
+      allowInsecureHttp: false,
+      remoteCredentialManagement: true,
+    };
+    const capturedLogs: string[] = [];
+    vi.spyOn(process.stderr, "write").mockImplementation(((chunk: string | Uint8Array) => {
+      capturedLogs.push(String(chunk));
+      return true;
+    }) as typeof process.stderr.write);
+    const logger = createLogger({ consoleLogLevel: "warn", environment: "production", color: false });
+
+    let audit = new AutomationAuditExportService(storage);
+    let credentialRepository = new AutomationCredentialRepository(storage);
+    let broker = new CredentialBroker(
       credentialRepository,
       new EncryptedSqliteSecretStore(credentialRepository, keyProvider),
       keyProvider,
       audit,
     );
 
-    // Credential values are configured outside the graph/agent authoring path.
+    // Secrets are supplied outside the agent-authored graph and never enter route payloads.
     const credential = await broker.create(project.id, {
       name: "Mock jobs and email API",
       kind: "http",
-      value: "E2E_SECRET_CANARY",
+      value: FIRST_SECRET_CANARY,
       capabilities: ["read", "write"],
     });
     broker.bind(project.id, credential.id, "jobs-api", ["read"]);
 
-    // The mocked command boundary proves generation + isolated validation/build without Docker/network access.
     const customNodeRepository = new CustomNodeRepository(storage);
     const customNodeProjectService = new CustomNodeProjectService();
     const commandRunner = vi.fn(async (_command: string, args: string[]): Promise<CommandResult> => {
@@ -79,106 +168,224 @@ describe("credentialed automation authoring-to-execution", () => {
       commandRunner,
       vulnerabilityAudit: async () => ({ passed: true, details: "mock audit passed" }),
     });
-    const flowRepository = new NodeFlowRepository(storage);
-    const flowService = new NodeFlowService(flowRepository, undefined, broker, {
+    let flowRepository = new NodeFlowRepository(storage);
+    let flowService = new NodeFlowService(flowRepository, undefined, broker, {
       repository: customNodeRepository,
       projectService: customNodeProjectService,
       buildService: customNodeBuildService,
       resolveProjectRoot: () => root,
     });
-    await flowService.createCustomNode(project.id, {
-      nodeId: "fixture-record-selector",
-      name: "Fixture record selector",
-      sourceRevision: "fixture-r1",
-      createdBy: "author-agent",
-    });
-    const validation = await flowService.validateCustomNode(project.id, "fixture-record-selector", "author-agent", "invocation-build", "correlation-build");
-    expect(validation).toMatchObject({ status: "passed" });
+    let approvalService = new ApprovalService(new AutomationApprovalRepository(storage), audit);
+    let readinessService = new HeadlessOperationalReadinessService({ credentialRepository, keyProvider, auditService: audit, security });
+    let app = createHeadlessApp({ nodeFlowService: flowService, approvalService, auditService: audit, readinessService, security, logger });
 
-    const firstDraft = flowService.createDraft(project.id, {
-      title: "Mocked candidate outreach",
-      graph: { nodes: [{ id: "output-v1", type: "output", title: "Output v1", data: { release: "v1" } }], edges: [] },
-    });
-    flowService.publishDraft(project.id, firstDraft.flowId, firstDraft.draftRevision, "publisher-service");
-    const patched = flowService.patchDraft(firstDraft.flowId, {
-      projectId: project.id,
-      draftRevision: firstDraft.draftRevision,
-      graph: { nodes: [{ id: "output-v2", type: "output", title: "Output v2", data: { release: "v2" } }], edges: [] },
-    }).draft!;
-    flowService.publishDraft(project.id, firstDraft.flowId, patched.draftRevision, "publisher-service");
-    const publicationV2 = flowRepository.getPublication(firstDraft.flowId)!;
-
-    const fixturePath = path.resolve("tests/e2e/fixtures/headless-automation-records.json");
-    const jobApi = { list: vi.fn(async (): Promise<JobFixture[]> => JSON.parse(await fs.readFile(fixturePath, "utf8")) as JobFixture[]) };
-    const records = await jobApi.list();
-    expect(records).toHaveLength(20);
+    expect((await request(app).get("/health").set("Host", "localhost")).body).toEqual({ status: "UP" });
+    await request(app).get("/ready").set("Host", "localhost").expect(200);
+    await request(app).get(`/api/projects/${project.id}/node-flows`)
+      .set("Host", "localhost").set("X-Forwarded-Proto", "https").expect(401);
+    await authenticated(request(app).get("/api/projects/unauthorized-project/node-flows")).expect(403, /not authorized/i);
+
+    // This fixture is the authoring agent: it uses only authenticated governed routes.
+    const customNodeResponse = await authenticated(request(app).post(`/api/projects/${project.id}/custom-nodes`))
+      .send({ nodeId: "fixture-record-selector", name: "Fixture record selector", sourceRevision: "fixture-r1", createdBy: "author-agent" })
+      .expect(201);
+    expect(customNodeResponse.body).toMatchObject({ id: "fixture-record-selector", status: "draft" });
+    const validationResponse = await authenticated(request(app).post(`/api/projects/${project.id}/custom-nodes/fixture-record-selector/validate`))
+      .send({ actor: "author-agent", invocationId: "invocation-build", correlationId: "correlation-build" })
+      .expect(200);
+    expect(validationResponse.body).toMatchObject({ status: "passed" });
+    const customNodeArtifact = customNodeBuildService.publish("fixture-record-selector", "publisher-service");
+    expect(customNodeArtifact.manifest.nodeType).toBe("custom.fixture-record-selector");
+
+    const graphV1 = {
+      nodes: [
+        { id: "select", type: "custom.fixture-record-selector", title: "Select fixtures", definition: { type: "custom.fixture-record-selector", version: 1 } },
+        {
+          id: "jobs", type: "http_request", title: "Read mocked jobs", definition: { type: "http_request", version: 1 },
+          data: { url: "https://jobs.example.test/fixtures", method: "GET" },
+          credentialBindings: [{ slot: "auth", credentialId: credential.id }],
+        },
+        { id: "output-v1", type: "output", title: "Output v1", data: { release: "v1" } },
+      ],
+      edges: [{ fromNodeId: "select", toNodeId: "jobs" }, { fromNodeId: "jobs", toNodeId: "output-v1" }],
+    };
+    const draftResponse = await authenticated(request(app).post(`/api/projects/${project.id}/node-flow-drafts`))
+      .send({ title: "Mocked candidate outreach", graph: graphV1 })
+      .expect(201);
+    expect(draftResponse.body).toMatchObject({ valid: true, draftRevision: 1 });
+    expect(draftResponse.body.requiredCredentials).toEqual([
+      expect.objectContaining({ nodeId: "jobs", credentialId: credential.id, status: "bound" }),
+    ]);
+    await authenticated(request(app).post(`/api/node-flow-drafts/${draftResponse.body.flowId}/publish`))
+      .send({ projectId: project.id, draftRevision: 1, publishedBy: "publisher-service" })
+      .expect(200);
+
+    const graphV2 = structuredClone(graphV1);
+    graphV2.nodes[2] = { id: "output-v2", type: "output", title: "Output v2", data: { release: "v2" } };
+    graphV2.edges[1] = { fromNodeId: "jobs", toNodeId: "output-v2" };
+    const patchResponse = await authenticated(request(app).patch(`/api/node-flow-drafts/${draftResponse.body.flowId}`))
+      .send({ projectId: project.id, draftRevision: 1, graph: graphV2 })
+      .expect(200);
+    await authenticated(request(app).post(`/api/node-flow-drafts/${draftResponse.body.flowId}/publish`))
+      .send({ projectId: project.id, draftRevision: patchResponse.body.draft.draftRevision, publishedBy: "publisher-service" })
+      .expect(200);
+    const publicationV2 = flowRepository.getPublication(draftResponse.body.flowId);
+    expect(publicationV2?.version).toBe(2);
+
+    const initialCredential = await broker.resolve({ projectId: project.id, bindingKey: "jobs-api", capability: "read", workspaceId: "fixture-fetch" });
+    const jobApi = {
+      list: vi.fn(async (value: string): Promise<JobFixture[]> => {
+        expect(value).toBe(FIRST_SECRET_CANARY);
+        return JSON.parse(await fs.readFile(path.resolve("tests/e2e/fixtures/headless-automation-records.json"), "utf8")) as JobFixture[];
+      }),
+      authenticate: vi.fn(async (_value: string, _version: number): Promise<void> => undefined),
+      unavailable: vi.fn(async (): Promise<JobFixture[]> => { throw new Error("mock jobs provider unavailable"); }),
+    };
+    const records = await jobApi.list(initialCredential.value);
+    expect(records).toHaveLength(EXPECTED_RECORD_COUNT);
     const selected = records.filter((record) => record.selected);
-    const drafts = selected.map((record) => ({ to: `${record.id}@example.test`, subject: "Fixture follow-up", body: `Hello ${record.name}` }));
-    expect(drafts).toHaveLength(5);
+    const drafts: NodeFlowJsonObject[] = selected.map((record) => ({
+      to: `${record.id}@example.test`, subject: "Fixture follow-up", body: `Hello ${record.name}`,
+    }));
+    expect(drafts).toHaveLength(EXPECTED_SELECTED_MESSAGE_COUNT);
 
     const run = flowRepository.createRun({
       projectId: project.id,
-      flowId: firstDraft.flowId,
-      version: publicationV2.version,
-      publicationId: publicationV2.id,
-      policy: publicationV2.policy,
+      flowId: draftResponse.body.flowId,
+      version: publicationV2!.version,
+      publicationId: publicationV2!.id,
+      policy: publicationV2!.policy,
       status: "queued",
       input: { recordCount: records.length },
     });
-    const approvalService = new ApprovalService(new AutomationApprovalRepository(storage), audit);
-    const provider = new MockSideEffectProvider();
-    const firstOutbox = new OutboxService(new AutomationOutboxRepository(storage), provider, audit);
+    const claimed = new NodeFlowQueueService(flowRepository).claim(run, "worker-before-restart");
+    const nodeRun = flowRepository.createNodeRun({
+      runId: run.id, flowId: run.flowId, projectId: project.id, nodeId: "send", status: "running",
+    });
+    const activeAttempt = flowRepository.createNodeAttempt({
+      runId: run.id, nodeRunId: nodeRun.id, nodeId: "send", attemptNumber: 1, status: "running",
+      executorId: claimed.leaseOwner!, invocationId: null, artifactDigest: null, input: { processed: 0 }, output: null,
+      credentialIds: [credential.id], failureClassification: null, retryDecision: null, errorMessage: null,
+      startedAt: new Date().toISOString(), finishedAt: null,
+    });
     for (const [index, draft] of drafts.entries()) {
       const logicalItem = selected[index]!.id;
       try {
-        approvalService.requireApproval({ projectId: project.id, flowId: firstDraft.flowId, runId: run.id, nodeId: "send", logicalItem, request: draft });
+        approvalService.requireApproval({ projectId: project.id, flowId: run.flowId, runId: run.id, nodeId: "send", logicalItem, request: draft });
       } catch (error) {
         expect(error).toBeInstanceOf(ApprovalRequiredError);
         approvalService.approve((error as ApprovalRequiredError).approval.id, "approver-service");
       }
-      approvalService.requireApproval({ projectId: project.id, flowId: firstDraft.flowId, runId: run.id, nodeId: "send", logicalItem, request: draft });
-      await firstOutbox.dispatch({ projectId: project.id, flowId: firstDraft.flowId, publicationId: publicationV2.id, runId: run.id, nodeId: "send", logicalItem, effectType: "email", payload: draft });
+      approvalService.requireApproval({ projectId: project.id, flowId: run.flowId, runId: run.id, nodeId: "send", logicalItem, request: draft });
+    }
+    expect(approvalService.listForRun(run.id).filter((approval) => approval.status === "approved")).toHaveLength(EXPECTED_SELECTED_MESSAGE_COUNT);
+
+    const providerBeforeRestart = new MockSideEffectProvider();
+    const outboxBeforeRestart = new OutboxService(new AutomationOutboxRepository(storage), providerBeforeRestart, audit);
+    for (let index = 0; index < 2; index += 1) {
+      await outboxBeforeRestart.dispatch({
+        projectId: project.id, flowId: run.flowId, publicationId: publicationV2!.id, runId: run.id,
+        nodeId: "send", logicalItem: selected[index]!.id, effectType: "email", payload: drafts[index]!,
+      });
     }
-    expect(provider.sends).toHaveLength(5);
+    expect(providerBeforeRestart.sends).toHaveLength(2);
+    flowRepository.updateRun(run.id, { leaseExpiresAt: "2020-01-01T00:00:00.000Z" });
+
+    // Reopen the same database to model a process restart while the run and attempt are active.
+    storage.close();
+    storage = new AppDbStorage(databasePath);
+    audit = new AutomationAuditExportService(storage);
+    credentialRepository = new AutomationCredentialRepository(storage);
+    broker = new CredentialBroker(
+      credentialRepository,
+      new EncryptedSqliteSecretStore(credentialRepository, keyProvider),
+      keyProvider,
+      audit,
+    );
+    flowRepository = new NodeFlowRepository(storage);
+    flowService = new NodeFlowService(flowRepository, undefined, broker);
+    approvalService = new ApprovalService(new AutomationApprovalRepository(storage), audit);
+    readinessService = new HeadlessOperationalReadinessService({ credentialRepository, keyProvider, auditService: audit, security });
+    app = createHeadlessApp({ nodeFlowService: flowService, approvalService, auditService: audit, readinessService, security, logger });
+
+    const [recovered] = new NodeFlowRecoveryService(flowRepository).recover();
+    expect(recovered).toMatchObject({ id: run.id, status: "queued", leaseOwner: null, leaseExpiresAt: null });
+    expect(flowRepository.listNodeAttempts(run.id)).toHaveLength(1);
+    const reclaimed = new NodeFlowQueueService(flowRepository).claim(recovered!, "worker-after-restart");
+    expect(reclaimed).toMatchObject({ status: "running", leaseOwner: "worker-after-restart" });
 
-    // A new service instance models process restart. Re-dispatch uses the durable idempotency key and sends nothing twice.
-    const restartedProvider = new MockSideEffectProvider();
-    const restartedOutbox = new OutboxService(new AutomationOutboxRepository(storage), restartedProvider, audit);
+    const providerAfterRestart = new MockSideEffectProvider();
+    const outboxAfterRestart = new OutboxService(new AutomationOutboxRepository(storage), providerAfterRestart, audit);
     for (const [index, draft] of drafts.entries()) {
-      await restartedOutbox.dispatch({ projectId: project.id, flowId: firstDraft.flowId, publicationId: publicationV2.id, runId: run.id, nodeId: "send", logicalItem: selected[index]!.id, effectType: "email", payload: draft });
+      await outboxAfterRestart.dispatch({
+        projectId: project.id, flowId: run.flowId, publicationId: publicationV2!.id, runId: run.id,
+        nodeId: "send", logicalItem: selected[index]!.id, effectType: "email", payload: draft,
+      });
     }
-    expect(restartedProvider.sends).toHaveLength(0);
-    expect(new AutomationOutboxRepository(storage).listForRun(run.id).filter((item) => item.status === "sent")).toHaveLength(5);
+    const allProviderSends = [...providerBeforeRestart.sends, ...providerAfterRestart.sends];
+    const idempotencyKeys = allProviderSends.map((send) => send.idempotencyKey);
+    expect(allProviderSends).toHaveLength(EXPECTED_SELECTED_MESSAGE_COUNT);
+    expect(new Set(idempotencyKeys)).toHaveLength(EXPECTED_SELECTED_MESSAGE_COUNT);
+    expect(idempotencyKeys.every((key) => idempotencyKeys.filter((candidate) => candidate === key).length === 1)).toBe(true);
+    const persistedOutbox = new AutomationOutboxRepository(storage).listForRun(run.id);
+    expect(persistedOutbox).toHaveLength(EXPECTED_SELECTED_MESSAGE_COUNT);
+    expect(persistedOutbox.every((item) => item.status === "sent" && idempotencyKeys.includes(item.idempotencyKey))).toBe(true);
+    flowRepository.updateNodeAttempt(activeAttempt.id, { status: "succeeded", output: { delivered: drafts.length }, retryDecision: "stop", finishedAt: new Date().toISOString() });
+    flowRepository.updateNodeRun(nodeRun.id, { status: "succeeded", output: { delivered: drafts.length }, finishedAt: new Date().toISOString() });
+    const completedRun = flowRepository.updateRun(run.id, {
+      status: "succeeded", output: { processed: records.length, delivered: drafts.length },
+      leaseOwner: null, leaseExpiresAt: null, finishedAt: new Date().toISOString(),
+    });
+    expect(completedRun).toMatchObject({ status: "succeeded", output: { processed: EXPECTED_RECORD_COUNT, delivered: EXPECTED_SELECTED_MESSAGE_COUNT } });
 
-    await broker.rotate(project.id, credential.id, "ROTATED_SECRET_CANARY");
+    await broker.rotate(project.id, credential.id, ROTATED_SECRET_CANARY);
     const rotated = await broker.resolve({ projectId: project.id, bindingKey: "jobs-api", capability: "read", workspaceId: "run-after-rotation" });
-    expect(rotated).toMatchObject({ credentialId: credential.id, version: 2 });
-    expect(rotated.value).toBe("ROTATED_SECRET_CANARY");
-    broker.revoke(project.id, credential.id);
-    await expect(broker.resolve({ projectId: project.id, bindingKey: "jobs-api", capability: "read", workspaceId: "revoked" })).rejects.toThrow(/not active/i);
+    await jobApi.authenticate(rotated.value, rotated.version);
+    expect(jobApi.authenticate).toHaveBeenCalledWith(ROTATED_SECRET_CANARY, 2);
 
-    const unavailableProvider: SideEffectProvider = { send: vi.fn(async () => { throw new Error("mock email provider unavailable"); }) };
-    const failed = await new OutboxService(new AutomationOutboxRepository(storage), unavailableProvider, audit).dispatch({
-      projectId: project.id, flowId: firstDraft.flowId, publicationId: publicationV2.id, runId: run.id,
+    const publicationService = new NodeFlowPublicationService(flowRepository);
+    expect(publicationService.resolve(run.flowId, { mode: "pinned", version: 2 }).id).toBe(run.publicationId);
+    const rollbackResponse = await authenticated(request(app).post(`/api/node-flows/${run.flowId}/rollback`))
+      .send({ projectId: project.id, version: 1, draftRevision: 2 })
+      .expect(200);
+    await authenticated(request(app).post(`/api/node-flow-drafts/${run.flowId}/publish`))
+      .send({ projectId: project.id, draftRevision: rollbackResponse.body.draftRevision, publishedBy: "publisher-service" })
+      .expect(200);
+    const latestAfterRollback = publicationService.resolve(run.flowId, { mode: "latest_published" });
+    expect(latestAfterRollback.version).toBe(3);
+    expect(latestAfterRollback.graph.nodes.some((node) => node.id === "output-v1")).toBe(true);
+    expect(publicationService.resolve(run.flowId, { mode: "pinned", version: 2 }).graph.nodes.some((node) => node.id === "output-v2")).toBe(true);
+    expect(flowRepository.getRun(run.id)).toMatchObject({ version: 2, publicationId: publicationV2!.id });
+
+    await expect(jobApi.unavailable()).rejects.toThrow(/jobs provider unavailable/i);
+    const unavailableEmailProvider: SideEffectProvider = {
+      send: vi.fn(async () => { throw new Error("mock email provider unavailable"); }),
+    };
+    const failedDelivery = await new OutboxService(new AutomationOutboxRepository(storage), unavailableEmailProvider, audit).dispatch({
+      projectId: project.id, flowId: run.flowId, publicationId: latestAfterRollback.id, runId: run.id,
       nodeId: "send", logicalItem: "provider-unavailable", effectType: "email", payload: { to: "nobody@example.test" },
     });
-    expect(failed).toMatchObject({ status: "failed" });
-
-    const rolledBack = flowService.rollback(project.id, firstDraft.flowId, 1, patched.draftRevision);
-    flowService.publishDraft(project.id, firstDraft.flowId, rolledBack.draftRevision, "publisher-service");
-    expect(flowRepository.getPublication(firstDraft.flowId)?.graph.nodes[0]?.id).toBe("output-v1");
-
-    const exportedState = JSON.stringify({
-      credential: broker.list(project.id),
-      validation,
-      graph: flowRepository.getFlow(firstDraft.flowId)?.graph,
-      audit: audit.list({ projectId: project.id }),
-      drafts,
-      diagnostics: { processed: records.length, delivered: provider.sends.length },
+    expect(failedDelivery).toMatchObject({ status: "failed", attemptCount: 1 });
+
+    broker.revoke(project.id, credential.id);
+    await expect(broker.resolve({ projectId: project.id, bindingKey: "jobs-api", capability: "read", workspaceId: "revoked" })).rejects.toThrow(/not active/i);
+    keyAvailable = false;
+    await request(app).get("/health").set("Host", "localhost").expect(200, { status: "UP" });
+    await request(app).get("/ready").set("Host", "localhost").expect(503, /mock key provider unavailable/i);
+    await expect(readinessService.assertStartupReady()).rejects.toThrow(/key recovery is unavailable/i);
+
+    logger.error("credentialed automation diagnostic", { apiKey: FIRST_SECRET_CANARY, authorization: `Bearer ${ROTATED_SECRET_CANARY}` });
+    const auditResponse = await authenticated(request(app).get(`/api/admin/audit/export?projectId=${project.id}`)).expect(200);
+    const observable = JSON.stringify({
+      routeBodies: [customNodeResponse.body, validationResponse.body, draftResponse.body, patchResponse.body, rollbackResponse.body],
+      audit: auditResponse.text,
+      logs: capturedLogs,
+      diagnostics: { processed: records.length, selected: selected.length, outbox: persistedOutbox, readiness: readinessService.snapshot() },
     });
-    expect(exportedState).not.toContain("E2E_SECRET_CANARY");
-    expect(exportedState).not.toContain("ROTATED_SECRET_CANARY");
-    expect(exportedState).not.toMatch(/Bearer\s+/i);
+    expect(observable).not.toContain(FIRST_SECRET_CANARY);
+    expect(observable).not.toContain(ROTATED_SECRET_CANARY);
+    expect(observable).not.toContain(SERVICE_TOKEN);
+    expect(observable).toContain("[REDACTED]");
     expect(jobApi.list).toHaveBeenCalledTimes(1);
     expect(commandRunner).toHaveBeenCalled();
     storage.close();

From da9c405011c2f211e6488409bb1c14dd90857167 Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 07:44:42 +0000
Subject: [PATCH 11/25] feat(task T09): implement via codex

---
 docs-web/architecture/node-flows.md           |  2 +
 .../content/docs/architecture-node-flows.mdx  |  2 +
 .../content/docs/operations-server-mode.mdx   |  2 +
 docs-web/operations/server-mode.md            |  2 +
 docs/architecture/node-flows.md               |  2 +
 docs/operations/server-mode.md                |  2 +
 src/server/dashboard-middleware.ts            | 40 ++++++++---
 src/services/headless-auth-service.ts         | 26 ++++---
 src/services/node-flow-service.ts             |  8 +++
 src/services/node-flows/approval-service.ts   |  1 +
 .../server/headless-dashboard-auth.test.ts    | 60 ++++++++++++++++
 tests/backend/server/node-flow-routes.test.ts | 70 +++++++++++++++++++
 12 files changed, 199 insertions(+), 18 deletions(-)

diff --git a/docs-web/architecture/node-flows.md b/docs-web/architecture/node-flows.md
index ed7653f450..12573fb52e 100644
--- a/docs-web/architecture/node-flows.md
+++ b/docs-web/architecture/node-flows.md
@@ -2,6 +2,8 @@
 
 Node flows are project-owned, versioned Graph v2 workflows.
 
+Authenticated dashboard routes resolve persisted project ownership from flow, run, or approval ids before authorizing the request. Drafts, publications, comparisons, rollbacks, attachments, webhook configuration, debugger data, attempts, cancellation, retry, and approvals cannot be accessed by presenting a different body or query project id. Webhook ingress remains on its path-token and webhook-secret scheme, with dashboard host and browser-origin protections still enforced.
+
 ## Implemented runtime nodes
 
 | Type | Execution |
diff --git a/docs-web/content/docs/architecture-node-flows.mdx b/docs-web/content/docs/architecture-node-flows.mdx
index b19d3c6608..f846041fde 100644
--- a/docs-web/content/docs/architecture-node-flows.mdx
+++ b/docs-web/content/docs/architecture-node-flows.mdx
@@ -2,6 +2,8 @@
 
 Node flows are project-owned, versioned Graph v2 workflows.
 
+Authenticated dashboard routes resolve persisted project ownership from flow, run, or approval ids before authorizing the request. Drafts, publications, comparisons, rollbacks, attachments, webhook configuration, debugger data, attempts, cancellation, retry, and approvals cannot be accessed by presenting a different body or query project id. Webhook ingress remains on its path-token and webhook-secret scheme, with dashboard host and browser-origin protections still enforced.
+
 ## Implemented runtime nodes
 
 | Type | Execution |
diff --git a/docs-web/content/docs/operations-server-mode.mdx b/docs-web/content/docs/operations-server-mode.mdx
index f4ec240e0e..4838b616ef 100644
--- a/docs-web/content/docs/operations-server-mode.mdx
+++ b/docs-web/content/docs/operations-server-mode.mdx
@@ -10,6 +10,8 @@ Alternatively, set `CODE_UX_DASHBOARD_AUTH_MODE=trusted_proxy`, configure `CODE_
 
 Roles are `credential_admin`, `automation_author`, `automation_publisher`, `automation_runner`, and `viewer`. Credential routes additionally require `CODE_UX_REMOTE_CREDENTIAL_MANAGEMENT=true`; enabling it without a healthy secure key provider makes readiness fail. Host/origin checks, no-store responses, and administrative rate limits remain active.
 
+The `credential_admin` role can still read administrative readiness, audit export, and SLO metrics while remote credential management is disabled. The feature flag gates credential-management and credential-health routes only.
+
 ## Probes, audit, and SLOs
 
 `/health` is liveness. `/ready` also checks credential-key recovery, the audit store, and distributed-runner identities and returns `503` when required components are unavailable. If encrypted credential rows exist and their key cannot be recovered, startup aborts before listeners bind.
diff --git a/docs-web/operations/server-mode.md b/docs-web/operations/server-mode.md
index f4ec240e0e..4838b616ef 100644
--- a/docs-web/operations/server-mode.md
+++ b/docs-web/operations/server-mode.md
@@ -10,6 +10,8 @@ Alternatively, set `CODE_UX_DASHBOARD_AUTH_MODE=trusted_proxy`, configure `CODE_
 
 Roles are `credential_admin`, `automation_author`, `automation_publisher`, `automation_runner`, and `viewer`. Credential routes additionally require `CODE_UX_REMOTE_CREDENTIAL_MANAGEMENT=true`; enabling it without a healthy secure key provider makes readiness fail. Host/origin checks, no-store responses, and administrative rate limits remain active.
 
+The `credential_admin` role can still read administrative readiness, audit export, and SLO metrics while remote credential management is disabled. The feature flag gates credential-management and credential-health routes only.
+
 ## Probes, audit, and SLOs
 
 `/health` is liveness. `/ready` also checks credential-key recovery, the audit store, and distributed-runner identities and returns `503` when required components are unavailable. If encrypted credential rows exist and their key cannot be recovered, startup aborts before listeners bind.
diff --git a/docs/architecture/node-flows.md b/docs/architecture/node-flows.md
index f8ba39cec3..6593dfb9c0 100644
--- a/docs/architecture/node-flows.md
+++ b/docs/architecture/node-flows.md
@@ -20,6 +20,8 @@ Node-flow persistence is owned by `NodeFlowRepository` and stored in SQLite:
 
 All graphs, widget schemas, run inputs, outputs, and trigger payloads are stored as JSON text and hydrated into typed contracts at the repository boundary. Flow, version, run, and attachment records belong to a project. Agent attachment operations verify that the target agent preset belongs to the same project as the flow.
 
+Authenticated dashboard requests resolve project ownership from the persisted flow, run, or approval record before role and project authorization. This applies to ID-only draft, publication, comparison, rollback, attachment, webhook-configuration, run debugger, attempt, cancellation, retry, and approval routes; a caller-supplied body or query project id is not treated as proof of ownership. Webhook ingress is the exception to dashboard bearer authentication and continues to use its path-token and webhook-secret scheme, while dashboard host and browser-origin protections still apply.
+
 ## Graph Contract
 
 The shared contract lives in `src/contracts/node-flow-types.ts`.
diff --git a/docs/operations/server-mode.md b/docs/operations/server-mode.md
index 37f1b271b5..984c89f951 100644
--- a/docs/operations/server-mode.md
+++ b/docs/operations/server-mode.md
@@ -25,6 +25,8 @@ Choose one boundary:
 
 Roles are `credential_admin`, `automation_author`, `automation_publisher`, `automation_runner`, and `viewer`. Project ids are explicit; `*` is an operator-only all-project grant. Credential routes additionally require `CODE_UX_REMOTE_CREDENTIAL_MANAGEMENT=true`. Enabling that flag without a healthy secure key provider makes readiness fail.
 
+The `credential_admin` role can read `/api/admin/readiness`, `/api/admin/audit/export`, and `/api/admin/metrics/slo` even when remote credential management is disabled. The feature flag gates credential creation, binding, testing, rotation, replacement, revocation, promotion, restriction, and credential-health routes; it does not disable operational readiness, audit, or SLO inspection.
+
 TLS is assumed at the reverse proxy. Authenticated remote requests must arrive with HTTPS or a trusted `X-Forwarded-Proto: https`; `CODE_UX_ALLOW_INSECURE_HTTP=true` is limited to isolated test networks. Same-origin browser checks, no-store headers, host validation, and a 600-request/minute administrative API limiter remain active. Webhook and provider-ingress endpoints retain their dedicated authentication schemes.
 
 Example identity generation (the JSON stores only the digest):
diff --git a/src/server/dashboard-middleware.ts b/src/server/dashboard-middleware.ts
index 67eac754bd..7d0c058c5c 100644
--- a/src/server/dashboard-middleware.ts
+++ b/src/server/dashboard-middleware.ts
@@ -45,9 +45,10 @@ export const applyDashboardPreRouteMiddleware = (
       applyDashboardSecurityHeaders(res);
     }
 
-    const isRuntimeDataPath = req.path.startsWith("/api/")
-      || req.path === "/health"
-      || req.path === "/ready";
+    const requestPath = req.path.toLowerCase();
+    const isRuntimeDataPath = requestPath.startsWith("/api/")
+      || requestPath === "/health"
+      || requestPath === "/ready";
     if (isRuntimeDataPath) {
       res.setHeader("Cache-Control", "no-store, no-cache, must-revalidate, proxy-revalidate");
       res.setHeader("Pragma", "no-cache");
@@ -68,14 +69,15 @@ export const applyDashboardPreRouteMiddleware = (
     }),
   }));
   app.use("/api", (req, res, next) => {
-    if (req.path.startsWith("/webhooks/") || req.path.includes("/ingress/")) {
+    const requestPath = req.path.toLowerCase();
+    if (requestPath.startsWith("/webhooks/") || requestPath.includes("/ingress/")) {
       next();
       return;
     }
     const startedAt = Date.now();
     try {
       const principal = authService.authenticate(req);
-      authService.authorize(req, principal);
+      authService.authorize(req, principal, resolveNodeFlowProjectId(req.path, options));
       res.locals.codeUxPrincipal = principal;
       res.on("finish", () => {
         options.automationSloService?.observeManagementRequest(Date.now() - startedAt, res.statusCode);
@@ -137,9 +139,10 @@ export const applyDashboardPreRouteMiddleware = (
   });
 
   app.use((req, res, next) => {
-    const isRuntimeDataPath = req.path.startsWith("/api/")
-      || req.path === "/health"
-      || req.path === "/ready";
+    const requestPath = req.path.toLowerCase();
+    const isRuntimeDataPath = requestPath.startsWith("/api/")
+      || requestPath === "/health"
+      || requestPath === "/ready";
 
     if (isRuntimeDataPath && !isTrustedDashboardHost(req.headers.host, req.headers["x-forwarded-host"])) {
       dashboardLogger.warn("Blocked runtime request with untrusted Host header", {
@@ -185,10 +188,29 @@ export const applyDashboardPreRouteMiddleware = (
 };
 
 function extractProjectId(pathname: string): string | null {
-  const match = pathname.match(/^\/projects\/([^/]+)/);
+  const match = pathname.match(/^\/projects\/([^/]+)/i);
   return match?.[1] ? decodeURIComponent(match[1]) : null;
 }
 
+function resolveNodeFlowProjectId(pathname: string, options: DashboardServerOptions): string | null | undefined {
+  const runMatch = pathname.match(/^\/node-flow-runs\/([^/]+)(?:\/|$)/i);
+  if (runMatch?.[1]) {
+    return options.nodeFlowService?.resolveRunProjectId(decodeURIComponent(runMatch[1])) ?? null;
+  }
+
+  const flowMatch = pathname.match(/^\/(?:node-flow-drafts|node-flows)\/([^/]+)(?:\/|$)/i);
+  if (flowMatch?.[1]) {
+    return options.nodeFlowService?.resolveFlowProjectId(decodeURIComponent(flowMatch[1])) ?? null;
+  }
+
+  const approvalMatch = pathname.match(/^\/automation-approvals\/([^/]+)(?:\/|$)/i);
+  if (approvalMatch?.[1]) {
+    return options.approvalService?.resolveProjectId(decodeURIComponent(approvalMatch[1])) ?? null;
+  }
+
+  return undefined;
+}
+
 function captureRawJsonBody(req: IncomingMessage, _res: unknown, buf: Buffer): void {
   (req as IncomingMessage & { rawBody?: string }).rawBody = buf.toString("utf8");
 }
diff --git a/src/services/headless-auth-service.ts b/src/services/headless-auth-service.ts
index ab68fa4d9e..e175af585f 100644
--- a/src/services/headless-auth-service.ts
+++ b/src/services/headless-auth-service.ts
@@ -97,7 +97,7 @@ function constantTimeHexEqual(left: string, right: string): boolean {
 function projectIdFromRequest(req: Request): string | null {
   const routeId = req.params?.projectId;
   if (typeof routeId === "string" && routeId.trim()) return routeId.trim();
-  const match = req.path.match(/^\/(?:api\/)?projects\/([^/]+)/);
+  const match = req.path.match(/^\/(?:api\/)?projects\/([^/]+)/i);
   if (match?.[1]) return decodeURIComponent(match[1]);
   const bodyProjectId = req.body && typeof req.body === "object" && typeof (req.body as Record<string, unknown>).projectId === "string"
     ? String((req.body as Record<string, unknown>).projectId).trim()
@@ -105,12 +105,20 @@ function projectIdFromRequest(req: Request): string | null {
   return bodyProjectId || null;
 }
 
+function isCredentialManagementRequest(req: Request): boolean {
+  const pathname = req.path.toLowerCase();
+  return pathname.startsWith("/api/credentials")
+    || pathname.startsWith("/credentials")
+    || /\/credentials(?:\/|$)/.test(pathname);
+}
+
 export function requiredRoleForDashboardRequest(req: Request): CodeUxRole {
-  if (req.path.startsWith("/admin/") || req.path.startsWith("/api/admin/")) return "credential_admin";
-  if (req.path.startsWith("/api/credentials") || /\/credentials(?:\/|$)/.test(req.path)) return "credential_admin";
-  if (/\/node-flows?\//.test(req.path) || req.path.includes("/node-flows")) {
-    if (/\/(publish|rollback)(?:\/|$)/.test(req.path)) return "automation_publisher";
-    if (/\/(run|retry|cancel|approve|approvals)(?:\/|$)/.test(req.path)) return "automation_runner";
+  const pathname = req.path.toLowerCase();
+  if (pathname.startsWith("/admin/") || pathname.startsWith("/api/admin/")) return "credential_admin";
+  if (isCredentialManagementRequest(req)) return "credential_admin";
+  if (/\/(?:node-flow(?:s|-drafts|-runs)?|automation-approvals)(?:\/|$)/.test(pathname)) {
+    if (/\/(publish|rollback)(?:\/|$)/.test(pathname)) return "automation_publisher";
+    if (/\/(run|retry|cancel|decision|approve|approvals)(?:\/|$)/.test(pathname)) return "automation_runner";
     return MUTATING_METHODS.has(req.method) ? "automation_author" : "viewer";
   }
   return MUTATING_METHODS.has(req.method) ? "automation_author" : "viewer";
@@ -141,18 +149,18 @@ export class HeadlessAuthService {
       : this.authenticateServiceToken(req);
   }
 
-  authorize(req: Request, principal: CodeUxPrincipal): void {
+  authorize(req: Request, principal: CodeUxPrincipal, resolvedProjectId?: string | null): void {
     const requiredRole = requiredRoleForDashboardRequest(req);
     if (!principal.roles.includes(requiredRole)) {
       throw new HeadlessAuthenticationError(`Role ${requiredRole} is required.`, 403);
     }
-    const projectId = projectIdFromRequest(req);
+    const projectId = resolvedProjectId ?? projectIdFromRequest(req);
     if (projectId && !principal.projectIds.includes("*") && !principal.projectIds.includes(projectId)) {
       throw new HeadlessAuthenticationError("The authenticated principal is not authorized for this project.", 403);
     }
     if (
       this.configuration.mode !== "local"
-      && requiredRole === "credential_admin"
+      && isCredentialManagementRequest(req)
       && !this.configuration.remoteCredentialManagement
     ) {
       throw new HeadlessAuthenticationError("Remote credential management is disabled.", 403);
diff --git a/src/services/node-flow-service.ts b/src/services/node-flow-service.ts
index 753612b958..2bdca5cae4 100644
--- a/src/services/node-flow-service.ts
+++ b/src/services/node-flow-service.ts
@@ -62,6 +62,14 @@ export class NodeFlowService {
     return this.repository.getFlow(flowId);
   }
 
+  resolveFlowProjectId(flowId: string): string | null {
+    return this.repository.getFlow(flowId)?.projectId ?? null;
+  }
+
+  resolveRunProjectId(runId: string): string | null {
+    return this.repository.getRun(runId)?.projectId ?? null;
+  }
+
   create(projectId: string, input: CreateNodeFlowInput): NodeFlowRecord {
     const title = normalizeRequiredText(input.title, "Node flow title");
     const description = normalizeOptionalText(input.description);
diff --git a/src/services/node-flows/approval-service.ts b/src/services/node-flows/approval-service.ts
index da353c9d48..e2d28759fe 100644
--- a/src/services/node-flows/approval-service.ts
+++ b/src/services/node-flows/approval-service.ts
@@ -39,5 +39,6 @@ export class ApprovalService {
     this.auditService?.recordSystem({ action: "approval.rejected", resourceType: "automation_approval", resourceId: approval.id, projectId: approval.projectId, outcome: "succeeded", principalId: decidedBy, metadata: { flowId: approval.flowId, runId: approval.runId, nodeId: approval.nodeId } });
     return approval;
   }
+  resolveProjectId(id: string): string | null { return this.repository.get(id)?.projectId ?? null; }
   listForRun(runId: string): AutomationApprovalRecord[] { return this.repository.listForRun(runId); }
 }
diff --git a/tests/backend/server/headless-dashboard-auth.test.ts b/tests/backend/server/headless-dashboard-auth.test.ts
index 3d6d460c62..081c2df8b4 100644
--- a/tests/backend/server/headless-dashboard-auth.test.ts
+++ b/tests/backend/server/headless-dashboard-auth.test.ts
@@ -5,6 +5,7 @@ import { describe, expect, it } from "vitest";
 import { applyDashboardPreRouteMiddleware } from "../../../src/server/dashboard-middleware.js";
 import type { DashboardServerOptions } from "../../../src/server/dashboard-server.js";
 import { configureDashboardApp } from "../../../src/server/dashboard-server.js";
+import { registerHeadlessOperationsRoutes } from "../../../src/server/headless-operations-routes.js";
 import type { HeadlessOperationalReadinessService } from "../../../src/services/headless-operational-readiness-service.js";
 import { HeadlessAuthService } from "../../../src/services/headless-auth-service.js";
 import { createLogger } from "../../../src/shared/logging/logger.js";
@@ -55,6 +56,65 @@ describe("headless dashboard API authentication", () => {
     expect(response.headers["x-correlation-id"]).toMatch(/^[a-f\d-]+$/i);
   });
 
+  it("permits authenticated admin operations when remote credential management is disabled", async () => {
+    const adminToken = "headless-dashboard-admin-token";
+    const application = express();
+    applyDashboardPreRouteMiddleware(application, {
+      headlessAuthService: new HeadlessAuthService({
+        mode: "service_token",
+        serviceIdentities: [{
+          id: "admin",
+          displayName: "Operations administrator",
+          tokenSha256: createHash("sha256").update(adminToken).digest("hex"),
+          roles: ["credential_admin"],
+          projectIds: ["*"],
+          enabled: true,
+        }],
+        allowInsecureHttp: false,
+        remoteCredentialManagement: false,
+      }),
+    } as DashboardServerOptions, createLogger({ level: "error" }));
+    registerHeadlessOperationsRoutes(application, {
+      automationAuditService: { exportNdjson: () => "{\"status\":\"ok\"}\n" },
+      headlessReadinessService: { refresh: async () => ({ status: "READY" }) },
+      automationSloService: { snapshot: () => ({ managementRequestCount: 1 }) },
+    } as never);
+
+    const authorized = (path: string) => request(application).get(path)
+      .set("Host", "localhost")
+      .set("X-Forwarded-Proto", "https")
+      .set("Authorization", `Bearer ${adminToken}`);
+
+    await authorized("/api/admin/readiness").expect(200);
+    await authorized("/api/admin/audit/export").expect(200);
+    await authorized("/api/admin/metrics/slo").expect(200);
+  });
+
+  it("keeps webhook ingress on its secret boundary while enforcing host and origin protections", async () => {
+    const application = express();
+    applyDashboardPreRouteMiddleware(application, {
+      headlessAuthService: authService,
+    } as DashboardServerOptions, createLogger({ level: "error" }));
+    application.post("/api/webhooks/node-flows/path-token", (_req, res) => res.json({ accepted: true }));
+
+    await request(application).post("/api/webhooks/node-flows/path-token")
+      .set("Host", "localhost")
+      .set("X-Codeux-Webhook-Secret", "webhook-secret")
+      .send({ event: "test" })
+      .expect(200, { accepted: true });
+    await request(application).post("/api/webhooks/node-flows/path-token")
+      .set("Host", "untrusted.example")
+      .set("X-Codeux-Webhook-Secret", "webhook-secret")
+      .send({ event: "test" })
+      .expect(403, /Untrusted host/);
+    await request(application).post("/api/webhooks/node-flows/path-token")
+      .set("Host", "localhost")
+      .set("Origin", "https://untrusted.example")
+      .set("X-Codeux-Webhook-Secret", "webhook-secret")
+      .send({ event: "test" })
+      .expect(403, /Cross-site/);
+  });
+
   it("keeps health live while key-backed readiness fails closed", async () => {
     const application = express();
     const readiness = {
diff --git a/tests/backend/server/node-flow-routes.test.ts b/tests/backend/server/node-flow-routes.test.ts
index f7a7a05f45..a8a8d45d22 100644
--- a/tests/backend/server/node-flow-routes.test.ts
+++ b/tests/backend/server/node-flow-routes.test.ts
@@ -1,8 +1,12 @@
+import { createHash } from "node:crypto";
 import express from "express";
 import request from "supertest";
 import { describe, expect, it, vi } from "vitest";
 import { registerNodeFlowRoutes } from "../../../src/server/node-flow-routes.js";
 import { NodeFlowValidationError } from "../../../src/domain/node-flows/node-flow-validation.js";
+import { applyDashboardPreRouteMiddleware } from "../../../src/server/dashboard-middleware.js";
+import { HeadlessAuthService } from "../../../src/services/headless-auth-service.js";
+import { createLogger } from "../../../src/shared/logging/logger.js";
 
 describe("node flow routes", () => {
   it("creates project-scoped node flows through the service", async () => {
@@ -151,4 +155,70 @@ describe("node flow routes", () => {
     expect(response.status).toBe(409);
     expect(response.body.conflict).toMatchObject({ code: "draft_revision_conflict", actualDraftRevision: 2 });
   });
+
+  it("denies project-scoped principals access to another project's flow and run resources", async () => {
+    const token = "project-one-node-flow-token";
+    const forbiddenHandler = vi.fn(() => {
+      throw new Error("A forbidden node-flow handler must not run.");
+    });
+    const nodeFlowService = {
+      resolveFlowProjectId: vi.fn((flowId: string) => flowId === "flow-two" ? "project-two" : null),
+      resolveRunProjectId: vi.fn((runId: string) => runId === "run-two" ? "project-two" : null),
+      get: forbiddenHandler,
+      runFlow: forbiddenHandler,
+      patchDraft: forbiddenHandler,
+      publishDraft: forbiddenHandler,
+      rollback: forbiddenHandler,
+      cancelRun: forbiddenHandler,
+      getRun: forbiddenHandler,
+      listNodeRuns: forbiddenHandler,
+      listNodeAttempts: forbiddenHandler,
+      list: forbiddenHandler,
+      delete: forbiddenHandler,
+    };
+    const approvalService = {
+      resolveProjectId: vi.fn((approvalId: string) => approvalId === "approval-two" ? "project-two" : null),
+      approve: forbiddenHandler,
+      reject: forbiddenHandler,
+    };
+    const app = express();
+    applyDashboardPreRouteMiddleware(app, {
+      nodeFlowService,
+      approvalService,
+      headlessAuthService: new HeadlessAuthService({
+        mode: "service_token",
+        serviceIdentities: [{
+          id: "project-one-automation",
+          displayName: "Project one automation principal",
+          tokenSha256: createHash("sha256").update(token).digest("hex"),
+          roles: ["viewer", "automation_author", "automation_publisher", "automation_runner"],
+          projectIds: ["project-one"],
+          enabled: true,
+        }],
+        allowInsecureHttp: false,
+        remoteCredentialManagement: false,
+      }),
+    } as never, createLogger({ level: "error" }));
+    registerNodeFlowRoutes(app, { nodeFlowService, approvalService } as any);
+
+    const authorized = (method: "get" | "post" | "patch" | "delete", path: string) => request(app)[method](path)
+      .set("Host", "localhost")
+      .set("X-Forwarded-Proto", "https")
+      .set("Authorization", `Bearer ${token}`);
+
+    await authorized("get", "/api/node-flows/flow-two").expect(403);
+    await authorized("post", "/api/node-flows/flow-two/run").send({ projectId: "project-one" }).expect(403);
+    await authorized("patch", "/api/node-flow-drafts/flow-two").send({ projectId: "project-one", draftRevision: 1 }).expect(403);
+    await authorized("post", "/api/node-flow-drafts/flow-two/publish").send({ projectId: "project-one", draftRevision: 1, publishedBy: "principal" }).expect(403);
+    await authorized("post", "/api/node-flows/flow-two/rollback").send({ projectId: "project-one", version: 1, draftRevision: 1 }).expect(403);
+    await authorized("post", "/api/node-flow-runs/run-two/cancel").send({ projectId: "project-one" }).expect(403);
+    await authorized("get", "/api/node-flow-runs/run-two").expect(403);
+    await authorized("get", "/api/node-flow-runs/run-two/node-runs").expect(403);
+    await authorized("get", "/api/node-flow-runs/run-two/attempts").expect(403);
+    await authorized("get", "/api/node-flows/flow-two/webhook").expect(403);
+    await authorized("post", "/api/automation-approvals/approval-two/decision").send({ decision: "approve", decidedBy: "principal" }).expect(403);
+    await authorized("get", "/API/PROJECTS/project-two/NODE-FLOWS").expect(403);
+    await authorized("delete", "/API/NODE-FLOWS/flow-two").expect(403);
+    expect(forbiddenHandler).not.toHaveBeenCalled();
+  });
 });

From a06659d463607797ee4803dfabf467df1f57d074 Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 07:46:34 +0000
Subject: [PATCH 12/25] feat(task T12): implement via codex

---
 .../docs/operations-credential-security.mdx   |   6 +
 docs-web/operations/credential-security.md    |   6 +
 docs/operations/credential-security.md        |   6 +
 src/services/node-flow-runtime-service.ts     | 233 ++++++++++++------
 .../node-flows/builtins/builtin-executors.ts  |  16 +-
 src/services/provider-execution-service.ts    |  29 ++-
 .../node-flow-runtime-service.test.ts         | 152 +++++++++++-
 7 files changed, 359 insertions(+), 89 deletions(-)

diff --git a/docs-web/content/docs/operations-credential-security.mdx b/docs-web/content/docs/operations-credential-security.mdx
index e76d076cfc..d075c473f7 100644
--- a/docs-web/content/docs/operations-credential-security.mdx
+++ b/docs-web/content/docs/operations-credential-security.mdx
@@ -11,6 +11,12 @@ Code UX resolves canonical node credential IDs and named project binding keys th
 
 Create, rotate, and replace requests are write-only. API responses contain configuration and status metadata but never stored values.
 
+## Runtime redaction boundary
+
+Node-flow credentials exist in plaintext only for the active node attempt. Exact resolved values are replaced with `[REDACTED]` before provider responses, HTTP bodies, retry errors, external-effect payloads, diagnostics, invocation messages, attempts, node outputs, or run summaries are stored. Credential IDs and non-secret metadata remain available for auditability.
+
+The same redactor protects provider activity and raw usage telemetry. Temporary credential references are cleared after the attempt and are never logged as redaction input. Custom-node outputs, stderr logs, and diagnostics follow the same rule.
+
 ## Encryption and key custody
 
 The SQLite secret store uses AES-256-GCM envelope encryption with a unique data key, payload nonce, and key-wrapping nonce for every write. Credential ownership and workspace context are authenticated. SQLite stores ciphertext, authentication tags, wrapped keys, nonces, and key identifiers/versions—not root keys.
diff --git a/docs-web/operations/credential-security.md b/docs-web/operations/credential-security.md
index e76d076cfc..d075c473f7 100644
--- a/docs-web/operations/credential-security.md
+++ b/docs-web/operations/credential-security.md
@@ -11,6 +11,12 @@ Code UX resolves canonical node credential IDs and named project binding keys th
 
 Create, rotate, and replace requests are write-only. API responses contain configuration and status metadata but never stored values.
 
+## Runtime redaction boundary
+
+Node-flow credentials exist in plaintext only for the active node attempt. Exact resolved values are replaced with `[REDACTED]` before provider responses, HTTP bodies, retry errors, external-effect payloads, diagnostics, invocation messages, attempts, node outputs, or run summaries are stored. Credential IDs and non-secret metadata remain available for auditability.
+
+The same redactor protects provider activity and raw usage telemetry. Temporary credential references are cleared after the attempt and are never logged as redaction input. Custom-node outputs, stderr logs, and diagnostics follow the same rule.
+
 ## Encryption and key custody
 
 The SQLite secret store uses AES-256-GCM envelope encryption with a unique data key, payload nonce, and key-wrapping nonce for every write. Credential ownership and workspace context are authenticated. SQLite stores ciphertext, authentication tags, wrapped keys, nonces, and key identifiers/versions—not root keys.
diff --git a/docs/operations/credential-security.md b/docs/operations/credential-security.md
index 067fe67fc7..07a3431b80 100644
--- a/docs/operations/credential-security.md
+++ b/docs/operations/credential-security.md
@@ -11,6 +11,12 @@ Code UX stores automation credentials through a broker rather than exposing secr
 
 The dashboard accepts secret values only on create, rotate, and replace requests. Responses contain configuration, scope, status, key-version, and validation metadata but never stored values. Access-event rows contain identifiers, binding keys, capabilities, outcomes, and denial reasons; they never contain secret material.
 
+## Runtime redaction boundary
+
+Node-flow execution resolves credential values only for the active node attempt. Before any provider response, HTTP body, retry error, external-effect payload, diagnostic, invocation message, attempt, node output, or run summary is persisted, the runtime replaces exact resolved values with `[REDACTED]` in addition to masking secret-shaped keys. Credential IDs and non-secret metadata remain available for audit and attempt correlation.
+
+Provider activity persistence uses the same invocation-scoped redactor, including raw usage telemetry and provider session identifiers. Temporary credential references are cleared after each attempt and are never included in redaction logs or diagnostics. Custom-node containers apply the equivalent policy to structured output, stderr logs, and diagnostics before returning control to the flow runtime.
+
 ## Encryption and key custody
 
 The SQLite secret store uses AES-256-GCM envelope encryption. Each write generates a unique 256-bit data key, payload nonce, and key-wrapping nonce. Credential ownership and workspace context are authenticated as additional data. SQLite stores only ciphertext, authentication tags, wrapped keys, nonces, and key identifiers/versions.
diff --git a/src/services/node-flow-runtime-service.ts b/src/services/node-flow-runtime-service.ts
index c36615e7e6..62dbb03225 100644
--- a/src/services/node-flow-runtime-service.ts
+++ b/src/services/node-flow-runtime-service.ts
@@ -77,6 +77,7 @@ interface RuntimeContext {
   currentAttemptId?: string;
   publicationId: string;
   subflowDepth: number;
+  resolvedCredentialValues: string[];
 }
 
 interface NodeExecutionResult {
@@ -182,6 +183,7 @@ export class NodeFlowRuntimeService {
       executorId,
       publicationId: publication.id,
       subflowDepth: options.subflowDepth ?? 0,
+      resolvedCredentialValues: [],
     };
 
     const blockedNodes = new Set<string>();
@@ -238,6 +240,7 @@ export class NodeFlowRuntimeService {
       let attemptNumber = 0;
       while (attemptNumber < retryPolicy.maxAttempts) {
         attemptNumber += 1;
+        clearResolvedCredentials(context);
         const attempt = attemptService.start(nodeRun, executorId, nodeInput, (node.credentialBindings ?? []).map((binding) => binding.credentialId));
         context.currentAttemptId = attempt.id;
         const timeoutMs = node.policy?.timeout?.timeoutMs ?? publication.policy.defaultTimeoutMs;
@@ -248,74 +251,80 @@ export class NodeFlowRuntimeService {
         const previousOptions = context.options;
         context.options = { ...options, signal: timeoutController.signal };
         try {
-        const result = await this.executeNode(context, node, nodeRun);
-        context.outputs.set(node.id, result.output);
-        if (result.selectedPorts) context.selectedPorts.set(node.id, new Set(result.selectedPorts));
-        attemptService.succeed(attempt, maskSecrets(result.output), result.invocationId);
-        this.deps.auditService?.recordSystem({ action: "automation.attempt.succeeded", resourceType: "node_flow_attempt", resourceId: attempt.id, projectId, outcome: "succeeded", metadata: { runId: run.id, flowId: flow.id, nodeId: node.id, attemptNumber } });
-        this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, {
-          status: "succeeded",
-          executionInvocationId: result.invocationId ?? nodeRun.executionInvocationId,
-          output: maskSecrets(result.output),
-          finishedAt: new Date().toISOString(),
-        });
-        clearTimeout(timeout); options.signal?.removeEventListener("abort", parentAbort); context.options = previousOptions;
-        break;
-      } catch (error) {
-        clearTimeout(timeout); options.signal?.removeEventListener("abort", parentAbort); context.options = previousOptions;
-        const message = error instanceof Error ? error.message : String(error);
-        const classification = classifyFailure(error, options.signal?.aborted === true, timeoutController.signal.aborted);
-        this.deps.auditService?.recordSystem({ action: "automation.attempt.failed", resourceType: "node_flow_attempt", resourceId: attempt.id, projectId, outcome: "failed", metadata: { runId: run.id, flowId: flow.id, nodeId: node.id, attemptNumber, classification } });
-        if (error instanceof ApprovalRequiredError) {
-          attemptService.fail(attempt, "permanent", message, false);
-          this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, {
-            status: "approval_waiting", errorMessage: message, finishedAt: null,
-          });
-          terminalStatus = "approval_waiting";
-          terminalError = message;
-          break;
-        }
-        const wasCancelled = classification === "cancelled";
-        const retryable = retryPolicy.retryableClasses.includes(classification) && attemptNumber < retryPolicy.maxAttempts;
-        attemptService.fail(attempt, classification, message, retryable, this.deps.nodeFlowRepository.listNodeAttempts(run.id).find((candidate) => candidate.id === attempt.id)?.invocationId);
-        if (retryable) {
-          this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, { status: "retry_waiting", errorMessage: message });
-          await delay(retryDelay(retryPolicy.backoffMs, retryPolicy.maxBackoffMs ?? retryPolicy.backoffMs, retryPolicy.jitterRatio ?? 0, attemptNumber), options.signal);
-          this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, { status: "running", errorMessage: null });
-          continue;
-        }
-        const continueOnError = node.data?.continueOnError === true;
-        const failureOutput = { error: message };
-        context.outputs.set(node.id, failureOutput);
-        this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, {
-          status: wasCancelled ? "cancelled" : "failed",
-          output: maskSecrets(failureOutput),
-          errorMessage: message,
-          finishedAt: new Date().toISOString(),
-        });
-        if (classification === "unknown_side_effect") {
-          terminalStatus = "attention_required";
-          terminalError = message;
-        } else if (wasCancelled) {
-          terminalStatus = "cancelled";
-          terminalError ??= message || "Node flow run was cancelled.";
-          for (const remainingNodeId of executionOrder.slice(nodeIndex + 1)) {
-            const remaining = graph.nodes.find((candidate) => candidate.id === remainingNodeId);
-            if (remaining) {
-              await this.persistSkippedNode(context, remaining, "cancelled", terminalError);
+          try {
+            const result = await this.executeNode(context, node, nodeRun);
+            const safeOutput = redactCredentialJson(result.output, context.resolvedCredentialValues);
+            context.outputs.set(node.id, safeOutput);
+            if (result.selectedPorts) context.selectedPorts.set(node.id, new Set(result.selectedPorts));
+            attemptService.succeed(attempt, safeOutput, result.invocationId);
+            this.deps.auditService?.recordSystem({ action: "automation.attempt.succeeded", resourceType: "node_flow_attempt", resourceId: attempt.id, projectId, outcome: "succeeded", metadata: { runId: run.id, flowId: flow.id, nodeId: node.id, attemptNumber } });
+            this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, {
+              status: "succeeded",
+              executionInvocationId: result.invocationId ?? nodeRun.executionInvocationId,
+              output: safeOutput,
+              finishedAt: new Date().toISOString(),
+            });
+            clearTimeout(timeout); options.signal?.removeEventListener("abort", parentAbort); context.options = previousOptions;
+            break;
+          } catch (error) {
+            clearTimeout(timeout); options.signal?.removeEventListener("abort", parentAbort); context.options = previousOptions;
+            const message = redactCredentialText(error instanceof Error ? error.message : String(error), context.resolvedCredentialValues);
+            const classification = classifyFailure(error, options.signal?.aborted === true, timeoutController.signal.aborted);
+            this.deps.auditService?.recordSystem({ action: "automation.attempt.failed", resourceType: "node_flow_attempt", resourceId: attempt.id, projectId, outcome: "failed", metadata: { runId: run.id, flowId: flow.id, nodeId: node.id, attemptNumber, classification } });
+            if (error instanceof ApprovalRequiredError) {
+              attemptService.fail(attempt, "permanent", message, false);
+              this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, {
+                status: "approval_waiting", errorMessage: message, finishedAt: null,
+              });
+              terminalStatus = "approval_waiting";
+              terminalError = message;
+              break;
             }
+            const wasCancelled = classification === "cancelled";
+            const retryable = retryPolicy.retryableClasses.includes(classification) && attemptNumber < retryPolicy.maxAttempts;
+            attemptService.fail(attempt, classification, message, retryable, this.deps.nodeFlowRepository.listNodeAttempts(run.id).find((candidate) => candidate.id === attempt.id)?.invocationId);
+            if (retryable) {
+              this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, { status: "retry_waiting", errorMessage: message });
+              clearResolvedCredentials(context);
+              await delay(retryDelay(retryPolicy.backoffMs, retryPolicy.maxBackoffMs ?? retryPolicy.backoffMs, retryPolicy.jitterRatio ?? 0, attemptNumber), options.signal);
+              this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, { status: "running", errorMessage: null });
+              continue;
+            }
+            const continueOnError = node.data?.continueOnError === true;
+            const failureOutput = { error: message };
+            context.outputs.set(node.id, failureOutput);
+            this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, {
+              status: wasCancelled ? "cancelled" : "failed",
+              output: maskSecrets(failureOutput),
+              errorMessage: message,
+              finishedAt: new Date().toISOString(),
+            });
+            if (classification === "unknown_side_effect") {
+              terminalStatus = "attention_required";
+              terminalError = message;
+            } else if (wasCancelled) {
+              terminalStatus = "cancelled";
+              terminalError ??= message || "Node flow run was cancelled.";
+              for (const remainingNodeId of executionOrder.slice(nodeIndex + 1)) {
+                const remaining = graph.nodes.find((candidate) => candidate.id === remainingNodeId);
+                if (remaining) {
+                  await this.persistSkippedNode(context, remaining, "cancelled", terminalError);
+                }
+              }
+              break;
+            }
+            if (!continueOnError) {
+              terminalStatus = "failed";
+              terminalError ??= message;
+              for (const descendant of context.descendants.get(node.id) ?? []) {
+                blockedNodes.add(descendant);
+              }
+            }
+            break;
           }
-          break;
-        }
-        if (!continueOnError) {
-          terminalStatus = "failed";
-          terminalError ??= message;
-          for (const descendant of context.descendants.get(node.id) ?? []) {
-            blockedNodes.add(descendant);
-          }
+        } finally {
+          clearResolvedCredentials(context);
         }
-        break;
-      }
       }
       if (terminalStatus === "cancelled" || terminalStatus === "attention_required" || terminalStatus === "approval_waiting") {
         break;
@@ -398,12 +407,18 @@ export class NodeFlowRuntimeService {
           status: "completed",
           finishedAt: new Date().toISOString(),
         });
-        return { ...result, invocationId: invocation.id };
+        return {
+          ...result,
+          output: redactCredentialJson(result.output, context.resolvedCredentialValues),
+          invocationId: invocation.id,
+        };
       } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+        const message = redactCredentialText(error instanceof Error ? error.message : String(error), context.resolvedCredentialValues);
+        this.deps.executionRepository.clearExecutionInvocationMessages(invocation.id);
         this.deps.executionRepository.updateExecutionInvocation(invocation.id, {
           status: context.options.signal?.aborted ? "cancelled" : "failed",
           errorMessage: message,
+          lastErrorMessage: message,
           finishedAt: new Date().toISOString(),
         });
         this.deps.executionRepository.appendExecutionInvocationMessage(invocation.id, {
@@ -431,6 +446,8 @@ export class NodeFlowRuntimeService {
           config: evaluateTemplates(readNodeConfig(node), context) as NodeFlowJsonObject,
           upstream: this.buildUpstreamObject(context, node.id), flowInput: context.input,
           signal: context.options.signal, subflowDepth: context.subflowDepth,
+          redactJson: (value) => redactCredentialJson(value, context.resolvedCredentialValues),
+          redactText: (value) => redactCredentialText(value, context.resolvedCredentialValues),
         });
     }
   }
@@ -565,11 +582,21 @@ export class NodeFlowRuntimeService {
       trackPromptInInvocation: false,
       trackAssistantInInvocation: false,
       finalizeExecutionInvocation: false,
+      onActivity: () => undefined,
+      redactTextForPersistence: (value) => redactCredentialText(value, context.resolvedCredentialValues),
+      redactJsonForPersistence: (value) => {
+        if (!value) return null;
+        return readJsonObject(redactCredentialJson(toJsonValue(value), context.resolvedCredentialValues));
+      },
     });
+    this.redactProviderInvocationUsage(invocationId, result, context.resolvedCredentialValues);
     if (!result.ok) {
-      throw new Error(providerFailureMessage(result));
+      throw new Error(redactCredentialText(providerFailureMessage(result), context.resolvedCredentialValues));
     }
-    const text = result.text ?? result.stdout ?? result.usageTelemetry.transcriptText ?? "";
+    const text = redactCredentialText(
+      result.text ?? result.stdout ?? result.usageTelemetry.transcriptText ?? "",
+      context.resolvedCredentialValues,
+    );
     this.deps.executionRepository.appendExecutionInvocationMessage(invocationId, {
       role: "assistant",
       contentMarkdown: "Node flow provider prompt completed.",
@@ -578,7 +605,9 @@ export class NodeFlowRuntimeService {
     return {
       output: {
         text,
-        nativeSessionId: result.nativeSessionId,
+        nativeSessionId: result.nativeSessionId
+          ? redactCredentialText(result.nativeSessionId, context.resolvedCredentialValues)
+          : result.nativeSessionId,
       },
       invocationId,
     };
@@ -654,22 +683,26 @@ export class NodeFlowRuntimeService {
       if (!response.ok) {
         throw new Error(`HTTP node ${node.id} failed with status ${response.status}.`);
       }
+      const safeBody = redactCredentialJson(toJsonValue(body), context.resolvedCredentialValues);
       const responsePath = readString(config.responsePath) ?? readString(config.extractJsonPath);
-      const extracted = responsePath ? readPath(body, responsePath) : body;
+      const extracted = responsePath ? readPath(safeBody, responsePath) : safeBody;
       return {
         output: {
           status: response.status,
           ok: response.ok,
-          body: toJsonValue(body),
+          body: safeBody,
           extracted: toJsonValue(extracted),
         },
         invocationId,
       };
     } catch (error) {
-      if (controller.signal.aborted) {
-        throw new Error(error instanceof Error ? error.message : `HTTP node ${node.id} timed out.`);
-      }
-      throw error;
+      const message = redactCredentialText(
+        error instanceof Error ? error.message : `HTTP node ${node.id} request failed.`,
+        context.resolvedCredentialValues,
+      );
+      if (controller.signal.aborted) throw new Error(message || `HTTP node ${node.id} timed out.`);
+      if (error instanceof Error && message === error.message) throw error;
+      throw new Error(message);
     } finally {
       clearTimeout(timeout);
       context.options.signal?.removeEventListener("abort", abortListener);
@@ -681,6 +714,7 @@ export class NodeFlowRuntimeService {
     if (!binding) return undefined;
     if (!this.deps.credentialBroker) throw new ValidationError("Credential broker is not configured for node flow runtime.");
     const resolved=await this.deps.credentialBroker.resolveCredentialId({projectId:context.projectId,credentialId:binding.credentialId,bindingKey:`${context.flowId}:${node.id}:${slot}`,capability:"read",workspaceId:context.runId});
+    if (resolved.value) context.resolvedCredentialValues.push(resolved.value);
     return resolved.value;
   }
 
@@ -780,6 +814,24 @@ export class NodeFlowRuntimeService {
     }
     return providerSettings;
   }
+
+  private redactProviderInvocationUsage(
+    invocationId: string,
+    result: ProviderRunResult,
+    credentials: readonly string[],
+  ): void {
+    const providerInvocationId = this.deps.executionRepository.getExecutionInvocation(invocationId)?.providerInvocationId;
+    if (!providerInvocationId) return;
+    const rawUsageJson = result.usageTelemetry.rawUsageJson
+      ? redactCredentialJson(toJsonValue(result.usageTelemetry.rawUsageJson), credentials)
+      : null;
+    this.deps.executionRepository.updateProviderInvocationUsage(providerInvocationId, {
+      nativeSessionId: result.nativeSessionId
+        ? redactCredentialText(result.nativeSessionId, credentials)
+        : result.nativeSessionId,
+      rawUsageJson: readJsonObject(rawUsageJson),
+    });
+  }
 }
 
 function readNodeConfig(node: NodeFlowNode): NodeFlowJsonObject {
@@ -928,6 +980,35 @@ function maskSecrets(value: NodeFlowJsonValue): NodeFlowJsonValue {
   return value;
 }
 
+function redactCredentialText(value: string, credentials: readonly string[]): string {
+  let redacted = value;
+  for (const credential of [...credentials].filter(Boolean).sort((left, right) => right.length - left.length)) {
+    redacted = redacted.split(credential).join("[REDACTED]");
+  }
+  return redacted;
+}
+
+function redactCredentialJson<T extends NodeFlowJsonValue>(value: T, credentials: readonly string[]): T;
+function redactCredentialJson(value: NodeFlowJsonObject, credentials: readonly string[]): NodeFlowJsonObject;
+function redactCredentialJson(value: NodeFlowJsonValue, credentials: readonly string[]): NodeFlowJsonValue {
+  const masked = maskSecrets(value);
+  if (typeof masked === "string") return redactCredentialText(masked, credentials);
+  if (Array.isArray(masked)) return masked.map((entry) => redactCredentialJson(entry, credentials));
+  if (masked && typeof masked === "object") {
+    return Object.fromEntries(
+      Object.entries(masked).map(([key, entry]) => [key, redactCredentialJson(entry, credentials)]),
+    );
+  }
+  return masked;
+}
+
+function clearResolvedCredentials(context: RuntimeContext): void {
+  for (let index = 0; index < context.resolvedCredentialValues.length; index += 1) {
+    context.resolvedCredentialValues[index] = "";
+  }
+  context.resolvedCredentialValues.length = 0;
+}
+
 function normalizeHeaders(headers: NodeFlowJsonObject | null): Record<string, string> {
   if (!headers) {
     return {};
diff --git a/src/services/node-flows/builtins/builtin-executors.ts b/src/services/node-flows/builtins/builtin-executors.ts
index 5a5530a138..093bffdb02 100644
--- a/src/services/node-flows/builtins/builtin-executors.ts
+++ b/src/services/node-flows/builtins/builtin-executors.ts
@@ -11,6 +11,8 @@ export interface BuiltinExecutionContext {
   projectId: string; flowId: string; publicationId: string; runId: string; nodeId: string;
   config: NodeFlowJsonObject; upstream: NodeFlowJsonObject; flowInput: NodeFlowJsonObject;
   signal?: AbortSignal; subflowDepth: number;
+  redactJson?: (value: NodeFlowJsonObject) => NodeFlowJsonObject;
+  redactText?: (value: string) => string;
 }
 export interface BuiltinExecutionResult { output: NodeFlowJsonObject; selectedPorts?: string[] }
 export interface BuiltinExecutorDependencies {
@@ -48,16 +50,17 @@ export class BuiltinExecutors {
 
   private async executeEmailSend(context: BuiltinExecutionContext): Promise<BuiltinExecutionResult> {
     if (!this.deps.approvalService || !this.deps.outboxService) throw new ValidationError("Email side-effect services are not configured.");
-    const draft = buildEmail(context);
+    const rawDraft = buildEmail(context);
+    const draft = context.redactJson?.(rawDraft) ?? rawDraft;
     const logicalItem = readString(context.config.logicalItem) ?? "default";
     this.deps.approvalService.requireApproval({ projectId: context.projectId, flowId: context.flowId, runId: context.runId,
       nodeId: context.nodeId, logicalItem, request: { effectType: "email", draft } });
     const sent = await this.deps.outboxService.dispatch({ projectId: context.projectId, flowId: context.flowId,
       publicationId: context.publicationId, runId: context.runId, nodeId: context.nodeId, logicalItem,
       effectType: "email", payload: draft });
-    if (sent.status === "attention_required") throw new Error(sent.lastError ?? "Email provider outcome is unknown.");
-    if (sent.status !== "sent") throw new Error(sent.lastError ?? "Email send failed.");
-    return { output: { sent: true, outboxId: sent.id, providerMessageId: sent.providerMessageId } };
+    if (sent.status === "attention_required") throw new Error(context.redactText?.(sent.lastError ?? "Email provider outcome is unknown.") ?? sent.lastError ?? "Email provider outcome is unknown.");
+    if (sent.status !== "sent") throw new Error(context.redactText?.(sent.lastError ?? "Email send failed.") ?? sent.lastError ?? "Email send failed.");
+    return { output: context.redactJson?.({ sent: true, outboxId: sent.id, providerMessageId: sent.providerMessageId }) ?? { sent: true, outboxId: sent.id, providerMessageId: sent.providerMessageId } };
   }
 
   private async executeSubflow(context: BuiltinExecutionContext): Promise<BuiltinExecutionResult> {
@@ -66,8 +69,9 @@ export class BuiltinExecutors {
     if (flowId === context.flowId) throw new ValidationError("A node flow cannot directly execute itself.");
     if (context.subflowDepth >= MAX_SUBFLOW_DEPTH) throw new ValidationError(`Subflow depth exceeds ${MAX_SUBFLOW_DEPTH}.`);
     if (!this.deps.executeSubflow) throw new ValidationError("Subflow execution is not configured.");
-    return { output: await this.deps.executeSubflow({ projectId: context.projectId, flowId,
-      input: readObject(context.config.input) ?? context.upstream, depth: context.subflowDepth + 1, signal: context.signal }) };
+    const output = await this.deps.executeSubflow({ projectId: context.projectId, flowId,
+      input: readObject(context.config.input) ?? context.upstream, depth: context.subflowDepth + 1, signal: context.signal });
+    return { output: context.redactJson?.(output) ?? output };
   }
 }
 
diff --git a/src/services/provider-execution-service.ts b/src/services/provider-execution-service.ts
index 2aa0606bd1..2c08247772 100644
--- a/src/services/provider-execution-service.ts
+++ b/src/services/provider-execution-service.ts
@@ -231,6 +231,10 @@ export interface ExecutionProviderRunArgs {
   trackPromptInInvocation?: boolean;
   trackAssistantInInvocation?: boolean;
   finalizeExecutionInvocation?: boolean;
+  /** Sanitizes provider-controlled text before node-flow callers allow it to reach durable records. */
+  redactTextForPersistence?: (value: string) => string;
+  /** Sanitizes provider-controlled usage payloads before durable telemetry writes. */
+  redactJsonForPersistence?: (value: Record<string, unknown> | null) => Record<string, unknown> | null;
 
   /** MCP server connection info for injecting management tools into the CLI provider. */
   mcpConnection?: McpConnectionInfo | null;
@@ -485,7 +489,9 @@ export class ProviderExecutionService {
             this.deps.executionRepository.updateProviderInvocationUsage(invocation.id, {
               status: "running",
               model: effectiveModel,
-              nativeSessionId: telemetry.nativeSessionId || undefined,
+              nativeSessionId: telemetry.nativeSessionId
+                ? args.redactTextForPersistence?.(telemetry.nativeSessionId) ?? telemetry.nativeSessionId
+                : undefined,
               durationMs,
               transcriptChars: telemetry.transcriptText.length,
               inputTokens: telemetry.inputTokens,
@@ -495,7 +501,11 @@ export class ProviderExecutionService {
               totalTokens: telemetry.totalTokens,
               toolCallCount: countConversationToolCalls(telemetry.conversation),
               usageSource: telemetry.usageSource,
-              rawUsageJson: telemetry.rawUsageJson || undefined,
+              rawUsageJson: telemetry.rawUsageJson
+                ? args.redactJsonForPersistence
+                  ? args.redactJsonForPersistence(telemetry.rawUsageJson)
+                  : telemetry.rawUsageJson
+                : undefined,
             });
             this.refreshLinkedDispatchHeartbeat(args.dispatchId);
             lastPersistedUsageSignature = usageSignature;
@@ -594,7 +604,9 @@ export class ProviderExecutionService {
           this.deps.executionRepository.updateProviderInvocationUsage(invocation.id, {
             status: (args.signal?.aborted || isRuntimeShutdownInProgress()) ? "cancelled" : (result.ok ? "completed" : "failed"),
             model: effectiveModel,
-            nativeSessionId: result.nativeSessionId,
+            nativeSessionId: result.nativeSessionId
+              ? args.redactTextForPersistence?.(result.nativeSessionId) ?? result.nativeSessionId
+              : result.nativeSessionId,
             finishedAt,
             durationMs,
             transcriptChars: result.usageTelemetry.transcriptText.length,
@@ -605,7 +617,11 @@ export class ProviderExecutionService {
             totalTokens: result.usageTelemetry.totalTokens,
             toolCallCount: countConversationToolCalls(result.usageTelemetry.conversation),
             usageSource: result.usageTelemetry.usageSource,
-            rawUsageJson: result.usageTelemetry.rawUsageJson,
+            rawUsageJson: result.usageTelemetry.rawUsageJson
+              ? args.redactJsonForPersistence
+                ? args.redactJsonForPersistence(result.usageTelemetry.rawUsageJson)
+                : result.usageTelemetry.rawUsageJson
+              : result.usageTelemetry.rawUsageJson,
           });
         }
 
@@ -736,6 +752,7 @@ export class ProviderExecutionService {
       }
 
       const classification = classifyProviderError(args.provider, providerResult);
+      const persistedUserMessage = args.redactTextForPersistence?.(classification.userMessage) ?? classification.userMessage;
       const retryDecision = resolveProviderRetryDecision(classification, args.workflowSettings);
       const retryAfterIso = retryDecision
         && !(retryDecision.kind === "rate_limit" && rateLimitRetryCount >= args.workflowSettings.maxRateLimitRetries)
@@ -744,12 +761,12 @@ export class ProviderExecutionService {
       if (execInvocationId) {
         this.deps.executionRepository?.updateExecutionInvocation(execInvocationId, {
           lastErrorCategory: classification.category,
-          lastErrorMessage: classification.userMessage,
+          lastErrorMessage: persistedUserMessage,
           lastRetryAfterIso: retryAfterIso,
         });
         this.deps.executionRepository?.appendExecutionInvocationMessage(execInvocationId, {
           role: "system",
-          contentMarkdown: `Provider error (${classification.category}): ${classification.userMessage}`,
+          contentMarkdown: `Provider error (${classification.category}): ${persistedUserMessage}`,
           metadata: {
             provider: args.provider,
             model: args.model,
diff --git a/tests/backend/services/node-flow-runtime-service.test.ts b/tests/backend/services/node-flow-runtime-service.test.ts
index c08eeb0df2..efb379d313 100644
--- a/tests/backend/services/node-flow-runtime-service.test.ts
+++ b/tests/backend/services/node-flow-runtime-service.test.ts
@@ -13,6 +13,7 @@ import type { ProviderExecutionService } from "../../../src/services/provider-ex
 import type { NodeFlowGraph } from "../../../src/contracts/node-flow-types.js";
 import type { CredentialBroker } from "../../../src/services/credentials/credential-broker.js";
 import { EgressPolicyService } from "../../../src/services/node-flows/egress-policy-service.js";
+import { AutomationAuditExportService } from "../../../src/services/automation-audit-export-service.js";
 
 const tempDirs: string[] = [];
 
@@ -21,6 +22,7 @@ async function createRuntime(providerExecutionService?: Partial<ProviderExecutio
   projectRepository: ProjectManagementRepository;
   nodeFlowRepository: NodeFlowRepository;
   executionRepository: ExecutionRepository;
+  auditService: AutomationAuditExportService;
   runtime: NodeFlowRuntimeService;
 }> {
   const dir = await fs.mkdtemp(path.join(os.tmpdir(), "node-flow-runtime-"));
@@ -29,6 +31,7 @@ async function createRuntime(providerExecutionService?: Partial<ProviderExecutio
   const projectRepository = new ProjectManagementRepository(storage);
   const nodeFlowRepository = new NodeFlowRepository(storage);
   const executionRepository = new ExecutionRepository(storage);
+  const auditService = new AutomationAuditExportService(storage);
   const runtime = new NodeFlowRuntimeService({
     nodeFlowRepository,
     executionRepository,
@@ -37,9 +40,10 @@ async function createRuntime(providerExecutionService?: Partial<ProviderExecutio
     providerExecutionService: providerExecutionService as ProviderExecutionService | undefined,
     credentialBroker: credentialBroker as CredentialBroker | undefined,
     egressPolicyService,
+    auditService,
     getDashboardSettings: () => DEFAULT_DASHBOARD_SETTINGS,
   });
-  return { dir, projectRepository, nodeFlowRepository, executionRepository, runtime };
+  return { dir, projectRepository, nodeFlowRepository, executionRepository, auditService, runtime };
 }
 
 afterEach(async () => {
@@ -198,6 +202,95 @@ describe("NodeFlowRuntimeService", () => {
     expect(executionRepository.getExecutionInvocation(promptRun!.executionInvocationId!)?.type).toBe("node_flow_node");
   });
 
+  it("redacts a resolved credential echoed by provider output and retry errors from every runtime record", async () => {
+    const credentialCanary = "CODEUX_PROVIDER_CANARY_X9Q7";
+    const persistedBoundaryValues: unknown[] = [];
+    let providerAttempt = 0;
+    const providerResult = {
+        ok: true,
+        stdout: `stdout ${credentialCanary}`,
+        stderr: "",
+        code: 0,
+        text: `answer ${credentialCanary}`,
+        nativeSessionId: `session-${credentialCanary}`,
+        usageTelemetry: {
+          transcriptText: `transcript ${credentialCanary}`,
+          inputTokens: 0,
+          cachedInputTokens: 0,
+          outputTokens: 0,
+          reasoningOutputTokens: 0,
+          totalTokens: 0,
+          usageSource: "reported",
+          rawUsageJson: { echoed: credentialCanary },
+        },
+      };
+    const executeProvider = vi.fn().mockImplementation(async (args: {
+      redactTextForPersistence?: (value: string) => string;
+      redactJsonForPersistence?: (value: Record<string, unknown>) => Record<string, unknown> | null;
+      onActivity?: (description: string) => void;
+    }) => {
+      providerAttempt += 1;
+      persistedBoundaryValues.push(
+        args.redactTextForPersistence?.(`retry ${credentialCanary}`),
+        args.redactJsonForPersistence?.({ echoed: credentialCanary }),
+        typeof args.onActivity,
+      );
+      if (providerAttempt === 1) throw new Error(`503 retry echoed ${credentialCanary}`);
+      return providerResult;
+    });
+    const resolveCredentialId = vi.fn().mockResolvedValue({
+      credentialId: "credential-provider",
+      value: credentialCanary,
+      version: 3,
+    });
+    const { dir, projectRepository, nodeFlowRepository, executionRepository, auditService, runtime } = await createRuntime(
+      { executeProvider } as Partial<ProviderExecutionService>,
+      { resolveCredentialId },
+    );
+    const project = projectRepository.createProject({ name: "Provider Canary Project", sourceType: "local", sourceRef: dir });
+    const flow = nodeFlowRepository.createFlow(project.id, {
+      title: "Provider canary",
+      graph: {
+        nodes: [{
+          id: "prompt",
+          type: "provider_prompt",
+          title: "Prompt",
+          data: { provider: "mockup-cli", prompt: "Answer safely" },
+          credentialBindings: [{ slot: "provider", credentialId: "credential-provider" }],
+          policy: { retry: { maxAttempts: 2, backoffMs: 0, maxBackoffMs: 0 } },
+        }],
+        edges: [],
+      },
+    });
+
+    const result = await runtime.runFlow(project.id, flow.id, {});
+    const invocations = executionRepository.listExecutionInvocations({ projectId: project.id, limit: 20 });
+    const invocationMessages = invocations.flatMap((invocation) => executionRepository.listExecutionInvocationMessages(invocation.id));
+    const persisted = JSON.stringify({
+      summary: result,
+      attempts: nodeFlowRepository.listNodeAttempts(result.run.id),
+      invocations,
+      invocationMessages,
+      audit: auditService.list({ projectId: project.id }),
+      logs: invocationMessages,
+      diagnostics: result.nodeRuns.map((nodeRun) => ({ output: nodeRun.output, error: nodeRun.errorMessage })),
+    });
+
+    expect(executeProvider).toHaveBeenCalledTimes(2);
+    expect(persistedBoundaryValues).toEqual([
+      "retry [REDACTED]", { echoed: "[REDACTED]" }, "function",
+      "retry [REDACTED]", { echoed: "[REDACTED]" }, "function",
+    ]);
+    expect(result.output).toMatchObject({ text: "answer [REDACTED]", nativeSessionId: "session-[REDACTED]" });
+    expect(result.attempts?.[0]).toMatchObject({
+      credentialIds: ["credential-provider"],
+      errorMessage: "503 retry echoed [REDACTED]",
+      retryDecision: "retry",
+    });
+    expect(persisted).not.toContain(credentialCanary);
+    expect(persisted).toContain("credential-provider");
+  });
+
   it("executes governed HTTP request nodes with query, body, timeout, and JSON response extraction", async () => {
       const fetchMock = vi.fn().mockResolvedValue(new Response(JSON.stringify({ data: { message: "hello" } }), {
         status: 200, headers: { "content-type": "application/json" },
@@ -235,6 +328,63 @@ describe("NodeFlowRuntimeService", () => {
       expect(fetchMock).toHaveBeenCalledWith(expect.objectContaining({ search: "?name=Ada" }), expect.objectContaining({ redirect: "manual" }));
   });
 
+  it("redacts a resolved HTTP credential echoed by the mock boundary from bodies and persisted diagnostics", async () => {
+    const credentialCanary = "CODEUX_HTTP_CANARY_X9Q7";
+    const fetchMock = vi.fn().mockImplementation(async (_url: URL, init?: RequestInit) => {
+      expect(init?.headers).toMatchObject({ authorization: credentialCanary });
+      return new Response(JSON.stringify({ echoed: credentialCanary, detail: `Authorization: ${credentialCanary}` }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    });
+    const egressPolicyService = new EgressPolicyService({ fetch: fetchMock, lookup: async () => [{ address: "8.8.8.8", family: 4 }] });
+    const resolveCredentialId = vi.fn().mockResolvedValue({
+      credentialId: "credential-http",
+      value: credentialCanary,
+      version: 2,
+    });
+    const { dir, projectRepository, nodeFlowRepository, executionRepository, auditService, runtime } = await createRuntime(
+      undefined,
+      { resolveCredentialId },
+      egressPolicyService,
+    );
+    const project = projectRepository.createProject({ name: "HTTP Canary Project", sourceType: "local", sourceRef: dir });
+    const flow = nodeFlowRepository.createFlow(project.id, {
+      title: "HTTP canary",
+      graph: {
+        nodes: [{
+          id: "http",
+          type: "http_request",
+          title: "HTTP",
+          data: { method: "GET", url: "https://api.example.test/echo" },
+          credentialBindings: [{ slot: "auth", credentialId: "credential-http" }],
+        }],
+        edges: [],
+      },
+    });
+
+    const result = await runtime.runFlow(project.id, flow.id, {});
+    const invocations = executionRepository.listExecutionInvocations({ projectId: project.id, limit: 20 });
+    const invocationMessages = invocations.flatMap((invocation) => executionRepository.listExecutionInvocationMessages(invocation.id));
+    const persisted = JSON.stringify({
+      summary: result,
+      attempts: nodeFlowRepository.listNodeAttempts(result.run.id),
+      invocations,
+      invocationMessages,
+      audit: auditService.list({ projectId: project.id }),
+      logs: invocationMessages,
+      diagnostics: result.nodeRuns.map((nodeRun) => ({ output: nodeRun.output, error: nodeRun.errorMessage })),
+    });
+
+    expect(result.output).toMatchObject({
+      body: { echoed: "[REDACTED]", detail: "Authorization: [REDACTED]" },
+      extracted: { echoed: "[REDACTED]", detail: "Authorization: [REDACTED]" },
+    });
+    expect(result.attempts?.[0]?.credentialIds).toEqual(["credential-http"]);
+    expect(persisted).not.toContain(credentialCanary);
+    expect(persisted).toContain("credential-http");
+  });
+
   it("fails HTTP nodes clearly and skips downstream nodes without continueOnError", async () => {
     const { dir, projectRepository, nodeFlowRepository, runtime } = await createRuntime();
     const project = projectRepository.createProject({ name: "HTTP Failure Project", sourceType: "local", sourceRef: dir });

From 686d4177520c0a8bf6425bb6c9d5dd1ef6be0d96 Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 07:51:25 +0000
Subject: [PATCH 13/25] feat(task T10): implement via codex

---
 dashboard/src/v2/NodesPage.tsx                |   6 +-
 dashboard/src/v2/lib/nodes-canvas-state.ts    | 124 +++++---
 docs-web/architecture/node-flow-foundation.md |   4 +-
 .../architecture-node-flow-foundation.mdx     |   4 +-
 docs-web/content/docs/registry.ts             |   4 +-
 .../docs/user-dashboard-nodes-canvas.mdx      |  48 +--
 docs-web/user/dashboard/nodes-canvas.md       |  48 +--
 docs/architecture/node-flow-foundation.md     |   2 +
 docs/dashboard/nodes-canvas.md                |   4 +-
 src/domain/node-flows/node-flow-migrators.ts  | 161 ++++++----
 src/domain/node-flows/node-flow-validation.ts | 277 ++++++++++++++----
 .../node-flows/node-flow-migrators.test.ts    |  40 ++-
 .../node-flows/node-flow-validation.test.ts   |  67 +++++
 .../dashboard/lib/nodes-canvas-state.test.ts  |  26 ++
 tests/dashboard/v2/nodes-page.test.tsx        |  30 +-
 15 files changed, 610 insertions(+), 235 deletions(-)

diff --git a/dashboard/src/v2/NodesPage.tsx b/dashboard/src/v2/NodesPage.tsx
index f550fa51fc..15deca241b 100644
--- a/dashboard/src/v2/NodesPage.tsx
+++ b/dashboard/src/v2/NodesPage.tsx
@@ -69,7 +69,11 @@ export const NodesPage: FunctionComponent = () => {
       let nextFlows = library.flows;
       const legacy = typeof window !== "undefined" ? window.localStorage.getItem(NODES_CANVAS_STORAGE_KEY) : null;
       if (legacy && !window.localStorage.getItem(migrationMarker(nextProjectId))) {
-        const importedGraph = toCanonicalNodeFlowGraph(deserializeNodeCanvasGraphWithMigration(legacy).graph);
+        const legacySnapshot: unknown = JSON.parse(legacy);
+        const importedGraph = toCanonicalNodeFlowGraph(
+          deserializeNodeCanvasGraphWithMigration(legacy).graph,
+          legacySnapshot,
+        );
         const imported = await createNodeFlowDraft(nextProjectId, { title: "Imported Nodes Canvas", description: "One-time import from the legacy browser canvas.", graph: importedGraph });
         window.localStorage.setItem(migrationMarker(nextProjectId), imported.flowId);
         window.localStorage.removeItem(NODES_CANVAS_STORAGE_KEY);
diff --git a/dashboard/src/v2/lib/nodes-canvas-state.ts b/dashboard/src/v2/lib/nodes-canvas-state.ts
index 0b363bd42f..d963f62114 100644
--- a/dashboard/src/v2/lib/nodes-canvas-state.ts
+++ b/dashboard/src/v2/lib/nodes-canvas-state.ts
@@ -1,4 +1,4 @@
-import type { NodeFlowGraph, NodeFlowJsonObject, NodeFlowJsonValue, NodeFlowPort } from "../../../../src/contracts/node-flow-types.js";
+import type { NodeFlowGraph, NodeFlowJsonObject, NodeFlowJsonValue } from "../../../../src/contracts/node-flow-types.js";
 
 export type NodeCanvasNodeKind = "trigger" | "agent" | "task" | "condition" | "output";
 export type NodeCanvasPortDirection = "input" | "output";
@@ -133,6 +133,19 @@ const NODE_KINDS: readonly NodeCanvasNodeKind[] = ["trigger", "agent", "task", "
 const AGENT_INTENTS: readonly NodeCanvasAgentIntent[] = ["plan", "implement", "review", "qa"];
 const TASK_INTENTS: readonly NodeCanvasTaskIntent[] = ["feature", "refactor", "test", "docs", "ops"];
 
+interface CanonicalCanvasDefinition {
+  type: string;
+  handles: Readonly<Record<string, string>>;
+}
+
+const CANONICAL_CANVAS_DEFINITIONS: Readonly<Record<NodeCanvasNodeKind, CanonicalCanvasDefinition>> = {
+  trigger: { type: "input", handles: { event: "output" } },
+  agent: { type: "set_fields", handles: { in: "input", agent: "output" } },
+  task: { type: "template", handles: { agent: "input", task: "output" } },
+  condition: { type: "condition", handles: { task: "input", pass: "true", fail: "false" } },
+  output: { type: "output", handles: { result: "input" } },
+};
+
 interface NodeTemplate {
   label: string;
   description: string;
@@ -500,47 +513,60 @@ export const serializeNodeCanvasGraph = (graph: NodeCanvasGraph): string => (
   JSON.stringify(toStableJson(toCanonicalNodeFlowGraph(graph)), null, 2)
 );
 
-export const toCanonicalNodeFlowGraph = (graph: NodeCanvasGraph): NodeFlowGraph => {
+export const toCanonicalNodeFlowGraph = (graph: NodeCanvasGraph, legacySnapshot?: unknown): NodeFlowGraph => {
   const normalized = normalizeNodeCanvasGraph(graph);
   return {
     schemaVersion: 2,
-    nodes: normalized.nodes.map((node) => ({
-      id: node.id,
-      type: node.kind,
-      title: node.label,
-      description: node.description,
-      position: node.position,
-      definition: { type: node.kind, version: 1 },
-      ports: [...node.inputPorts, ...node.outputPorts].map(toCanonicalPort),
-      credentialBindings: [],
-      policy: {},
-      capabilities: [],
-      sideEffect: "none",
-      disabled: false,
-      data: {
-        canvas: {
-          config: node.config as unknown as NodeFlowJsonValue,
-          metadata: node.metadata as unknown as NodeFlowJsonValue,
+    nodes: normalized.nodes.map(toCanonicalNode),
+    edges: normalized.edges.map((edge) => {
+      const source = normalized.nodes.find((node) => node.id === edge.source.nodeId);
+      const target = normalized.nodes.find((node) => node.id === edge.target.nodeId);
+      return {
+        id: edge.id,
+        fromNodeId: edge.source.nodeId,
+        toNodeId: edge.target.nodeId,
+        ...(source ? { fromHandle: CANONICAL_CANVAS_DEFINITIONS[source.kind].handles[edge.source.portId] } : {}),
+        ...(target ? { toHandle: CANONICAL_CANVAS_DEFINITIONS[target.kind].handles[edge.target.portId] } : {}),
+      };
+    }),
+    metadata: {
+      canvasSelection: normalized.selection as unknown as NodeFlowJsonObject,
+      ...(legacySnapshot !== undefined ? {
+        migration: {
+          source: "browser_canvas_v1",
+          legacySnapshot: toStableJson(cloneStableValue(legacySnapshot)) as NodeFlowJsonValue,
         },
-      },
-    })),
-    edges: normalized.edges.map((edge) => ({
-      id: edge.id,
-      fromNodeId: edge.source.nodeId,
-      toNodeId: edge.target.nodeId,
-      fromHandle: edge.source.portId,
-      toHandle: edge.target.portId,
-    })),
-    metadata: { canvasSelection: normalized.selection as unknown as NodeFlowJsonObject },
+      } : {}),
+    },
   };
 };
 
-const toCanonicalPort = (port: NodeCanvasPort): NodeFlowPort => ({
-  id: port.id,
-  direction: port.direction,
-  schema: { type: "object", description: port.type },
-  required: port.required,
-});
+const toCanonicalNode = (node: NodeCanvasNode): NodeFlowGraph["nodes"][number] => {
+  const definition = CANONICAL_CANVAS_DEFINITIONS[node.kind];
+  const config = Object.fromEntries(node.config.map((field) => [field.id, field.value]));
+  const prompt = typeof config.prompt === "string" && config.prompt.trim()
+    ? config.prompt
+    : "Use the selected agent to complete the task.";
+  return {
+    id: node.id,
+    type: definition.type,
+    title: node.label,
+    description: node.description,
+    position: node.position,
+    definition: { type: definition.type, version: 1 },
+    disabled: false,
+    data: {
+      ...(node.kind === "agent" ? { fields: { legacyAgent: config } } : {}),
+      ...(node.kind === "task" ? { template: prompt, outputKey: "task" } : {}),
+      canvas: {
+        kind: node.kind,
+        config: toStableJson(node.config) as NodeFlowJsonValue,
+        values: toStableJson(config) as NodeFlowJsonValue,
+        metadata: toStableJson(node.metadata) as NodeFlowJsonValue,
+      },
+    },
+  };
+};
 
 export const deserializeNodeCanvasGraph = (serialized: string): NodeCanvasGraph => {
   return deserializeNodeCanvasGraphWithMigration(serialized).graph;
@@ -577,9 +603,11 @@ export const normalizeNodeCanvasGraph = (input: unknown): NodeCanvasGraph => {
     return createInitialNodeCanvasGraph();
   }
 
-  const parsedEdges = Array.isArray(input.edges)
+  const rawParsedEdges = Array.isArray(input.edges)
     ? input.edges.map(parseEdge).filter((edge): edge is NodeCanvasEdge => edge !== null)
     : [];
+  const nodeById = new Map(parsedNodes.map((node) => [node.id, node]));
+  const parsedEdges = rawParsedEdges.map((edge) => normalizeCanvasEdgeHandles(edge, nodeById));
 
   const validNodeIds = new Set(parsedNodes.map((node) => node.id));
   const canvasSelection = isRecord(input.metadata) ? input.metadata.canvasSelection : undefined;
@@ -688,7 +716,8 @@ const normalizeMetadata = (metadata: NodeCanvasNodeMetadata): NodeCanvasNodeMeta
 });
 
 const parseNode = (value: unknown): NodeCanvasNode | null => {
-  const kindValue = isRecord(value) ? value.kind ?? value.type : undefined;
+  const canvasData = isRecord(value) ? readCanonicalCanvasData(value.data) : null;
+  const kindValue = isRecord(value) ? value.kind ?? canvasData?.kind ?? value.type : undefined;
   if (!isRecord(value) || !isString(value.id) || !isNodeKind(kindValue)) {
     return null;
   }
@@ -700,7 +729,6 @@ const parseNode = (value: unknown): NodeCanvasNode | null => {
       }
     : template.position;
 
-  const canvasData = readCanonicalCanvasData(value.data);
   const canonicalPorts = Array.isArray(value.ports) ? value.ports : undefined;
   return {
     ...template,
@@ -821,6 +849,26 @@ const parseEdge = (value: unknown): NodeCanvasEdge | null => {
   };
 };
 
+const normalizeCanvasEdgeHandles = (
+  edge: NodeCanvasEdge,
+  nodeById: ReadonlyMap<string, NodeCanvasNode>,
+): NodeCanvasEdge => {
+  const source = nodeById.get(edge.source.nodeId);
+  const target = nodeById.get(edge.target.nodeId);
+  const legacyHandle = (node: NodeCanvasNode | undefined, handle: string): string => {
+    if (!node) return handle;
+    const ports = [...node.inputPorts, ...node.outputPorts];
+    if (ports.some((port) => port.id === handle)) return handle;
+    return Object.entries(CANONICAL_CANVAS_DEFINITIONS[node.kind].handles)
+      .find(([, canonical]) => canonical === handle)?.[0] ?? handle;
+  };
+  return {
+    ...edge,
+    source: { ...edge.source, portId: legacyHandle(source, edge.source.portId) },
+    target: { ...edge.target, portId: legacyHandle(target, edge.target.portId) },
+  };
+};
+
 const parseSelection = (
   value: unknown,
   nodeIds: ReadonlySet<string>,
diff --git a/docs-web/architecture/node-flow-foundation.md b/docs-web/architecture/node-flow-foundation.md
index acd3237449..d1dbf7317f 100644
--- a/docs-web/architecture/node-flow-foundation.md
+++ b/docs-web/architecture/node-flow-foundation.md
@@ -4,4 +4,6 @@ Code UX uses one canonical Graph v2 contract across backend, MCP, runtime, and d
 
 Validation resolves definitions, checks configuration, ports, policies, graph limits, and cycles, and rejects plaintext secrets and custom source. Only `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output` are executable.
 
-Persisted Graph v1 records retain their original immutable version and append deterministic Graph v2. Browser migration retains its original snapshot outside executable graph JSON.
+Persisted Graph v1 records retain their original immutable version and append deterministic Graph v2. One-time browser migration maps legacy planning kinds to registered definitions and retains the JSON-safe original snapshot in non-executable graph migration metadata.
+
+Graph JSON is treated as untrusted input. Malformed definition references, ports, credential bindings, policies, widget entries, schemas, publication metadata, and null array members return deterministic field-level validation issues instead of throwing. Secret-shaped keys and custom source fields remain rejected through migration and normalization.
diff --git a/docs-web/content/docs/architecture-node-flow-foundation.mdx b/docs-web/content/docs/architecture-node-flow-foundation.mdx
index acd3237449..d1dbf7317f 100644
--- a/docs-web/content/docs/architecture-node-flow-foundation.mdx
+++ b/docs-web/content/docs/architecture-node-flow-foundation.mdx
@@ -4,4 +4,6 @@ Code UX uses one canonical Graph v2 contract across backend, MCP, runtime, and d
 
 Validation resolves definitions, checks configuration, ports, policies, graph limits, and cycles, and rejects plaintext secrets and custom source. Only `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output` are executable.
 
-Persisted Graph v1 records retain their original immutable version and append deterministic Graph v2. Browser migration retains its original snapshot outside executable graph JSON.
+Persisted Graph v1 records retain their original immutable version and append deterministic Graph v2. One-time browser migration maps legacy planning kinds to registered definitions and retains the JSON-safe original snapshot in non-executable graph migration metadata.
+
+Graph JSON is treated as untrusted input. Malformed definition references, ports, credential bindings, policies, widget entries, schemas, publication metadata, and null array members return deterministic field-level validation issues instead of throwing. Secret-shaped keys and custom source fields remain rejected through migration and normalization.
diff --git a/docs-web/content/docs/registry.ts b/docs-web/content/docs/registry.ts
index 6bf849a8b0..d0f9792640 100644
--- a/docs-web/content/docs/registry.ts
+++ b/docs-web/content/docs/registry.ts
@@ -266,8 +266,8 @@ export const docsRegistry: Record<DocsSlug, DocsRegistryEntry> = {
     id: 'user-dashboard-nodes-canvas',
     path: '/docs/user-dashboard-nodes-canvas',
     section: 'User Guide',
-    title: "Nodes Canvas",
-    description: "The Nodes Canvas page (/nodes) is a browser-local workspace for drafting Code UX workflow graphs. It combines the canvas, palette, inspector, validation panel, JSON exchange controls, and agent command summary without...",
+    title: "Nodes Automation Workspace",
+    description: "The Nodes page (/nodes) is a project-scoped automation workspace backed by the canonical node-flow repository. Browser storage is not a workflow database and edits are never auto-saved locally.",
   },
   'user-dashboard-node-flows': {
     id: 'user-dashboard-node-flows',
diff --git a/docs-web/content/docs/user-dashboard-nodes-canvas.mdx b/docs-web/content/docs/user-dashboard-nodes-canvas.mdx
index 2c7a5bc4b7..a8a2710611 100644
--- a/docs-web/content/docs/user-dashboard-nodes-canvas.mdx
+++ b/docs-web/content/docs/user-dashboard-nodes-canvas.mdx
@@ -1,47 +1,19 @@
-# Nodes Canvas
+# Nodes Automation Workspace
 
-The **Nodes Canvas** page (`/nodes`) is a browser-local workspace for drafting Code UX workflow graphs. It combines the canvas, palette, inspector, validation panel, JSON exchange controls, and agent command summary without calling backend APIs or writing to the database.
+The **Nodes** page (`/nodes`) is a project-scoped automation workspace backed by the canonical node-flow repository. Browser storage is not a workflow database and edits are never auto-saved locally.
 
-This page does not synchronize graphs to projects, execute n8n workflows, or run node flows through the Code UX runtime.
+## Legacy canvas import
 
-## Local persistence
+On the first load for a selected project, the dashboard checks the former `codeux:nodes-canvas:v1` key. When present, it normalizes the payload to Graph v2, creates an **Imported Nodes Canvas** backend draft, records a project-specific migration marker, and removes the legacy graph value. A failed import leaves the value available for retry. The marker prevents duplicates, so browser storage is a one-time migration source rather than a second workflow database.
 
-The page saves the current graph to browser `localStorage` under `codeux:nodes-canvas:v1`. Reloading `/nodes` restores that graph when it can be parsed through the canvas contract. Malformed persisted data falls back to the starter graph.
+Legacy planning nodes map to registered definitions and handles: `trigger` becomes `input`, `agent` becomes `set_fields`, `task` becomes `template`, and `condition` and `output` use their matching definitions. The original JSON-safe browser snapshot is retained in non-executable graph migration metadata for review. Secret-shaped keys and custom source fields remain visible to backend validation and cause the import to be rejected instead of being silently discarded.
 
-The inspector's enabled switch is an editing-session flag only and is not persisted in the graph JSON.
+## Governed editing
 
-## Node types
+The registry supplies executable state, typed ports, widget schemas, capabilities, credential slots, side-effect classification, and default policy. The graph stores only a type/version reference and configuration; it never stores custom source or credential values.
 
-| Type | Purpose |
-| --- | --- |
-| `trigger` | Starts the graph from a manual or scheduled event source. |
-| `agent` | Routes downstream work to a planning, implementation, review, or QA agent intent. |
-| `task` | Captures a concrete task prompt and task intent. |
-| `condition` | Branches based on an expression such as a validation result. |
-| `output` | Collects the final graph result. |
+Draft saves use `draftRevision`. A concurrent update returns a visible conflict. Validation, policy findings, credential status, dry runs, publication, version comparison, and rollback use the governed draft APIs.
 
-## Validation behavior
+## Operations
 
-Validation runs locally after each graph change. It checks duplicate node ids, missing edge nodes or ports, self-connections, input/output direction mismatches, incompatible port types, empty required values, and invalid agent or task intent metadata.
-
-The status strip reports the issue count. The validation panel groups issues by node or edge and provides select/focus actions. Valid JSON imports can still contain validation issues so users can repair them on the canvas.
-
-## Import and export format
-
-`Export JSON` writes the deterministic graph JSON into the exchange textarea. The JSON contains `nodes`, `edges`, and `selection`.
-
-`Import JSON` applies the textarea content through the agent `replace_graph` command helper. Invalid JSON leaves the current graph unchanged and reports a live error. Valid JSON is normalized, loaded into the canvas, saved locally, and revalidated.
-
-## Agent command surface
-
-Agents should use the node canvas agent helper contract rather than driving the UI. Supported commands are `add_node`, `patch_node`, `connect_ports`, `delete_entities`, `select_entities`, and `replace_graph`.
-
-The page displays a deterministic graph summary for command workflows, including node and edge counts, selected ids, ports, config values, and validation blockers.
-
-## Empty and reset states
-
-`Clear` empties the canvas while keeping the palette available. `Reset` restores the starter trigger -> agent -> task -> condition -> output graph. The layout collapses to a single column at smaller widths so controls remain reachable without overlapping.
-
-## Graph v2 migration
-
-Serialization writes `schemaVersion: 2`. Legacy browser v1 values migrate deterministically with their untouched snapshot retained separately. Trigger, agent, task, condition, and output are planning concepts; executable definitions are limited to `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output`.
+Only published versions run. The debugger shows redacted run output, graph and node states, attempts, retry classifications and decisions, invocation links, timing, cancellation, and safe retry controls. Scheduling is entered through the Scheduler page.
diff --git a/docs-web/user/dashboard/nodes-canvas.md b/docs-web/user/dashboard/nodes-canvas.md
index 2c7a5bc4b7..a8a2710611 100644
--- a/docs-web/user/dashboard/nodes-canvas.md
+++ b/docs-web/user/dashboard/nodes-canvas.md
@@ -1,47 +1,19 @@
-# Nodes Canvas
+# Nodes Automation Workspace
 
-The **Nodes Canvas** page (`/nodes`) is a browser-local workspace for drafting Code UX workflow graphs. It combines the canvas, palette, inspector, validation panel, JSON exchange controls, and agent command summary without calling backend APIs or writing to the database.
+The **Nodes** page (`/nodes`) is a project-scoped automation workspace backed by the canonical node-flow repository. Browser storage is not a workflow database and edits are never auto-saved locally.
 
-This page does not synchronize graphs to projects, execute n8n workflows, or run node flows through the Code UX runtime.
+## Legacy canvas import
 
-## Local persistence
+On the first load for a selected project, the dashboard checks the former `codeux:nodes-canvas:v1` key. When present, it normalizes the payload to Graph v2, creates an **Imported Nodes Canvas** backend draft, records a project-specific migration marker, and removes the legacy graph value. A failed import leaves the value available for retry. The marker prevents duplicates, so browser storage is a one-time migration source rather than a second workflow database.
 
-The page saves the current graph to browser `localStorage` under `codeux:nodes-canvas:v1`. Reloading `/nodes` restores that graph when it can be parsed through the canvas contract. Malformed persisted data falls back to the starter graph.
+Legacy planning nodes map to registered definitions and handles: `trigger` becomes `input`, `agent` becomes `set_fields`, `task` becomes `template`, and `condition` and `output` use their matching definitions. The original JSON-safe browser snapshot is retained in non-executable graph migration metadata for review. Secret-shaped keys and custom source fields remain visible to backend validation and cause the import to be rejected instead of being silently discarded.
 
-The inspector's enabled switch is an editing-session flag only and is not persisted in the graph JSON.
+## Governed editing
 
-## Node types
+The registry supplies executable state, typed ports, widget schemas, capabilities, credential slots, side-effect classification, and default policy. The graph stores only a type/version reference and configuration; it never stores custom source or credential values.
 
-| Type | Purpose |
-| --- | --- |
-| `trigger` | Starts the graph from a manual or scheduled event source. |
-| `agent` | Routes downstream work to a planning, implementation, review, or QA agent intent. |
-| `task` | Captures a concrete task prompt and task intent. |
-| `condition` | Branches based on an expression such as a validation result. |
-| `output` | Collects the final graph result. |
+Draft saves use `draftRevision`. A concurrent update returns a visible conflict. Validation, policy findings, credential status, dry runs, publication, version comparison, and rollback use the governed draft APIs.
 
-## Validation behavior
+## Operations
 
-Validation runs locally after each graph change. It checks duplicate node ids, missing edge nodes or ports, self-connections, input/output direction mismatches, incompatible port types, empty required values, and invalid agent or task intent metadata.
-
-The status strip reports the issue count. The validation panel groups issues by node or edge and provides select/focus actions. Valid JSON imports can still contain validation issues so users can repair them on the canvas.
-
-## Import and export format
-
-`Export JSON` writes the deterministic graph JSON into the exchange textarea. The JSON contains `nodes`, `edges`, and `selection`.
-
-`Import JSON` applies the textarea content through the agent `replace_graph` command helper. Invalid JSON leaves the current graph unchanged and reports a live error. Valid JSON is normalized, loaded into the canvas, saved locally, and revalidated.
-
-## Agent command surface
-
-Agents should use the node canvas agent helper contract rather than driving the UI. Supported commands are `add_node`, `patch_node`, `connect_ports`, `delete_entities`, `select_entities`, and `replace_graph`.
-
-The page displays a deterministic graph summary for command workflows, including node and edge counts, selected ids, ports, config values, and validation blockers.
-
-## Empty and reset states
-
-`Clear` empties the canvas while keeping the palette available. `Reset` restores the starter trigger -> agent -> task -> condition -> output graph. The layout collapses to a single column at smaller widths so controls remain reachable without overlapping.
-
-## Graph v2 migration
-
-Serialization writes `schemaVersion: 2`. Legacy browser v1 values migrate deterministically with their untouched snapshot retained separately. Trigger, agent, task, condition, and output are planning concepts; executable definitions are limited to `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output`.
+Only published versions run. The debugger shows redacted run output, graph and node states, attempts, retry classifications and decisions, invocation links, timing, cancellation, and safe retry controls. Scheduling is entered through the Scheduler page.
diff --git a/docs/architecture/node-flow-foundation.md b/docs/architecture/node-flow-foundation.md
index 7a854f6f65..8212685de4 100644
--- a/docs/architecture/node-flow-foundation.md
+++ b/docs/architecture/node-flow-foundation.md
@@ -85,3 +85,5 @@ Normalized graphs carry `schemaVersion: 2`. Nodes reference a stable definition
 The typed registry includes configuration and UI schemas, ports, credential slots, capabilities, side effects, default policies, documentation, deprecation, and execution kind. Only `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output` are executable. Other palette ideas are planned concepts without runtime handlers.
 
 Validation resolves definitions and checks configuration, handles, policies, graph limits, and cycles with field-level issues. Graph JSON rejects secret-shaped fields and generated/custom source fields. Persisted Graph v1 rows keep their original immutable snapshot and append deterministic Graph v2 as a new current version.
+
+Validation treats graph JSON as untrusted input. Malformed definition references, ports, credential bindings, policies, widget entries, schemas, publication metadata, and null array members produce deterministic field-level issues; the validation API does not throw while inspecting them. One-time browser canvas migration maps legacy planning kinds to registered canonical definitions and retains the original JSON snapshot as non-executable migration metadata.
diff --git a/docs/dashboard/nodes-canvas.md b/docs/dashboard/nodes-canvas.md
index 6d906e6db2..28ffae0d24 100644
--- a/docs/dashboard/nodes-canvas.md
+++ b/docs/dashboard/nodes-canvas.md
@@ -4,7 +4,9 @@ The **Nodes** page (`/nodes`) is a project-scoped automation workspace backed by
 
 ## Legacy canvas import
 
-On the first load for a selected project, the dashboard checks the former `codeux:nodes-canvas:v1` key. When present, it normalizes the payload to Graph v2, creates an **Imported Nodes Canvas** backend draft, records a project-specific migration marker, and removes the legacy graph value. A failed import leaves the value available for retry. The marker prevents duplicates.
+On the first load for a selected project, the dashboard checks the former `codeux:nodes-canvas:v1` key. When present, it normalizes the payload to Graph v2, creates an **Imported Nodes Canvas** backend draft, records a project-specific migration marker, and removes the legacy graph value. A failed import leaves the value available for retry. The marker prevents duplicates, so browser storage is a one-time migration source rather than a second workflow database.
+
+Legacy planning nodes map to registered definitions and handles: `trigger` becomes `input`, `agent` becomes `set_fields`, `task` becomes `template`, and `condition` and `output` use their matching definitions. The original JSON-safe browser snapshot is retained in non-executable graph migration metadata for review. Secret-shaped keys and custom source fields remain visible to backend validation and cause the import to be rejected instead of being silently discarded.
 
 ## Governed editing
 
diff --git a/src/domain/node-flows/node-flow-migrators.ts b/src/domain/node-flows/node-flow-migrators.ts
index 527ae746c3..daf257a1a5 100644
--- a/src/domain/node-flows/node-flow-migrators.ts
+++ b/src/domain/node-flows/node-flow-migrators.ts
@@ -1,5 +1,6 @@
 import {
   NODE_FLOW_SCHEMA_VERSION,
+  type NodeFlowEdge,
   type NodeFlowGraph,
   type NodeFlowJsonObject,
   type NodeFlowJsonValue,
@@ -13,98 +14,148 @@ export interface NodeFlowMigrationResult<TLegacy = unknown> {
   legacySnapshot: TLegacy | null;
 }
 
-const cloneJson = <T>(value: T): T => JSON.parse(JSON.stringify(value)) as T;
+interface LegacyCanvasDefinition {
+  type: string;
+  handles: Readonly<Record<string, string>>;
+}
+
+const LEGACY_CANVAS_DEFINITIONS: Readonly<Record<string, LegacyCanvasDefinition>> = {
+  trigger: { type: "input", handles: { event: "output" } },
+  agent: { type: "set_fields", handles: { in: "input", agent: "output" } },
+  task: { type: "template", handles: { agent: "input", task: "output" } },
+  condition: { type: "condition", handles: { task: "input", pass: "true", fail: "false" } },
+  output: { type: "output", handles: { result: "input" } },
+};
+
+const cloneValue = <T>(value: T): T => {
+  try {
+    return structuredClone(value);
+  } catch {
+    return value;
+  }
+};
 
 export function migrateNodeFlowGraph(graph: unknown): NodeFlowMigrationResult<NodeFlowGraph> {
   if (isRecord(graph) && graph.schemaVersion === NODE_FLOW_SCHEMA_VERSION) {
-    return { graph: cloneJson(graph as unknown as NodeFlowGraph), migrated: false, legacySnapshot: null };
+    return { graph: cloneValue(graph) as unknown as NodeFlowGraph, migrated: false, legacySnapshot: null };
   }
 
-  const legacy = isRecord(graph) ? cloneJson(graph as unknown as NodeFlowGraph) : { nodes: [], edges: [] };
-  const nodes = Array.isArray(legacy.nodes) ? legacy.nodes.map(migrateNode) : [];
-  const definitionByNode = new Map(nodes.map((node) => [node.id, resolveLatestNodeDefinition(node.type)]));
-  const edges = Array.isArray(legacy.edges) ? legacy.edges.map((edge) => ({
-    ...edge,
-    ...(edge.fromHandle ? {} : { fromHandle: definitionByNode.get(edge.fromNodeId)?.ports.find((port) => port.direction === "output")?.id }),
-    ...(edge.toHandle ? {} : { toHandle: definitionByNode.get(edge.toNodeId)?.ports.find((port) => port.direction === "input")?.id }),
-  })) : [];
+  const legacy = isRecord(graph) ? cloneValue(graph) : { nodes: [], edges: [] };
+  const rawNodes = Array.isArray(legacy.nodes) ? legacy.nodes : [];
+  const nodes = rawNodes.map((node) => isRecord(node) ? migrateNode(node) : node as NodeFlowNode);
+  const definitionByNode = new Map(nodes.filter(isNodeWithId).map((node) => [node.id, resolveLatestNodeDefinition(node.type)]));
+  const rawEdges = Array.isArray(legacy.edges) ? legacy.edges : [];
+  const edges = rawEdges.map((edge) => {
+    if (!isRecord(edge)) return edge as NodeFlowEdge;
+    const fromNodeId = stringValue(edge.fromNodeId);
+    const toNodeId = stringValue(edge.toNodeId);
+    return {
+      ...edge,
+      ...(trimmedString(edge.fromHandle) ? {} : { fromHandle: definitionByNode.get(fromNodeId)?.ports.find((port) => port.direction === "output")?.id }),
+      ...(trimmedString(edge.toHandle) ? {} : { toHandle: definitionByNode.get(toNodeId)?.ports.find((port) => port.direction === "input")?.id }),
+    } as NodeFlowEdge;
+  });
 
   return {
     migrated: true,
-    legacySnapshot: legacy,
+    legacySnapshot: legacy as unknown as NodeFlowGraph,
     graph: {
       schemaVersion: NODE_FLOW_SCHEMA_VERSION,
       nodes,
       edges,
-      ...(legacy.inputSchema ? { inputSchema: legacy.inputSchema } : {}),
-      ...(legacy.schemas ? { schemas: legacy.schemas } : {}),
-      ...(legacy.metadata ? { metadata: legacy.metadata } : {}),
-      ...(legacy.publication ? { publication: legacy.publication } : {}),
+      ...(legacy.inputSchema !== undefined ? { inputSchema: legacy.inputSchema as NodeFlowGraph["inputSchema"] } : {}),
+      ...(legacy.schemas !== undefined ? { schemas: legacy.schemas as NodeFlowGraph["schemas"] } : {}),
+      ...(legacy.metadata !== undefined ? { metadata: legacy.metadata as NodeFlowGraph["metadata"] } : {}),
+      ...(legacy.publication !== undefined ? { publication: legacy.publication as NodeFlowGraph["publication"] } : {}),
     },
   };
 }
 
-function migrateNode(node: NodeFlowNode): NodeFlowNode {
-  const definition = node.definition
-    ? resolveLatestNodeDefinition(node.definition.type)
-    : resolveLatestNodeDefinition(node.type);
+function migrateNode(node: Record<string, unknown>): NodeFlowNode {
+  const type = stringValue(node.type);
+  const definitionRef = isRecord(node.definition) ? node.definition : null;
+  const definitionType = stringValue(definitionRef?.type) || type;
+  const definition = resolveLatestNodeDefinition(definitionType);
+  const ports = node.ports === undefined ? definition?.ports.map((port) => cloneValue(port)) ?? [] : node.ports;
   return {
     ...node,
-    definition: node.definition ?? { type: node.type, version: definition?.version ?? 1 },
-    ports: node.ports ?? definition?.ports.map((port) => cloneJson(port)) ?? [],
-    credentialBindings: node.credentialBindings ?? [],
-    policy: node.policy ?? (definition ? cloneJson(definition.defaultPolicy) : {}),
-    capabilities: node.capabilities ?? [...(definition?.capabilities ?? [])],
+    definition: node.definition === undefined ? { type, version: definition?.version ?? 1 } : node.definition,
+    ports,
+    credentialBindings: node.credentialBindings === undefined ? [] : node.credentialBindings,
+    policy: node.policy === undefined ? definition ? cloneValue(definition.defaultPolicy) : {} : node.policy,
+    capabilities: node.capabilities === undefined ? [...(definition?.capabilities ?? [])] : node.capabilities,
     sideEffect: node.sideEffect ?? definition?.sideEffect ?? "none",
     disabled: node.disabled ?? false,
-  };
+  } as unknown as NodeFlowNode;
 }
 
 export function migrateNodeCanvasGraphV1(graph: unknown): NodeFlowMigrationResult<unknown> {
   if (isRecord(graph) && graph.schemaVersion === NODE_FLOW_SCHEMA_VERSION && Array.isArray(graph.nodes) && graph.nodes.every(isCanonicalNode)) {
     return migrateNodeFlowGraph(graph);
   }
-  const legacySnapshot = cloneJson(graph);
+  const legacySnapshot = cloneValue(graph);
   const legacy = isRecord(graph) ? graph : {};
-  const nodes = Array.isArray(legacy.nodes) ? legacy.nodes.filter(isRecord).map((node): NodeFlowNode => ({
-    id: stringValue(node.id),
-    type: stringValue(node.kind) || stringValue(node.type),
-    title: stringValue(node.label) || stringValue(node.title) || stringValue(node.id),
-    description: stringValue(node.description) || undefined,
-    position: isPosition(node.position) ? { x: node.position.x, y: node.position.y } : undefined,
-    definition: { type: stringValue(node.kind) || stringValue(node.type), version: 1 },
-    ports: [...readPorts(node.inputPorts, "input"), ...readPorts(node.outputPorts, "output")],
-    data: canvasNodeData(node),
-    credentialBindings: [], policy: {}, capabilities: [], sideEffect: "none", disabled: false,
-  })).filter((node) => node.id && node.type) : [];
-  const edges = Array.isArray(legacy.edges) ? legacy.edges.filter(isRecord).map((edge) => ({
-    id: stringValue(edge.id) || undefined,
-    fromNodeId: endpointValue(edge.source, "nodeId"),
-    toNodeId: endpointValue(edge.target, "nodeId"),
-    fromHandle: endpointValue(edge.source, "portId") || undefined,
-    toHandle: endpointValue(edge.target, "portId") || undefined,
-  })).filter((edge) => edge.fromNodeId && edge.toNodeId) : [];
+  const nodeDefinitions = new Map<string, LegacyCanvasDefinition>();
+  const nodes = Array.isArray(legacy.nodes) ? legacy.nodes.filter(isRecord).map((node): NodeFlowNode | null => {
+    const id = stringValue(node.id);
+    const legacyType = stringValue(node.kind) || stringValue(node.type);
+    const mapping = LEGACY_CANVAS_DEFINITIONS[legacyType];
+    if (!id || !mapping) return null;
+    nodeDefinitions.set(id, mapping);
+    return migrateNode({
+      id,
+      type: mapping.type,
+      title: stringValue(node.label) || stringValue(node.title) || id,
+      description: stringValue(node.description) || undefined,
+      position: isPosition(node.position) ? { x: node.position.x, y: node.position.y } : undefined,
+      data: canvasNodeData(node, legacyType),
+      disabled: false,
+    });
+  }).filter((node): node is NodeFlowNode => node !== null) : [];
+  const edges = Array.isArray(legacy.edges) ? legacy.edges.filter(isRecord).map((edge) => {
+    const fromNodeId = endpointValue(edge.source, "nodeId");
+    const toNodeId = endpointValue(edge.target, "nodeId");
+    const sourceMapping = nodeDefinitions.get(fromNodeId);
+    const targetMapping = nodeDefinitions.get(toNodeId);
+    return {
+      id: stringValue(edge.id) || undefined,
+      fromNodeId,
+      toNodeId,
+      fromHandle: sourceMapping?.handles[endpointValue(edge.source, "portId")],
+      toHandle: targetMapping?.handles[endpointValue(edge.target, "portId")],
+    };
+  }).filter((edge) => edge.fromNodeId && edge.toNodeId) : [];
   return {
     migrated: true,
     legacySnapshot,
-    graph: { schemaVersion: NODE_FLOW_SCHEMA_VERSION, nodes, edges, metadata: { canvasSelection: jsonValue(legacy.selection) } },
+    graph: {
+      schemaVersion: NODE_FLOW_SCHEMA_VERSION,
+      nodes,
+      edges,
+      metadata: {
+        canvasSelection: jsonValue(legacy.selection),
+        migration: { source: "browser_canvas_v1", legacySnapshot: jsonValue(legacySnapshot) },
+      },
+    },
   };
 }
 
-function readPorts(value: unknown, direction: "input" | "output") {
-  return Array.isArray(value) ? value.filter(isRecord).map((port) => ({
-    id: stringValue(port.id), direction, schema: { type: "any" as const }, required: port.required === true,
-  })).filter((port) => port.id) : [];
-}
-
-function canvasNodeData(node: Record<string, unknown>): NodeFlowJsonObject {
-  const config = Array.isArray(node.config) ? Object.fromEntries(node.config.filter(isRecord).map((entry) => [stringValue(entry.id), jsonValue(entry.value)]).filter(([id]) => id)) : {};
-  return { config, canvasMetadata: jsonValue(node.metadata) };
+function canvasNodeData(node: Record<string, unknown>, legacyType: string): NodeFlowJsonObject {
+  const configEntries = Array.isArray(node.config) ? node.config.filter(isRecord) : [];
+  const config = Object.fromEntries(configEntries.map((entry) => [stringValue(entry.id), jsonValue(entry.value)]).filter(([id]) => id));
+  const prompt = typeof config.prompt === "string" && config.prompt.trim() ? config.prompt : "Use the selected agent to complete the task.";
+  return {
+    ...(legacyType === "agent" ? { fields: { legacyAgent: cloneValue(config) } } : {}),
+    ...(legacyType === "task" ? { template: prompt, outputKey: "task" } : {}),
+    canvas: { kind: legacyType, config: jsonValue(node.config), values: config, metadata: jsonValue(node.metadata) },
+  };
 }
 
-const jsonValue = (value: unknown): NodeFlowJsonValue => JSON.parse(JSON.stringify(value ?? null)) as NodeFlowJsonValue;
+const jsonValue = (value: unknown): NodeFlowJsonValue => cloneValue(value ?? null) as NodeFlowJsonValue;
 const endpointValue = (value: unknown, key: string): string => isRecord(value) ? stringValue(value[key]) : "";
 const stringValue = (value: unknown): string => typeof value === "string" ? value : "";
+const trimmedString = (value: unknown): string => stringValue(value).trim();
 const isRecord = (value: unknown): value is Record<string, unknown> => Boolean(value) && typeof value === "object" && !Array.isArray(value);
 const isPosition = (value: unknown): value is { x: number; y: number } => isRecord(value) && Number.isFinite(value.x) && Number.isFinite(value.y);
 const isCanonicalNode = (value: unknown): boolean => isRecord(value) && isRecord(value.definition);
+const isNodeWithId = (value: NodeFlowNode): value is NodeFlowNode & { id: string; type: string } => isRecord(value) && typeof value.id === "string" && typeof value.type === "string";
diff --git a/src/domain/node-flows/node-flow-validation.ts b/src/domain/node-flows/node-flow-validation.ts
index ad98c35254..8877bd9c92 100644
--- a/src/domain/node-flows/node-flow-validation.ts
+++ b/src/domain/node-flows/node-flow-validation.ts
@@ -58,6 +58,10 @@ function trimmedString(value: unknown): string | null {
   return trimmed.length > 0 ? trimmed : null;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
 function isJsonValue(value: unknown, seen = new Set<object>()): value is NodeFlowJsonValue {
   if (value === null) {
     return true;
@@ -252,48 +256,81 @@ function normalizeWidgetSchema(
   return { fields: normalizedFields };
 }
 
-function containsForbiddenGraphValue(value: NodeFlowJsonValue): boolean {
-  if (Array.isArray(value)) return value.some(containsForbiddenGraphValue);
+function containsForbiddenGraphValue(value: unknown, seen = new Set<object>()): boolean {
+  if (Array.isArray(value)) return value.some((entry) => containsForbiddenGraphValue(entry, seen));
   if (!value || typeof value !== "object") return false;
-  return Object.entries(value).some(([key, entry]) => FORBIDDEN_GRAPH_KEY.test(key) || containsForbiddenGraphValue(entry));
+  if (seen.has(value)) return false;
+  seen.add(value);
+  return Object.entries(value).some(([key, entry]) => FORBIDDEN_GRAPH_KEY.test(key) || containsForbiddenGraphValue(entry, seen));
 }
 
 function validatePolicy(
-  policy: NodeFlowNode["policy"],
+  policy: unknown,
   path: string,
   issues: NodeFlowValidationIssue[],
 ): void {
-  if (!policy) return;
-  const retry = policy.retry;
-  if (retry && (!Number.isInteger(retry.maxAttempts) || retry.maxAttempts < 1 || retry.maxAttempts > 10)) {
+  if (policy === undefined) return;
+  if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
+    issues.push(issue(path, "invalid_policy", "Node policy must be an object."));
+    return;
+  }
+  const typedPolicy = policy as Record<string, unknown>;
+  if (typedPolicy.retry !== undefined && (!typedPolicy.retry || typeof typedPolicy.retry !== "object" || Array.isArray(typedPolicy.retry))) {
+    issues.push(issue(`${path}.retry`, "invalid_retry_policy", "Retry policy must be an object."));
+  }
+  if (typedPolicy.timeout !== undefined && (!typedPolicy.timeout || typeof typedPolicy.timeout !== "object" || Array.isArray(typedPolicy.timeout))) {
+    issues.push(issue(`${path}.timeout`, "invalid_timeout_policy", "Timeout policy must be an object."));
+  }
+  const retry = isRecord(typedPolicy.retry) ? typedPolicy.retry : undefined;
+  const timeout = isRecord(typedPolicy.timeout) ? typedPolicy.timeout : undefined;
+  if (retry && (typeof retry.maxAttempts !== "number" || !Number.isInteger(retry.maxAttempts) || retry.maxAttempts < 1 || retry.maxAttempts > 10)) {
     issues.push(issue(`${path}.retry.maxAttempts`, "invalid_retry_policy", "Retry maxAttempts must be an integer from 1 to 10."));
   }
-  if (retry && (!Number.isFinite(retry.backoffMs) || retry.backoffMs < 0 || retry.backoffMs > 300_000)) {
+  if (retry && (typeof retry.backoffMs !== "number" || !Number.isFinite(retry.backoffMs) || retry.backoffMs < 0 || retry.backoffMs > 300_000)) {
     issues.push(issue(`${path}.retry.backoffMs`, "invalid_retry_policy", "Retry backoffMs must be between 0 and 300000."));
   }
-  if (retry?.maxBackoffMs !== undefined && (!Number.isFinite(retry.maxBackoffMs) || retry.maxBackoffMs < retry.backoffMs)) {
+  if (retry?.maxBackoffMs !== undefined && (
+    typeof retry.maxBackoffMs !== "number"
+    || !Number.isFinite(retry.maxBackoffMs)
+    || typeof retry.backoffMs !== "number"
+    || retry.maxBackoffMs < retry.backoffMs
+  )) {
     issues.push(issue(`${path}.retry.maxBackoffMs`, "invalid_retry_policy", "Retry maxBackoffMs must be at least backoffMs."));
   }
-  if (policy.timeout && (!Number.isInteger(policy.timeout.timeoutMs) || policy.timeout.timeoutMs < 1 || policy.timeout.timeoutMs > 300_000)) {
+  if (timeout && (typeof timeout.timeoutMs !== "number" || !Number.isInteger(timeout.timeoutMs) || timeout.timeoutMs < 1 || timeout.timeoutMs > 300_000)) {
     issues.push(issue(`${path}.timeout.timeoutMs`, "invalid_timeout_policy", "Timeout must be an integer from 1 to 300000 milliseconds."));
   }
 }
 
 function validateCredentialBindings(
-  node: NodeFlowNode,
+  bindings: unknown,
   nodePath: string,
   allowedSlots: string[],
   issues: NodeFlowValidationIssue[],
-): void {
+): NodeFlowNode["credentialBindings"] {
+  if (bindings === undefined) return [];
+  if (!Array.isArray(bindings)) {
+    issues.push(issue(`${nodePath}.credentialBindings`, "invalid_credential_bindings", "Credential bindings must be an array."));
+    return [];
+  }
   const slots = new Set<string>();
-  (node.credentialBindings ?? []).forEach((binding, index) => {
+  const normalized: NonNullable<NodeFlowNode["credentialBindings"]> = [];
+  bindings.forEach((binding, index) => {
     const path = `${nodePath}.credentialBindings[${index}]`;
-    if (!trimmedString(binding.slot)) issues.push(issue(`${path}.slot`, "required", "Credential slot is required."));
-    if (!trimmedString(binding.credentialId)) issues.push(issue(`${path}.credentialId`, "required", "Credential binding must reference a credential id."));
-    if (slots.has(binding.slot)) issues.push(issue(`${path}.slot`, "duplicate_credential_slot", `Duplicate credential slot: ${binding.slot}`));
-    if (!allowedSlots.includes(binding.slot)) issues.push(issue(`${path}.slot`, "unknown_credential_slot", `Definition does not declare credential slot: ${binding.slot}`));
-    slots.add(binding.slot);
+    if (!isRecord(binding)) {
+      issues.push(issue(path, "invalid_credential_binding", "Credential binding must be an object."));
+      return;
+    }
+    const slot = trimmedString(binding.slot);
+    const credentialId = trimmedString(binding.credentialId);
+    if (!slot) issues.push(issue(`${path}.slot`, "required", "Credential slot is required."));
+    if (!credentialId) issues.push(issue(`${path}.credentialId`, "required", "Credential binding must reference a credential id."));
+    if (slot && slots.has(slot)) issues.push(issue(`${path}.slot`, "duplicate_credential_slot", `Duplicate credential slot: ${slot}`));
+    if (slot && !allowedSlots.includes(slot)) issues.push(issue(`${path}.slot`, "unknown_credential_slot", `Definition does not declare credential slot: ${slot}`));
+    if (slot) slots.add(slot);
+    if (slot && credentialId) normalized.push({ slot, credentialId });
   });
+  return normalized;
 }
 
 function validateConfiguration(
@@ -324,9 +361,70 @@ function matchesValueSchema(value: NodeFlowJsonValue, type: NodeFlowValueSchema[
   return typeof value === type;
 }
 
-function normalizeNode(rawNode: NodeFlowNode, index: number, issues: NodeFlowValidationIssue[]): NodeFlowNode | null {
+const VALUE_SCHEMA_TYPES = new Set<NodeFlowValueSchema["type"]>([
+  "any", "object", "array", "string", "number", "boolean", "null",
+]);
+
+function normalizeValueSchema(
+  value: unknown,
+  path: string,
+  issues: NodeFlowValidationIssue[],
+  ancestors = new Set<object>(),
+): NodeFlowValueSchema | undefined {
+  if (!isRecord(value)) {
+    issues.push(issue(path, "invalid_value_schema", "Value schema must be an object."));
+    return undefined;
+  }
+  if (ancestors.has(value)) {
+    issues.push(issue(path, "invalid_value_schema", "Value schema cannot contain circular references."));
+    return undefined;
+  }
+  const type = value.type;
+  if (typeof type !== "string" || !VALUE_SCHEMA_TYPES.has(type as NodeFlowValueSchema["type"])) {
+    issues.push(issue(`${path}.type`, "invalid_value_schema_type", "Value schema type is not supported."));
+    return undefined;
+  }
+  const nextAncestors = new Set(ancestors).add(value);
+  const normalized: NodeFlowValueSchema = { type: type as NodeFlowValueSchema["type"] };
+  if (value.description !== undefined) {
+    if (typeof value.description === "string") normalized.description = value.description.trim();
+    else issues.push(issue(`${path}.description`, "invalid_value_schema", "Value schema description must be a string."));
+  }
+  if (value.required !== undefined) {
+    if (!Array.isArray(value.required)) {
+      issues.push(issue(`${path}.required`, "invalid_value_schema", "Value schema required must be an array of strings."));
+    } else {
+      const required: string[] = [];
+      value.required.forEach((entry, index) => {
+        const name = trimmedString(entry);
+        if (!name) issues.push(issue(`${path}.required[${index}]`, "invalid_value_schema", "Required property name must be a non-empty string."));
+        else required.push(name);
+      });
+      normalized.required = required;
+    }
+  }
+  if (value.properties !== undefined) {
+    if (!isRecord(value.properties)) {
+      issues.push(issue(`${path}.properties`, "invalid_value_schema", "Value schema properties must be an object."));
+    } else {
+      const properties: Record<string, NodeFlowValueSchema> = {};
+      for (const [key, property] of Object.entries(value.properties)) {
+        const normalizedProperty = normalizeValueSchema(property, `${path}.properties.${key}`, issues, nextAncestors);
+        if (normalizedProperty) properties[key] = normalizedProperty;
+      }
+      normalized.properties = properties;
+    }
+  }
+  if (value.items !== undefined) {
+    const items = normalizeValueSchema(value.items, `${path}.items`, issues, nextAncestors);
+    if (items) normalized.items = items;
+  }
+  return normalized;
+}
+
+function normalizeNode(rawNode: unknown, index: number, issues: NodeFlowValidationIssue[]): NodeFlowNode | null {
   const nodePath = `nodes[${index}]`;
-  if (!rawNode || typeof rawNode !== "object" || Array.isArray(rawNode)) {
+  if (!isRecord(rawNode)) {
     issues.push(issue(nodePath, "invalid_node", "Node must be an object."));
     return null;
   }
@@ -346,8 +444,8 @@ function normalizeNode(rawNode: NodeFlowNode, index: number, issues: NodeFlowVal
     return null;
   }
 
-  const widgetSchema = normalizeWidgetSchema(rawNode.widgetSchema, `${nodePath}.widgetSchema`, issues);
-  const position = rawNode.position
+  const widgetSchema = normalizeWidgetSchema(rawNode.widgetSchema as NodeWidgetSchema | undefined, `${nodePath}.widgetSchema`, issues);
+  const position = isRecord(rawNode.position)
     && typeof rawNode.position.x === "number"
     && Number.isFinite(rawNode.position.x)
     && typeof rawNode.position.y === "number"
@@ -361,31 +459,76 @@ function normalizeNode(rawNode: NodeFlowNode, index: number, issues: NodeFlowVal
     issues.push(issue(`${nodePath}.data`, "invalid_data", `Node ${id} data must be a JSON object.`));
   }
 
-  const definitionRef = rawNode.definition ?? { type, version: 1 };
-  const definition = resolveNodeDefinition(definitionRef.type, definitionRef.version);
-  if (definitionRef.type !== type) {
+  const rawDefinitionRef = rawNode.definition === undefined ? { type, version: 1 } : rawNode.definition;
+  let definitionType: string | null = null;
+  let definitionVersion: number | null = null;
+  if (!isRecord(rawDefinitionRef)) {
+    issues.push(issue(`${nodePath}.definition`, "invalid_definition_reference", "Node definition reference must be an object."));
+  } else {
+    definitionType = trimmedString(rawDefinitionRef.type);
+    if (!definitionType) issues.push(issue(`${nodePath}.definition.type`, "required", "Node definition type is required."));
+    if (typeof rawDefinitionRef.version !== "number" || !Number.isInteger(rawDefinitionRef.version) || rawDefinitionRef.version < 1) {
+      issues.push(issue(`${nodePath}.definition.version`, "invalid_definition_version", "Node definition version must be a positive integer."));
+    } else {
+      definitionVersion = rawDefinitionRef.version;
+    }
+  }
+  const definition = definitionType && definitionVersion ? resolveNodeDefinition(definitionType, definitionVersion) : null;
+  if (definitionType && definitionType !== type) {
     issues.push(issue(`${nodePath}.definition.type`, "definition_type_mismatch", "Node type must match its definition reference."));
   }
-  if (!definition) {
-    issues.push(issue(`${nodePath}.definition`, "unknown_node_definition", `Unknown node definition: ${definitionRef.type}@${definitionRef.version}`));
+  if (definitionType && definitionVersion && !definition) {
+    issues.push(issue(`${nodePath}.definition`, "unknown_node_definition", `Unknown node definition: ${definitionType}@${definitionVersion}`));
   }
   if (definition && rawNode.sideEffect !== undefined && rawNode.sideEffect !== definition.sideEffect) {
     issues.push(issue(`${nodePath}.sideEffect`, "definition_metadata_mismatch", "Node side effect must match its definition."));
   }
-  if (definition && rawNode.capabilities !== undefined && [...rawNode.capabilities].sort().join("\0") !== [...definition.capabilities].sort().join("\0")) {
-    issues.push(issue(`${nodePath}.capabilities`, "definition_metadata_mismatch", "Node capabilities must match its definition."));
+  let suppliedCapabilities: string[] | undefined;
+  if (rawNode.capabilities !== undefined) {
+    if (!Array.isArray(rawNode.capabilities) || rawNode.capabilities.some((capability) => typeof capability !== "string")) {
+      issues.push(issue(`${nodePath}.capabilities`, "invalid_capabilities", "Node capabilities must be an array of strings."));
+    } else {
+      suppliedCapabilities = rawNode.capabilities;
+      if (definition && [...suppliedCapabilities].sort().join("\0") !== [...definition.capabilities].sort().join("\0")) {
+        issues.push(issue(`${nodePath}.capabilities`, "definition_metadata_mismatch", "Node capabilities must match its definition."));
+      }
+    }
   }
-  const ports = rawNode.ports ?? definition?.ports ?? [];
+  const rawPorts = rawNode.ports === undefined ? definition?.ports ?? [] : rawNode.ports;
+  if (!Array.isArray(rawPorts)) {
+    issues.push(issue(`${nodePath}.ports`, "invalid_ports", "Node ports must be an array."));
+  }
+  const ports: NonNullable<NodeFlowNode["ports"]> = [];
   const portIds = new Set<string>();
-  ports.forEach((port, portIndex) => {
+  (Array.isArray(rawPorts) ? rawPorts : []).forEach((port, portIndex) => {
     const portPath = `${nodePath}.ports[${portIndex}]`;
-    if (!trimmedString(port.id)) issues.push(issue(`${portPath}.id`, "required", "Port id is required."));
-    if (portIds.has(port.id)) issues.push(issue(`${portPath}.id`, "duplicate_port_id", `Duplicate port id: ${port.id}`));
-    portIds.add(port.id);
-    if (port.direction !== "input" && port.direction !== "output") issues.push(issue(`${portPath}.direction`, "invalid_port_direction", "Port direction must be input or output."));
+    if (!isRecord(port)) {
+      issues.push(issue(portPath, "invalid_port", "Port must be an object."));
+      return;
+    }
+    const portId = trimmedString(port.id);
+    if (!portId) issues.push(issue(`${portPath}.id`, "required", "Port id is required."));
+    if (portId && portIds.has(portId)) issues.push(issue(`${portPath}.id`, "duplicate_port_id", `Duplicate port id: ${portId}`));
+    if (portId) portIds.add(portId);
+    const direction = port.direction;
+    if (direction !== "input" && direction !== "output") issues.push(issue(`${portPath}.direction`, "invalid_port_direction", "Port direction must be input or output."));
+    const schema = normalizeValueSchema(port.schema, `${portPath}.schema`, issues);
+    const cardinality = port.cardinality;
+    if (cardinality !== undefined && cardinality !== "one" && cardinality !== "many") {
+      issues.push(issue(`${portPath}.cardinality`, "invalid_port_cardinality", "Port cardinality must be one or many."));
+    }
+    if (portId && (direction === "input" || direction === "output") && schema) {
+      ports.push({
+        id: portId,
+        direction,
+        schema,
+        ...(port.required !== undefined ? { required: Boolean(port.required) } : {}),
+        ...(cardinality === "one" || cardinality === "many" ? { cardinality } : {}),
+      });
+    }
   });
   validatePolicy(rawNode.policy, `${nodePath}.policy`, issues);
-  validateCredentialBindings(rawNode, nodePath, definition?.credentials.map((credential) => credential.slot) ?? [], issues);
+  const credentialBindings = validateCredentialBindings(rawNode.credentialBindings, nodePath, definition?.credentials.map((credential) => credential.slot) ?? [], issues);
   if (rawNode.data && containsForbiddenGraphValue(rawNode.data)) {
     issues.push(issue(`${nodePath}.data`, "unsafe_graph_data", "Graph data cannot contain raw secrets or custom source code."));
   }
@@ -399,19 +542,19 @@ function normalizeNode(rawNode: NodeFlowNode, index: number, issues: NodeFlowVal
     ...(widgetSchema ? { widgetSchema } : {}),
     ...(position ? { position } : {}),
     ...(rawNode.data !== undefined && isPlainJsonObject(rawNode.data) ? { data: rawNode.data } : {}),
-    definition: definitionRef,
+    definition: { type: definitionType ?? type, version: definitionVersion ?? 1 },
     ports,
-    credentialBindings: rawNode.credentialBindings ?? [],
-    policy: rawNode.policy ?? definition?.defaultPolicy ?? {},
-    capabilities: definition?.capabilities ?? rawNode.capabilities ?? [],
-    sideEffect: definition?.sideEffect ?? rawNode.sideEffect ?? "none",
-    disabled: rawNode.disabled ?? false,
+    credentialBindings,
+    policy: isRecord(rawNode.policy) ? rawNode.policy as NodeFlowNode["policy"] : definition?.defaultPolicy ?? {},
+    capabilities: definition?.capabilities ?? suppliedCapabilities ?? [],
+    sideEffect: definition?.sideEffect ?? (typeof rawNode.sideEffect === "string" ? rawNode.sideEffect as NodeFlowNode["sideEffect"] : "none"),
+    disabled: typeof rawNode.disabled === "boolean" ? rawNode.disabled : false,
   };
 }
 
-function normalizeEdge(rawEdge: NodeFlowEdge, index: number, issues: NodeFlowValidationIssue[]): NodeFlowEdge | null {
+function normalizeEdge(rawEdge: unknown, index: number, issues: NodeFlowValidationIssue[]): NodeFlowEdge | null {
   const edgePath = `edges[${index}]`;
-  if (!rawEdge || typeof rawEdge !== "object" || Array.isArray(rawEdge)) {
+  if (!isRecord(rawEdge)) {
     issues.push(issue(edgePath, "invalid_edge", "Edge must be an object."));
     return null;
   }
@@ -534,22 +677,36 @@ export function validateNodeFlowGraph(graph: unknown): NodeFlowValidationRespons
   });
 
   const inputSchema = normalizeWidgetSchema(rawGraph.inputSchema, "inputSchema", issues);
+  let schemas: NodeFlowGraph["schemas"] | undefined;
+  if (rawGraph.schemas !== undefined) {
+    if (!isRecord(rawGraph.schemas)) {
+      issues.push(issue("schemas", "invalid_schemas", "Node flow schemas must be an object."));
+    } else {
+      const input = rawGraph.schemas.input === undefined
+        ? undefined
+        : normalizeValueSchema(rawGraph.schemas.input, "schemas.input", issues);
+      const output = rawGraph.schemas.output === undefined
+        ? undefined
+        : normalizeValueSchema(rawGraph.schemas.output, "schemas.output", issues);
+      schemas = { ...(input ? { input } : {}), ...(output ? { output } : {}) };
+    }
+  }
   if (rawGraph.metadata !== undefined && !isPlainJsonObject(rawGraph.metadata)) {
     issues.push(issue("metadata", "invalid_metadata", "Node flow graph metadata must be a JSON object."));
   }
   if (rawGraph.metadata && containsForbiddenGraphValue(rawGraph.metadata)) {
     issues.push(issue("metadata", "unsafe_graph_metadata", "Graph metadata cannot contain raw secrets or custom source code."));
   }
-  validatePublication(rawGraph.publication, issues);
+  const publication = validatePublication(rawGraph.publication, issues);
 
   const normalizedGraph: NodeFlowGraph = {
     schemaVersion: NODE_FLOW_SCHEMA_VERSION,
     nodes,
     edges,
     ...(inputSchema ? { inputSchema } : {}),
-    ...(rawGraph.schemas ? { schemas: rawGraph.schemas } : {}),
+    ...(schemas ? { schemas } : {}),
     ...(rawGraph.metadata !== undefined && isPlainJsonObject(rawGraph.metadata) ? { metadata: rawGraph.metadata } : {}),
-    ...(rawGraph.publication ? { publication: rawGraph.publication } : {}),
+    ...(publication ? { publication } : {}),
   };
   const executionOrder = computeExecutionOrder(nodes, edges, issues);
   const valid = issues.length === 0;
@@ -561,18 +718,30 @@ export function validateNodeFlowGraph(graph: unknown): NodeFlowValidationRespons
 }
 
 function validatePublication(
-  publication: NodeFlowGraph["publication"],
+  publication: unknown,
   issues: NodeFlowValidationIssue[],
-): void {
-  if (!publication) return;
-  if (!trimmedString(publication.publicationId)) issues.push(issue("publication.publicationId", "required", "Publication id is required."));
-  if (!trimmedString(publication.publishedBy)) issues.push(issue("publication.publishedBy", "required", "Publication author is required."));
-  if (!trimmedString(publication.publishedAt) || !Number.isFinite(Date.parse(publication.publishedAt))) {
+): NodeFlowGraph["publication"] | undefined {
+  if (publication === undefined) return undefined;
+  if (!isRecord(publication)) {
+    issues.push(issue("publication", "invalid_publication", "Publication metadata must be an object."));
+    return undefined;
+  }
+  const publicationId = trimmedString(publication.publicationId);
+  const publishedBy = trimmedString(publication.publishedBy);
+  const publishedAt = trimmedString(publication.publishedAt);
+  const sourceVersion = publication.sourceVersion;
+  if (!publicationId) issues.push(issue("publication.publicationId", "required", "Publication id is required."));
+  if (!publishedBy) issues.push(issue("publication.publishedBy", "required", "Publication author is required."));
+  if (!publishedAt || !Number.isFinite(Date.parse(publishedAt))) {
     issues.push(issue("publication.publishedAt", "invalid_publication", "Publication timestamp must be ISO-compatible."));
   }
-  if (!Number.isInteger(publication.sourceVersion) || publication.sourceVersion < 1) {
+  if (typeof sourceVersion !== "number" || !Number.isInteger(sourceVersion) || sourceVersion < 1) {
     issues.push(issue("publication.sourceVersion", "invalid_publication", "Publication sourceVersion must be a positive integer."));
   }
+  if (!publicationId || !publishedBy || !publishedAt || typeof sourceVersion !== "number" || !Number.isInteger(sourceVersion) || sourceVersion < 1) {
+    return undefined;
+  }
+  return { publicationId, publishedBy, publishedAt, sourceVersion };
 }
 
 export function normalizeNodeFlowGraph(graph: unknown): NormalizedNodeFlowValidation {
diff --git a/tests/backend/domain/node-flows/node-flow-migrators.test.ts b/tests/backend/domain/node-flows/node-flow-migrators.test.ts
index 5ee0b0727a..770dbf693f 100644
--- a/tests/backend/domain/node-flows/node-flow-migrators.test.ts
+++ b/tests/backend/domain/node-flows/node-flow-migrators.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { migrateNodeCanvasGraphV1, migrateNodeFlowGraph } from "../../../../src/domain/node-flows/node-flow-migrators.js";
+import { validateNodeFlowGraph } from "../../../../src/domain/node-flows/node-flow-validation.js";
 
 describe("node flow migrators", () => {
   it("deterministically migrates backend v1 while retaining an untouched snapshot", () => {
@@ -16,16 +17,45 @@ describe("node flow migrators", () => {
     expect(legacy).toEqual({ nodes: [{ id: "start", type: "input", title: "Start" }], edges: [] });
   });
 
-  it("migrates a browser v1 canvas into the canonical graph without embedding its snapshot", () => {
+  it("migrates a browser v1 canvas into a valid canonical graph with reviewable snapshot metadata", () => {
     const legacy = {
-      nodes: [{ id: "trigger-1", kind: "trigger", label: "Trigger", description: "Draft", position: { x: 1, y: 2 }, inputPorts: [], outputPorts: [{ id: "event" }], config: [], metadata: {} }],
-      edges: [], selection: { nodeIds: ["trigger-1"], edgeIds: [] },
+      nodes: [
+        { id: "trigger-1", kind: "trigger", label: "Trigger", description: "Draft", position: { x: 1, y: 2 }, inputPorts: [], outputPorts: [{ id: "event" }], config: [], metadata: {} },
+        { id: "agent-1", kind: "agent", label: "Agent", inputPorts: [{ id: "in" }], outputPorts: [{ id: "agent" }], config: [], metadata: {} },
+        { id: "task-1", kind: "task", label: "Task", inputPorts: [{ id: "agent" }], outputPorts: [{ id: "task" }], config: [{ id: "prompt", value: "Do the work" }], metadata: {} },
+      ],
+      edges: [
+        { id: "one", source: { nodeId: "trigger-1", portId: "event" }, target: { nodeId: "agent-1", portId: "in" } },
+        { id: "two", source: { nodeId: "agent-1", portId: "agent" }, target: { nodeId: "task-1", portId: "agent" } },
+      ],
+      selection: { nodeIds: ["trigger-1"], edgeIds: [] },
     };
     const result = migrateNodeCanvasGraphV1(legacy);
 
     expect(result.legacySnapshot).toEqual(legacy);
     expect(result.graph.schemaVersion).toBe(2);
-    expect(result.graph.metadata).toEqual({ canvasSelection: legacy.selection });
-    expect(JSON.stringify(result.graph)).not.toContain("legacySnapshot");
+    expect(result.graph.nodes.map((node) => node.type)).toEqual(["input", "set_fields", "template"]);
+    expect(result.graph.edges).toEqual([
+      expect.objectContaining({ fromHandle: "output", toHandle: "input" }),
+      expect.objectContaining({ fromHandle: "output", toHandle: "input" }),
+    ]);
+    expect(result.graph.metadata).toEqual({
+      canvasSelection: legacy.selection,
+      migration: { source: "browser_canvas_v1", legacySnapshot: legacy },
+    });
+    expect(validateNodeFlowGraph(result.graph)).toMatchObject({ valid: true, errors: [] });
+    expect(migrateNodeCanvasGraphV1(result.graph)).toMatchObject({ migrated: false, legacySnapshot: null });
+  });
+
+  it("preserves unsafe legacy keys so canonical validation rejects them", () => {
+    const result = migrateNodeCanvasGraphV1({
+      nodes: [{ id: "task-1", kind: "task", label: "Task", config: [{ id: "prompt", value: "Safe" }, { id: "generatedSource", value: "unsafe" }] }],
+      edges: [],
+    });
+
+    expect(validateNodeFlowGraph(result.graph).errors).toContainEqual(expect.objectContaining({
+      field: "nodes[0].data",
+      code: "unsafe_graph_data",
+    }));
   });
 });
diff --git a/tests/backend/domain/node-flows/node-flow-validation.test.ts b/tests/backend/domain/node-flows/node-flow-validation.test.ts
index 2e56cc6bbb..481aff17ee 100644
--- a/tests/backend/domain/node-flows/node-flow-validation.test.ts
+++ b/tests/backend/domain/node-flows/node-flow-validation.test.ts
@@ -112,4 +112,71 @@ describe("node flow validation", () => {
 
     expect(validateNodeFlowGraph(graph).executionOrder).toEqual(["a", "z"]);
   });
+
+  it("returns deterministic field-level issues for malformed nested graph entries", () => {
+    const malformed = {
+      schemaVersion: 2,
+      nodes: [
+        null,
+        {
+          id: "broken",
+          type: "input",
+          title: "Broken",
+          definition: { type: null, version: "one" },
+          ports: [null, { id: "", direction: "sideways", schema: null }],
+          credentialBindings: [null, { slot: "provider", credentialId: null }],
+          policy: { retry: null, timeout: [] },
+          data: { nested: [null, { value: true }] },
+        },
+      ],
+      edges: [null],
+      inputSchema: { fields: [null] },
+      schemas: { input: { type: "object", required: [null], properties: { child: null } }, output: [] },
+      publication: null,
+    } as unknown;
+
+    const first = validateNodeFlowGraph(malformed);
+    const second = validateNodeFlowGraph(malformed);
+
+    expect(first).toEqual(second);
+    expect(first.valid).toBe(false);
+    expect(first.errors).toEqual(expect.arrayContaining([
+      expect.objectContaining({ field: "nodes[0]", code: "invalid_node" }),
+      expect.objectContaining({ field: "nodes[1].definition.type", code: "required" }),
+      expect.objectContaining({ field: "nodes[1].definition.version", code: "invalid_definition_version" }),
+      expect.objectContaining({ field: "nodes[1].ports[0]", code: "invalid_port" }),
+      expect.objectContaining({ field: "nodes[1].credentialBindings[0]", code: "invalid_credential_binding" }),
+      expect.objectContaining({ field: "nodes[1].policy.retry", code: "invalid_retry_policy" }),
+      expect.objectContaining({ field: "edges[0]", code: "invalid_edge" }),
+      expect.objectContaining({ field: "inputSchema.fields[0]", code: "invalid_widget_field" }),
+      expect.objectContaining({ field: "schemas.input.required[0]", code: "invalid_value_schema" }),
+      expect.objectContaining({ field: "schemas.input.properties.child", code: "invalid_value_schema" }),
+      expect.objectContaining({ field: "schemas.output", code: "invalid_value_schema" }),
+      expect.objectContaining({ field: "publication", code: "invalid_publication" }),
+    ]));
+  });
+
+  it("rejects malformed collection containers without throwing", () => {
+    const result = validateNodeFlowGraph({
+      nodes: [{
+        id: "start",
+        type: "input",
+        title: "Start",
+        definition: null,
+        ports: null,
+        credentialBindings: {},
+        policy: "forever",
+        capabilities: [null],
+      }],
+      edges: [],
+    });
+
+    expect(result.errors).toEqual(expect.arrayContaining([
+      expect.objectContaining({ field: "nodes[0].definition", code: "invalid_definition_reference" }),
+      expect.objectContaining({ field: "nodes[0].ports", code: "invalid_ports" }),
+      expect.objectContaining({ field: "nodes[0].credentialBindings", code: "invalid_credential_bindings" }),
+      expect.objectContaining({ field: "nodes[0].policy", code: "invalid_policy" }),
+      expect.objectContaining({ field: "nodes[0].capabilities", code: "invalid_capabilities" }),
+    ]));
+  });
 });
diff --git a/tests/dashboard/lib/nodes-canvas-state.test.ts b/tests/dashboard/lib/nodes-canvas-state.test.ts
index be3bb89561..829fc89f8f 100644
--- a/tests/dashboard/lib/nodes-canvas-state.test.ts
+++ b/tests/dashboard/lib/nodes-canvas-state.test.ts
@@ -7,8 +7,10 @@ import {
   migrateNodeCanvasGraph,
   nodesCanvasReducer,
   serializeNodeCanvasGraph,
+  toCanonicalNodeFlowGraph,
   validateNodeCanvasGraph,
 } from "../../../dashboard/src/v2/lib/nodes-canvas-state.js";
+import { validateNodeFlowGraph } from "../../../src/domain/node-flows/node-flow-validation.js";
 
 const validationCodes = (graph: NodeCanvasGraph): string[] => (
   validateNodeCanvasGraph(graph).map((issue) => `${issue.code}:${issue.entityId}`)
@@ -33,6 +35,15 @@ describe("nodes canvas state", () => {
     ]);
     expect(graph.selection).toEqual({ nodeIds: ["trigger-1"], edgeIds: [] });
     expect(validateNodeCanvasGraph(graph)).toEqual([]);
+    const canonical = toCanonicalNodeFlowGraph(graph);
+    expect(validateNodeFlowGraph(canonical)).toMatchObject({ valid: true, errors: [] });
+    expect(canonical.nodes.map((node) => node.type)).toEqual([
+      "set_fields",
+      "condition",
+      "output",
+      "template",
+      "input",
+    ]);
   });
 
   it("handles reducer node, edge, config, selection, and delete operations", () => {
@@ -211,6 +222,21 @@ describe("nodes canvas state", () => {
     expect(migrateNodeCanvasGraph(first.graph)).toMatchObject({ migrated: false, legacySnapshot: null });
   });
 
+  it("retains a legacy localStorage snapshot as non-executable migration metadata", () => {
+    const current = createInitialNodeCanvasGraph();
+    const { schemaVersion: _schemaVersion, ...legacyGraph } = current;
+    const legacy = JSON.parse(JSON.stringify(legacyGraph)) as typeof legacyGraph;
+    const migrated = migrateNodeCanvasGraph(legacy);
+    const canonical = toCanonicalNodeFlowGraph(migrated.graph, migrated.legacySnapshot);
+
+    expect(canonical.metadata?.migration).toEqual({
+      source: "browser_canvas_v1",
+      legacySnapshot: legacy,
+    });
+    expect(validateNodeFlowGraph(canonical)).toMatchObject({ valid: true, errors: [] });
+    expect(toCanonicalNodeFlowGraph(migrated.graph, migrated.legacySnapshot)).toEqual(canonical);
+  });
+
   it("lays out graphs deterministically from ids and edges", () => {
     const graph = {
       ...createInitialNodeCanvasGraph(),
diff --git a/tests/dashboard/v2/nodes-page.test.tsx b/tests/dashboard/v2/nodes-page.test.tsx
index f3c48eb3e8..7810e3895f 100644
--- a/tests/dashboard/v2/nodes-page.test.tsx
+++ b/tests/dashboard/v2/nodes-page.test.tsx
@@ -7,6 +7,7 @@ import "@testing-library/jest-dom/vitest";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { NODES_CANVAS_STORAGE_KEY, NodesPage } from "../../../dashboard/src/v2/NodesPage.js";
 import { ProjectDataContext } from "../../../dashboard/src/v2/context/project-data.js";
+import { createInitialNodeCanvasGraph } from "../../../dashboard/src/v2/lib/nodes-canvas-state.js";
 
 const api = vi.hoisted(() => ({ fetchNodeFlows: vi.fn(), fetchNodeFlowCatalog: vi.fn(), createNodeFlowDraft: vi.fn(), fetchNodeFlow: vi.fn(), fetchNodeFlowRuns: vi.fn(), fetchNodeFlowNodeRuns: vi.fn(), fetchNodeFlowAttempts: vi.fn(), patchNodeFlowDraft: vi.fn(), fetchNodeDefinition: vi.fn(), validateNodeFlowDraft: vi.fn(), deleteNodeFlow: vi.fn() }));
 vi.mock("../../../dashboard/src/v2/lib/node-flow-api.js", async (original) => ({ ...(await original()), ...api }));
@@ -31,15 +32,42 @@ describe("NodesPage governed workspace", () => {
   });
 
   it("imports legacy localStorage once and removes it as a source of truth", async () => {
-    window.localStorage.setItem(NODES_CANVAS_STORAGE_KEY, JSON.stringify({ schemaVersion: 2, nodes: [{ id: "input-1", type: "input", title: "Input", position: { x: 1, y: 1 } }], edges: [] }));
+    const { schemaVersion: _schemaVersion, ...legacy } = createInitialNodeCanvasGraph();
+    window.localStorage.setItem(NODES_CANVAS_STORAGE_KEY, JSON.stringify(legacy));
     api.createNodeFlowDraft.mockResolvedValue({ flowId: "imported", draftRevision: 1 });
     api.fetchNodeFlows.mockResolvedValueOnce({ flows: [] }).mockResolvedValueOnce({ flows: [flow] });
     render(<ProjectDataContext.Provider value={context as never}><NodesPage /></ProjectDataContext.Provider>);
     await waitFor(() => expect(api.createNodeFlowDraft).toHaveBeenCalledTimes(1));
+    expect(api.createNodeFlowDraft).toHaveBeenCalledWith("project-1", expect.objectContaining({
+      graph: expect.objectContaining({
+        schemaVersion: 2,
+        nodes: expect.arrayContaining([
+          expect.objectContaining({ type: "input", definition: { type: "input", version: 1 } }),
+          expect.objectContaining({ type: "set_fields", definition: { type: "set_fields", version: 1 } }),
+          expect.objectContaining({ type: "template", definition: { type: "template", version: 1 } }),
+        ]),
+        metadata: expect.objectContaining({
+          migration: { source: "browser_canvas_v1", legacySnapshot: legacy },
+        }),
+      }),
+    }));
     expect(window.localStorage.getItem(NODES_CANVAS_STORAGE_KEY)).toBeNull();
     expect(window.localStorage.getItem("codeux:nodes-canvas:imported:project-1")).toBe("imported");
   });
 
+  it("keeps legacy localStorage available when backend persistence fails", async () => {
+    const legacy = JSON.stringify(createInitialNodeCanvasGraph());
+    window.localStorage.setItem(NODES_CANVAS_STORAGE_KEY, legacy);
+    api.createNodeFlowDraft.mockRejectedValue(new Error("Draft persistence failed"));
+    api.fetchNodeFlows.mockResolvedValueOnce({ flows: [] });
+
+    render(<ProjectDataContext.Provider value={context as never}><NodesPage /></ProjectDataContext.Provider>);
+
+    expect(await screen.findByRole("alert")).toHaveTextContent("Draft persistence failed");
+    expect(window.localStorage.getItem(NODES_CANVAS_STORAGE_KEY)).toBe(legacy);
+    expect(window.localStorage.getItem("codeux:nodes-canvas:imported:project-1")).toBeNull();
+  });
+
   it("surfaces optimistic save conflicts", async () => {
     const user = userEvent.setup(); api.patchNodeFlowDraft.mockResolvedValue({ conflict: { message: "The draft changed after it was read; reload the summary and reapply the patch.", actualDraftRevision: 3 } });
     render(<ProjectDataContext.Provider value={context as never}><NodesPage /></ProjectDataContext.Provider>);

From 2b9336296dfe3515faa99388a7acb6574577bed4 Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 07:53:10 +0000
Subject: [PATCH 14/25] feat(task T11): implement via codex

---
 dashboard/src/v2/NodesPage.tsx                |  11 +-
 .../v2/components/nodes/NodeRunDebugger.tsx   |  10 +-
 dashboard/src/v2/lib/node-flow-api.ts         |  18 ++
 dashboard/src/v2/types.ts                     |   2 +
 .../node-flow-builtins-and-security.md        |   4 +-
 .../node-flow-durable-execution.md            |   4 +-
 ...ecture-node-flow-builtins-and-security.mdx |   4 +-
 ...chitecture-node-flow-durable-execution.mdx |   4 +-
 .../docs/user-dashboard-node-flows.mdx        |   2 +
 docs-web/user/dashboard/node-flows.md         |   2 +
 .../node-flow-builtins-and-security.md        |   2 +-
 .../node-flow-durable-execution.md            |   4 +-
 docs/dashboard/node-flows.md                  |   2 +-
 .../dependency-factory/dashboard-factory.ts   |   6 +-
 src/contracts/node-flow-types.ts              |  20 +++
 .../automation-approval-repository.ts         |  53 +++---
 src/repositories/node-flow-repository.ts      |   7 +
 src/server/node-flow-routes.ts                |  27 ++-
 src/services/node-flow-runtime-service.ts     | 161 +++++++++++++++---
 src/services/node-flow-service.ts             |   7 +
 src/services/node-flows/approval-service.ts   |  24 ++-
 .../node-flows/builtins/builtin-executors.ts  |   4 +-
 .../node-flows/node-flow-recovery-service.ts  |  25 ++-
 ...automation-governance-repositories.test.ts |  16 ++
 tests/backend/server/node-flow-routes.test.ts |  38 +++++
 .../node-flow-recovery-service.test.ts        |  21 +++
 .../node-flow-runtime-service.test.ts         | 101 ++++++++++-
 tests/dashboard/v2/node-run-debugger.test.tsx |  26 +++
 tests/dashboard/v2/nodes-page.test.tsx        |   4 +-
 29 files changed, 522 insertions(+), 87 deletions(-)
 create mode 100644 tests/dashboard/v2/node-run-debugger.test.tsx

diff --git a/dashboard/src/v2/NodesPage.tsx b/dashboard/src/v2/NodesPage.tsx
index f550fa51fc..4af49b2dd2 100644
--- a/dashboard/src/v2/NodesPage.tsx
+++ b/dashboard/src/v2/NodesPage.tsx
@@ -12,12 +12,12 @@ import { NodePalette } from "./components/nodes/NodePalette.js";
 import { NodeGovernancePanel } from "./components/nodes/NodeGovernancePanel.js";
 import { NodeRunDebugger } from "./components/nodes/NodeRunDebugger.js";
 import { useProjectData } from "./context/project-data.js";
-import type { NodeDefinitionManifest, NodeFlowDraftReview, NodeFlowGraph, NodeFlowNode, NodeFlowNodeAttemptRecord, NodeFlowNodeRunRecord, NodeFlowRecord, NodeFlowRunRecord } from "./types.js";
+import type { AutomationApprovalRecord, NodeDefinitionManifest, NodeFlowDraftReview, NodeFlowGraph, NodeFlowNode, NodeFlowNodeAttemptRecord, NodeFlowNodeRunRecord, NodeFlowRecord, NodeFlowRunRecord } from "./types.js";
 import { createDefaultNodeFlowGraph, isNodeFlowDirty, updateNodeInGraph } from "./lib/node-flow-view-models.js";
 import { deserializeNodeCanvasGraphWithMigration, toCanonicalNodeFlowGraph } from "./lib/nodes-canvas-state.js";
 import {
-  cancelNodeFlowRun, compareNodeFlowVersions, createNodeFlowDraft, deleteNodeFlow, dryRunNodeFlowDraft,
-  fetchNodeDefinition, fetchNodeFlow, fetchNodeFlowAttempts, fetchNodeFlowCatalog, fetchNodeFlowNodeRuns,
+  cancelNodeFlowRun, compareNodeFlowVersions, createNodeFlowDraft, decideNodeFlowApproval, deleteNodeFlow, dryRunNodeFlowDraft,
+  fetchNodeDefinition, fetchNodeFlow, fetchNodeFlowApprovals, fetchNodeFlowAttempts, fetchNodeFlowCatalog, fetchNodeFlowNodeRuns,
   fetchNodeFlowRuns, fetchNodeFlows, patchNodeFlowDraft, publishNodeFlowDraft, requestNodeFlowCredential,
   retryNodeFlowRun, rollbackNodeFlow, runNodeFlow, validateNodeFlowDraft,
   type NodeDefinitionSummary, type NodeFlowDryRunResponse, type NodeFlowVersionDiff,
@@ -47,6 +47,7 @@ export const NodesPage: FunctionComponent = () => {
   const [selectedRunId, setSelectedRunId] = useState<string | null>(null);
   const [nodeRuns, setNodeRuns] = useState<NodeFlowNodeRunRecord[]>([]);
   const [attempts, setAttempts] = useState<NodeFlowNodeAttemptRecord[]>([]);
+  const [approvals, setApprovals] = useState<AutomationApprovalRecord[]>([]);
   const [loading, setLoading] = useState(false);
   const [busy, setBusy] = useState(false);
   const [error, setError] = useState<string | null>(null);
@@ -104,7 +105,7 @@ export const NodesPage: FunctionComponent = () => {
     const response = await fetchNodeFlowRuns(record.id); setRuns(response.runs); setSelectedRunId((current) => current ?? response.runs[0]?.id ?? null);
   }, [record]);
   useEffect(() => { setRuns([]); setSelectedRunId(null); if (record) void refreshRuns().catch((requestError) => setError(errorMessage(requestError))); }, [record?.id]);
-  useEffect(() => { if (!selectedRunId) { setNodeRuns([]); setAttempts([]); return; } const controller = new AbortController(); void Promise.all([fetchNodeFlowNodeRuns(selectedRunId, controller.signal), fetchNodeFlowAttempts(selectedRunId, controller.signal)]).then(([nodes, history]) => { setNodeRuns(nodes.nodeRuns); setAttempts(history.attempts); }).catch((requestError) => { if (!controller.signal.aborted) setError(errorMessage(requestError)); }); return () => controller.abort(); }, [selectedRunId]);
+  useEffect(() => { if (!selectedRunId) { setNodeRuns([]); setAttempts([]); setApprovals([]); return; } const controller = new AbortController(); void Promise.all([fetchNodeFlowNodeRuns(selectedRunId, controller.signal), fetchNodeFlowAttempts(selectedRunId, controller.signal), fetchNodeFlowApprovals(selectedRunId, controller.signal)]).then(([nodes, history, governed]) => { setNodeRuns(nodes.nodeRuns); setAttempts(history.attempts); setApprovals(governed.approvals); }).catch((requestError) => { if (!controller.signal.aborted) setError(errorMessage(requestError)); }); return () => controller.abort(); }, [selectedRunId]);
 
   const act = async (action: () => Promise<void>): Promise<void> => { setBusy(true); setError(null); setNotice(null); try { await action(); } catch (requestError) { setError(errorMessage(requestError)); } finally { setBusy(false); } };
   const selectFlow = (flowId: string): void => { const flow = flows.find((item) => item.id === flowId); if (!flow || !projectId) return; applyRecord(flow); void validateNodeFlowDraft(projectId, flow.id).then(setReview).catch((requestError) => setError(errorMessage(requestError))); };
@@ -129,6 +130,6 @@ export const NodesPage: FunctionComponent = () => {
       <NodePalette definitions={catalog} loading={loading} disabled={!record || busy} onCreateNode={addNode} />
       {record ? <NodeFlowInspector selectedNode={selectedNode} definition={selectedDefinition} validation={review ? { valid: review.valid, errors: review.validationIssues } : null} requiredCredentials={review?.requiredCredentials.filter((item) => item.nodeId === selectedNode?.id) ?? []} agents={[]} attachments={[]} attachAgentId="" onAttachAgentIdChange={() => undefined} onAttachAgent={() => undefined} onDetachAgent={() => undefined} onNodeChange={(id, update) => setGraph((current) => updateNodeInGraph(current, id, update))} onRequestCredential={(nodeId, slot) => { if (projectId && record) void act(async () => { await requestNodeFlowCredential(projectId, record.id, nodeId, slot); setNotice("Credential binding request recorded; secret material remains outside the graph."); }); }} /> : null}
     </div>
-    {record ? <><NodeGovernancePanel review={review} dryRun={dryRun} diff={diff} busy={busy} onValidate={validate} onDryRun={runDry} onCompare={compare} onPublish={publish} onRollback={rollback} /><NodeRunDebugger runs={runs} selectedRunId={selectedRunId} nodeRuns={nodeRuns} attempts={attempts} busy={busy} onSelectRun={setSelectedRunId} onRefresh={() => void act(refreshRuns)} onCancel={() => { const active = runs.find((item) => item.id === selectedRunId); if (projectId && active) void act(async () => { await cancelNodeFlowRun(projectId, active.id); await refreshRuns(); }); }} onRetry={() => { const active = runs.find((item) => item.id === selectedRunId); if (projectId && active) void act(async () => { const result = await retryNodeFlowRun(projectId, active.id); setRuns((current) => [result.run, ...current]); setSelectedRunId(result.run.id); }); }} /></> : null}
+    {record ? <><NodeGovernancePanel review={review} dryRun={dryRun} diff={diff} busy={busy} onValidate={validate} onDryRun={runDry} onCompare={compare} onPublish={publish} onRollback={rollback} /><NodeRunDebugger runs={runs} selectedRunId={selectedRunId} nodeRuns={nodeRuns} attempts={attempts} approvals={approvals} busy={busy} onSelectRun={setSelectedRunId} onRefresh={() => void act(refreshRuns)} onCancel={() => { const active = runs.find((item) => item.id === selectedRunId); if (projectId && active) void act(async () => { await cancelNodeFlowRun(projectId, active.id); await refreshRuns(); }); }} onRetry={() => { const active = runs.find((item) => item.id === selectedRunId); if (projectId && active) void act(async () => { const result = await retryNodeFlowRun(projectId, active.id); setRuns((current) => [result.run, ...current]); setSelectedRunId(result.run.id); }); }} onApprovalDecision={(approvalId, decision) => void act(async () => { const result = await decideNodeFlowApproval(approvalId, decision); setRuns((current) => current.map((item) => item.id === result.run.id ? result.run : item)); setNodeRuns(result.nodeRuns); setAttempts(result.attempts ?? []); setApprovals((current) => current.map((item) => item.id === approvalId ? { ...item, status: result.status, decidedAt: result.decidedAt, decidedBy: result.decidedBy, decision: result.decision, updatedAt: result.updatedAt } : item)); })} /></> : null}
   </PageContainer>;
 };
diff --git a/dashboard/src/v2/components/nodes/NodeRunDebugger.tsx b/dashboard/src/v2/components/nodes/NodeRunDebugger.tsx
index af284a8cff..6701ae9daf 100644
--- a/dashboard/src/v2/components/nodes/NodeRunDebugger.tsx
+++ b/dashboard/src/v2/components/nodes/NodeRunDebugger.tsx
@@ -1,17 +1,17 @@
 import type { FunctionComponent } from "preact";
-import { Ban, CalendarClock, ExternalLink, RefreshCw, RotateCw } from "lucide-preact";
-import type { NodeFlowNodeAttemptRecord, NodeFlowNodeRunRecord, NodeFlowRunRecord } from "../../types.js";
+import { Ban, CalendarClock, Check, ExternalLink, RefreshCw, RotateCw, X } from "lucide-preact";
+import type { AutomationApprovalRecord, NodeFlowNodeAttemptRecord, NodeFlowNodeRunRecord, NodeFlowRunRecord } from "../../types.js";
 import { redactNodeFlowSecrets } from "../../lib/node-flow-view-models.js";
 import { Button } from "../ui/Button.js";
 
-interface NodeRunDebuggerProps { runs: NodeFlowRunRecord[]; selectedRunId: string | null; nodeRuns: NodeFlowNodeRunRecord[]; attempts: NodeFlowNodeAttemptRecord[]; busy?: boolean; onSelectRun: (id: string) => void; onRefresh: () => void; onCancel: () => void; onRetry: () => void; }
+interface NodeRunDebuggerProps { runs: NodeFlowRunRecord[]; selectedRunId: string | null; nodeRuns: NodeFlowNodeRunRecord[]; attempts: NodeFlowNodeAttemptRecord[]; approvals?: AutomationApprovalRecord[]; busy?: boolean; onSelectRun: (id: string) => void; onRefresh: () => void; onCancel: () => void; onRetry: () => void; onApprovalDecision?: (approvalId: string, decision: "approve" | "reject") => void; }
 const terminal = new Set(["succeeded", "failed", "cancelled"]);
 const duration = (start: string | null, end: string | null): string => start ? `${Math.max(0, new Date(end ?? Date.now()).getTime() - new Date(start).getTime())} ms` : "Not started";
-export const NodeRunDebugger: FunctionComponent<NodeRunDebuggerProps> = ({ runs, selectedRunId, nodeRuns, attempts, busy, onSelectRun, onRefresh, onCancel, onRetry }) => {
+export const NodeRunDebugger: FunctionComponent<NodeRunDebuggerProps> = ({ runs, selectedRunId, nodeRuns, attempts, approvals = [], busy, onSelectRun, onRefresh, onCancel, onRetry, onApprovalDecision }) => {
   const run = runs.find((item) => item.id === selectedRunId) ?? runs[0] ?? null;
   return <section className="rounded-[var(--radius-panel)] border border-black/[0.06] bg-white/70 p-4 shadow-[var(--elevation-soft)] dark:border-white/[0.06] dark:bg-white/[0.035]" aria-labelledby="debugger-heading">
     <div className="flex flex-wrap items-start justify-between gap-3"><div><p className="text-[10px] font-bold uppercase tracking-[0.18em] text-signal-600 dark:text-signal-400">Redacted operations</p><h2 id="debugger-heading" className="text-base font-bold text-slate-900 dark:text-white">Run debugger</h2></div><div className="flex gap-2"><a href="/scheduler" className="inline-flex items-center gap-2 rounded-xl border border-black/[0.08] px-3 py-2 text-sm font-bold text-slate-600 focus:outline-none focus-visible:ring-2 focus-visible:ring-signal-500/40 dark:border-white/[0.08] dark:text-slate-300"><CalendarClock className="h-4 w-4" aria-hidden="true" />Schedule</a><Button size="sm" variant="secondary" icon={RefreshCw} onClick={onRefresh} disabled={busy}>Refresh</Button></div></div>
     <div className="mt-4 grid gap-4 lg:grid-cols-[16rem_minmax(0,1fr)]"><div className="flex max-h-80 flex-col gap-2 overflow-auto">{runs.length ? runs.map((item) => <button key={item.id} type="button" onClick={() => onSelectRun(item.id)} aria-current={run?.id === item.id ? "true" : undefined} className="rounded-xl border border-black/[0.06] p-3 text-left focus:outline-none focus-visible:ring-2 focus-visible:ring-signal-500/40 dark:border-white/[0.06]"><span className="block text-xs font-bold uppercase text-slate-500">{item.status} · v{item.version}</span><span className="mt-1 block truncate font-mono text-[11px] text-slate-400">{item.id}</span></button>) : <p role="status" className="text-sm text-slate-500">No persisted runs.</p>}</div>
-      <div className="min-w-0">{run ? <><div className="flex flex-wrap gap-2"><Button size="sm" variant="secondary" icon={Ban} onClick={onCancel} disabled={busy || terminal.has(run.status)}>Cancel</Button><Button size="sm" variant="secondary" icon={RotateCw} onClick={onRetry} disabled={busy || !["failed", "cancelled", "attention_required"].includes(run.status)}>Safe retry</Button></div><p className="mt-3 text-xs text-slate-500">Timing: {duration(run.startedAt, run.finishedAt)} · trigger {run.triggerType}</p><div className="mt-3 grid gap-2">{nodeRuns.map((nodeRun) => <div key={nodeRun.id} className="rounded-xl border border-black/[0.06] p-3 dark:border-white/[0.06]"><p className="text-sm font-bold text-slate-800 dark:text-slate-100">{nodeRun.nodeId} · {nodeRun.status} · {duration(nodeRun.startedAt, nodeRun.finishedAt)}</p>{nodeRun.executionInvocationId ? <a className="mt-1 inline-flex items-center gap-1 text-xs text-signal-600" href={`/?invocation=${encodeURIComponent(nodeRun.executionInvocationId)}`}>Invocation {nodeRun.executionInvocationId}<ExternalLink className="h-3 w-3" aria-hidden="true" /></a> : null}{attempts.filter((attempt) => attempt.nodeRunId === nodeRun.id).map((attempt) => <p key={attempt.id} className="mt-1 text-xs text-slate-500">Attempt {attempt.attemptNumber}: {attempt.status}{attempt.failureClassification ? ` · ${attempt.failureClassification}` : ""}{attempt.retryDecision ? ` · ${attempt.retryDecision}` : ""}</p>)}</div>)}</div><pre className="mt-3 max-h-72 overflow-auto rounded-xl bg-slate-950 p-3 text-xs text-slate-100">{JSON.stringify(redactNodeFlowSecrets(run.output ?? run.input ?? {}), null, 2)}</pre></> : <p className="text-sm text-slate-500">Select a run to inspect its graph state and attempts.</p>}</div></div>
+      <div className="min-w-0">{run ? <><div className="flex flex-wrap gap-2"><Button size="sm" variant="secondary" icon={Ban} onClick={onCancel} disabled={busy || terminal.has(run.status)}>Cancel</Button><Button size="sm" variant="secondary" icon={RotateCw} onClick={onRetry} disabled={busy || !["failed", "cancelled", "attention_required"].includes(run.status)}>Safe retry</Button></div>{approvals.map((approval) => <div key={approval.id} className="mt-3 rounded-xl border border-amber-400/30 bg-amber-400/[0.08] p-3"><p className="text-sm font-bold text-slate-800 dark:text-slate-100">Approval · {approval.nodeId} · {approval.status}</p><p className="mt-1 text-xs text-slate-500">Logical item: {approval.logicalItem}</p>{approval.status === "pending" && onApprovalDecision ? <div className="mt-3 flex gap-2"><Button size="sm" icon={Check} onClick={() => onApprovalDecision(approval.id, "approve")} disabled={busy}>Approve &amp; continue</Button><Button size="sm" variant="secondary" icon={X} onClick={() => onApprovalDecision(approval.id, "reject")} disabled={busy}>Reject</Button></div> : null}</div>)}<p className="mt-3 text-xs text-slate-500">Timing: {duration(run.startedAt, run.finishedAt)} · trigger {run.triggerType}</p><div className="mt-3 grid gap-2">{nodeRuns.map((nodeRun) => <div key={nodeRun.id} className="rounded-xl border border-black/[0.06] p-3 dark:border-white/[0.06]"><p className="text-sm font-bold text-slate-800 dark:text-slate-100">{nodeRun.nodeId} · {nodeRun.status} · {duration(nodeRun.startedAt, nodeRun.finishedAt)}</p>{nodeRun.executionInvocationId ? <a className="mt-1 inline-flex items-center gap-1 text-xs text-signal-600" href={`/?invocation=${encodeURIComponent(nodeRun.executionInvocationId)}`}>Invocation {nodeRun.executionInvocationId}<ExternalLink className="h-3 w-3" aria-hidden="true" /></a> : null}{attempts.filter((attempt) => attempt.nodeRunId === nodeRun.id).map((attempt) => <p key={attempt.id} className="mt-1 text-xs text-slate-500">Attempt {attempt.attemptNumber}: {attempt.status}{attempt.failureClassification ? ` · ${attempt.failureClassification}` : ""}{attempt.retryDecision ? ` · ${attempt.retryDecision}` : ""}</p>)}</div>)}</div><pre className="mt-3 max-h-72 overflow-auto rounded-xl bg-slate-950 p-3 text-xs text-slate-100">{JSON.stringify(redactNodeFlowSecrets(run.output ?? run.input ?? {}), null, 2)}</pre></> : <p className="text-sm text-slate-500">Select a run to inspect its graph state and attempts.</p>}</div></div>
   </section>;
 };
diff --git a/dashboard/src/v2/lib/node-flow-api.ts b/dashboard/src/v2/lib/node-flow-api.ts
index 633ef161de..96ca454ba8 100644
--- a/dashboard/src/v2/lib/node-flow-api.ts
+++ b/dashboard/src/v2/lib/node-flow-api.ts
@@ -1,4 +1,5 @@
 import type {
+  AutomationApprovalRecord,
   AttachNodeFlowSkillInput,
   CreateNodeFlowInput,
   NodeFlowListResponse,
@@ -131,6 +132,23 @@ export const retryNodeFlowRun = async (projectId: string, runId: string): Promis
 export const fetchNodeFlowAttempts = async (runId: string, signal?: AbortSignal): Promise<{ attempts: NodeFlowNodeAttemptRecord[] }> =>
   fetchJson<{ attempts: NodeFlowNodeAttemptRecord[] }>(`/api/node-flow-runs/${encodeURIComponent(runId)}/attempts`, { signal });
 
+export const fetchNodeFlowApprovals = async (runId: string, signal?: AbortSignal): Promise<{ approvals: AutomationApprovalRecord[] }> =>
+  fetchJson<{ approvals: AutomationApprovalRecord[] }>(`/api/node-flow-runs/${encodeURIComponent(runId)}/approvals`, { signal });
+
+export const decideNodeFlowApproval = async (
+  approvalId: string,
+  decision: "approve" | "reject",
+  decidedBy = "dashboard",
+): Promise<AutomationApprovalRecord & NodeFlowRunSummaryResponse> =>
+  fetchJson<AutomationApprovalRecord & NodeFlowRunSummaryResponse>(`/api/automation-approvals/${encodeURIComponent(approvalId)}/decision`, {
+    method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ decision, decidedBy }),
+  });
+
+export const resumeNodeFlowApproval = async (projectId: string, runId: string, approvalId: string): Promise<NodeFlowRunSummaryResponse> =>
+  fetchJson<NodeFlowRunSummaryResponse>(`/api/node-flow-runs/${encodeURIComponent(runId)}/resume-approval`, {
+    method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ projectId, approvalId }),
+  });
+
 export const fetchNodeFlows = async (
   projectId: string,
   signal?: AbortSignal,
diff --git a/dashboard/src/v2/types.ts b/dashboard/src/v2/types.ts
index 739712b32e..c7e3a5bb00 100644
--- a/dashboard/src/v2/types.ts
+++ b/dashboard/src/v2/types.ts
@@ -126,6 +126,7 @@ import type {
   UpdateSchedulerEntryInput,
 } from "../../../src/contracts/scheduler-types.js";
 import type {
+  AutomationApprovalRecord,
   AttachNodeFlowSkillInput,
   CreateNodeFlowInput,
   NodeFlowEdge,
@@ -478,6 +479,7 @@ export type {
   SpeechTranscriptionProvider,
   SpeechTranscriptionRequestMetadata,
   SpeechTranscriptionResult,
+  AutomationApprovalRecord,
   AttachNodeFlowSkillInput,
   CreateNodeFlowInput,
   NodeFlowEdge,
diff --git a/docs-web/architecture/node-flow-builtins-and-security.md b/docs-web/architecture/node-flow-builtins-and-security.md
index 74a54d6688..3c98e077e8 100644
--- a/docs-web/architecture/node-flow-builtins-and-security.md
+++ b/docs-web/architecture/node-flow-builtins-and-security.md
@@ -7,7 +7,7 @@ The governed catalog adds deterministic branches, bounded collection processing,
 - `condition` selects `true` or `false`; `switch` selects one named case or `default`. Unselected branches persist as skipped node runs.
 - `foreach` accepts no more than 1,000 items. `merge` supports `object`, `array`, and `first` strategies.
 - `delay` is cancellable and capped at one hour. `execute_subflow` requires same-project ownership, rejects direct self-reference, and caps depth at eight.
-- `approval` persists an operator decision. `email_draft` never sends. `email_send` requires approval and uses the idempotent outbox.
+- `approval` persists an idempotent operator decision and continues the exact pinned run after approval. `email_draft` never sends. `email_send` requires approval and uses the idempotent outbox.
 - `webhook_trigger` emits payloads accepted through secret-authenticated webhook ingress.
 
 ## Network policy
@@ -18,6 +18,8 @@ Every redirect is manually revalidated. DNS is checked for private results and r
 
 ## OAuth, approvals, and outbox
 
+Pending approvals preserve the run, governed node, logical item, and numbered attempt. Approved decisions resume at that node boundary; rejected and expired decisions terminate durably. Repeated decisions and restart recovery do not create a second approval request, attempt, or external delivery.
+
 OAuth authorization uses PKCE S256 and short-lived AES-256-GCM state tied to an allowlisted callback origin. Tokens live behind the connection store, rotate on refresh, enforce scopes and expiry, and are never written into graph JSON or agent-visible output. Revocation, reconnect, and health checks expose no token values.
 
 Approvals are unique per run, node, and logical item. Outbox entries use a unique key derived from publication, run, node, and logical item, and store the provider message id after success. A restart while an entry is sending changes it to `attention_required`; Code UX does not automatically replay an unknown provider outcome.
diff --git a/docs-web/architecture/node-flow-durable-execution.md b/docs-web/architecture/node-flow-durable-execution.md
index 4d5eb01e34..2fb818f283 100644
--- a/docs-web/architecture/node-flow-durable-execution.md
+++ b/docs-web/architecture/node-flow-durable-execution.md
@@ -6,4 +6,6 @@ Distributed runners are authenticated service principals with `automation_runner
 
 Runs are durably queued and leased with bounded global and project concurrency. Node attempts retain attempt number, executor and invocation identity, artifact digest, redacted payloads, credential ids, failure class, and retry decision. Retryable failures use bounded exponential backoff and jitter, while cancellation and timeout signals propagate to provider and HTTP work.
 
-On restart, expired pre-invocation work is safely requeued. Work with an external invocation and an unknown outcome moves to `attention_required` and is never silently replayed. Credential values are resolved only for the active node and are not retained in run history or diagnostics.
+On restart, expired pre-invocation work is safely requeued. Work with an external invocation and an unknown outcome moves to `attention_required` and is never silently replayed. Pending approvals stay paused; persisted approvals continue the same run and pinned publication, while rejected or expired decisions fail the governed node and run durably. Credential values are resolved only for the active node and are not retained in run history or diagnostics.
+
+Approval continuation compare-and-set claims the waiting run, reconstructs prior outputs and branch choices, and reuses the waiting node attempt. Repeated decisions or explicit resume requests therefore return the current durable run state without creating another attempt or outbox delivery.
diff --git a/docs-web/content/docs/architecture-node-flow-builtins-and-security.mdx b/docs-web/content/docs/architecture-node-flow-builtins-and-security.mdx
index 74a54d6688..3c98e077e8 100644
--- a/docs-web/content/docs/architecture-node-flow-builtins-and-security.mdx
+++ b/docs-web/content/docs/architecture-node-flow-builtins-and-security.mdx
@@ -7,7 +7,7 @@ The governed catalog adds deterministic branches, bounded collection processing,
 - `condition` selects `true` or `false`; `switch` selects one named case or `default`. Unselected branches persist as skipped node runs.
 - `foreach` accepts no more than 1,000 items. `merge` supports `object`, `array`, and `first` strategies.
 - `delay` is cancellable and capped at one hour. `execute_subflow` requires same-project ownership, rejects direct self-reference, and caps depth at eight.
-- `approval` persists an operator decision. `email_draft` never sends. `email_send` requires approval and uses the idempotent outbox.
+- `approval` persists an idempotent operator decision and continues the exact pinned run after approval. `email_draft` never sends. `email_send` requires approval and uses the idempotent outbox.
 - `webhook_trigger` emits payloads accepted through secret-authenticated webhook ingress.
 
 ## Network policy
@@ -18,6 +18,8 @@ Every redirect is manually revalidated. DNS is checked for private results and r
 
 ## OAuth, approvals, and outbox
 
+Pending approvals preserve the run, governed node, logical item, and numbered attempt. Approved decisions resume at that node boundary; rejected and expired decisions terminate durably. Repeated decisions and restart recovery do not create a second approval request, attempt, or external delivery.
+
 OAuth authorization uses PKCE S256 and short-lived AES-256-GCM state tied to an allowlisted callback origin. Tokens live behind the connection store, rotate on refresh, enforce scopes and expiry, and are never written into graph JSON or agent-visible output. Revocation, reconnect, and health checks expose no token values.
 
 Approvals are unique per run, node, and logical item. Outbox entries use a unique key derived from publication, run, node, and logical item, and store the provider message id after success. A restart while an entry is sending changes it to `attention_required`; Code UX does not automatically replay an unknown provider outcome.
diff --git a/docs-web/content/docs/architecture-node-flow-durable-execution.mdx b/docs-web/content/docs/architecture-node-flow-durable-execution.mdx
index 4d5eb01e34..2fb818f283 100644
--- a/docs-web/content/docs/architecture-node-flow-durable-execution.mdx
+++ b/docs-web/content/docs/architecture-node-flow-durable-execution.mdx
@@ -6,4 +6,6 @@ Distributed runners are authenticated service principals with `automation_runner
 
 Runs are durably queued and leased with bounded global and project concurrency. Node attempts retain attempt number, executor and invocation identity, artifact digest, redacted payloads, credential ids, failure class, and retry decision. Retryable failures use bounded exponential backoff and jitter, while cancellation and timeout signals propagate to provider and HTTP work.
 
-On restart, expired pre-invocation work is safely requeued. Work with an external invocation and an unknown outcome moves to `attention_required` and is never silently replayed. Credential values are resolved only for the active node and are not retained in run history or diagnostics.
+On restart, expired pre-invocation work is safely requeued. Work with an external invocation and an unknown outcome moves to `attention_required` and is never silently replayed. Pending approvals stay paused; persisted approvals continue the same run and pinned publication, while rejected or expired decisions fail the governed node and run durably. Credential values are resolved only for the active node and are not retained in run history or diagnostics.
+
+Approval continuation compare-and-set claims the waiting run, reconstructs prior outputs and branch choices, and reuses the waiting node attempt. Repeated decisions or explicit resume requests therefore return the current durable run state without creating another attempt or outbox delivery.
diff --git a/docs-web/content/docs/user-dashboard-node-flows.mdx b/docs-web/content/docs/user-dashboard-node-flows.mdx
index 949de5d5ed..0b39ac2177 100644
--- a/docs-web/content/docs/user-dashboard-node-flows.mdx
+++ b/docs-web/content/docs/user-dashboard-node-flows.mdx
@@ -32,6 +32,8 @@ The manual run panel accepts JSON object input and starts a node-flow run. Runs
 
 Rendered run payloads redact secret-shaped keys such as `apiKey`, `authorization`, `cookie`, `password`, `secret`, and `token`.
 
+The run debugger lists durable approvals beside node attempts. A pending item offers **Approve & continue** and **Reject** actions. The decision applies to the same pinned run, and repeated clicks return its current state without sending an approved external effect twice.
+
 ## Agent Attachment
 
 A flow can be attached to a project agent preset as a repeatable skill with a name and description. Detaching removes only that binding; the flow, its graph, schedules, and run history remain in the project.
diff --git a/docs-web/user/dashboard/node-flows.md b/docs-web/user/dashboard/node-flows.md
index d532ef1050..0acfe45d15 100644
--- a/docs-web/user/dashboard/node-flows.md
+++ b/docs-web/user/dashboard/node-flows.md
@@ -32,6 +32,8 @@ The manual run panel accepts JSON object input and starts a node-flow run. Runs
 
 Rendered run payloads redact secret-shaped keys such as `apiKey`, `authorization`, `cookie`, `password`, `secret`, and `token`.
 
+The run debugger lists durable approvals beside node attempts. A pending item offers **Approve & continue** and **Reject** actions. The decision applies to the same pinned run, and repeated clicks return its current state without sending an approved external effect twice.
+
 ## Agent Attachment
 
 A flow can be attached to a project agent preset as a repeatable skill with a name and description. Detaching removes only that binding; the flow, its graph, schedules, and run history remain in the project.
diff --git a/docs/architecture/node-flow-builtins-and-security.md b/docs/architecture/node-flow-builtins-and-security.md
index 1156cb9ca5..d59181c764 100644
--- a/docs/architecture/node-flow-builtins-and-security.md
+++ b/docs/architecture/node-flow-builtins-and-security.md
@@ -33,7 +33,7 @@ Refresh happens shortly before expiry and rotates the stored refresh token when
 
 ## Approvals and outbox
 
-`automation_approvals` persists pending and terminal decisions. Repeating the same run, node, and logical item returns the existing decision, so restarts do not create a second prompt. Email sending is approval-gated by default; `email_draft` is the non-irreversible default.
+`automation_approvals` persists pending and terminal decisions. Repeating the same run, node, and logical item returns the existing decision, so restarts do not create a second prompt. Repeating an identical decision is also idempotent. Approval or rejection through the decision endpoint resumes or terminates the exact waiting run; approval preserves its publication, run id, logical item, and attempt number. Email sending is approval-gated by default; `email_draft` is the non-irreversible default.
 
 `automation_outbox` has a unique SHA-256 idempotency key derived from publication id, run id, node id, and logical item. Provider message ids are stored after success. A process restart while an entry is `sending` changes it to `attention_required`, because the provider may have accepted the operation; Code UX does not replay an unknown external outcome automatically.
 
diff --git a/docs/architecture/node-flow-durable-execution.md b/docs/architecture/node-flow-durable-execution.md
index 6bdd4ba290..c07bfdb48b 100644
--- a/docs/architecture/node-flow-durable-execution.md
+++ b/docs/architecture/node-flow-durable-execution.md
@@ -10,7 +10,7 @@ Every node execution creates a numbered attempt with executor identity, optional
 
 ## Recovery contract
 
-Startup recovery scans queued and waiting work plus running work with expired leases. A pre-invocation attempt can be requeued safely without inserting a duplicate attempt. An expired attempt with an invocation id has an unknown externally observable outcome and moves to `attention_required`; Code UX does not silently replay it. Approval- and retry-waiting runs retain their durable state until their prerequisite becomes actionable.
+Startup recovery scans queued and waiting work plus running work with expired leases. A pre-invocation attempt can be requeued safely without inserting a duplicate attempt. An expired attempt with an invocation id has an unknown externally observable outcome and moves to `attention_required`; Code UX does not silently replay it. Pending approvals remain `approval_waiting`. A persisted approved decision is resumed during startup on the same run and pinned publication, while rejected or expired decisions durably fail the waiting run and governed node.
 
 The relevant tables are `node_flow_publications`, `node_flow_runs`, `node_flow_node_runs`, and `node_flow_node_attempts`. Attempt history is available at `GET /api/node-flow-runs/:runId/attempts` and contains only redacted payloads and credential identifiers.
 
@@ -19,3 +19,5 @@ The relevant tables are `node_flow_publications`, `node_flow_runs`, `node_flow_n
 Authenticated runners claim through a service principal with `automation_runner` and explicit project membership. The database update from queued/retry-waiting to running is the ownership compare-and-set; heartbeats renew only when both run id and lease owner match. A second runner therefore cannot acquire an active lease.
 
 External email-style effects use `automation_outbox`. The idempotency key is derived from publication, run, node, and logical item, so reconstructing services after restart returns an existing sent row rather than invoking the provider twice. Known failures may be retried; unknown outcomes become `attention_required`. Approval decisions and deliveries are durable and produce redacted correlation audit records alongside run and attempt events.
+
+Approval continuation uses a compare-and-set claim from `approval_waiting` to `running`. It reconstructs completed node outputs and branch selections, reuses the waiting node run and numbered attempt, and continues at the governed node boundary. Repeating the same decision or explicit `POST /api/node-flow-runs/:runId/resume-approval` request returns the existing run state when another owner already claimed or completed it; it does not create a second attempt or outbox delivery.
diff --git a/docs/dashboard/node-flows.md b/docs/dashboard/node-flows.md
index 69701d85ac..a80ed9c383 100644
--- a/docs/dashboard/node-flows.md
+++ b/docs/dashboard/node-flows.md
@@ -20,6 +20,6 @@ T06 draft endpoints provide structural validation, policy findings, requested pe
 
 ## Run debugger and scheduling
 
-The debugger reads persisted runs, node runs, and attempt history. It overlays node state, shows retry reasons and decisions, links invocation ids, reports timing, supports cancellation and safe retry, and redacts secret-shaped values before rendering. Scheduling is entered through `/scheduler`; scheduler execution also resolves published versions.
+The debugger reads persisted runs, node runs, attempt history, and approval decisions. Pending approvals expose keyboard-accessible **Approve & continue** and **Reject** actions. A decision continues or terminates the same pinned run, and repeated clicks return its current durable state without duplicating the governed attempt or external send. The debugger also overlays node state, shows retry reasons and decisions, links invocation ids, reports timing, supports cancellation and safe retry, and redacts secret-shaped values before rendering. Scheduling is entered through `/scheduler`; scheduler execution also resolves published versions.
 
 The layout stacks on small screens, preserves keyboard-visible focus, labels loading/error/empty states, and bounds long histories and JSON output with scrolling.
diff --git a/src/app/dependency-factory/dashboard-factory.ts b/src/app/dependency-factory/dashboard-factory.ts
index 0a6c971945..7d0d88244f 100644
--- a/src/app/dependency-factory/dashboard-factory.ts
+++ b/src/app/dependency-factory/dashboard-factory.ts
@@ -274,7 +274,11 @@ export function createDashboardDependencies(
     getDashboardSettings: (projectId) => resolveDashboardSettings({ projectId }),
   });
   if (coreDeps.nodeFlowRepository) {
-    new NodeFlowRecoveryService(coreDeps.nodeFlowRepository).recover();
+    const recoveryService = new NodeFlowRecoveryService(coreDeps.nodeFlowRepository, approvalService, nodeFlowRuntimeService);
+    recoveryService.recover();
+    void recoveryService.resumeDecidedApprovals().catch((error: unknown) => {
+      logger.error("Failed to resume a decided node-flow approval during startup recovery", { error: error instanceof Error ? error.message : String(error) });
+    });
   }
   const nodeFlowService = new NodeFlowService(coreDeps.nodeFlowRepository, nodeFlowRuntimeService, coreDeps.credentialBroker, {
     repository: customNodeRepository,
diff --git a/src/contracts/node-flow-types.ts b/src/contracts/node-flow-types.ts
index bce9c7ce8c..4cf590bddd 100644
--- a/src/contracts/node-flow-types.ts
+++ b/src/contracts/node-flow-types.ts
@@ -15,6 +15,26 @@ export type NodeFlowJsonValue =
   | { [key: string]: NodeFlowJsonValue };
 export type NodeFlowJsonObject = { [key: string]: NodeFlowJsonValue };
 
+export type AutomationApprovalStatus = "pending" | "approved" | "rejected" | "expired";
+
+export interface AutomationApprovalRecord {
+  id: string;
+  projectId: string;
+  flowId: string;
+  runId: string;
+  nodeId: string;
+  logicalItem: string;
+  status: AutomationApprovalStatus;
+  request: NodeFlowJsonObject;
+  decision: NodeFlowJsonObject | null;
+  requestedAt: string;
+  decidedAt: string | null;
+  decidedBy: string | null;
+  expiresAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
 export const NODE_FLOW_SCHEMA_VERSION = 2 as const;
 export type NodeFlowSchemaVersion = typeof NODE_FLOW_SCHEMA_VERSION;
 
diff --git a/src/repositories/automation-approval-repository.ts b/src/repositories/automation-approval-repository.ts
index b623b3494d..e877e3362a 100644
--- a/src/repositories/automation-approval-repository.ts
+++ b/src/repositories/automation-approval-repository.ts
@@ -2,26 +2,12 @@ import { randomUUID } from "node:crypto";
 import { AppDbStorage } from "./app-db-storage.js";
 import type { DatabaseAdapter } from "./db/database-adapter.js";
 import { EntityNotFoundError, ValidationError } from "./repository-utils.js";
-import type { NodeFlowJsonObject } from "../contracts/node-flow-types.js";
+import type { AutomationApprovalRecord, AutomationApprovalStatus, NodeFlowJsonObject } from "../contracts/node-flow-types.js";
+export type { AutomationApprovalRecord, AutomationApprovalStatus } from "../contracts/node-flow-types.js";
 
-export type AutomationApprovalStatus = "pending" | "approved" | "rejected" | "expired";
-
-export interface AutomationApprovalRecord {
-  id: string;
-  projectId: string;
-  flowId: string;
-  runId: string;
-  nodeId: string;
-  logicalItem: string;
-  status: AutomationApprovalStatus;
-  request: NodeFlowJsonObject;
-  decision: NodeFlowJsonObject | null;
-  requestedAt: string;
-  decidedAt: string | null;
-  decidedBy: string | null;
-  expiresAt: string | null;
-  createdAt: string;
-  updatedAt: string;
+export interface AutomationApprovalMutationResult {
+  approval: AutomationApprovalRecord;
+  changed: boolean;
 }
 
 interface ApprovalRow {
@@ -42,18 +28,27 @@ export class AutomationApprovalRepository {
     projectId: string; flowId: string; runId: string; nodeId: string;
     logicalItem: string; request: NodeFlowJsonObject; expiresAt?: string | null;
   }): AutomationApprovalRecord {
+    return this.requestIdempotently(input).approval;
+  }
+
+  requestIdempotently(input: {
+    projectId: string; flowId: string; runId: string; nodeId: string;
+    logicalItem: string; request: NodeFlowJsonObject; expiresAt?: string | null;
+  }): AutomationApprovalMutationResult {
     const logicalItem = input.logicalItem.trim() || "default";
     const existing = this.getForItem(input.runId, input.nodeId, logicalItem);
-    if (existing) return existing;
+    if (existing) return { approval: existing, changed: false };
     const id = randomUUID();
     const now = new Date().toISOString();
-    this.db.prepare(`INSERT INTO automation_approvals
+    const result = this.db.prepare(`INSERT OR IGNORE INTO automation_approvals
       (id, project_id, flow_id, run_id, node_id, logical_item, status, request_json,
        requested_at, expires_at, created_at, updated_at)
       VALUES (?, ?, ?, ?, ?, ?, 'pending', ?, ?, ?, ?, ?)`)
       .run(id, input.projectId, input.flowId, input.runId, input.nodeId, logicalItem,
         JSON.stringify(input.request), now, input.expiresAt ?? null, now, now);
-    return this.require(id);
+    const approval = result.changes > 0 ? this.require(id) : this.getForItem(input.runId, input.nodeId, logicalItem);
+    if (!approval) throw new EntityNotFoundError("Automation approval request could not be persisted.");
+    return { approval, changed: result.changes > 0 };
   }
 
   get(id: string): AutomationApprovalRecord | null {
@@ -73,18 +68,26 @@ export class AutomationApprovalRepository {
   }
 
   decide(id: string, input: { status: "approved" | "rejected"; decidedBy: string; decision?: NodeFlowJsonObject }): AutomationApprovalRecord {
+    return this.decideIdempotently(id, input).approval;
+  }
+
+  decideIdempotently(id: string, input: { status: "approved" | "rejected"; decidedBy: string; decision?: NodeFlowJsonObject }): AutomationApprovalMutationResult {
     const current = this.require(id);
     if (current.status !== "pending") {
-      if (current.status === input.status) return current;
+      if (current.status === input.status) return { approval: current, changed: false };
       throw new ValidationError(`Approval ${id} has already been decided.`);
     }
     const decidedBy = input.decidedBy.trim();
     if (!decidedBy) throw new ValidationError("decidedBy is required.");
     const now = new Date().toISOString();
-    this.db.prepare(`UPDATE automation_approvals SET status = ?, decision_json = ?, decided_at = ?,
+    const result = this.db.prepare(`UPDATE automation_approvals SET status = ?, decision_json = ?, decided_at = ?,
       decided_by = ?, updated_at = ? WHERE id = ? AND status = 'pending'`)
       .run(input.status, JSON.stringify(input.decision ?? {}), now, decidedBy, now, id);
-    return this.require(id);
+    const approval = this.require(id);
+    if (result.changes === 0 && approval.status !== input.status) {
+      throw new ValidationError(`Approval ${id} has already been decided.`);
+    }
+    return { approval, changed: result.changes > 0 };
   }
 
   expireDue(now = new Date()): number {
diff --git a/src/repositories/node-flow-repository.ts b/src/repositories/node-flow-repository.ts
index d40fea4196..10d3cf3fbe 100644
--- a/src/repositories/node-flow-repository.ts
+++ b/src/repositories/node-flow-repository.ts
@@ -429,6 +429,13 @@ export class NodeFlowRepository {
     return result.changes > 0 ? this.getRun(runId) : null;
   }
 
+  claimApprovalWaitingRun(runId: string, executorId: string, leaseDurationMs: number, now = new Date()): NodeFlowRunRecord | null {
+    const expiresAt = new Date(now.getTime() + leaseDurationMs).toISOString();
+    const result = this.db.prepare(`UPDATE node_flow_runs SET status = 'running', lease_owner = ?, lease_expires_at = ?, heartbeat_at = ?, updated_at = ? WHERE id = ? AND status = 'approval_waiting' AND cancel_requested_at IS NULL`)
+      .run(executorId, expiresAt, now.toISOString(), now.toISOString(), runId);
+    return result.changes > 0 ? this.getRun(runId) : null;
+  }
+
   heartbeatRun(runId: string, executorId: string, leaseDurationMs: number, now = new Date()): boolean {
     const result = this.db.prepare(`UPDATE node_flow_runs SET heartbeat_at = ?, lease_expires_at = ?, updated_at = ? WHERE id = ? AND status = 'running' AND lease_owner = ?`)
       .run(now.toISOString(), new Date(now.getTime() + leaseDurationMs).toISOString(), now.toISOString(), runId, executorId);
diff --git a/src/server/node-flow-routes.ts b/src/server/node-flow-routes.ts
index f20c244148..b5ad71cda4 100644
--- a/src/server/node-flow-routes.ts
+++ b/src/server/node-flow-routes.ts
@@ -115,6 +115,14 @@ export function registerNodeFlowRoutes(app: Express, deps: DashboardDependencies
   app.post("/api/node-flow-runs/:runId/retry", asyncRoute(async (req, res) => {
     res.status(201).json(await requireNodeFlowService(deps).retryRun(requireTrimmedString(req.body?.projectId, "projectId"), requireTrimmedString(req.params.runId, "runId")));
   }));
+
+  app.post("/api/node-flow-runs/:runId/resume-approval", asyncRoute(async (req, res) => {
+    res.json(await requireNodeFlowService(deps).resumeApproval(
+      requireTrimmedString(req.body?.projectId, "projectId"),
+      requireTrimmedString(req.params.runId, "runId"),
+      requireTrimmedString(req.body?.approvalId, "approvalId"),
+    ));
+  }));
   app.get("/api/projects/:projectId/node-flows", syncRoute((req, res) => {
     res.json(requireNodeFlowService(deps).list(requireTrimmedString(req.params.projectId, "projectId")));
   }));
@@ -230,13 +238,26 @@ export function registerNodeFlowRoutes(app: Express, deps: DashboardDependencies
     res.json({ approvals: deps.approvalService.listForRun(requireTrimmedString(req.params.runId, "runId")) });
   }));
 
-  app.post("/api/automation-approvals/:approvalId/decision", syncRoute((req, res) => {
+  app.post("/api/automation-approvals/:approvalId/decision", asyncRoute(async (req, res) => {
     if (!deps.approvalService) throw new HttpRouteError(404, "Approval service is not enabled.");
     const body = req.body as { decision?: string; decidedBy?: string; metadata?: NodeFlowJsonObject };
     const approvalId = requireTrimmedString(req.params.approvalId, "approvalId");
     const decidedBy = requireTrimmedString(body.decidedBy, "decidedBy");
-    if (body.decision === "approve") res.json(deps.approvalService.approve(approvalId, decidedBy, body.metadata));
-    else if (body.decision === "reject") res.json(deps.approvalService.reject(approvalId, decidedBy, body.metadata));
+    const current = deps.approvalService.get(approvalId);
+    if (current?.status === "expired") {
+      const resumed = await requireNodeFlowService(deps).resumeApproval(current.projectId, current.runId, current.id);
+      res.json({ ...current, run: resumed.run, nodeRuns: resumed.nodeRuns, attempts: resumed.attempts, output: resumed.output });
+      return;
+    }
+    const approval = body.decision === "approve"
+      ? deps.approvalService.approve(approvalId, decidedBy, body.metadata)
+      : body.decision === "reject"
+        ? deps.approvalService.reject(approvalId, decidedBy, body.metadata)
+        : null;
+    if (approval) {
+      const resumed = await requireNodeFlowService(deps).resumeApproval(approval.projectId, approval.runId, approval.id);
+      res.json({ ...approval, run: resumed.run, nodeRuns: resumed.nodeRuns, attempts: resumed.attempts, output: resumed.output });
+    }
     else throw new HttpRouteError(400, "decision must be approve or reject.");
   }));
 
diff --git a/src/services/node-flow-runtime-service.ts b/src/services/node-flow-runtime-service.ts
index c36615e7e6..bd3841578c 100644
--- a/src/services/node-flow-runtime-service.ts
+++ b/src/services/node-flow-runtime-service.ts
@@ -19,7 +19,7 @@ import { EgressPolicyService } from "./node-flows/egress-policy-service.js";
 import { BuiltinExecutors } from "./node-flows/builtins/builtin-executors.js";
 import type { ApprovalService } from "./node-flows/approval-service.js";
 import { ApprovalRequiredError } from "./node-flows/approval-service.js";
-import type { OutboxService } from "./node-flows/outbox-service.js";
+import { UnknownSideEffectOutcomeError, type OutboxService } from "./node-flows/outbox-service.js";
 import type { CustomNodeRuntimeService } from "./custom-nodes/custom-node-runtime-service.js";
 import type { AutomationAuditExportService } from "./automation-audit-export-service.js";
 import type { NodeFlowFailureClassification } from "../contracts/node-flow-execution-policy-types.js";
@@ -35,6 +35,7 @@ import type {
   NodeFlowJsonValue,
   NodeFlowNode,
   NodeFlowNodeRunRecord,
+  NodeFlowPublicationRecord,
   NodeFlowRunRecord,
   NodeFlowRunSummaryResponse,
   RunNodeFlowOptions,
@@ -105,7 +106,8 @@ export class NodeFlowRuntimeService {
   }
 
   requestCancellation(runId: string): NodeFlowRunRecord {
-    return this.deps.nodeFlowRepository.requestCancellation(runId);
+    const requested = this.deps.nodeFlowRepository.requestCancellation(runId);
+    return requested.status === "approval_waiting" ? this.terminateCancelledRun(requested).run : requested;
   }
 
   async runFlow(
@@ -159,8 +161,57 @@ export class NodeFlowRuntimeService {
       startedAt: null,
     });
     this.deps.auditService?.recordSystem({ action: "automation.run.started", resourceType: "node_flow_run", resourceId: run.id, projectId, outcome: "succeeded", metadata: { flowId: flow.id, publicationId: publication.id, version: publication.version, triggerType: options.triggerType ?? "manual" } });
+    return await this.executeRun(run, publication, graph, executionOrder, input, options, "queued");
+  }
+
+  async resumeApproval(projectId: string, approvalId: string, expectedRunId?: string, options: Pick<RunNodeFlowOptions, "signal" | "executorId"> = {}): Promise<NodeFlowRunSummaryResponse> {
+    if (!this.deps.approvalService) throw new ValidationError("Approval service is not configured.");
+    const approval = this.deps.approvalService.get(approvalId);
+    if (!approval) throw new EntityNotFoundError(`Automation approval not found: ${approvalId}`);
+    const run = this.deps.nodeFlowRepository.getRun(approval.runId);
+    if (!run) throw new EntityNotFoundError(`Node flow run not found: ${approval.runId}`);
+    if (expectedRunId && run.id !== expectedRunId) throw new ValidationError("Approval does not belong to the requested node flow run.");
+    if (run.projectId !== projectId) throw new ValidationError("Node flow run does not belong to the requested project.");
+    if (run.flowId !== approval.flowId || run.projectId !== approval.projectId) {
+      throw new ValidationError("Approval scope does not match its node flow run.");
+    }
+    if (run.status !== "approval_waiting") return this.summarizeRun(run.id);
+    const waitingNode = this.deps.nodeFlowRepository.listNodeRuns(run.id).find((candidate) => candidate.status === "approval_waiting");
+    if (!waitingNode || waitingNode.nodeId !== approval.nodeId) {
+      throw new ValidationError("Approval does not match the governed node currently waiting in this run.");
+    }
+    if (approval.status === "pending") throw new ValidationError(`Approval ${approval.id} is still pending.`);
+    if (approval.status === "rejected" || approval.status === "expired") {
+      return this.terminateApprovalRun(run, approval.nodeId, approval.status);
+    }
+    if (run.cancelRequestedAt) return this.terminateCancelledRun(run);
+    const publication = new NodeFlowPublicationService(this.deps.nodeFlowRepository).resolve(run.flowId, { mode: "pinned", version: run.version });
+    if (run.publicationId && publication.id !== run.publicationId) {
+      throw new ValidationError("The waiting run no longer matches its pinned publication.");
+    }
+    const { graph, executionOrder } = normalizeNodeFlowGraph(publication.graph);
+    this.requireSupportedNodes(graph);
+    return await this.executeRun(run, publication, graph, executionOrder, run.input ?? {}, options, "approval_waiting");
+  }
+
+  private async executeRun(
+    run: NodeFlowRunRecord,
+    publication: NodeFlowPublicationRecord,
+    graph: NodeFlowGraph,
+    executionOrder: string[],
+    input: NodeFlowJsonObject,
+    options: RunNodeFlowOptions,
+    claimFrom: "queued" | "approval_waiting",
+  ): Promise<NodeFlowRunSummaryResponse> {
+    const projectId = run.projectId;
+    const flowId = run.flowId;
+    const parentInvocationId = run.executionInvocationId;
+    if (!parentInvocationId) throw new ValidationError(`Node flow run ${run.id} has no parent execution invocation.`);
     const executorId = options.executorId?.trim() || `node-flow-runtime:${process.pid}:${randomUUID()}`;
-    const claimedRun = new NodeFlowQueueService(this.deps.nodeFlowRepository).claim(run, executorId);
+    const claimedRun = claimFrom === "queued"
+      ? new NodeFlowQueueService(this.deps.nodeFlowRepository).claim(run, executorId)
+      : this.deps.nodeFlowRepository.claimApprovalWaitingRun(run.id, executorId, publication.policy.leaseDurationMs);
+    if (!claimedRun) return this.summarizeRun(run.id);
     const leaseService = new NodeFlowLeaseService(this.deps.nodeFlowRepository);
     const heartbeatTimer = setInterval(() => {
       leaseService.heartbeat(claimedRun.id, executorId, publication.policy.leaseDurationMs);
@@ -169,7 +220,7 @@ export class NodeFlowRuntimeService {
 
     const context: RuntimeContext = {
       projectId,
-      flowId: flow.id,
+      flowId,
       runId: claimedRun.id,
       graph,
       order: executionOrder,
@@ -184,6 +235,17 @@ export class NodeFlowRuntimeService {
       subflowDepth: options.subflowDepth ?? 0,
     };
 
+    const persistedNodeRuns = this.deps.nodeFlowRepository.listNodeRuns(run.id);
+    const persistedByNode = new Map<string, NodeFlowNodeRunRecord>();
+    for (const persisted of persistedNodeRuns) persistedByNode.set(persisted.nodeId, persisted);
+    for (const node of graph.nodes) {
+      const persisted = persistedByNode.get(node.id);
+      if (!persisted?.output || !["succeeded", "failed"].includes(persisted.status)) continue;
+      context.outputs.set(node.id, persisted.output);
+      const selectedPorts = inferSelectedPorts(node, persisted.output);
+      if (selectedPorts) context.selectedPorts.set(node.id, selectedPorts);
+    }
+
     const blockedNodes = new Set<string>();
     let terminalStatus: NodeFlowRunRecord["status"] = "succeeded";
     let terminalError: string | null = null;
@@ -194,6 +256,10 @@ export class NodeFlowRuntimeService {
       if (!node) {
         continue;
       }
+      const persistedNodeRun = persistedByNode.get(node.id);
+      if (persistedNodeRun && ["succeeded", "failed", "skipped", "cancelled"].includes(persistedNodeRun.status)) {
+        continue;
+      }
       if (options.signal?.aborted || this.deps.nodeFlowRepository.getRun(run.id)?.cancelRequestedAt) {
         terminalStatus = "cancelled";
         terminalError ??= "Node flow run was cancelled.";
@@ -220,25 +286,32 @@ export class NodeFlowRuntimeService {
       }
 
       const nodeInput = maskSecrets(this.buildNodeInput(context, node.id));
-      const nodeRun = this.deps.nodeFlowRepository.createNodeRun({
-        runId: run.id,
-        flowId: flow.id,
-        projectId,
-        nodeId: node.id,
-        status: "running",
-        input: nodeInput,
-        startedAt: new Date().toISOString(),
-      });
+      const nodeRun = persistedNodeRun?.status === "approval_waiting"
+        ? this.deps.nodeFlowRepository.updateNodeRun(persistedNodeRun.id, { status: "running", errorMessage: null })
+        : this.deps.nodeFlowRepository.createNodeRun({
+          runId: run.id,
+          flowId,
+          projectId,
+          nodeId: node.id,
+          status: "running",
+          input: nodeInput,
+          startedAt: new Date().toISOString(),
+        });
 
       const attemptService = new NodeFlowAttemptService(this.deps.nodeFlowRepository);
       const retryPolicy = {
         ...publication.policy.retry,
         ...(node.policy?.retry ?? {}),
       };
-      let attemptNumber = 0;
-      while (attemptNumber < retryPolicy.maxAttempts) {
-        attemptNumber += 1;
-        const attempt = attemptService.start(nodeRun, executorId, nodeInput, (node.credentialBindings ?? []).map((binding) => binding.credentialId));
+      let executionAttempt = 0;
+      let waitingAttempt = this.deps.nodeFlowRepository.listNodeAttempts(run.id)
+        .find((candidate) => candidate.nodeRunId === nodeRun.id && candidate.status === "approval_waiting");
+      while (executionAttempt < retryPolicy.maxAttempts) {
+        executionAttempt += 1;
+        const attempt = waitingAttempt
+          ? this.deps.nodeFlowRepository.updateNodeAttempt(waitingAttempt.id, { status: "running", errorMessage: null, finishedAt: null })
+          : attemptService.start(nodeRun, executorId, nodeInput, (node.credentialBindings ?? []).map((binding) => binding.credentialId));
+        waitingAttempt = undefined;
         context.currentAttemptId = attempt.id;
         const timeoutMs = node.policy?.timeout?.timeoutMs ?? publication.policy.defaultTimeoutMs;
         const timeoutController = new AbortController();
@@ -252,7 +325,7 @@ export class NodeFlowRuntimeService {
         context.outputs.set(node.id, result.output);
         if (result.selectedPorts) context.selectedPorts.set(node.id, new Set(result.selectedPorts));
         attemptService.succeed(attempt, maskSecrets(result.output), result.invocationId);
-        this.deps.auditService?.recordSystem({ action: "automation.attempt.succeeded", resourceType: "node_flow_attempt", resourceId: attempt.id, projectId, outcome: "succeeded", metadata: { runId: run.id, flowId: flow.id, nodeId: node.id, attemptNumber } });
+        this.deps.auditService?.recordSystem({ action: "automation.attempt.succeeded", resourceType: "node_flow_attempt", resourceId: attempt.id, projectId, outcome: "succeeded", metadata: { runId: run.id, flowId, nodeId: node.id, attemptNumber: attempt.attemptNumber } });
         this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, {
           status: "succeeded",
           executionInvocationId: result.invocationId ?? nodeRun.executionInvocationId,
@@ -265,9 +338,8 @@ export class NodeFlowRuntimeService {
         clearTimeout(timeout); options.signal?.removeEventListener("abort", parentAbort); context.options = previousOptions;
         const message = error instanceof Error ? error.message : String(error);
         const classification = classifyFailure(error, options.signal?.aborted === true, timeoutController.signal.aborted);
-        this.deps.auditService?.recordSystem({ action: "automation.attempt.failed", resourceType: "node_flow_attempt", resourceId: attempt.id, projectId, outcome: "failed", metadata: { runId: run.id, flowId: flow.id, nodeId: node.id, attemptNumber, classification } });
         if (error instanceof ApprovalRequiredError) {
-          attemptService.fail(attempt, "permanent", message, false);
+          this.deps.nodeFlowRepository.updateNodeAttempt(attempt.id, { status: "approval_waiting", errorMessage: message, retryDecision: null, finishedAt: null });
           this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, {
             status: "approval_waiting", errorMessage: message, finishedAt: null,
           });
@@ -275,12 +347,13 @@ export class NodeFlowRuntimeService {
           terminalError = message;
           break;
         }
+        this.deps.auditService?.recordSystem({ action: "automation.attempt.failed", resourceType: "node_flow_attempt", resourceId: attempt.id, projectId, outcome: "failed", metadata: { runId: run.id, flowId, nodeId: node.id, attemptNumber: attempt.attemptNumber, classification } });
         const wasCancelled = classification === "cancelled";
-        const retryable = retryPolicy.retryableClasses.includes(classification) && attemptNumber < retryPolicy.maxAttempts;
+        const retryable = retryPolicy.retryableClasses.includes(classification) && executionAttempt < retryPolicy.maxAttempts;
         attemptService.fail(attempt, classification, message, retryable, this.deps.nodeFlowRepository.listNodeAttempts(run.id).find((candidate) => candidate.id === attempt.id)?.invocationId);
         if (retryable) {
           this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, { status: "retry_waiting", errorMessage: message });
-          await delay(retryDelay(retryPolicy.backoffMs, retryPolicy.maxBackoffMs ?? retryPolicy.backoffMs, retryPolicy.jitterRatio ?? 0, attemptNumber), options.signal);
+          await delay(retryDelay(retryPolicy.backoffMs, retryPolicy.maxBackoffMs ?? retryPolicy.backoffMs, retryPolicy.jitterRatio ?? 0, executionAttempt), options.signal);
           this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, { status: "running", errorMessage: null });
           continue;
         }
@@ -332,23 +405,23 @@ export class NodeFlowRuntimeService {
       leaseOwner: null,
       leaseExpiresAt: null,
     });
-    this.deps.executionRepository.updateExecutionInvocation(parentInvocation.id, {
+    this.deps.executionRepository.updateExecutionInvocation(parentInvocationId, {
       status: terminalStatus === "succeeded" ? "completed" : terminalStatus === "attention_required" ? "failed" : terminalStatus === "approval_waiting" ? "running" : terminalStatus,
       errorMessage: terminalStatus === "approval_waiting" ? null : terminalError,
       finishedAt,
     });
-    this.deps.executionRepository.appendExecutionInvocationMessage(parentInvocation.id, {
+    this.deps.executionRepository.appendExecutionInvocationMessage(parentInvocationId, {
       role: terminalStatus === "succeeded" ? "assistant" : "system",
       contentMarkdown: terminalStatus === "succeeded"
         ? "Node flow run completed."
         : `Node flow run ${terminalStatus}: ${terminalError ?? "No error message."}`,
       metadata: {
-        flowId: flow.id,
+        flowId,
         runId: run.id,
         status: terminalStatus,
       },
     });
-    this.deps.auditService?.recordSystem({ action: "automation.run.finished", resourceType: "node_flow_run", resourceId: run.id, projectId, outcome: terminalStatus === "succeeded" ? "succeeded" : "failed", metadata: { flowId: flow.id, publicationId: publication.id, status: terminalStatus } });
+    this.deps.auditService?.recordSystem({ action: terminalStatus === "approval_waiting" ? "automation.run.approval_waiting" : "automation.run.finished", resourceType: "node_flow_run", resourceId: run.id, projectId, outcome: terminalStatus === "succeeded" || terminalStatus === "approval_waiting" ? "succeeded" : "failed", metadata: { flowId, publicationId: publication.id, status: terminalStatus } });
 
     clearInterval(heartbeatTimer);
     return {
@@ -359,6 +432,34 @@ export class NodeFlowRuntimeService {
     };
   }
 
+  private terminateApprovalRun(run: NodeFlowRunRecord, nodeId: string, status: "rejected" | "expired"): NodeFlowRunSummaryResponse {
+    const message = `Approval for node ${nodeId} was ${status}.`;
+    const nodeRun = this.deps.nodeFlowRepository.listNodeRuns(run.id).find((candidate) => candidate.nodeId === nodeId && candidate.status === "approval_waiting");
+    if (nodeRun) this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, { status: "failed", errorMessage: message, finishedAt: new Date().toISOString() });
+    const attempt = this.deps.nodeFlowRepository.listNodeAttempts(run.id).find((candidate) => candidate.nodeId === nodeId && candidate.status === "approval_waiting");
+    if (attempt) this.deps.nodeFlowRepository.updateNodeAttempt(attempt.id, { status: "failed", failureClassification: "permanent", retryDecision: "stop", errorMessage: message, finishedAt: new Date().toISOString() });
+    const updated = this.deps.nodeFlowRepository.updateRun(run.id, { status: "failed", errorMessage: message, finishedAt: new Date().toISOString(), leaseOwner: null, leaseExpiresAt: null });
+    if (updated.executionInvocationId) this.deps.executionRepository.updateExecutionInvocation(updated.executionInvocationId, { status: "failed", errorMessage: message, finishedAt: updated.finishedAt });
+    return this.summarizeRun(updated.id);
+  }
+
+  private terminateCancelledRun(run: NodeFlowRunRecord): NodeFlowRunSummaryResponse {
+    const message = "Node flow run was cancelled while waiting for approval.";
+    const nodeRun = this.deps.nodeFlowRepository.listNodeRuns(run.id).find((candidate) => candidate.status === "approval_waiting");
+    if (nodeRun) this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, { status: "cancelled", errorMessage: message, finishedAt: new Date().toISOString() });
+    const attempt = this.deps.nodeFlowRepository.listNodeAttempts(run.id).find((candidate) => candidate.status === "approval_waiting");
+    if (attempt) this.deps.nodeFlowRepository.updateNodeAttempt(attempt.id, { status: "cancelled", failureClassification: "cancelled", retryDecision: "stop", errorMessage: message, finishedAt: new Date().toISOString() });
+    const updated = this.deps.nodeFlowRepository.updateRun(run.id, { status: "cancelled", errorMessage: message, finishedAt: new Date().toISOString(), leaseOwner: null, leaseExpiresAt: null });
+    if (updated.executionInvocationId) this.deps.executionRepository.updateExecutionInvocation(updated.executionInvocationId, { status: "cancelled", errorMessage: message, finishedAt: updated.finishedAt });
+    return this.summarizeRun(updated.id);
+  }
+
+  private summarizeRun(runId: string): NodeFlowRunSummaryResponse {
+    const run = this.deps.nodeFlowRepository.getRun(runId);
+    if (!run) throw new EntityNotFoundError(`Node flow run not found: ${runId}`);
+    return { run, nodeRuns: this.deps.nodeFlowRepository.listNodeRuns(runId), attempts: this.deps.nodeFlowRepository.listNodeAttempts(runId), output: run.output };
+  }
+
   private requireSupportedNodes(graph: NodeFlowGraph): void {
     const unsupported = graph.nodes.filter((node) => {
       const reference = node.definition ?? { type: node.type, version: 1 };
@@ -825,6 +926,13 @@ function buildDescendants(graph: NodeFlowGraph): Map<string, Set<string>> {
   }));
 }
 
+function inferSelectedPorts(node: NodeFlowNode, output: NodeFlowJsonObject): Set<string> | null {
+  if (node.type === "condition" && typeof output.matched === "boolean") return new Set([output.matched ? "true" : "false"]);
+  if (node.type === "switch" && typeof output.selectedCase === "string") return new Set([output.selectedCase]);
+  if (node.type === "approval" && output.approved === true) return new Set(["approved"]);
+  return null;
+}
+
 function renderTemplate(template: string, context: RuntimeContext): string {
   const source = contextToObject(context);
   return template.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_match, rawPath: string) => {
@@ -973,6 +1081,7 @@ function classifyFailure(error: unknown, parentAborted: boolean, attemptAborted:
   if (parentAborted) return "cancelled";
   const message = error instanceof Error ? error.message : String(error);
   if (attemptAborted || /timed? out|timeout/i.test(message)) return "timeout";
+  if (error instanceof UnknownSideEffectOutcomeError) return "unknown_side_effect";
   if (/quota|rate.?limit|429/i.test(message)) return "quota";
   if (/credential|secret|access denied/i.test(message)) return "credential";
   if (error instanceof ValidationError || /requires|unsupported|must /i.test(message)) return "validation";
diff --git a/src/services/node-flow-service.ts b/src/services/node-flow-service.ts
index 753612b958..09231fbdde 100644
--- a/src/services/node-flow-service.ts
+++ b/src/services/node-flow-service.ts
@@ -224,6 +224,13 @@ export class NodeFlowService {
     });
   }
 
+  async resumeApproval(projectId: string, runId: string, approvalId: string): Promise<NodeFlowRunSummaryResponse> {
+    const run = this.requireOwnedRun(runId, projectId);
+    if (!this.runtimeService) throw new ValidationError("Node flow runtime is not configured.");
+    const result = await this.runtimeService.resumeApproval(projectId, approvalId, run.id);
+    return result;
+  }
+
   update(flowId: string, input: UpdateNodeFlowInput): NodeFlowRecord {
     const update: UpdateNodeFlowInput = {};
     if (input.title !== undefined) {
diff --git a/src/services/node-flows/approval-service.ts b/src/services/node-flows/approval-service.ts
index da353c9d48..05ee59b392 100644
--- a/src/services/node-flows/approval-service.ts
+++ b/src/services/node-flows/approval-service.ts
@@ -19,10 +19,13 @@ export class ApprovalService {
   }): AutomationApprovalRecord {
     const logicalItem = input.logicalItem?.trim() || "default";
     this.repository.expireDue();
-    const approval = this.repository.getForItem(input.runId, input.nodeId, logicalItem)
-      ?? this.repository.request({ ...input, logicalItem });
+    const existing = this.repository.getForItem(input.runId, input.nodeId, logicalItem);
+    const requested = existing
+      ? { approval: existing, changed: false }
+      : this.repository.requestIdempotently({ ...input, logicalItem });
+    const approval = requested.approval;
     if (approval.status === "approved") return approval;
-    this.auditService?.recordSystem({ action: "approval.requested", resourceType: "automation_approval", resourceId: approval.id, projectId: approval.projectId, outcome: "succeeded", metadata: { flowId: approval.flowId, runId: approval.runId, nodeId: approval.nodeId, logicalItem: approval.logicalItem } });
+    if (requested.changed) this.auditService?.recordSystem({ action: "approval.requested", resourceType: "automation_approval", resourceId: approval.id, projectId: approval.projectId, outcome: "succeeded", metadata: { flowId: approval.flowId, runId: approval.runId, nodeId: approval.nodeId, logicalItem: approval.logicalItem } });
     if (approval.status === "rejected" || approval.status === "expired") {
       throw new ValidationError(`Approval ${approval.id} is ${approval.status}.`);
     }
@@ -30,14 +33,19 @@ export class ApprovalService {
   }
 
   approve(id: string, decidedBy: string, decision: NodeFlowJsonObject = {}): AutomationApprovalRecord {
-    const approval = this.repository.decide(id, { status: "approved", decidedBy, decision });
-    this.auditService?.recordSystem({ action: "approval.approved", resourceType: "automation_approval", resourceId: approval.id, projectId: approval.projectId, outcome: "succeeded", principalId: decidedBy, metadata: { flowId: approval.flowId, runId: approval.runId, nodeId: approval.nodeId } });
+    this.repository.expireDue();
+    const result = this.repository.decideIdempotently(id, { status: "approved", decidedBy, decision });
+    const approval = result.approval;
+    if (result.changed) this.auditService?.recordSystem({ action: "approval.approved", resourceType: "automation_approval", resourceId: approval.id, projectId: approval.projectId, outcome: "succeeded", principalId: decidedBy, metadata: { flowId: approval.flowId, runId: approval.runId, nodeId: approval.nodeId } });
     return approval;
   }
   reject(id: string, decidedBy: string, decision: NodeFlowJsonObject = {}): AutomationApprovalRecord {
-    const approval = this.repository.decide(id, { status: "rejected", decidedBy, decision });
-    this.auditService?.recordSystem({ action: "approval.rejected", resourceType: "automation_approval", resourceId: approval.id, projectId: approval.projectId, outcome: "succeeded", principalId: decidedBy, metadata: { flowId: approval.flowId, runId: approval.runId, nodeId: approval.nodeId } });
+    this.repository.expireDue();
+    const result = this.repository.decideIdempotently(id, { status: "rejected", decidedBy, decision });
+    const approval = result.approval;
+    if (result.changed) this.auditService?.recordSystem({ action: "approval.rejected", resourceType: "automation_approval", resourceId: approval.id, projectId: approval.projectId, outcome: "succeeded", principalId: decidedBy, metadata: { flowId: approval.flowId, runId: approval.runId, nodeId: approval.nodeId } });
     return approval;
   }
-  listForRun(runId: string): AutomationApprovalRecord[] { return this.repository.listForRun(runId); }
+  listForRun(runId: string): AutomationApprovalRecord[] { this.repository.expireDue(); return this.repository.listForRun(runId); }
+  get(id: string): AutomationApprovalRecord | null { this.repository.expireDue(); return this.repository.get(id); }
 }
diff --git a/src/services/node-flows/builtins/builtin-executors.ts b/src/services/node-flows/builtins/builtin-executors.ts
index 5a5530a138..350f30f69a 100644
--- a/src/services/node-flows/builtins/builtin-executors.ts
+++ b/src/services/node-flows/builtins/builtin-executors.ts
@@ -1,7 +1,7 @@
 import { ValidationError } from "../../../repositories/repository-utils.js";
 import type { NodeFlowJsonObject, NodeFlowJsonValue } from "../../../contracts/node-flow-types.js";
 import type { ApprovalService } from "../approval-service.js";
-import type { OutboxService } from "../outbox-service.js";
+import { UnknownSideEffectOutcomeError, type OutboxService } from "../outbox-service.js";
 
 export const MAX_FOREACH_ITEMS = 1_000;
 export const MAX_SUBFLOW_DEPTH = 8;
@@ -55,7 +55,7 @@ export class BuiltinExecutors {
     const sent = await this.deps.outboxService.dispatch({ projectId: context.projectId, flowId: context.flowId,
       publicationId: context.publicationId, runId: context.runId, nodeId: context.nodeId, logicalItem,
       effectType: "email", payload: draft });
-    if (sent.status === "attention_required") throw new Error(sent.lastError ?? "Email provider outcome is unknown.");
+    if (sent.status === "attention_required") throw new UnknownSideEffectOutcomeError(sent.lastError ?? "Email provider outcome is unknown.");
     if (sent.status !== "sent") throw new Error(sent.lastError ?? "Email send failed.");
     return { output: { sent: true, outboxId: sent.id, providerMessageId: sent.providerMessageId } };
   }
diff --git a/src/services/node-flows/node-flow-recovery-service.ts b/src/services/node-flows/node-flow-recovery-service.ts
index 2af71113cb..6b8a2e63f6 100644
--- a/src/services/node-flows/node-flow-recovery-service.ts
+++ b/src/services/node-flows/node-flow-recovery-service.ts
@@ -1,8 +1,14 @@
 import type { NodeFlowRepository } from "../../repositories/node-flow-repository.js";
 import type { NodeFlowRunRecord } from "../../contracts/node-flow-types.js";
+import type { ApprovalService } from "./approval-service.js";
+import type { NodeFlowRuntimeService } from "../node-flow-runtime-service.js";
 
 export class NodeFlowRecoveryService {
-  constructor(private readonly repository: NodeFlowRepository) {}
+  constructor(
+    private readonly repository: NodeFlowRepository,
+    private readonly approvalService?: ApprovalService,
+    private readonly runtimeService?: NodeFlowRuntimeService,
+  ) {}
 
   recover(now = new Date()): NodeFlowRunRecord[] {
     const recoverable = this.repository.listRecoverableRuns(now.toISOString());
@@ -24,4 +30,21 @@ export class NodeFlowRecoveryService {
       return this.repository.updateRun(run.id, { status: "queued", leaseOwner: null, leaseExpiresAt: null });
     });
   }
+
+  async resumeDecidedApprovals(): Promise<NodeFlowRunRecord[]> {
+    if (!this.approvalService || !this.runtimeService) return [];
+    const resumed: NodeFlowRunRecord[] = [];
+    const waitingRuns = this.repository.listRecoverableRuns().filter((run) => run.status === "approval_waiting");
+    for (const run of waitingRuns) {
+      const waitingNode = this.repository.listNodeRuns(run.id).find((candidate) => candidate.status === "approval_waiting");
+      if (!waitingNode) continue;
+      const approval = this.approvalService.listForRun(run.id)
+        .map((candidate) => this.approvalService!.get(candidate.id) ?? candidate)
+        .find((candidate) => candidate.nodeId === waitingNode.nodeId && candidate.status !== "pending");
+      if (!approval) continue;
+      const summary = await this.runtimeService.resumeApproval(run.projectId, approval.id, run.id);
+      resumed.push(summary.run);
+    }
+    return resumed;
+  }
 }
diff --git a/tests/backend/repositories/automation-governance-repositories.test.ts b/tests/backend/repositories/automation-governance-repositories.test.ts
index ae0a962d38..d8e5958a49 100644
--- a/tests/backend/repositories/automation-governance-repositories.test.ts
+++ b/tests/backend/repositories/automation-governance-repositories.test.ts
@@ -33,6 +33,22 @@ describe("automation governance repositories", () => {
     storage.close();
   });
 
+  it("deduplicates approval requests and repeated identical decisions", async () => {
+    const { storage, project, flow, run } = await fixture();
+    const repository = new AutomationApprovalRepository(storage);
+    const input = { projectId: project.id, flowId: flow.id, runId: run.id, nodeId: "send", logicalItem: "message-1", request: { effectType: "email" } };
+    const first = repository.requestIdempotently(input);
+    const duplicate = repository.requestIdempotently(input);
+    const decided = repository.decideIdempotently(first.approval.id, { status: "approved", decidedBy: "operator" });
+    const repeated = repository.decideIdempotently(first.approval.id, { status: "approved", decidedBy: "operator" });
+    expect(first.changed).toBe(true);
+    expect(duplicate).toMatchObject({ changed: false, approval: { id: first.approval.id } });
+    expect(decided.changed).toBe(true);
+    expect(repeated).toMatchObject({ changed: false, approval: { status: "approved" } });
+    expect(repository.listForRun(run.id)).toHaveLength(1);
+    storage.close();
+  });
+
   it("deduplicates outbox sends and marks restart-unknown outcomes for attention", async () => {
     const { storage, project, flow, publication, run } = await fixture();
     const repository = new AutomationOutboxRepository(storage); const provider = new MockSideEffectProvider();
diff --git a/tests/backend/server/node-flow-routes.test.ts b/tests/backend/server/node-flow-routes.test.ts
index f7a7a05f45..9b9b323569 100644
--- a/tests/backend/server/node-flow-routes.test.ts
+++ b/tests/backend/server/node-flow-routes.test.ts
@@ -151,4 +151,42 @@ describe("node flow routes", () => {
     expect(response.status).toBe(409);
     expect(response.body.conflict).toMatchObject({ code: "draft_revision_conflict", actualDraftRevision: 2 });
   });
+
+  it.each(["approve", "reject"] as const)("decides and resumes the exact run for an approval %s", async (decision) => {
+    const approval = { id: "approval-1", projectId: "project-1", flowId: "flow-1", runId: "run-1", nodeId: "send", logicalItem: "default", status: decision === "approve" ? "approved" : "rejected" };
+    const approvalService = {
+      get: vi.fn().mockReturnValue(null),
+      approve: vi.fn().mockReturnValue(approval),
+      reject: vi.fn().mockReturnValue(approval),
+    };
+    const nodeFlowService = {
+      resumeApproval: vi.fn().mockResolvedValue({ run: { id: "run-1", status: decision === "approve" ? "succeeded" : "failed" }, nodeRuns: [], attempts: [], output: {} }),
+    };
+    const app = express(); app.use(express.json()); registerNodeFlowRoutes(app, { approvalService, nodeFlowService } as any);
+
+    const response = await request(app).post("/api/automation-approvals/approval-1/decision").send({ decision, decidedBy: "operator" });
+
+    expect(response.status).toBe(200);
+    expect(response.body.run.id).toBe("run-1");
+    expect(nodeFlowService.resumeApproval).toHaveBeenCalledWith("project-1", "run-1", "approval-1");
+  });
+
+  it("exposes an explicit idempotent approval-resume route", async () => {
+    const nodeFlowService = { resumeApproval: vi.fn().mockResolvedValue({ run: { id: "run-1", status: "succeeded" }, nodeRuns: [], attempts: [] }) };
+    const app = express(); app.use(express.json()); registerNodeFlowRoutes(app, { nodeFlowService } as any);
+    const response = await request(app).post("/api/node-flow-runs/run-1/resume-approval").send({ projectId: "project-1", approvalId: "approval-1" });
+    expect(response.status).toBe(200);
+    expect(nodeFlowService.resumeApproval).toHaveBeenCalledWith("project-1", "run-1", "approval-1");
+  });
+
+  it("terminates an expired approval through the decision route without overwriting its decision", async () => {
+    const expired = { id: "approval-1", projectId: "project-1", flowId: "flow-1", runId: "run-1", nodeId: "send", logicalItem: "default", status: "expired" };
+    const approvalService = { get: vi.fn().mockReturnValue(expired), approve: vi.fn(), reject: vi.fn() };
+    const nodeFlowService = { resumeApproval: vi.fn().mockResolvedValue({ run: { id: "run-1", status: "failed" }, nodeRuns: [], attempts: [] }) };
+    const app = express(); app.use(express.json()); registerNodeFlowRoutes(app, { approvalService, nodeFlowService } as any);
+    const response = await request(app).post("/api/automation-approvals/approval-1/decision").send({ decision: "approve", decidedBy: "operator" });
+    expect(response.status).toBe(200);
+    expect(response.body).toMatchObject({ status: "expired", run: { status: "failed" } });
+    expect(approvalService.approve).not.toHaveBeenCalled();
+  });
 });
diff --git a/tests/backend/services/node-flow-recovery-service.test.ts b/tests/backend/services/node-flow-recovery-service.test.ts
index 918f0e4719..05f8ed74f4 100644
--- a/tests/backend/services/node-flow-recovery-service.test.ts
+++ b/tests/backend/services/node-flow-recovery-service.test.ts
@@ -8,6 +8,9 @@ import { ProjectManagementRepository } from "../../../src/repositories/project-m
 import { NodeFlowRecoveryService } from "../../../src/services/node-flows/node-flow-recovery-service.js";
 import { NodeFlowQueueService, NodeFlowQuotaExceededError } from "../../../src/services/node-flows/node-flow-queue-service.js";
 import { DEFAULT_NODE_FLOW_EXECUTION_POLICY } from "../../../src/contracts/node-flow-execution-policy-types.js";
+import { AutomationApprovalRepository } from "../../../src/repositories/automation-approval-repository.js";
+import { ApprovalService } from "../../../src/services/node-flows/approval-service.js";
+import type { NodeFlowRuntimeService } from "../../../src/services/node-flow-runtime-service.js";
 
 const dirs: string[] = [];
 afterEach(async () => Promise.all(dirs.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true }))));
@@ -56,4 +59,22 @@ describe("NodeFlowRecoveryService", () => {
     expect(recovered?.status).toBe("attention_required");
     expect(recovered?.errorMessage).toMatch(/outcome is unknown/i);
   });
+
+  it("resumes a decision persisted before process restart", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "flow-approval-recovery-")); dirs.push(dir);
+    const storage = new AppDbStorage(path.join(dir, "app.db"));
+    const projects = new ProjectManagementRepository(storage); const repository = new NodeFlowRepository(storage);
+    const project = projects.createProject({ name: "Approval Recovery", sourceType: "local", sourceRef: dir });
+    const flow = repository.createFlow(project.id, { title: "Recover approval", graph: { nodes: [{ id: "approval", type: "approval", title: "Approval" }], edges: [] } });
+    const run = repository.createRun({ flowId: flow.id, projectId: project.id, version: 1, publicationId: repository.getPublication(flow.id)!.id, status: "approval_waiting" });
+    repository.createNodeRun({ runId: run.id, flowId: flow.id, projectId: project.id, nodeId: "approval", status: "approval_waiting" });
+    const approvals = new AutomationApprovalRepository(storage);
+    const approval = approvals.request({ projectId: project.id, flowId: flow.id, runId: run.id, nodeId: "approval", logicalItem: "default", request: {} });
+    approvals.decide(approval.id, { status: "approved", decidedBy: "operator" });
+    const resumed = { ...run, status: "succeeded" as const };
+    const runtime = { resumeApproval: async () => ({ run: resumed, nodeRuns: [], attempts: [], output: {} }) } as unknown as NodeFlowRuntimeService;
+
+    const recovered = await new NodeFlowRecoveryService(repository, new ApprovalService(approvals), runtime).resumeDecidedApprovals();
+    expect(recovered).toEqual([resumed]);
+  });
 });
diff --git a/tests/backend/services/node-flow-runtime-service.test.ts b/tests/backend/services/node-flow-runtime-service.test.ts
index c08eeb0df2..c3bdae3f49 100644
--- a/tests/backend/services/node-flow-runtime-service.test.ts
+++ b/tests/backend/services/node-flow-runtime-service.test.ts
@@ -13,15 +13,22 @@ import type { ProviderExecutionService } from "../../../src/services/provider-ex
 import type { NodeFlowGraph } from "../../../src/contracts/node-flow-types.js";
 import type { CredentialBroker } from "../../../src/services/credentials/credential-broker.js";
 import { EgressPolicyService } from "../../../src/services/node-flows/egress-policy-service.js";
+import { AutomationApprovalRepository } from "../../../src/repositories/automation-approval-repository.js";
+import { AutomationOutboxRepository } from "../../../src/repositories/automation-outbox-repository.js";
+import { ApprovalService } from "../../../src/services/node-flows/approval-service.js";
+import { MockSideEffectProvider, OutboxService, type SideEffectProvider } from "../../../src/services/node-flows/outbox-service.js";
 
 const tempDirs: string[] = [];
 
-async function createRuntime(providerExecutionService?: Partial<ProviderExecutionService>,credentialBroker?:Partial<CredentialBroker>, egressPolicyService?: EgressPolicyService): Promise<{
+async function createRuntime(providerExecutionService?: Partial<ProviderExecutionService>,credentialBroker?:Partial<CredentialBroker>, egressPolicyService?: EgressPolicyService, sideEffectProvider?: SideEffectProvider): Promise<{
   dir: string;
+  storage: AppDbStorage;
   projectRepository: ProjectManagementRepository;
   nodeFlowRepository: NodeFlowRepository;
   executionRepository: ExecutionRepository;
   runtime: NodeFlowRuntimeService;
+  approvalService?: ApprovalService;
+  outboxRepository?: AutomationOutboxRepository;
 }> {
   const dir = await fs.mkdtemp(path.join(os.tmpdir(), "node-flow-runtime-"));
   tempDirs.push(dir);
@@ -29,6 +36,8 @@ async function createRuntime(providerExecutionService?: Partial<ProviderExecutio
   const projectRepository = new ProjectManagementRepository(storage);
   const nodeFlowRepository = new NodeFlowRepository(storage);
   const executionRepository = new ExecutionRepository(storage);
+  const approvalService = sideEffectProvider ? new ApprovalService(new AutomationApprovalRepository(storage)) : undefined;
+  const outboxRepository = sideEffectProvider ? new AutomationOutboxRepository(storage) : undefined;
   const runtime = new NodeFlowRuntimeService({
     nodeFlowRepository,
     executionRepository,
@@ -37,9 +46,11 @@ async function createRuntime(providerExecutionService?: Partial<ProviderExecutio
     providerExecutionService: providerExecutionService as ProviderExecutionService | undefined,
     credentialBroker: credentialBroker as CredentialBroker | undefined,
     egressPolicyService,
+    approvalService,
+    outboxService: sideEffectProvider && outboxRepository ? new OutboxService(outboxRepository, sideEffectProvider) : undefined,
     getDashboardSettings: () => DEFAULT_DASHBOARD_SETTINGS,
   });
-  return { dir, projectRepository, nodeFlowRepository, executionRepository, runtime };
+  return { dir, storage, projectRepository, nodeFlowRepository, executionRepository, runtime, approvalService, outboxRepository };
 }
 
 afterEach(async () => {
@@ -47,6 +58,92 @@ afterEach(async () => {
 });
 
 describe("NodeFlowRuntimeService", () => {
+  it("resumes an approval-gated email send on the pinned run exactly once across restart and repeated decisions", async () => {
+    const firstProvider = new MockSideEffectProvider();
+    const setup = await createRuntime(undefined, undefined, undefined, firstProvider);
+    const project = setup.projectRepository.createProject({ name: "Approval Project", sourceType: "local", sourceRef: setup.dir });
+    const flow = setup.nodeFlowRepository.createFlow(project.id, { title: "Approved email", graph: {
+      nodes: [
+        { id: "input", type: "input", title: "Input" },
+        { id: "send", type: "email_send", title: "Send", data: { to: "ops@example.test", subject: "Release", body: "Ready", logicalItem: "release-email" } },
+        { id: "output", type: "output", title: "Output" },
+      ],
+      edges: [{ fromNodeId: "input", toNodeId: "send" }, { fromNodeId: "send", toNodeId: "output" }],
+    } });
+
+    const waiting = await setup.runtime.runFlow(project.id, flow.id, { release: "v1" });
+    expect(waiting.run.status).toBe("approval_waiting");
+    expect(waiting.attempts).toHaveLength(2);
+    expect(waiting.attempts?.find((attempt) => attempt.nodeId === "send")).toMatchObject({ attemptNumber: 1, status: "approval_waiting" });
+    expect(firstProvider.sends).toHaveLength(0);
+    expect(setup.outboxRepository?.listForRun(waiting.run.id)).toHaveLength(0);
+
+    const approval = setup.approvalService!.listForRun(waiting.run.id)[0]!;
+    setup.approvalService!.approve(approval.id, "operator", { ticket: "change-1" });
+    const restartedProvider = new MockSideEffectProvider();
+    const restartedRuntime = new NodeFlowRuntimeService({
+      nodeFlowRepository: new NodeFlowRepository(setup.storage),
+      executionRepository: new ExecutionRepository(setup.storage),
+      projectManagementRepository: new ProjectManagementRepository(setup.storage),
+      settingsRepository: new SettingsRepository(path.join(setup.dir, "settings-restarted.db")),
+      approvalService: new ApprovalService(new AutomationApprovalRepository(setup.storage)),
+      outboxService: new OutboxService(new AutomationOutboxRepository(setup.storage), restartedProvider),
+      getDashboardSettings: () => DEFAULT_DASHBOARD_SETTINGS,
+    });
+
+    const concurrent = await Promise.all([
+      restartedRuntime.resumeApproval(project.id, approval.id, waiting.run.id),
+      restartedRuntime.resumeApproval(project.id, approval.id, waiting.run.id),
+    ]);
+    const completed = concurrent.find((result) => result.run.status === "succeeded")!;
+    const repeated = await restartedRuntime.resumeApproval(project.id, approval.id, waiting.run.id);
+    expect(completed.run).toMatchObject({ id: waiting.run.id, publicationId: waiting.run.publicationId, status: "succeeded" });
+    expect(repeated.run.status).toBe("succeeded");
+    expect(completed.attempts?.find((attempt) => attempt.nodeId === "send")).toMatchObject({ attemptNumber: 1, status: "succeeded" });
+    expect(completed.attempts?.filter((attempt) => attempt.nodeId === "send")).toHaveLength(1);
+    expect(restartedProvider.sends).toHaveLength(1);
+    expect(new AutomationOutboxRepository(setup.storage).listForRun(waiting.run.id)).toHaveLength(1);
+  });
+
+  it.each(["rejected", "expired"] as const)("terminates a %s waiting approval durably", async (decision) => {
+    const provider = new MockSideEffectProvider();
+    const setup = await createRuntime(undefined, undefined, undefined, provider);
+    const project = setup.projectRepository.createProject({ name: `Approval ${decision}`, sourceType: "local", sourceRef: setup.dir });
+    const flow = setup.nodeFlowRepository.createFlow(project.id, { title: "Approval", graph: { nodes: [{ id: "approval", type: "approval", title: "Approval" }], edges: [] } });
+    const waiting = await setup.runtime.runFlow(project.id, flow.id, {});
+    const approval = setup.approvalService!.listForRun(waiting.run.id)[0]!;
+    if (decision === "rejected") setup.approvalService!.reject(approval.id, "operator");
+    else {
+      setup.storage.getDatabase().prepare("UPDATE automation_approvals SET expires_at = ? WHERE id = ?").run("2020-01-01T00:00:00.000Z", approval.id);
+      setup.approvalService!.get(approval.id);
+    }
+    const result = await setup.runtime.resumeApproval(project.id, approval.id, waiting.run.id);
+    expect(result.run).toMatchObject({ id: waiting.run.id, status: "failed" });
+    expect(result.run.errorMessage).toContain(decision);
+    expect(result.attempts?.[0]).toMatchObject({ status: "failed", retryDecision: "stop" });
+    expect(provider.sends).toHaveLength(0);
+  });
+
+  it("does not resume an approval that is still pending", async () => {
+    const setup = await createRuntime(undefined, undefined, undefined, new MockSideEffectProvider());
+    const project = setup.projectRepository.createProject({ name: "Pending Approval", sourceType: "local", sourceRef: setup.dir });
+    const flow = setup.nodeFlowRepository.createFlow(project.id, { title: "Approval", graph: { nodes: [{ id: "approval", type: "approval", title: "Approval" }], edges: [] } });
+    const waiting = await setup.runtime.runFlow(project.id, flow.id, {});
+    const approval = setup.approvalService!.listForRun(waiting.run.id)[0]!;
+    await expect(setup.runtime.resumeApproval(project.id, approval.id, waiting.run.id)).rejects.toThrow(/still pending/i);
+    expect(setup.nodeFlowRepository.getRun(waiting.run.id)?.status).toBe("approval_waiting");
+  });
+
+  it("cancels a waiting approval without leaving an active node attempt", async () => {
+    const setup = await createRuntime(undefined, undefined, undefined, new MockSideEffectProvider());
+    const project = setup.projectRepository.createProject({ name: "Cancelled Approval", sourceType: "local", sourceRef: setup.dir });
+    const flow = setup.nodeFlowRepository.createFlow(project.id, { title: "Approval", graph: { nodes: [{ id: "approval", type: "approval", title: "Approval" }], edges: [] } });
+    const waiting = await setup.runtime.runFlow(project.id, flow.id, {});
+    const cancelled = setup.runtime.requestCancellation(waiting.run.id);
+    expect(cancelled.status).toBe("cancelled");
+    expect(setup.nodeFlowRepository.listNodeRuns(waiting.run.id)[0]?.status).toBe("cancelled");
+    expect(setup.nodeFlowRepository.listNodeAttempts(waiting.run.id)[0]?.status).toBe("cancelled");
+  });
   it("persists unselected condition branches as skipped while the selected branch runs", async () => {
     const { dir, projectRepository, nodeFlowRepository, runtime } = await createRuntime();
     const project = projectRepository.createProject({ name: "Branch Project", sourceType: "local", sourceRef: dir });
diff --git a/tests/dashboard/v2/node-run-debugger.test.tsx b/tests/dashboard/v2/node-run-debugger.test.tsx
new file mode 100644
index 0000000000..16bfcbc3cd
--- /dev/null
+++ b/tests/dashboard/v2/node-run-debugger.test.tsx
@@ -0,0 +1,26 @@
+/** @vitest-environment jsdom */
+/** @jsx h */
+import { h } from "preact";
+import { cleanup, render, screen } from "@testing-library/preact";
+import userEvent from "@testing-library/user-event";
+import "@testing-library/jest-dom/vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { NodeRunDebugger } from "../../../dashboard/src/v2/components/nodes/NodeRunDebugger.js";
+
+afterEach(cleanup);
+
+describe("NodeRunDebugger approvals", () => {
+  it("shows a pending approval and dispatches one explicit decision", async () => {
+    const onApprovalDecision = vi.fn();
+    render(<NodeRunDebugger
+      runs={[{ id: "run-1", flowId: "flow-1", projectId: "project-1", version: 1, publicationId: "publication-1", status: "approval_waiting", policy: {} as never, leaseOwner: null, leaseExpiresAt: null, heartbeatAt: null, cancelRequestedAt: null, executionInvocationId: "xi-1", triggerType: "manual", triggerPayload: null, input: {}, output: {}, errorMessage: null, startedAt: "2026-01-01T00:00:00.000Z", finishedAt: null, createdAt: "2026-01-01T00:00:00.000Z", updatedAt: "2026-01-01T00:00:00.000Z" }]}
+      selectedRunId="run-1" nodeRuns={[]} attempts={[]}
+      approvals={[{ id: "approval-1", projectId: "project-1", flowId: "flow-1", runId: "run-1", nodeId: "send", logicalItem: "email-1", status: "pending", request: {}, decision: null, requestedAt: "2026-01-01T00:00:00.000Z", decidedAt: null, decidedBy: null, expiresAt: null, createdAt: "2026-01-01T00:00:00.000Z", updatedAt: "2026-01-01T00:00:00.000Z" }]}
+      onSelectRun={() => undefined} onRefresh={() => undefined} onCancel={() => undefined} onRetry={() => undefined}
+      onApprovalDecision={onApprovalDecision}
+    />);
+    await userEvent.click(screen.getByRole("button", { name: "Approve & continue" }));
+    expect(onApprovalDecision).toHaveBeenCalledOnce();
+    expect(onApprovalDecision).toHaveBeenCalledWith("approval-1", "approve");
+  });
+});
diff --git a/tests/dashboard/v2/nodes-page.test.tsx b/tests/dashboard/v2/nodes-page.test.tsx
index f3c48eb3e8..e7579cbc71 100644
--- a/tests/dashboard/v2/nodes-page.test.tsx
+++ b/tests/dashboard/v2/nodes-page.test.tsx
@@ -8,7 +8,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { NODES_CANVAS_STORAGE_KEY, NodesPage } from "../../../dashboard/src/v2/NodesPage.js";
 import { ProjectDataContext } from "../../../dashboard/src/v2/context/project-data.js";
 
-const api = vi.hoisted(() => ({ fetchNodeFlows: vi.fn(), fetchNodeFlowCatalog: vi.fn(), createNodeFlowDraft: vi.fn(), fetchNodeFlow: vi.fn(), fetchNodeFlowRuns: vi.fn(), fetchNodeFlowNodeRuns: vi.fn(), fetchNodeFlowAttempts: vi.fn(), patchNodeFlowDraft: vi.fn(), fetchNodeDefinition: vi.fn(), validateNodeFlowDraft: vi.fn(), deleteNodeFlow: vi.fn() }));
+const api = vi.hoisted(() => ({ fetchNodeFlows: vi.fn(), fetchNodeFlowCatalog: vi.fn(), createNodeFlowDraft: vi.fn(), fetchNodeFlow: vi.fn(), fetchNodeFlowRuns: vi.fn(), fetchNodeFlowNodeRuns: vi.fn(), fetchNodeFlowAttempts: vi.fn(), fetchNodeFlowApprovals: vi.fn(), decideNodeFlowApproval: vi.fn(), patchNodeFlowDraft: vi.fn(), fetchNodeDefinition: vi.fn(), validateNodeFlowDraft: vi.fn(), deleteNodeFlow: vi.fn() }));
 vi.mock("../../../dashboard/src/v2/lib/node-flow-api.js", async (original) => ({ ...(await original()), ...api }));
 vi.mock("../../../dashboard/src/v2/hooks/use-reduced-motion.js", () => ({ useReducedMotion: () => true, useResolvedMotionDuration: <T,>(value: T): T => value }));
 
@@ -18,7 +18,7 @@ const context = { projects: [{ id: "project-1", name: "Test project" }], selecte
 describe("NodesPage governed workspace", () => {
   const review = { flowId: "flow-1", projectId: "project-1", name: "Release automation", description: "Governed", draftRevision: 2, nodeCount: 1, edgeCount: 0, valid: true, validationIssues: [], policyFindings: [], requiredCredentials: [], requestedCapabilities: [], sideEffectDiffs: [], publishedVersion: 1 };
   beforeEach(() => { api.validateNodeFlowDraft.mockResolvedValue(review); });
-  beforeEach(() => { window.localStorage.clear(); api.fetchNodeFlows.mockResolvedValue({ flows: [flow] }); api.fetchNodeFlowCatalog.mockResolvedValue({ nodes: [{ type: "input", version: 1, executable: true, executionKind: "local", label: "Input", description: "Input", category: "Core", credentials: [], capabilities: [], sideEffect: "none", ports: [] }] }); api.fetchNodeFlowRuns.mockResolvedValue({ runs: [] }); api.fetchNodeFlowNodeRuns.mockResolvedValue({ nodeRuns: [] }); api.fetchNodeFlowAttempts.mockResolvedValue({ attempts: [] }); api.fetchNodeDefinition.mockResolvedValue({ type: "input", version: 1, executable: true, executionKind: "local", configurationSchema: { type: "object" }, ui: { label: "Input", description: "Input", category: "Core", widgetSchema: { fields: [] } }, ports: [], credentials: [], capabilities: [], sideEffect: "none", defaultPolicy: {}, documentation: "", deprecation: { deprecated: false } }); });
+  beforeEach(() => { window.localStorage.clear(); api.fetchNodeFlows.mockResolvedValue({ flows: [flow] }); api.fetchNodeFlowCatalog.mockResolvedValue({ nodes: [{ type: "input", version: 1, executable: true, executionKind: "local", label: "Input", description: "Input", category: "Core", credentials: [], capabilities: [], sideEffect: "none", ports: [] }] }); api.fetchNodeFlowRuns.mockResolvedValue({ runs: [] }); api.fetchNodeFlowNodeRuns.mockResolvedValue({ nodeRuns: [] }); api.fetchNodeFlowAttempts.mockResolvedValue({ attempts: [] }); api.fetchNodeFlowApprovals.mockResolvedValue({ approvals: [] }); api.fetchNodeDefinition.mockResolvedValue({ type: "input", version: 1, executable: true, executionKind: "local", configurationSchema: { type: "object" }, ui: { label: "Input", description: "Input", category: "Core", widgetSchema: { fields: [] } }, ports: [], credentials: [], capabilities: [], sideEffect: "none", defaultPolicy: {}, documentation: "", deprecation: { deprecated: false } }); });
   afterEach(() => { cleanup(); vi.clearAllMocks(); });
 
   it("loads a project flow library and registry-backed editor", async () => {

From e196a6183635527a8cc7f87a8625598ab577f9bf Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 08:20:33 +0000
Subject: [PATCH 15/25] feat(task T15): implement via codex

---
 docs-web/architecture/node-flow-foundation.md | 34 +++++++++++--
 .../architecture-node-flow-foundation.mdx     | 34 +++++++++++--
 docs-web/content/docs/registry.ts             |  4 +-
 .../docs/user-dashboard-nodes-canvas.mdx      | 50 ++++++++-----------
 docs-web/user/dashboard/nodes-canvas.md       | 50 ++++++++-----------
 docs/architecture/node-flow-foundation.md     | 47 ++++++++++++++++-
 docs/architecture/node-flows.md               | 14 ++++--
 docs/dashboard/node-flows.md                  |  6 ++-
 docs/dashboard/nodes-canvas.md                | 22 ++++++--
 9 files changed, 182 insertions(+), 79 deletions(-)

diff --git a/docs-web/architecture/node-flow-foundation.md b/docs-web/architecture/node-flow-foundation.md
index acd3237449..b18fd8f0cd 100644
--- a/docs-web/architecture/node-flow-foundation.md
+++ b/docs-web/architecture/node-flow-foundation.md
@@ -1,7 +1,35 @@
 # Node Flow Foundation
 
-Code UX uses one canonical Graph v2 contract across backend, MCP, runtime, and dashboard. Graphs carry `schemaVersion: 2`, versioned definitions, typed ports, credential-id bindings, bounded policies, capabilities, side effects, disabled state, flow schemas, and optional immutable publication metadata.
+Code UX uses one project-owned Graph v2 contract across the dashboard, backend, MCP surface, scheduler, and runtime. Graphs carry `schemaVersion: 2`, stable versioned definition references, typed ports and flow schemas, credential-id bindings, bounded policies, capabilities, side effects, disabled state, and optional immutable publication metadata.
 
-Validation resolves definitions, checks configuration, ports, policies, graph limits, and cycles, and rejects plaintext secrets and custom source. Only `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output` are executable.
+## Registry and executable handlers
 
-Persisted Graph v1 records retain their original immutable version and append deterministic Graph v2. Browser migration retains its original snapshot outside executable graph JSON.
+The definition registry is the authority for the palette and runtime. Manifests provide configuration/UI schemas, ports, credential slots, capabilities, side effects, default policy, documentation, deprecation, executable state, and execution kind.
+
+The governed built-ins with registered handlers are:
+
+| Area | Definitions |
+| --- | --- |
+| Data, provider, and HTTP | `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, `output` |
+| Control and transformation | `condition`, `switch`, `foreach`, `merge`, `delay`, `execute_subflow` |
+| Governed effects and triggers | `approval`, `email_draft`, `email_send`, `webhook_trigger` |
+
+A validated custom definition becomes executable only after its immutable artifact and versioned manifest are registered and the custom-node runtime is configured. Unknown types, legacy browser-only `trigger`/`agent`/`task` kinds, mockups, and definitions marked non-executable are planned or unavailable definitions, not handlers.
+
+## Validation, policy, and secrets
+
+Validation resolves each definition and checks configuration, port handles and schemas, policies, graph bounds, and cycles. It rejects plaintext secret-shaped fields and generated or custom source in graph JSON. The dashboard receives credential binding ids and metadata-only states; resolved values remain behind the credential broker. Credential values and secret-shaped payloads are redacted before invocation messages, attempts, diagnostics, route responses, and debugger output are persisted or rendered.
+
+Draft review reports requested capabilities, side effects, credential status, policy findings, and a non-executing dry run. Publication requires the current `draftRevision`, a valid graph and policy review, and every required credential binding. Runs select an immutable pinned or latest-published snapshot.
+
+## Project workspace and migration
+
+`/nodes` loads the selected project's backend flow library and does not request flow data without a selected project. Revision-checked saves return a conflict rather than replacing a newer draft.
+
+The former `codeux:nodes-canvas:v1` value can be imported once into a project draft. Successful import records a project-specific marker and removes the legacy graph value; local storage is not ongoing persistence. Persisted Graph v1 records retain their exact immutable version and append deterministic Graph v2.
+
+## Operations and prerequisites
+
+The run debugger reads redacted flow runs, node runs, numbered attempts, approvals, retry decisions, invocation links, timing, and cancellation state. Scheduling preserves pinned-versus-latest publication selection.
+
+Outside development, `/nodes` requires the Nodes feature flag plus the node-flow backend and automation-security prerequisites. Definition-specific execution still requires the applicable provider, credential, egress, approval/outbox, webhook, or custom-node service and security policy. Registry presence alone is not a production-readiness claim.
diff --git a/docs-web/content/docs/architecture-node-flow-foundation.mdx b/docs-web/content/docs/architecture-node-flow-foundation.mdx
index acd3237449..b18fd8f0cd 100644
--- a/docs-web/content/docs/architecture-node-flow-foundation.mdx
+++ b/docs-web/content/docs/architecture-node-flow-foundation.mdx
@@ -1,7 +1,35 @@
 # Node Flow Foundation
 
-Code UX uses one canonical Graph v2 contract across backend, MCP, runtime, and dashboard. Graphs carry `schemaVersion: 2`, versioned definitions, typed ports, credential-id bindings, bounded policies, capabilities, side effects, disabled state, flow schemas, and optional immutable publication metadata.
+Code UX uses one project-owned Graph v2 contract across the dashboard, backend, MCP surface, scheduler, and runtime. Graphs carry `schemaVersion: 2`, stable versioned definition references, typed ports and flow schemas, credential-id bindings, bounded policies, capabilities, side effects, disabled state, and optional immutable publication metadata.
 
-Validation resolves definitions, checks configuration, ports, policies, graph limits, and cycles, and rejects plaintext secrets and custom source. Only `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output` are executable.
+## Registry and executable handlers
 
-Persisted Graph v1 records retain their original immutable version and append deterministic Graph v2. Browser migration retains its original snapshot outside executable graph JSON.
+The definition registry is the authority for the palette and runtime. Manifests provide configuration/UI schemas, ports, credential slots, capabilities, side effects, default policy, documentation, deprecation, executable state, and execution kind.
+
+The governed built-ins with registered handlers are:
+
+| Area | Definitions |
+| --- | --- |
+| Data, provider, and HTTP | `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, `output` |
+| Control and transformation | `condition`, `switch`, `foreach`, `merge`, `delay`, `execute_subflow` |
+| Governed effects and triggers | `approval`, `email_draft`, `email_send`, `webhook_trigger` |
+
+A validated custom definition becomes executable only after its immutable artifact and versioned manifest are registered and the custom-node runtime is configured. Unknown types, legacy browser-only `trigger`/`agent`/`task` kinds, mockups, and definitions marked non-executable are planned or unavailable definitions, not handlers.
+
+## Validation, policy, and secrets
+
+Validation resolves each definition and checks configuration, port handles and schemas, policies, graph bounds, and cycles. It rejects plaintext secret-shaped fields and generated or custom source in graph JSON. The dashboard receives credential binding ids and metadata-only states; resolved values remain behind the credential broker. Credential values and secret-shaped payloads are redacted before invocation messages, attempts, diagnostics, route responses, and debugger output are persisted or rendered.
+
+Draft review reports requested capabilities, side effects, credential status, policy findings, and a non-executing dry run. Publication requires the current `draftRevision`, a valid graph and policy review, and every required credential binding. Runs select an immutable pinned or latest-published snapshot.
+
+## Project workspace and migration
+
+`/nodes` loads the selected project's backend flow library and does not request flow data without a selected project. Revision-checked saves return a conflict rather than replacing a newer draft.
+
+The former `codeux:nodes-canvas:v1` value can be imported once into a project draft. Successful import records a project-specific marker and removes the legacy graph value; local storage is not ongoing persistence. Persisted Graph v1 records retain their exact immutable version and append deterministic Graph v2.
+
+## Operations and prerequisites
+
+The run debugger reads redacted flow runs, node runs, numbered attempts, approvals, retry decisions, invocation links, timing, and cancellation state. Scheduling preserves pinned-versus-latest publication selection.
+
+Outside development, `/nodes` requires the Nodes feature flag plus the node-flow backend and automation-security prerequisites. Definition-specific execution still requires the applicable provider, credential, egress, approval/outbox, webhook, or custom-node service and security policy. Registry presence alone is not a production-readiness claim.
diff --git a/docs-web/content/docs/registry.ts b/docs-web/content/docs/registry.ts
index 6bf849a8b0..29351c228c 100644
--- a/docs-web/content/docs/registry.ts
+++ b/docs-web/content/docs/registry.ts
@@ -267,7 +267,7 @@ export const docsRegistry: Record<DocsSlug, DocsRegistryEntry> = {
     path: '/docs/user-dashboard-nodes-canvas',
     section: 'User Guide',
     title: "Nodes Canvas",
-    description: "The Nodes Canvas page (/nodes) is a browser-local workspace for drafting Code UX workflow graphs. It combines the canvas, palette, inspector, validation panel, JSON exchange controls, and agent command summary without...",
+    description: "The Nodes page (/nodes) is a project-scoped Graph v2 workspace backed by the Code UX node-flow APIs. Select a project to load its flow library, credential metadata, publications, and run history. Changing projects cle...",
   },
   'user-dashboard-node-flows': {
     id: 'user-dashboard-node-flows',
@@ -911,7 +911,7 @@ export const docsRegistry: Record<DocsSlug, DocsRegistryEntry> = {
     path: '/docs/architecture-node-flow-foundation',
     section: 'Architecture',
     title: "Node Flow Foundation",
-    description: "Code UX uses one canonical Graph v2 contract across backend, MCP, runtime, and dashboard. Graphs carry schemaVersion: 2, versioned definitions, typed ports, credential-id bindings, bounded policies, capabilities, side...",
+    description: "Code UX uses one project-owned Graph v2 contract across the dashboard, backend, MCP surface, scheduler, and runtime. Graphs carry schemaVersion: 2, stable versioned definition references, typed ports and flow schemas,...",
   },
   'architecture-node-flows': {
     id: 'architecture-node-flows',
diff --git a/docs-web/content/docs/user-dashboard-nodes-canvas.mdx b/docs-web/content/docs/user-dashboard-nodes-canvas.mdx
index 2c7a5bc4b7..b8325b4b49 100644
--- a/docs-web/content/docs/user-dashboard-nodes-canvas.mdx
+++ b/docs-web/content/docs/user-dashboard-nodes-canvas.mdx
@@ -1,47 +1,37 @@
 # Nodes Canvas
 
-The **Nodes Canvas** page (`/nodes`) is a browser-local workspace for drafting Code UX workflow graphs. It combines the canvas, palette, inspector, validation panel, JSON exchange controls, and agent command summary without calling backend APIs or writing to the database.
+The **Nodes** page (`/nodes`) is a project-scoped Graph v2 workspace backed by the Code UX node-flow APIs. Select a project to load its flow library, credential metadata, publications, and run history. Changing projects clears the current view before loading the newly selected project's records; without a selected project, the page does not request node-flow data.
 
-This page does not synchronize graphs to projects, execute n8n workflows, or run node flows through the Code UX runtime.
+## Backend drafts and conflicts
 
-## Local persistence
+New flows and saved edits are persisted in the selected project's backend flow library. Each save includes the `draftRevision` that was loaded. If another editor has advanced that revision, Code UX reports a conflict instead of overwriting the newer draft; reload the flow and reapply the intended edit.
 
-The page saves the current graph to browser `localStorage` under `codeux:nodes-canvas:v1`. Reloading `/nodes` restores that graph when it can be parsed through the canvas contract. Malformed persisted data falls back to the starter graph.
+The former browser canvas is handled only as a one-time compatibility import. If `codeux:nodes-canvas:v1` exists when a project first loads, Code UX converts it to Graph v2 and creates an **Imported Nodes Canvas** draft. A successful import records a project-specific marker and removes the old graph value. A failed import leaves it available for retry. Local storage is not the workflow source of truth after this bridge.
 
-The inspector's enabled switch is an editing-session flag only and is not persisted in the graph JSON.
+## Registry-driven editing
 
-## Node types
+The backend definition registry drives the palette and inspector. Each versioned manifest declares whether it is executable, its typed input/output ports, configuration and widget schemas, credential slots, capabilities, side-effect class, default retry/timeout policy, documentation, and deprecation state. Graphs store versioned definition references, non-secret configuration, policies, and credential ids—not custom source or resolved credentials.
 
-| Type | Purpose |
-| --- | --- |
-| `trigger` | Starts the graph from a manual or scheduled event source. |
-| `agent` | Routes downstream work to a planning, implementation, review, or QA agent intent. |
-| `task` | Captures a concrete task prompt and task intent. |
-| `condition` | Branches based on an expression such as a validation result. |
-| `output` | Collects the final graph result. |
-
-## Validation behavior
-
-Validation runs locally after each graph change. It checks duplicate node ids, missing edge nodes or ports, self-connections, input/output direction mismatches, incompatible port types, empty required values, and invalid agent or task intent metadata.
+The governed built-ins with runtime handlers are:
 
-The status strip reports the issue count. The validation panel groups issues by node or edge and provides select/focus actions. Valid JSON imports can still contain validation issues so users can repair them on the canvas.
-
-## Import and export format
-
-`Export JSON` writes the deterministic graph JSON into the exchange textarea. The JSON contains `nodes`, `edges`, and `selection`.
+| Area | Executable definitions |
+| --- | --- |
+| Data, AI, and HTTP | `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, `output` |
+| Control and transformation | `condition`, `switch`, `foreach`, `merge`, `delay`, `execute_subflow` |
+| Governed effects and triggers | `approval`, `email_draft`, `email_send`, `webhook_trigger` |
 
-`Import JSON` applies the textarea content through the agent `replace_graph` command helper. Invalid JSON leaves the current graph unchanged and reports a live error. Valid JSON is normalized, loaded into the canvas, saved locally, and revalidated.
+Validated custom definitions can also execute after their immutable artifact and versioned manifest are registered and the custom-node runtime is available. Legacy `trigger`, `agent`, and `task` canvas kinds, unknown types, mockup entries, and definitions marked non-executable are planning or unavailable definitions, not executable handlers.
 
-## Agent command surface
+## Credentials, review, and publication
 
-Agents should use the node canvas agent helper contract rather than driving the UI. Supported commands are `add_node`, `patch_node`, `connect_ports`, `delete_entities`, `select_entities`, and `replace_graph`.
+Credential slots display metadata-only status such as bound, missing, or denied and can submit a binding request. Secret values remain behind the credential broker and are not returned to the graph or browser.
 
-The page displays a deterministic graph summary for command workflows, including node and edge counts, selected ids, ports, config values, and validation blockers.
+Validation and dry run report graph issues, requested capabilities, credential requirements, side-effect differences, and policy findings. Dry run does not execute nodes. Publication requires the current draft revision, a valid graph and policy review, and all required credentials bound. Published snapshots are immutable; the workspace can compare versions or restore a prior version into a new draft revision.
 
-## Empty and reset states
+## Runs and schedules
 
-`Clear` empties the canvas while keeping the palette available. `Reset` restores the starter trigger -> agent -> task -> condition -> output graph. The layout collapses to a single column at smaller widths so controls remain reachable without overlapping.
+Only published versions run. The debugger shows redacted run output, flow and node status, numbered attempts, retry classifications and decisions, approvals, invocation links, timing, cancellation, and safe retry controls. Approval decisions continue or terminate the same pinned durable run rather than starting an unrelated run.
 
-## Graph v2 migration
+Use the [Scheduler](/docs/user-dashboard-scheduler) to schedule a pinned or latest-published flow version. Provider, HTTP, approval-gated email, webhook, and custom-node execution each require their corresponding configured runtime and security services.
 
-Serialization writes `schemaVersion: 2`. Legacy browser v1 values migrate deterministically with their untouched snapshot retained separately. Trigger, agent, task, condition, and output are planning concepts; executable definitions are limited to `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output`.
+Outside development builds, the workspace is available only when the Nodes feature flag, node-flow backend prerequisite, and automation-security prerequisite are enabled. These gates expose the feature; they do not assert that every external integration is configured for production.
diff --git a/docs-web/user/dashboard/nodes-canvas.md b/docs-web/user/dashboard/nodes-canvas.md
index 2c7a5bc4b7..d6425dbf6a 100644
--- a/docs-web/user/dashboard/nodes-canvas.md
+++ b/docs-web/user/dashboard/nodes-canvas.md
@@ -1,47 +1,37 @@
 # Nodes Canvas
 
-The **Nodes Canvas** page (`/nodes`) is a browser-local workspace for drafting Code UX workflow graphs. It combines the canvas, palette, inspector, validation panel, JSON exchange controls, and agent command summary without calling backend APIs or writing to the database.
+The **Nodes** page (`/nodes`) is a project-scoped Graph v2 workspace backed by the Code UX node-flow APIs. Select a project to load its flow library, credential metadata, publications, and run history. Changing projects clears the current view before loading the newly selected project's records; without a selected project, the page does not request node-flow data.
 
-This page does not synchronize graphs to projects, execute n8n workflows, or run node flows through the Code UX runtime.
+## Backend drafts and conflicts
 
-## Local persistence
+New flows and saved edits are persisted in the selected project's backend flow library. Each save includes the `draftRevision` that was loaded. If another editor has advanced that revision, Code UX reports a conflict instead of overwriting the newer draft; reload the flow and reapply the intended edit.
 
-The page saves the current graph to browser `localStorage` under `codeux:nodes-canvas:v1`. Reloading `/nodes` restores that graph when it can be parsed through the canvas contract. Malformed persisted data falls back to the starter graph.
+The former browser canvas is handled only as a one-time compatibility import. If `codeux:nodes-canvas:v1` exists when a project first loads, Code UX converts it to Graph v2 and creates an **Imported Nodes Canvas** draft. A successful import records a project-specific marker and removes the old graph value. A failed import leaves it available for retry. Local storage is not the workflow source of truth after this bridge.
 
-The inspector's enabled switch is an editing-session flag only and is not persisted in the graph JSON.
+## Registry-driven editing
 
-## Node types
+The backend definition registry drives the palette and inspector. Each versioned manifest declares whether it is executable, its typed input/output ports, configuration and widget schemas, credential slots, capabilities, side-effect class, default retry/timeout policy, documentation, and deprecation state. Graphs store versioned definition references, non-secret configuration, policies, and credential ids—not custom source or resolved credentials.
 
-| Type | Purpose |
-| --- | --- |
-| `trigger` | Starts the graph from a manual or scheduled event source. |
-| `agent` | Routes downstream work to a planning, implementation, review, or QA agent intent. |
-| `task` | Captures a concrete task prompt and task intent. |
-| `condition` | Branches based on an expression such as a validation result. |
-| `output` | Collects the final graph result. |
-
-## Validation behavior
-
-Validation runs locally after each graph change. It checks duplicate node ids, missing edge nodes or ports, self-connections, input/output direction mismatches, incompatible port types, empty required values, and invalid agent or task intent metadata.
+The governed built-ins with runtime handlers are:
 
-The status strip reports the issue count. The validation panel groups issues by node or edge and provides select/focus actions. Valid JSON imports can still contain validation issues so users can repair them on the canvas.
-
-## Import and export format
-
-`Export JSON` writes the deterministic graph JSON into the exchange textarea. The JSON contains `nodes`, `edges`, and `selection`.
+| Area | Executable definitions |
+| --- | --- |
+| Data, AI, and HTTP | `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, `output` |
+| Control and transformation | `condition`, `switch`, `foreach`, `merge`, `delay`, `execute_subflow` |
+| Governed effects and triggers | `approval`, `email_draft`, `email_send`, `webhook_trigger` |
 
-`Import JSON` applies the textarea content through the agent `replace_graph` command helper. Invalid JSON leaves the current graph unchanged and reports a live error. Valid JSON is normalized, loaded into the canvas, saved locally, and revalidated.
+Validated custom definitions can also execute after their immutable artifact and versioned manifest are registered and the custom-node runtime is available. Legacy `trigger`, `agent`, and `task` canvas kinds, unknown types, mockup entries, and definitions marked non-executable are planning or unavailable definitions, not executable handlers.
 
-## Agent command surface
+## Credentials, review, and publication
 
-Agents should use the node canvas agent helper contract rather than driving the UI. Supported commands are `add_node`, `patch_node`, `connect_ports`, `delete_entities`, `select_entities`, and `replace_graph`.
+Credential slots display metadata-only status such as bound, missing, or denied and can submit a binding request. Secret values remain behind the credential broker and are not returned to the graph or browser.
 
-The page displays a deterministic graph summary for command workflows, including node and edge counts, selected ids, ports, config values, and validation blockers.
+Validation and dry run report graph issues, requested capabilities, credential requirements, side-effect differences, and policy findings. Dry run does not execute nodes. Publication requires the current draft revision, a valid graph and policy review, and all required credentials bound. Published snapshots are immutable; the workspace can compare versions or restore a prior version into a new draft revision.
 
-## Empty and reset states
+## Runs and schedules
 
-`Clear` empties the canvas while keeping the palette available. `Reset` restores the starter trigger -> agent -> task -> condition -> output graph. The layout collapses to a single column at smaller widths so controls remain reachable without overlapping.
+Only published versions run. The debugger shows redacted run output, flow and node status, numbered attempts, retry classifications and decisions, approvals, invocation links, timing, cancellation, and safe retry controls. Approval decisions continue or terminate the same pinned durable run rather than starting an unrelated run.
 
-## Graph v2 migration
+Use the [Scheduler](./scheduler.md) to schedule a pinned or latest-published flow version. Provider, HTTP, approval-gated email, webhook, and custom-node execution each require their corresponding configured runtime and security services.
 
-Serialization writes `schemaVersion: 2`. Legacy browser v1 values migrate deterministically with their untouched snapshot retained separately. Trigger, agent, task, condition, and output are planning concepts; executable definitions are limited to `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output`.
+Outside development builds, the workspace is available only when the Nodes feature flag, node-flow backend prerequisite, and automation-security prerequisite are enabled. These gates expose the feature; they do not assert that every external integration is configured for production.
diff --git a/docs/architecture/node-flow-foundation.md b/docs/architecture/node-flow-foundation.md
index 7a854f6f65..0160fc5227 100644
--- a/docs/architecture/node-flow-foundation.md
+++ b/docs/architecture/node-flow-foundation.md
@@ -33,15 +33,24 @@ Invalid graphs throw a `ValidationError` with field-level details when persisten
 
 `src/services/node-flow-runtime-service.ts` executes the current flow version after revalidating the graph. It creates a parent `execution_invocations` row with `type = "node_flow"`, then runs nodes in the validator's topological order.
 
-Supported node types:
+The registry-backed runtime supports:
 
 - `input`: emits the run input object.
 - `set_fields`: merges upstream object output with configured fields, including template interpolation.
 - `template`: renders a string template into a configured output key.
 - `provider_prompt`: calls the existing `ProviderExecutionService` with `type = "node_flow_node"` and an existing invocation id. It does not create a parallel provider runner.
 - `http_request`: performs bounded HTTP/HTTPS requests with method, URL, headers, query, body, timeout, and JSON response extraction.
+- `condition` and `switch`: select an explicit output branch and persist unselected descendants as skipped.
+- `foreach` and `merge`: emit a bounded list or combine active upstream values with an explicit strategy.
+- `delay`: waits for a bounded cancellable duration.
+- `approval`: persists an operator decision gate and resumes the pinned run after a decision.
+- `email_draft` and `email_send`: build a draft, or send only after approval through the idempotent outbox.
+- `execute_subflow`: executes a same-project published flow with recursion bounds.
+- `webhook_trigger`: emits input received through secret-authenticated webhook ingress.
 - `output`: selects the final output from upstream data, configured fields, or a configured path.
 
+Versioned custom definitions can execute through the custom-node runtime after validation and registration. Definitions without a registered executable handler fail validation and cannot be published.
+
 Provider and HTTP nodes create linked child `execution_invocations` rows with `type = "node_flow_node"`. Prompt text and HTTP secrets are not written to invocation messages; persisted run inputs, outputs, node payloads, trigger payloads, and route responses are masked for secret-like keys.
 
 Failed nodes stop downstream descendants by default and persist skipped node runs. A node can set `data.continueOnError = true` to persist its own failure output while allowing downstream nodes to continue.
@@ -55,6 +64,10 @@ SQLite tables are created in both the initial schema and startup migrations:
 - `node_flow_agent_skills`
 - `node_flow_runs`
 - `node_flow_node_runs`
+- `node_flow_node_attempts`
+- `node_flow_publications`
+
+Approval, webhook, and external-effect state use the related automation approval, trigger, and outbox repositories. Publication snapshots and attempt records preserve the immutable graph/policy selection and retry history used for debugging and recovery.
 
 Graphs, widget schemas, run inputs, run outputs, and trigger payloads are stored as JSON text. Run and node-run rows store linked execution invocation ids where applicable. Flow create/update/delete and agent-skill attachment changes schedule a project structure refresh so realtime dashboard clients can refetch project-scoped data.
 
@@ -62,6 +75,16 @@ Graphs, widget schemas, run inputs, run outputs, and trigger payloads are stored
 
 Dashboard routes are registered through `registerNodeFlowRoutes`:
 
+- `GET /api/node-flow-catalog` and `GET /api/node-flow-catalog/:nodeType`
+- `POST /api/projects/:projectId/node-flow-drafts`
+- `PATCH /api/node-flow-drafts/:flowId`
+- `POST /api/node-flow-drafts/:flowId/validate`
+- `POST /api/node-flow-drafts/:flowId/dry-run`
+- `GET /api/node-flow-drafts/:flowId/bindings`
+- `POST /api/node-flow-drafts/:flowId/credential-requests`
+- `POST /api/node-flow-drafts/:flowId/publish`
+- `GET /api/node-flows/:flowId/compare`
+- `POST /api/node-flows/:flowId/rollback`
 - `GET /api/projects/:projectId/node-flows`
 - `POST /api/projects/:projectId/node-flows`
 - `GET /api/node-flows/:flowId`
@@ -75,6 +98,8 @@ Dashboard routes are registered through `registerNodeFlowRoutes`:
 - `GET /api/node-flows/:flowId/runs`
 - `GET /api/node-flow-runs/:runId`
 - `GET /api/node-flow-runs/:runId/node-runs`
+- `GET /api/node-flow-runs/:runId/attempts`
+- cancellation, retry, approval, and webhook routes described in the durable-execution and built-in security pages
 
 Handlers stay thin and delegate behavior to `NodeFlowService`.
 
@@ -82,6 +107,24 @@ Handlers stay thin and delegate behavior to `NodeFlowService`.
 
 Normalized graphs carry `schemaVersion: 2`. Nodes reference a stable definition type and version and carry typed ports, credential-id bindings, bounded retry/timeout policies, capabilities, side-effect classification, and disabled state. Graphs may declare typed input/output schemas and immutable publication metadata.
 
-The typed registry includes configuration and UI schemas, ports, credential slots, capabilities, side effects, default policies, documentation, deprecation, and execution kind. Only `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output` are executable. Other palette ideas are planned concepts without runtime handlers.
+The typed registry includes configuration and UI schemas, ports, credential slots, capabilities, side effects, default policies, documentation, deprecation, executable state, and execution kind. The palette and inspector consume these manifests, so ports and configuration controls are not maintained as a separate hard-coded node list.
+
+The governed built-ins with registered runtime handlers are:
+
+- data and provider operations: `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output`
+- control and transformation: `condition`, `switch`, `foreach`, `merge`, `delay`, and `execute_subflow`
+- governed effects and triggers: `approval`, `email_draft`, `email_send`, and `webhook_trigger`
+
+Validated custom definitions become executable only after their versioned manifest and immutable artifact are registered and the custom-node runtime is configured. Unknown types, legacy browser-only `trigger`/`agent`/`task` kinds, design mockups, and manifests marked non-executable are planned or unavailable definitions, not runtime handlers.
 
 Validation resolves definitions and checks configuration, handles, policies, graph limits, and cycles with field-level issues. Graph JSON rejects secret-shaped fields and generated/custom source fields. Persisted Graph v1 rows keep their original immutable snapshot and append deterministic Graph v2 as a new current version.
+
+## Dashboard workspace and governance
+
+`/nodes` requires a selected project and loads that project's flow library from the backend. Draft writes carry `draftRevision`; a stale revision returns a conflict rather than replacing newer work. The former `codeux:nodes-canvas:v1` browser value is eligible for one project-specific import into a backend draft. Successful import records a marker and removes the graph value; local storage is not an ongoing workflow store.
+
+Draft review combines structural validation, capability and side-effect policy findings, credential-slot status, and a non-executing dry run. The dashboard receives credential ids and status metadata only, never resolved secret values. Publication requires the current revision, a valid policy review, and all credential requirements bound. Runs resolve immutable pinned or latest-published snapshots.
+
+The run debugger reads persisted runs, node runs, numbered attempts, approvals, retry decisions, invocation links, timing, and cancellation state. Responses and persisted payloads are redacted before display. Scheduling delegates to the scheduler and retains pinned-versus-latest publication semantics.
+
+Outside development, the dashboard route requires `VITE_CODEUX_FEATURE_NODES`, `VITE_CODEUX_NODE_FLOW_BACKEND`, and `VITE_CODEUX_AUTOMATION_SECURITY` to resolve enabled. Runtime availability remains dependency-specific: providers, credential resolution, egress policy, approval/outbox, webhook configuration, and the custom-node runtime must be configured for definitions that use them.
diff --git a/docs/architecture/node-flows.md b/docs/architecture/node-flows.md
index 6593dfb9c0..0dd621f925 100644
--- a/docs/architecture/node-flows.md
+++ b/docs/architecture/node-flows.md
@@ -35,9 +35,11 @@ A `NodeFlowGraph` contains:
 
 Validation is owned by `src/domain/node-flows/node-flow-validation.ts`. It normalizes ids, labels, positions, widget defaults, and graph shape; rejects missing node/edge arrays; rejects duplicate node ids; rejects edges that point at missing nodes; requires at least one node; and rejects cycles. Widget validation supports `text`, `textarea`, `number`, `boolean`, `select`, `json`, `secretRef`, and `keyValue` fields.
 
-Validation intentionally permits arbitrary string node types at graph-save time so future node libraries can be drafted and stored. Runtime execution separately enforces the executable allowlist.
+Validation requires every node's type/version reference to resolve through the registry and rejects unknown definitions. Runtime execution then dispatches according to the registered definition's executable state and execution kind; a planning concept is not runnable merely because it has a string type.
 
-Dashboard-only editable canvas state lives in `dashboard/src/v2/lib/nodes-canvas-state.ts`. It is a pure TypeScript layer for in-progress graph editing: typed node kinds, input/output ports, port-based edges, config fields, selection state, reducer actions, deterministic layout helpers, validation issue codes, stable JSON serialization, and recovery from malformed persisted canvas drafts. The seed graph uses trigger, agent, task, condition, and output nodes so UI tasks can start from a meaningful workflow without depending on a rendering library.
+The dashboard uses the same backend-owned Graph v2 record as the runtime. The selected project controls library loading; no project means no flow, credential, publication, or run requests. The versioned registry drives palette entries, typed ports, configuration widgets, credential slots, capabilities, side-effect review, and policies. Draft saves use optimistic `draftRevision` checks and surface conflicts without overwriting the newer record.
+
+`dashboard/src/v2/lib/nodes-canvas-state.ts` remains only a compatibility and pure graph-state layer. Its legacy browser graph can be imported once into a project draft, after which the old graph key is removed and a project marker prevents duplicates. It is not the workflow source of truth.
 
 ## Runtime
 
@@ -104,7 +106,7 @@ Specialist agents designing node flows should adapt workflows to Code UX instead
 Use these rules:
 
 - Model the repeatable outcome first, then choose the smallest Code UX graph that captures the inputs, provider calls, HTTP calls, transformations, and final output.
-- Prefer `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output` nodes only when the workflow needs to execute today. Other node types may be saved for future design drafts, but they will fail at runtime until implemented.
+- Use the governed executable built-ins listed in the runtime table when the workflow needs to execute today. A registered custom definition is executable only when its validated immutable artifact and custom runtime are available. Treat unknown types, legacy browser-only kinds, and non-executable manifests as planned or unavailable definitions.
 - Put operator-editable values in `inputSchema` or per-node `widgetSchema` fields. Do not bury frequently changed values in opaque JSON blobs.
 - Use `secretRef` widgets and secret reference strings for credentials. Do not place raw API keys, bearer tokens, cookies, passwords, or private headers in graph metadata, node data, widget defaults, run input, or examples.
 - Validate every node field before saving: required prompt/template/url fields, finite numeric limits, supported HTTP method, JSON object input, and select defaults that match options.
@@ -118,3 +120,9 @@ Graph v2 is the single workflow model used by backend, MCP, runtime, and dashboa
 The executable registry contains the original deterministic/provider/HTTP nodes plus `condition`, `switch`, `foreach`, `merge`, `delay`, `approval`, `email_draft`, `email_send`, `execute_subflow`, and `webhook_trigger`. Unregistered custom types remain non-executable.
 
 Backend Graph v1 migration retains the exact prior version and appends deterministic v2. Browser canvas v1 migration returns the untouched legacy snapshot separately from the normalized graph.
+
+## Dashboard and security prerequisites
+
+Outside development builds, the Nodes workspace is enabled only when `VITE_CODEUX_FEATURE_NODES`, `VITE_CODEUX_NODE_FLOW_BACKEND`, and `VITE_CODEUX_AUTOMATION_SECURITY` are true. These flags expose the surface; they do not replace runtime dependencies. Provider execution, credential resolution, outbound HTTP, approval-gated email, webhook ingress, and custom-node containers each require their corresponding configured service and security policy.
+
+The dashboard exposes credential binding ids, declared kinds, scopes, and status metadata only. Resolved values stay at the credential broker/runtime boundary and are redacted before invocation messages, attempt payloads, diagnostics, and route responses are persisted or rendered. Policy review must surface requested capabilities and external side effects before publication, and publication requires a valid current draft with all required bindings satisfied.
diff --git a/docs/dashboard/node-flows.md b/docs/dashboard/node-flows.md
index a80ed9c383..80c54871a6 100644
--- a/docs/dashboard/node-flows.md
+++ b/docs/dashboard/node-flows.md
@@ -10,10 +10,12 @@ The former browser canvas is eligible for one project-specific import. After a s
 
 ## Registry and credentials
 
-`GET /api/node-flow-catalog` is the T01 source for palette entries, typed ports, widget schemas, execution availability, capabilities, side effects, policies, and credential requirements. Selecting a definition loads its full versioned manifest. Graphs reference a definition version and do not contain custom-node source.
+`GET /api/node-flow-catalog` is the registry source for palette entries, typed ports, configuration and widget schemas, execution availability, capabilities, side effects, policies, and credential requirements. Selecting a definition loads its full versioned manifest. Graphs reference a definition version and do not contain custom-node source.
 
 The inspector displays credential slots as bound, missing, or denied and can request a binding. It displays credential metadata only; secret values never enter the graph or dashboard output.
 
+The registered governed built-ins are `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, `condition`, `switch`, `foreach`, `merge`, `delay`, `approval`, `email_draft`, `email_send`, `execute_subflow`, `webhook_trigger`, and `output`. Registered, validated custom definitions can execute when their immutable artifact and runtime are available. Legacy canvas kinds, unregistered names, and definitions marked non-executable remain planning or unavailable definitions and cannot run.
+
 ## Governance and publication
 
 T06 draft endpoints provide structural validation, policy findings, requested permissions, side-effect review, dry runs, immutable publication, version comparison, and rollback. Dry runs never execute nodes. Only a valid draft with satisfied required credentials can publish, and only published versions execute.
@@ -23,3 +25,5 @@ T06 draft endpoints provide structural validation, policy findings, requested pe
 The debugger reads persisted runs, node runs, attempt history, and approval decisions. Pending approvals expose keyboard-accessible **Approve & continue** and **Reject** actions. A decision continues or terminates the same pinned run, and repeated clicks return its current durable state without duplicating the governed attempt or external send. The debugger also overlays node state, shows retry reasons and decisions, links invocation ids, reports timing, supports cancellation and safe retry, and redacts secret-shaped values before rendering. Scheduling is entered through `/scheduler`; scheduler execution also resolves published versions.
 
 The layout stacks on small screens, preserves keyboard-visible focus, labels loading/error/empty states, and bounds long histories and JSON output with scrolling.
+
+Outside development, `/nodes` requires the Nodes feature flag plus the node-flow backend and automation-security prerequisites. Individual definitions can require additional provider, credential-broker, egress, approval/outbox, webhook, or custom-runtime configuration; catalog presence alone does not assert production readiness for an integration.
diff --git a/docs/dashboard/nodes-canvas.md b/docs/dashboard/nodes-canvas.md
index 6d906e6db2..8b1fb81a55 100644
--- a/docs/dashboard/nodes-canvas.md
+++ b/docs/dashboard/nodes-canvas.md
@@ -1,17 +1,29 @@
 # Nodes Automation Workspace
 
-The **Nodes** page (`/nodes`) is a project-scoped automation workspace backed by the canonical node-flow repository. Browser storage is not a workflow database and edits are never auto-saved locally.
+The **Nodes** page (`/nodes`) is a project-scoped Graph v2 authoring and operations workspace backed by the canonical node-flow repository. Select a project before using it: the page does not request a flow library, credential metadata, publications, or run history without an active project. Browser storage is not a workflow database and edits are never auto-saved locally.
+
+The selected project's library is loaded from the backend. Creating and saving drafts writes to that project, and changing projects clears the current workspace before loading the next library. Saves include `draftRevision`; if another editor has advanced the draft, the backend returns a conflict and the page asks the operator to reload and reapply the change instead of overwriting it.
 
 ## Legacy canvas import
 
-On the first load for a selected project, the dashboard checks the former `codeux:nodes-canvas:v1` key. When present, it normalizes the payload to Graph v2, creates an **Imported Nodes Canvas** backend draft, records a project-specific migration marker, and removes the legacy graph value. A failed import leaves the value available for retry. The marker prevents duplicates.
+On the first load for a selected project, the dashboard checks the former `codeux:nodes-canvas:v1` key. When present, it normalizes the payload to Graph v2, creates an **Imported Nodes Canvas** backend draft, records a project-specific migration marker, and removes the legacy graph value. A failed import leaves the value available for retry. The marker prevents duplicates. After this one-time bridge, local storage is not read or written as the workflow source of truth.
 
 ## Governed editing
 
-The T01 registry supplies executable state, typed ports, widget schemas, capabilities, credential slots, side-effect classification, and default policy. The graph stores only a type/version reference and configuration; it never stores custom source or credential values.
+The versioned definition registry supplies the palette, executable state, typed ports, configuration and widget schemas, capabilities, credential slots, side-effect classification, and default retry/timeout policy. The inspector is rendered from the selected definition rather than a hard-coded node form. The graph stores a type/version reference, non-secret configuration, and credential ids; it never stores custom source or credential values.
+
+Credential slots show metadata-only states such as bound, missing, or denied and can submit a binding request. Secret material stays behind the credential broker and is excluded from graphs, browser output, logs, and examples.
+
+Validation and dry run report structural issues, requested capabilities, credential requirements, side-effect differences, and policy findings. Dry run is review-only and does not execute nodes. Publication requires the current draft revision, a valid graph with no error-level policy findings, and all declared credential requirements bound. Publications are immutable; comparison and rollback operate on versioned snapshots.
 
-Draft saves use `draftRevision`. A concurrent update returns a visible conflict. Validation, policy findings, credential status, dry runs, publication, version comparison, and rollback use the T06 draft APIs.
+## Executable definitions
+
+The governed built-ins currently registered with runtime handlers are `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, `condition`, `switch`, `foreach`, `merge`, `delay`, `approval`, `email_draft`, `email_send`, `execute_subflow`, `webhook_trigger`, and `output`.
+
+Validated custom definitions may also execute after their versioned manifest and immutable artifact are registered and the custom-node runtime is configured. A palette mockup, legacy `trigger`/`agent`/`task` canvas kind, unknown type, or definition marked non-executable is a planning or unavailable definition, not an executable handler.
 
 ## Operations
 
-Only published versions run. The debugger shows redacted run output, graph and node states, attempts, retry classifications and decisions, invocation links, timing, cancellation, and safe retry controls. Scheduling is entered through the Scheduler page.
+Only published versions run. The debugger shows redacted run output, graph and node states, attempts, retry classifications and decisions, approval state, invocation links, timing, cancellation, and safe retry controls. Approval decisions resume or terminate the same pinned durable run. Scheduling is entered through the Scheduler page and targets a pinned or latest-published version.
+
+Outside development builds, the workspace is exposed only when the Nodes feature flag and both node-flow backend and automation-security prerequisites are enabled. Execution also depends on the services required by a definition: for example, a configured provider for `provider_prompt`, allowed egress for `http_request`, approval and outbox services for governed email sending, webhook configuration for webhook ingress, and the custom-node runtime for registered custom definitions. Availability is not a claim that every integration is configured for production.

From b3abdf1107a4a6680dac986e26c0708c7ce6d49b Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 08:26:28 +0000
Subject: [PATCH 16/25] feat(task T14): implement via codex

---
 docs-web/content/docs/operations-runbook.mdx  |  16 +-
 docs-web/operations/runbook.md                |  16 +-
 docs/operations/runbook.md                    |  16 +-
 src/services/node-flow-runtime-service.ts     |  31 +-
 .../credentialed-automation-e2e.test.ts       | 471 +++++++++---------
 5 files changed, 289 insertions(+), 261 deletions(-)

diff --git a/docs-web/content/docs/operations-runbook.mdx b/docs-web/content/docs/operations-runbook.mdx
index 5fac8c0917..cc61f005e3 100644
--- a/docs-web/content/docs/operations-runbook.mdx
+++ b/docs-web/content/docs/operations-runbook.mdx
@@ -2,19 +2,19 @@
 
 Run recovery drills only against the approved local test project and mocked job/email providers.
 
-Run the complete offline drill with one command. It uses a temporary SQLite database, the checked-in 20-record fixture, authenticated in-process HTTP routes, and mocked custom-node/job/email boundaries. It does not dispatch a sprint, invoke a live provider, start Docker, or require network access.
+Run the complete offline drill with one command. It uses a temporary file-backed SQLite database, the checked-in 20-record fixture, an authenticated MCP authoring context, authenticated in-process HTTP routes, and mocked job, email, and Docker command boundaries. Generated custom-node code is validated and executed only through the custom-node container service; the test never evaluates it in the Code UX process or starts Docker.
 
 ```bash
 pnpm run test:e2e:credentialed-automation
 ```
 
-1. Verify a viewer can read its project and receives `403` for another project; correlate both requests in audit export.
-2. Stop the key provider with encrypted rows present. `/health` stays live, `/ready` returns `503`, and a new process refuses startup.
-3. Process the 20-record fixture, approve selected drafts, and restart after outbox enqueue. Sent idempotency keys must not invoke the provider twice; unknown outcomes require attention.
-4. Rotate the external credential and confirm the binding resolves its next version; revoke it and confirm access is denied without secret canaries in exports, logs, prompts, traces, or diagnostics.
-5. Publish a later automation, then draft/publish the earlier immutable version. Existing runs remain pinned and new runs select the rollback publication.
-6. Restore SQLite/WAL plus key versions in isolation. Keep runners disabled until readiness, audit continuity, lease ownership, approvals, and outbox counts match the backup manifest.
+1. Use `manage_node_flows` with authenticated agent/conversation metadata to generate and validate the custom node and to create, patch, validate, and publish the flow. Supply credentials only through the credential broker.
+2. Start pinned version 2 through `NodeFlowRuntimeService.runFlow`, interrupt an active pre-invocation node, reopen the same SQLite database, recover, and call `resumeRun`. The run id, publication id, node run, and attempt must remain unchanged.
+3. Process exactly 20 mocked job records through the custom-node runtime, approve the five selected messages in sequence, and deliver them through the durable outbox.
+4. Confirm five unique provider idempotency keys, each used once. Exercise provider unavailability, missing and revoked credentials, rotation, and readiness failure without live external calls.
+5. Publish a rollback of version 1 as the latest publication while proving the completed run remains pinned to version 2.
+6. Verify unauthenticated and unauthorized project failures, `/health` liveness, and `/ready` failure when key material is unavailable.
 
 Record database integrity, key ids/versions (never key material), last audit id, lease/outbox counts, and rollback publication. A drill passes only with 20 processed fixtures, the expected selected delivery count, no duplicate provider/idempotency ids, and no secret canary.
 
-The executable drill additionally asserts five approved and delivered messages, one provider idempotency key per message, expired pre-invocation lease recovery after reopening the database, credential version 2 after rotation, pinned version 2 versus the latest rollback publication, authenticated route failures, unavailable mocked providers, and zero canary disclosure in responses, logs, audit export, or diagnostics.
+The drill checks zero canary disclosure across MCP responses, graphs, attempts, invocation messages, audit export, logs, custom-node diagnostics, and run summaries. Recovery replays only pre-invocation work; externally observable attempts with unknown outcomes remain attention-required.
diff --git a/docs-web/operations/runbook.md b/docs-web/operations/runbook.md
index 5fac8c0917..cc61f005e3 100644
--- a/docs-web/operations/runbook.md
+++ b/docs-web/operations/runbook.md
@@ -2,19 +2,19 @@
 
 Run recovery drills only against the approved local test project and mocked job/email providers.
 
-Run the complete offline drill with one command. It uses a temporary SQLite database, the checked-in 20-record fixture, authenticated in-process HTTP routes, and mocked custom-node/job/email boundaries. It does not dispatch a sprint, invoke a live provider, start Docker, or require network access.
+Run the complete offline drill with one command. It uses a temporary file-backed SQLite database, the checked-in 20-record fixture, an authenticated MCP authoring context, authenticated in-process HTTP routes, and mocked job, email, and Docker command boundaries. Generated custom-node code is validated and executed only through the custom-node container service; the test never evaluates it in the Code UX process or starts Docker.
 
 ```bash
 pnpm run test:e2e:credentialed-automation
 ```
 
-1. Verify a viewer can read its project and receives `403` for another project; correlate both requests in audit export.
-2. Stop the key provider with encrypted rows present. `/health` stays live, `/ready` returns `503`, and a new process refuses startup.
-3. Process the 20-record fixture, approve selected drafts, and restart after outbox enqueue. Sent idempotency keys must not invoke the provider twice; unknown outcomes require attention.
-4. Rotate the external credential and confirm the binding resolves its next version; revoke it and confirm access is denied without secret canaries in exports, logs, prompts, traces, or diagnostics.
-5. Publish a later automation, then draft/publish the earlier immutable version. Existing runs remain pinned and new runs select the rollback publication.
-6. Restore SQLite/WAL plus key versions in isolation. Keep runners disabled until readiness, audit continuity, lease ownership, approvals, and outbox counts match the backup manifest.
+1. Use `manage_node_flows` with authenticated agent/conversation metadata to generate and validate the custom node and to create, patch, validate, and publish the flow. Supply credentials only through the credential broker.
+2. Start pinned version 2 through `NodeFlowRuntimeService.runFlow`, interrupt an active pre-invocation node, reopen the same SQLite database, recover, and call `resumeRun`. The run id, publication id, node run, and attempt must remain unchanged.
+3. Process exactly 20 mocked job records through the custom-node runtime, approve the five selected messages in sequence, and deliver them through the durable outbox.
+4. Confirm five unique provider idempotency keys, each used once. Exercise provider unavailability, missing and revoked credentials, rotation, and readiness failure without live external calls.
+5. Publish a rollback of version 1 as the latest publication while proving the completed run remains pinned to version 2.
+6. Verify unauthenticated and unauthorized project failures, `/health` liveness, and `/ready` failure when key material is unavailable.
 
 Record database integrity, key ids/versions (never key material), last audit id, lease/outbox counts, and rollback publication. A drill passes only with 20 processed fixtures, the expected selected delivery count, no duplicate provider/idempotency ids, and no secret canary.
 
-The executable drill additionally asserts five approved and delivered messages, one provider idempotency key per message, expired pre-invocation lease recovery after reopening the database, credential version 2 after rotation, pinned version 2 versus the latest rollback publication, authenticated route failures, unavailable mocked providers, and zero canary disclosure in responses, logs, audit export, or diagnostics.
+The drill checks zero canary disclosure across MCP responses, graphs, attempts, invocation messages, audit export, logs, custom-node diagnostics, and run summaries. Recovery replays only pre-invocation work; externally observable attempts with unknown outcomes remain attention-required.
diff --git a/docs/operations/runbook.md b/docs/operations/runbook.md
index fe685c5dcf..2aca9fbfc7 100644
--- a/docs/operations/runbook.md
+++ b/docs/operations/runbook.md
@@ -4,20 +4,20 @@
 
 Run these drills against the approved local test project with mocked job/email boundaries only:
 
-Run the complete offline drill with one command. It uses a temporary SQLite database, the checked-in 20-record fixture, authenticated in-process HTTP routes, and mocked custom-node/job/email boundaries; it does not dispatch a sprint, invoke a live provider, start Docker, or require network access.
+Run the complete offline drill with one command. It uses a temporary file-backed SQLite database, the checked-in 20-record fixture, an authenticated MCP authoring context, authenticated in-process HTTP routes, and mocked job, email, and Docker command boundaries. Generated custom-node code is validated and executed only through the custom-node container service; the test never evaluates it in the Code UX process, starts Docker, dispatches a sprint, invokes a live provider, or requires network access.
 
 ```bash
 pnpm run test:e2e:credentialed-automation
 ```
 
-1. Send an authenticated read using a viewer identity, then verify a different project returns `403` with the same correlation id visible in redacted audit export.
-2. Stop the key provider while encrypted rows exist. `/health` must remain live, `/ready` must return `503`, and a fresh process must refuse startup. Restore the exact key version before retrying.
-3. Start a 20-record fixture run, approve selected drafts, and restart after durable outbox enqueue. Recovery may reclaim expired pre-invocation work; it must not repeat a `sent` idempotency key. Unknown provider outcomes require attention instead of replay.
-4. Rotate the externally configured credential and verify the unchanged binding resolves the next credential version. Revoke it and verify new resolution is denied without secret text in logs, attempts, graph export, prompts, or diagnostics.
-5. Publish a second automation version, then roll back by drafting/publishing the earlier immutable version. Existing runs stay pinned; new runs select the rollback publication.
-6. Restore the SQLite/WAL snapshot and key-provider state into isolation. Keep runner admission disabled until `/ready`, audit continuity, approval rows, leases, and outbox counts match the backup manifest.
+1. In the authenticated agent/conversation context, call `manage_node_flows` to generate and validate the custom node, then create, patch, validate, and publish the flow through the governed approval handshake. Configure the jobs credential separately through the credential broker; graph JSON contains only its opaque id.
+2. Start pinned version 2 through `NodeFlowRuntimeService.runFlow`, interrupt it at an active pre-invocation node, expire its lease, close SQLite, and reopen the same database. Recovery must requeue that run, and `resumeRun` must retain its run id, publication id, node run, and attempt instead of creating a duplicate attempt.
+3. Let the custom-node runtime cross the mocked Docker command boundary and have the mocked jobs API return exactly 20 records. Approve each of the five selected messages in sequence; pending approvals cannot resume, while approved decisions continue the same run and deliver through the durable outbox.
+4. Confirm the mocked email provider receives five unique idempotency keys, exactly once each. Exercise mocked job/email unavailability, a missing credential id, credential rotation, and revocation without allowing a live external request.
+5. Roll back to the earlier publication and publish it as the latest version. The completed run must remain pinned to version 2 while latest selection resolves the new rollback publication.
+6. Stop the key provider with encrypted rows present. `/health` must remain live, `/ready` must return `503`, and startup readiness must refuse execution. Confirm unauthorized and unauthenticated project requests fail.
 
-The executable drill asserts authenticated authoring and custom-node validation/publication, 20 processed records, five approved and delivered messages, one provider idempotency key per message, expired pre-invocation lease recovery after a real database reopen, credential version 2 after rotation, pinned version 2 versus the latest rollback publication, liveness/readiness behavior, authorization failures, unavailable mocked providers, and zero secret-canary disclosure in responses, logs, audit export, or diagnostics.
+The executable drill checks zero canary disclosure across MCP responses, stored graphs, node attempts, invocation messages, audit export, structured logs, custom-node diagnostics, and final run summaries. Recovery automatically replays only an attempt that has no external invocation id; an expired externally observable attempt remains attention-required because its outcome is unknown.
 
 Record the backup timestamp, database integrity result, key ids/versions (never key material), last audit id, active lease count, outbox status counts, and rollback publication id. A drill passes only with 20 processed fixture records, the expected selected-message count, no duplicate provider ids/idempotency keys, and no secret canary in any exported artifact.
 
diff --git a/src/services/node-flow-runtime-service.ts b/src/services/node-flow-runtime-service.ts
index a7e3e09603..a89f7dab9c 100644
--- a/src/services/node-flow-runtime-service.ts
+++ b/src/services/node-flow-runtime-service.ts
@@ -165,6 +165,27 @@ export class NodeFlowRuntimeService {
     return await this.executeRun(run, publication, graph, executionOrder, input, options, "queued");
   }
 
+  async resumeRun(
+    projectId: string,
+    runId: string,
+    options: Pick<RunNodeFlowOptions, "signal" | "executorId"> = {},
+  ): Promise<NodeFlowRunSummaryResponse> {
+    const run = this.deps.nodeFlowRepository.getRun(runId);
+    if (!run) throw new EntityNotFoundError(`Node flow run not found: ${runId}`);
+    if (run.projectId !== projectId) throw new ValidationError("Node flow run does not belong to the requested project.");
+    if (run.status !== "queued") return this.summarizeRun(run.id);
+    const publication = new NodeFlowPublicationService(this.deps.nodeFlowRepository).resolve(run.flowId, {
+      mode: "pinned",
+      version: run.version,
+    });
+    if (run.publicationId && publication.id !== run.publicationId) {
+      throw new ValidationError("The recoverable run no longer matches its pinned publication.");
+    }
+    const { graph, executionOrder } = normalizeNodeFlowGraph(publication.graph);
+    this.requireSupportedNodes(graph);
+    return await this.executeRun(run, publication, graph, executionOrder, run.input ?? {}, options, "queued");
+  }
+
   async resumeApproval(projectId: string, approvalId: string, expectedRunId?: string, options: Pick<RunNodeFlowOptions, "signal" | "executorId"> = {}): Promise<NodeFlowRunSummaryResponse> {
     if (!this.deps.approvalService) throw new ValidationError("Approval service is not configured.");
     const approval = this.deps.approvalService.get(approvalId);
@@ -288,7 +309,8 @@ export class NodeFlowRuntimeService {
       }
 
       const nodeInput = maskSecrets(this.buildNodeInput(context, node.id));
-      const nodeRun = persistedNodeRun?.status === "approval_waiting"
+      const resumableNodeRun = persistedNodeRun && ["running", "retry_waiting", "approval_waiting"].includes(persistedNodeRun.status);
+      const nodeRun = resumableNodeRun
         ? this.deps.nodeFlowRepository.updateNodeRun(persistedNodeRun.id, { status: "running", errorMessage: null })
         : this.deps.nodeFlowRepository.createNodeRun({
           runId: run.id,
@@ -308,13 +330,18 @@ export class NodeFlowRuntimeService {
       let executionAttempt = 0;
       let waitingAttempt = this.deps.nodeFlowRepository.listNodeAttempts(run.id)
         .find((candidate) => candidate.nodeRunId === nodeRun.id && candidate.status === "approval_waiting");
+      let interruptedAttempt = this.deps.nodeFlowRepository.listNodeAttempts(run.id)
+        .find((candidate) => candidate.nodeRunId === nodeRun.id && candidate.status === "running" && candidate.invocationId === null);
       while (executionAttempt < retryPolicy.maxAttempts) {
         executionAttempt += 1;
         clearResolvedCredentials(context);
         const attempt = waitingAttempt
           ? this.deps.nodeFlowRepository.updateNodeAttempt(waitingAttempt.id, { status: "running", errorMessage: null, finishedAt: null })
-          : attemptService.start(nodeRun, executorId, nodeInput, (node.credentialBindings ?? []).map((binding) => binding.credentialId));
+          : interruptedAttempt
+            ? this.deps.nodeFlowRepository.updateNodeAttempt(interruptedAttempt.id, { status: "running", errorMessage: null, finishedAt: null })
+            : attemptService.start(nodeRun, executorId, nodeInput, (node.credentialBindings ?? []).map((binding) => binding.credentialId));
         waitingAttempt = undefined;
+        interruptedAttempt = undefined;
         context.currentAttemptId = attempt.id;
         const timeoutMs = node.policy?.timeout?.timeoutMs ?? publication.policy.defaultTimeoutMs;
         const timeoutController = new AbortController();
diff --git a/tests/backend/services/credentialed-automation-e2e.test.ts b/tests/backend/services/credentialed-automation-e2e.test.ts
index 98a5563e11..ad44f25ecf 100644
--- a/tests/backend/services/credentialed-automation-e2e.test.ts
+++ b/tests/backend/services/credentialed-automation-e2e.test.ts
@@ -5,19 +5,25 @@ import * as path from "node:path";
 import express, { type Express } from "express";
 import request, { type SuperTest, type Test } from "supertest";
 import { afterEach, describe, expect, it, vi } from "vitest";
-import type { NodeFlowJsonObject } from "../../../src/contracts/node-flow-types.js";
+import type { CustomNodeExecutionResult, CustomNodeManifest } from "../../../src/contracts/custom-node-types.js";
 import type { HeadlessSecurityConfiguration } from "../../../src/contracts/headless-security-types.js";
+import type { ManageNodeFlowsArgs } from "../../../src/contracts/internal-management-types.js";
+import type { NodeFlowGraph, NodeFlowJsonObject, NodeFlowRunSummaryResponse } from "../../../src/contracts/node-flow-types.js";
 import { EncryptedSqliteSecretStore } from "../../../src/infrastructure/security/encrypted-sqlite-secret-store.js";
+import { ManagementToolHandler } from "../../../src/mcp/management-tool-handler.js";
 import { AppDbStorage } from "../../../src/repositories/app-db-storage.js";
 import { AutomationApprovalRepository } from "../../../src/repositories/automation-approval-repository.js";
 import { AutomationCredentialRepository } from "../../../src/repositories/automation-credential-repository.js";
 import { AutomationOutboxRepository } from "../../../src/repositories/automation-outbox-repository.js";
 import { CustomNodeRepository } from "../../../src/repositories/custom-node-repository.js";
+import { ExecutionRepository } from "../../../src/repositories/execution-repository.js";
 import { NodeFlowRepository } from "../../../src/repositories/node-flow-repository.js";
 import { ProjectManagementRepository } from "../../../src/repositories/project-management-repository.js";
+import { SettingsRepository } from "../../../src/repositories/settings-repository.js";
 import { applyDashboardPreRouteMiddleware } from "../../../src/server/dashboard-middleware.js";
 import type { DashboardDependencies, DashboardServerOptions } from "../../../src/server/dashboard-server.js";
 import { registerHeadlessOperationsRoutes } from "../../../src/server/headless-operations-routes.js";
+import { runWithMcpAgentContext } from "../../../src/server/mcp-agent-context.js";
 import { registerNodeFlowRoutes } from "../../../src/server/node-flow-routes.js";
 import { AutomationAuditExportService } from "../../../src/services/automation-audit-export-service.js";
 import type { CommandResult } from "../../../src/services/cli-process-runner.js";
@@ -25,14 +31,16 @@ import { CredentialBroker } from "../../../src/services/credentials/credential-b
 import type { KeyProvider } from "../../../src/services/credentials/key-provider.js";
 import { CustomNodeBuildService } from "../../../src/services/custom-nodes/custom-node-build-service.js";
 import { CustomNodeProjectService } from "../../../src/services/custom-nodes/custom-node-project-service.js";
+import { CustomNodeRuntimeService } from "../../../src/services/custom-nodes/custom-node-runtime-service.js";
 import { HeadlessAuthService } from "../../../src/services/headless-auth-service.js";
 import { HeadlessOperationalReadinessService } from "../../../src/services/headless-operational-readiness-service.js";
+import { NodeFlowRuntimeService } from "../../../src/services/node-flow-runtime-service.js";
 import { NodeFlowService } from "../../../src/services/node-flow-service.js";
-import { ApprovalRequiredError, ApprovalService } from "../../../src/services/node-flows/approval-service.js";
+import { ApprovalService } from "../../../src/services/node-flows/approval-service.js";
+import { EgressPolicyService } from "../../../src/services/node-flows/egress-policy-service.js";
 import { NodeFlowPublicationService } from "../../../src/services/node-flows/node-flow-publication-service.js";
-import { NodeFlowQueueService } from "../../../src/services/node-flows/node-flow-queue-service.js";
 import { NodeFlowRecoveryService } from "../../../src/services/node-flows/node-flow-recovery-service.js";
-import { MockSideEffectProvider, OutboxService, type SideEffectProvider } from "../../../src/services/node-flows/outbox-service.js";
+import { OutboxService, type SideEffectProvider } from "../../../src/services/node-flows/outbox-service.js";
 import { createLogger, type Logger } from "../../../src/shared/logging/logger.js";
 
 interface JobFixture { id: string; name: string; selected: boolean }
@@ -53,11 +61,8 @@ afterEach(async () => {
 const commandResult = (stdout = "", stderr = ""): CommandResult => ({ ok: true, code: 0, stdout, stderr });
 
 function authenticated(agent: SuperTest<Test>, token = SERVICE_TOKEN): Test {
-  return agent
-    .set("Host", "localhost")
-    .set("X-Forwarded-Proto", "https")
-    .set("X-Code-UX-Service-Id", "automation-drill")
-    .set("Authorization", `Bearer ${token}`);
+  return agent.set("Host", "localhost").set("X-Forwarded-Proto", "https")
+    .set("X-Code-UX-Service-Id", "automation-drill").set("Authorization", `Bearer ${token}`);
 }
 
 function createHeadlessApp(input: {
@@ -69,9 +74,8 @@ function createHeadlessApp(input: {
   logger: Logger;
 }): Express {
   const app = express();
-  const authService = new HeadlessAuthService(input.security);
   applyDashboardPreRouteMiddleware(app, {
-    headlessAuthService: authService,
+    headlessAuthService: new HeadlessAuthService(input.security),
     automationAuditService: input.auditService,
   } as DashboardServerOptions, input.logger);
   app.get("/health", (_req, res) => res.json({ status: "UP" }));
@@ -90,304 +94,301 @@ function createHeadlessApp(input: {
   return app;
 }
 
+function createManagementHandler(nodeFlowService: NodeFlowService): ManagementToolHandler {
+  return new ManagementToolHandler({
+    projectManagementRepository: {}, sprintPreviewService: {}, executionRepository: {}, getDashboardSettings: () => ({}),
+    executionControlService: {}, taskRerunService: {}, settingsRepository: {}, chatProviderRepository: {},
+    agentPresetSyncService: {}, memoryService: {}, memoryPromotionService: {}, embeddingModelManager: {}, skillService: {},
+    nodeFlowService, knowledgeService: {}, planningAgentService: {}, sprintIssueService: {},
+  } as never);
+}
+
+async function manage(handler: ManagementToolHandler, args: ManageNodeFlowsArgs): Promise<Record<string, unknown>> {
+  const response = await runWithMcpAgentContext("author-agent", "authoring-conversation", () => handler.handleManageNodeFlows(args));
+  return JSON.parse(response.content[0]!.text) as Record<string, unknown>;
+}
+
+function resultOf<T>(envelope: Record<string, unknown>): T {
+  return envelope.result as T;
+}
+
+async function waitForActiveRun(repository: NodeFlowRepository, flowId: string): Promise<string> {
+  for (let count = 0; count < 100; count += 1) {
+    const run = repository.listRuns(flowId).find((candidate) => candidate.status === "running");
+    if (run && repository.listNodeAttempts(run.id).some((attempt) => attempt.status === "running")) return run.id;
+    await new Promise((resolve) => setTimeout(resolve, 1));
+  }
+  throw new Error("The fixture run did not become active.");
+}
+
 describe("credentialed automation authoring-to-execution", () => {
-  it("runs the complete mocked drill with authenticated authoring, restart recovery, rotation, and rollback", async () => {
+  it("runs the authenticated governed drill through the executable runtime and durable recovery boundaries", async () => {
     vi.stubEnv("VITEST_IN_MEMORY_DB", "false");
     const root = await fs.mkdtemp(path.join(os.tmpdir(), "code-ux-credentialed-e2e-"));
     temporaryDirectories.push(root);
     const databasePath = path.join(root, "app.db");
     let storage = new AppDbStorage(databasePath);
-    const project = new ProjectManagementRepository(storage).createProject({
-      name: "Approved local test project",
-      sourceType: "local",
-      sourceRef: root,
-    });
+    const projectRepository = new ProjectManagementRepository(storage);
+    const project = projectRepository.createProject({ name: "Approved local test project", sourceType: "local", sourceRef: root });
     let keyAvailable = true;
-    const key = Buffer.alloc(32, 7);
+    const encryptionKey = Buffer.alloc(32, 7);
     const keyProvider: KeyProvider = {
       providerName: "mock-kms",
-      health: async () => ({
-        available: keyAvailable,
-        secure: true,
-        provider: "mock-kms",
-        keyId: keyAvailable ? "fixture-key" : null,
-        keyVersion: keyAvailable ? 1 : null,
-        reason: keyAvailable ? undefined : "mock key provider unavailable",
-      }),
-      getActiveKey: async () => ({ key: Buffer.from(key), keyId: "fixture-key", version: 1 }),
-      getKey: async () => ({ key: Buffer.from(key), keyId: "fixture-key", version: 1 }),
+      health: async () => ({ available: keyAvailable, secure: true, provider: "mock-kms", keyId: keyAvailable ? "fixture-key" : null,
+        keyVersion: keyAvailable ? 1 : null, reason: keyAvailable ? undefined : "mock key provider unavailable" }),
+      getActiveKey: async () => ({ key: Buffer.from(encryptionKey), keyId: "fixture-key", version: 1 }),
+      getKey: async () => ({ key: Buffer.from(encryptionKey), keyId: "fixture-key", version: 1 }),
     };
     const security: HeadlessSecurityConfiguration = {
-      mode: "service_token",
-      serviceIdentities: [{
-        id: "automation-drill",
-        displayName: "Automation drill fixture",
+      mode: "service_token", allowInsecureHttp: false, remoteCredentialManagement: true,
+      serviceIdentities: [{ id: "automation-drill", displayName: "Automation drill fixture",
         tokenSha256: createHash("sha256").update(SERVICE_TOKEN).digest("hex"),
         roles: ["credential_admin", "automation_author", "automation_publisher", "automation_runner", "viewer"],
-        projectIds: [project.id],
-        enabled: true,
-      }],
-      allowInsecureHttp: false,
-      remoteCredentialManagement: true,
+        projectIds: [project.id], enabled: true }],
     };
     const capturedLogs: string[] = [];
     vi.spyOn(process.stderr, "write").mockImplementation(((chunk: string | Uint8Array) => {
-      capturedLogs.push(String(chunk));
-      return true;
+      capturedLogs.push(String(chunk)); return true;
     }) as typeof process.stderr.write);
     const logger = createLogger({ consoleLogLevel: "warn", environment: "production", color: false });
 
     let audit = new AutomationAuditExportService(storage);
     let credentialRepository = new AutomationCredentialRepository(storage);
-    let broker = new CredentialBroker(
-      credentialRepository,
-      new EncryptedSqliteSecretStore(credentialRepository, keyProvider),
-      keyProvider,
-      audit,
-    );
-
-    // Secrets are supplied outside the agent-authored graph and never enter route payloads.
+    let broker = new CredentialBroker(credentialRepository, new EncryptedSqliteSecretStore(credentialRepository, keyProvider), keyProvider, audit);
     const credential = await broker.create(project.id, {
-      name: "Mock jobs and email API",
-      kind: "http",
-      value: FIRST_SECRET_CANARY,
-      capabilities: ["read", "write"],
+      name: "Mock jobs API", kind: "http", value: FIRST_SECRET_CANARY, capabilities: ["read"],
     });
     broker.bind(project.id, credential.id, "jobs-api", ["read"]);
 
+    const fixtures = JSON.parse(await fs.readFile(path.resolve("tests/e2e/fixtures/headless-automation-records.json"), "utf8")) as JobFixture[];
+    expect(fixtures).toHaveLength(EXPECTED_RECORD_COUNT);
+    const selectedFixtures = fixtures.filter((record) => record.selected);
+    expect(selectedFixtures).toHaveLength(EXPECTED_SELECTED_MESSAGE_COUNT);
+    const jobApi = {
+      list: vi.fn(async (secret: string): Promise<JobFixture[]> => {
+        expect(secret).toBe(FIRST_SECRET_CANARY);
+        return fixtures;
+      }),
+      authenticate: vi.fn(async (_secret: string, _version: number): Promise<void> => undefined),
+      unavailable: vi.fn(async (): Promise<JobFixture[]> => { throw new Error("mock jobs provider unavailable"); }),
+    };
+    let emailUnavailable = false;
+    const emailSends: Array<{ payload: NodeFlowJsonObject; idempotencyKey: string }> = [];
+    const emailProvider: SideEffectProvider = {
+      send: vi.fn(async (_effectType, payload, idempotencyKey) => {
+        if (emailUnavailable) throw new Error("mock email provider unavailable");
+        emailSends.push({ payload, idempotencyKey });
+        return { providerMessageId: `mock-${idempotencyKey.slice(0, 16)}` };
+      }),
+    };
+
     const customNodeRepository = new CustomNodeRepository(storage);
     const customNodeProjectService = new CustomNodeProjectService();
-    const commandRunner = vi.fn(async (_command: string, args: string[]): Promise<CommandResult> => {
+    const buildCommandRunner = vi.fn(async (_command: string, args: string[]): Promise<CommandResult> => {
       if (args[0] === "image") return commandResult(`sha256:${"d".repeat(64)}\n`);
       if (args[0] === "run") return commandResult(JSON.stringify({ value: 1, executedAt: "2026-01-01T00:00:00.000Z" }));
       return commandResult();
     });
-    const customNodeBuildService = new CustomNodeBuildService({
-      repository: customNodeRepository,
-      projectService: customNodeProjectService,
-      commandRunner,
-      vulnerabilityAudit: async () => ({ passed: true, details: "mock audit passed" }),
+    const buildService = new CustomNodeBuildService({ repository: customNodeRepository, projectService: customNodeProjectService,
+      commandRunner: buildCommandRunner, vulnerabilityAudit: async () => ({ passed: true, details: "mock audit passed" }) });
+
+    let diagnosticMode = false;
+    const runtimeCommandRunner = vi.fn(async (_command: string, _args: string[], _cwd: string, options: { stdinFile?: string }): Promise<CommandResult> => {
+      const envelope = JSON.parse(await fs.readFile(options.stdinFile!, "utf8")) as { credentials: { jobs: string } };
+      if (diagnosticMode) return commandResult(JSON.stringify({ leak: envelope.credentials.jobs }), `diagnostic=${envelope.credentials.jobs}`);
+      const records = await jobApi.list(envelope.credentials.jobs);
+      return commandResult(JSON.stringify({ records, recordCount: records.length, selected: records.filter((record) => record.selected) }), `jobs credential ${envelope.credentials.jobs}`);
     });
+    let customRuntime = new CustomNodeRuntimeService({ repository: customNodeRepository, credentialBroker: broker,
+      egressPolicyService: new EgressPolicyService(), featureEnabled: true, commandRunner: runtimeCommandRunner });
     let flowRepository = new NodeFlowRepository(storage);
-    let flowService = new NodeFlowService(flowRepository, undefined, broker, {
-      repository: customNodeRepository,
-      projectService: customNodeProjectService,
-      buildService: customNodeBuildService,
-      resolveProjectRoot: () => root,
-    });
+    let executionRepository = new ExecutionRepository(storage);
     let approvalService = new ApprovalService(new AutomationApprovalRepository(storage), audit);
-    let readinessService = new HeadlessOperationalReadinessService({ credentialRepository, keyProvider, auditService: audit, security });
-    let app = createHeadlessApp({ nodeFlowService: flowService, approvalService, auditService: audit, readinessService, security, logger });
-
-    expect((await request(app).get("/health").set("Host", "localhost")).body).toEqual({ status: "UP" });
-    await request(app).get("/ready").set("Host", "localhost").expect(200);
-    await request(app).get(`/api/projects/${project.id}/node-flows`)
-      .set("Host", "localhost").set("X-Forwarded-Proto", "https").expect(401);
-    await authenticated(request(app).get("/api/projects/unauthorized-project/node-flows")).expect(403, /not authorized/i);
+    let outboxService = new OutboxService(new AutomationOutboxRepository(storage), emailProvider, audit);
+    let runtime = new NodeFlowRuntimeService({ nodeFlowRepository: flowRepository, executionRepository,
+      projectManagementRepository: projectRepository, settingsRepository: new SettingsRepository(path.join(root, "settings.db")),
+      credentialBroker: broker, approvalService, outboxService, customNodeRuntimeService: customRuntime, auditService: audit });
+    let flowService = new NodeFlowService(flowRepository, runtime, broker, { repository: customNodeRepository,
+      projectService: customNodeProjectService, buildService, resolveProjectRoot: () => root });
+    let handler = createManagementHandler(flowService);
 
-    // This fixture is the authoring agent: it uses only authenticated governed routes.
-    const customNodeResponse = await authenticated(request(app).post(`/api/projects/${project.id}/custom-nodes`))
-      .send({ nodeId: "fixture-record-selector", name: "Fixture record selector", sourceRevision: "fixture-r1", createdBy: "author-agent" })
-      .expect(201);
-    expect(customNodeResponse.body).toMatchObject({ id: "fixture-record-selector", status: "draft" });
-    const validationResponse = await authenticated(request(app).post(`/api/projects/${project.id}/custom-nodes/fixture-record-selector/validate`))
-      .send({ actor: "author-agent", invocationId: "invocation-build", correlationId: "correlation-build" })
-      .expect(200);
-    expect(validationResponse.body).toMatchObject({ status: "passed" });
-    const customNodeArtifact = customNodeBuildService.publish("fixture-record-selector", "publisher-service");
-    expect(customNodeArtifact.manifest.nodeType).toBe("custom.fixture-record-selector");
+    const createdCustom = resultOf<{ node: { manifest: CustomNodeManifest } }>(await manage(handler, {
+      action: "create_custom_node", projectId: project.id, nodeId: "fixture-record-selector", name: "Fixture record selector",
+      sourceRevision: "fixture-r1", actor: "author-agent",
+    } as ManageNodeFlowsArgs));
+    const manifest: CustomNodeManifest = {
+      ...createdCustom.node.manifest,
+      capabilities: ["credentials.read", "clock.read"],
+      credentials: [{ slot: "jobs", label: "Jobs API", required: true, allowedKinds: ["http"], requiredCapability: "read" }],
+    };
+    await manage(handler, { action: "update_custom_node", projectId: project.id, nodeId: "fixture-record-selector",
+      manifest, sourceRevision: "fixture-r1" } as ManageNodeFlowsArgs);
+    const customValidation = resultOf<{ status: string }>(await manage(handler, { action: "validate_custom_node",
+      projectId: project.id, nodeId: "fixture-record-selector", actor: "author-agent",
+      invocationId: "custom-build", correlationId: "authoring-conversation" } as ManageNodeFlowsArgs));
+    expect(customValidation.status).toBe("passed");
+    const customArtifact = buildService.publish("fixture-record-selector", "publisher-service");
+    expect(customArtifact.manifest.nodeType).toBe("custom.fixture-record-selector");
 
-    const graphV1 = {
+    const sendNodes = selectedFixtures.map((record, index) => ({
+      id: `send-${index}`, type: "email_send", title: `Send ${index + 1}`,
+      data: { to: `{{nodes.select.selected.${index}.id}}@example.test`, subject: "Fixture follow-up",
+        body: `Hello {{nodes.select.selected.${index}.name}}`, logicalItem: record.id },
+    }));
+    const graphV1: NodeFlowGraph = {
       nodes: [
-        { id: "select", type: "custom.fixture-record-selector", title: "Select fixtures", definition: { type: "custom.fixture-record-selector", version: 1 } },
-        {
-          id: "jobs", type: "http_request", title: "Read mocked jobs", definition: { type: "http_request", version: 1 },
-          data: { url: "https://jobs.example.test/fixtures", method: "GET" },
-          credentialBindings: [{ slot: "auth", credentialId: credential.id }],
-        },
-        { id: "output-v1", type: "output", title: "Output v1", data: { release: "v1" } },
+        { id: "interrupt", type: "delay", title: "Interruptible boundary", data: { delayMs: 20 } },
+        { id: "select", type: "custom.fixture-record-selector", title: "Read and select 20 fixtures",
+          definition: { type: "custom.fixture-record-selector", version: 1 },
+          credentialBindings: [{ slot: "jobs", credentialId: credential.id }] },
+        ...sendNodes,
+        { id: "output-v1", type: "output", title: "Output v1", data: { fields: { processed: "{{nodes.select.recordCount}}", delivered: 5, release: "v1" } } },
+      ],
+      edges: [
+        { fromNodeId: "interrupt", toNodeId: "select" },
+        { fromNodeId: "select", toNodeId: "send-0" },
+        ...sendNodes.slice(0, -1).map((_node, index) => ({ fromNodeId: `send-${index}`, toNodeId: `send-${index + 1}` })),
+        { fromNodeId: `send-${sendNodes.length - 1}`, toNodeId: "output-v1" },
       ],
-      edges: [{ fromNodeId: "select", toNodeId: "jobs" }, { fromNodeId: "jobs", toNodeId: "output-v1" }],
     };
-    const draftResponse = await authenticated(request(app).post(`/api/projects/${project.id}/node-flow-drafts`))
-      .send({ title: "Mocked candidate outreach", graph: graphV1 })
-      .expect(201);
-    expect(draftResponse.body).toMatchObject({ valid: true, draftRevision: 1 });
-    expect(draftResponse.body.requiredCredentials).toEqual([
-      expect.objectContaining({ nodeId: "jobs", credentialId: credential.id, status: "bound" }),
-    ]);
-    await authenticated(request(app).post(`/api/node-flow-drafts/${draftResponse.body.flowId}/publish`))
-      .send({ projectId: project.id, draftRevision: 1, publishedBy: "publisher-service" })
-      .expect(200);
-
+    const draftEnvelope = await manage(handler, { action: "create_draft", projectId: project.id,
+      name: "Mocked candidate outreach", graph: graphV1 });
+    const draft = resultOf<{ draft: { flowId: string; draftRevision: number; valid: boolean } }>(draftEnvelope).draft;
+    expect(draft).toMatchObject({ valid: true, draftRevision: 1 });
     const graphV2 = structuredClone(graphV1);
-    graphV2.nodes[2] = { id: "output-v2", type: "output", title: "Output v2", data: { release: "v2" } };
-    graphV2.edges[1] = { fromNodeId: "jobs", toNodeId: "output-v2" };
-    const patchResponse = await authenticated(request(app).patch(`/api/node-flow-drafts/${draftResponse.body.flowId}`))
-      .send({ projectId: project.id, draftRevision: 1, graph: graphV2 })
-      .expect(200);
-    await authenticated(request(app).post(`/api/node-flow-drafts/${draftResponse.body.flowId}/publish`))
-      .send({ projectId: project.id, draftRevision: patchResponse.body.draft.draftRevision, publishedBy: "publisher-service" })
-      .expect(200);
-    const publicationV2 = flowRepository.getPublication(draftResponse.body.flowId);
-    expect(publicationV2?.version).toBe(2);
+    graphV2.nodes[graphV2.nodes.length - 1] = { id: "output-v2", type: "output", title: "Output v2",
+      data: { fields: { processed: "{{nodes.select.recordCount}}", delivered: 5, release: "v2" } } };
+    graphV2.edges[graphV2.edges.length - 1] = { fromNodeId: `send-${sendNodes.length - 1}`, toNodeId: "output-v2" };
+    const patched = resultOf<{ draft: { draftRevision: number; valid: boolean } }>(await manage(handler, {
+      action: "patch_draft", projectId: project.id, flowId: draft.flowId, draftRevision: 1, patch: { graph: graphV2 },
+    })).draft;
+    expect(patched).toMatchObject({ valid: true, draftRevision: 2 });
+    expect(resultOf<{ draft: { valid: boolean } }>(await manage(handler, { action: "validate_draft", projectId: project.id, flowId: draft.flowId })).draft.valid).toBe(true);
+    const publishArgs = { action: "publish" as const, projectId: project.id, flowId: draft.flowId,
+      draftRevision: patched.draftRevision, publishedBy: "publisher-service", approval: { confirmed: true } };
+    expect((await manage(handler, publishArgs)).approvalRequired).toBe(true);
+    await manage(handler, publishArgs);
+    const publicationV2 = flowRepository.getPublication(draft.flowId)!;
+    expect(publicationV2.version).toBe(2);
 
-    const initialCredential = await broker.resolve({ projectId: project.id, bindingKey: "jobs-api", capability: "read", workspaceId: "fixture-fetch" });
-    const jobApi = {
-      list: vi.fn(async (value: string): Promise<JobFixture[]> => {
-        expect(value).toBe(FIRST_SECRET_CANARY);
-        return JSON.parse(await fs.readFile(path.resolve("tests/e2e/fixtures/headless-automation-records.json"), "utf8")) as JobFixture[];
-      }),
-      authenticate: vi.fn(async (_value: string, _version: number): Promise<void> => undefined),
-      unavailable: vi.fn(async (): Promise<JobFixture[]> => { throw new Error("mock jobs provider unavailable"); }),
-    };
-    const records = await jobApi.list(initialCredential.value);
-    expect(records).toHaveLength(EXPECTED_RECORD_COUNT);
-    const selected = records.filter((record) => record.selected);
-    const drafts: NodeFlowJsonObject[] = selected.map((record) => ({
-      to: `${record.id}@example.test`, subject: "Fixture follow-up", body: `Hello ${record.name}`,
-    }));
-    expect(drafts).toHaveLength(EXPECTED_SELECTED_MESSAGE_COUNT);
-
-    const run = flowRepository.createRun({
-      projectId: project.id,
-      flowId: draftResponse.body.flowId,
-      version: publicationV2!.version,
-      publicationId: publicationV2!.id,
-      policy: publicationV2!.policy,
-      status: "queued",
-      input: { recordCount: records.length },
-    });
-    const claimed = new NodeFlowQueueService(flowRepository).claim(run, "worker-before-restart");
-    const nodeRun = flowRepository.createNodeRun({
-      runId: run.id, flowId: run.flowId, projectId: project.id, nodeId: "send", status: "running",
-    });
-    const activeAttempt = flowRepository.createNodeAttempt({
-      runId: run.id, nodeRunId: nodeRun.id, nodeId: "send", attemptNumber: 1, status: "running",
-      executorId: claimed.leaseOwner!, invocationId: null, artifactDigest: null, input: { processed: 0 }, output: null,
-      credentialIds: [credential.id], failureClassification: null, retryDecision: null, errorMessage: null,
-      startedAt: new Date().toISOString(), finishedAt: null,
-    });
-    for (const [index, draft] of drafts.entries()) {
-      const logicalItem = selected[index]!.id;
-      try {
-        approvalService.requireApproval({ projectId: project.id, flowId: run.flowId, runId: run.id, nodeId: "send", logicalItem, request: draft });
-      } catch (error) {
-        expect(error).toBeInstanceOf(ApprovalRequiredError);
-        approvalService.approve((error as ApprovalRequiredError).approval.id, "approver-service");
-      }
-      approvalService.requireApproval({ projectId: project.id, flowId: run.flowId, runId: run.id, nodeId: "send", logicalItem, request: draft });
-    }
-    expect(approvalService.listForRun(run.id).filter((approval) => approval.status === "approved")).toHaveLength(EXPECTED_SELECTED_MESSAGE_COUNT);
-
-    const providerBeforeRestart = new MockSideEffectProvider();
-    const outboxBeforeRestart = new OutboxService(new AutomationOutboxRepository(storage), providerBeforeRestart, audit);
-    for (let index = 0; index < 2; index += 1) {
-      await outboxBeforeRestart.dispatch({
-        projectId: project.id, flowId: run.flowId, publicationId: publicationV2!.id, runId: run.id,
-        nodeId: "send", logicalItem: selected[index]!.id, effectType: "email", payload: drafts[index]!,
-      });
-    }
-    expect(providerBeforeRestart.sends).toHaveLength(2);
-    flowRepository.updateRun(run.id, { leaseExpiresAt: "2020-01-01T00:00:00.000Z" });
+    let readinessService = new HeadlessOperationalReadinessService({ credentialRepository, keyProvider, auditService: audit, security });
+    let app = createHeadlessApp({ nodeFlowService: flowService, approvalService, auditService: audit, readinessService, security, logger });
+    await request(app).get("/health").set("Host", "localhost").expect(200, { status: "UP" });
+    await request(app).get("/ready").set("Host", "localhost").expect(200);
+    await request(app).get(`/api/projects/${project.id}/node-flows`).set("Host", "localhost").set("X-Forwarded-Proto", "https").expect(401);
+    await authenticated(request(app).get("/api/projects/unauthorized-project/node-flows")).expect(403, /not authorized/i);
 
-    // Reopen the same database to model a process restart while the run and attempt are active.
+    const interruptedController = new AbortController();
+    const interruptedPromise = runtime.runFlow(project.id, draft.flowId, { fixtureCount: EXPECTED_RECORD_COUNT }, {
+      signal: interruptedController.signal, executorId: "worker-before-restart", versionSelection: { mode: "pinned", version: 2 },
+      triggerType: "mcp_management", triggerPayload: { initiatingAgentId: "author-agent", conversationId: "authoring-conversation" },
+    }).catch(() => undefined);
+    const runId = await waitForActiveRun(flowRepository, draft.flowId);
+    flowRepository.updateRun(runId, { leaseExpiresAt: "2020-01-01T00:00:00.000Z" });
+    expect(flowRepository.listNodeAttempts(runId)).toHaveLength(1);
     storage.close();
+    interruptedController.abort(new Error("simulated process interruption"));
+    void interruptedPromise;
+
     storage = new AppDbStorage(databasePath);
     audit = new AutomationAuditExportService(storage);
     credentialRepository = new AutomationCredentialRepository(storage);
-    broker = new CredentialBroker(
-      credentialRepository,
-      new EncryptedSqliteSecretStore(credentialRepository, keyProvider),
-      keyProvider,
-      audit,
-    );
+    broker = new CredentialBroker(credentialRepository, new EncryptedSqliteSecretStore(credentialRepository, keyProvider), keyProvider, audit);
     flowRepository = new NodeFlowRepository(storage);
-    flowService = new NodeFlowService(flowRepository, undefined, broker);
+    executionRepository = new ExecutionRepository(storage);
     approvalService = new ApprovalService(new AutomationApprovalRepository(storage), audit);
+    outboxService = new OutboxService(new AutomationOutboxRepository(storage), emailProvider, audit);
+    customRuntime = new CustomNodeRuntimeService({ repository: new CustomNodeRepository(storage), credentialBroker: broker,
+      egressPolicyService: new EgressPolicyService(), featureEnabled: true, commandRunner: runtimeCommandRunner });
+    runtime = new NodeFlowRuntimeService({ nodeFlowRepository: flowRepository, executionRepository,
+      projectManagementRepository: new ProjectManagementRepository(storage), settingsRepository: new SettingsRepository(path.join(root, "settings-restarted.db")),
+      credentialBroker: broker, approvalService, outboxService, customNodeRuntimeService: customRuntime, auditService: audit });
+    flowService = new NodeFlowService(flowRepository, runtime, broker);
+    handler = createManagementHandler(flowService);
     readinessService = new HeadlessOperationalReadinessService({ credentialRepository, keyProvider, auditService: audit, security });
     app = createHeadlessApp({ nodeFlowService: flowService, approvalService, auditService: audit, readinessService, security, logger });
 
     const [recovered] = new NodeFlowRecoveryService(flowRepository).recover();
-    expect(recovered).toMatchObject({ id: run.id, status: "queued", leaseOwner: null, leaseExpiresAt: null });
-    expect(flowRepository.listNodeAttempts(run.id)).toHaveLength(1);
-    const reclaimed = new NodeFlowQueueService(flowRepository).claim(recovered!, "worker-after-restart");
-    expect(reclaimed).toMatchObject({ status: "running", leaseOwner: "worker-after-restart" });
-
-    const providerAfterRestart = new MockSideEffectProvider();
-    const outboxAfterRestart = new OutboxService(new AutomationOutboxRepository(storage), providerAfterRestart, audit);
-    for (const [index, draft] of drafts.entries()) {
-      await outboxAfterRestart.dispatch({
-        projectId: project.id, flowId: run.flowId, publicationId: publicationV2!.id, runId: run.id,
-        nodeId: "send", logicalItem: selected[index]!.id, effectType: "email", payload: draft,
-      });
+    expect(recovered).toMatchObject({ id: runId, version: 2, publicationId: publicationV2.id, status: "queued", leaseOwner: null });
+    let summary = await runtime.resumeRun(project.id, runId, { executorId: "worker-after-restart" });
+    expect(summary.run).toMatchObject({ id: runId, status: "approval_waiting", version: 2, publicationId: publicationV2.id });
+    expect(flowRepository.listNodeAttempts(runId).filter((attempt) => attempt.nodeId === "interrupt")).toHaveLength(1);
+    for (let index = 0; index < EXPECTED_SELECTED_MESSAGE_COUNT; index += 1) {
+      const approvals = approvalService.listForRun(runId);
+      const pending = approvals.find((approval) => approval.status === "pending");
+      expect(pending).toMatchObject({ nodeId: `send-${index}`, logicalItem: selectedFixtures[index]!.id });
+      await expect(runtime.resumeApproval(project.id, pending!.id, runId)).rejects.toThrow(/still pending/i);
+      approvalService.approve(pending!.id, "approver-service");
+      summary = await runtime.resumeApproval(project.id, pending!.id, runId);
     }
-    const allProviderSends = [...providerBeforeRestart.sends, ...providerAfterRestart.sends];
-    const idempotencyKeys = allProviderSends.map((send) => send.idempotencyKey);
-    expect(allProviderSends).toHaveLength(EXPECTED_SELECTED_MESSAGE_COUNT);
+    expect(summary.run).toMatchObject({ id: runId, status: "succeeded", version: 2, publicationId: publicationV2.id });
+    expect(summary.output).toMatchObject({ processed: "20", delivered: 5, release: "v2" });
+    expect(jobApi.list).toHaveBeenCalledTimes(1);
+    expect(emailSends).toHaveLength(EXPECTED_SELECTED_MESSAGE_COUNT);
+    const idempotencyKeys = emailSends.map((send) => send.idempotencyKey);
     expect(new Set(idempotencyKeys)).toHaveLength(EXPECTED_SELECTED_MESSAGE_COUNT);
-    expect(idempotencyKeys.every((key) => idempotencyKeys.filter((candidate) => candidate === key).length === 1)).toBe(true);
-    const persistedOutbox = new AutomationOutboxRepository(storage).listForRun(run.id);
-    expect(persistedOutbox).toHaveLength(EXPECTED_SELECTED_MESSAGE_COUNT);
-    expect(persistedOutbox.every((item) => item.status === "sent" && idempotencyKeys.includes(item.idempotencyKey))).toBe(true);
-    flowRepository.updateNodeAttempt(activeAttempt.id, { status: "succeeded", output: { delivered: drafts.length }, retryDecision: "stop", finishedAt: new Date().toISOString() });
-    flowRepository.updateNodeRun(nodeRun.id, { status: "succeeded", output: { delivered: drafts.length }, finishedAt: new Date().toISOString() });
-    const completedRun = flowRepository.updateRun(run.id, {
-      status: "succeeded", output: { processed: records.length, delivered: drafts.length },
-      leaseOwner: null, leaseExpiresAt: null, finishedAt: new Date().toISOString(),
-    });
-    expect(completedRun).toMatchObject({ status: "succeeded", output: { processed: EXPECTED_RECORD_COUNT, delivered: EXPECTED_SELECTED_MESSAGE_COUNT } });
-
-    await broker.rotate(project.id, credential.id, ROTATED_SECRET_CANARY);
-    const rotated = await broker.resolve({ projectId: project.id, bindingKey: "jobs-api", capability: "read", workspaceId: "run-after-rotation" });
-    await jobApi.authenticate(rotated.value, rotated.version);
-    expect(jobApi.authenticate).toHaveBeenCalledWith(ROTATED_SECRET_CANARY, 2);
+    const mainOutbox = new AutomationOutboxRepository(storage).listForRun(runId);
+    expect(mainOutbox).toHaveLength(EXPECTED_SELECTED_MESSAGE_COUNT);
+    expect(mainOutbox.every((item) => item.status === "sent" && idempotencyKeys.includes(item.idempotencyKey))).toBe(true);
+    expect(flowRepository.listNodeAttempts(runId).every((attempt) => attempt.attemptNumber === 1)).toBe(true);
 
     const publicationService = new NodeFlowPublicationService(flowRepository);
-    expect(publicationService.resolve(run.flowId, { mode: "pinned", version: 2 }).id).toBe(run.publicationId);
-    const rollbackResponse = await authenticated(request(app).post(`/api/node-flows/${run.flowId}/rollback`))
-      .send({ projectId: project.id, version: 1, draftRevision: 2 })
-      .expect(200);
-    await authenticated(request(app).post(`/api/node-flow-drafts/${run.flowId}/publish`))
-      .send({ projectId: project.id, draftRevision: rollbackResponse.body.draftRevision, publishedBy: "publisher-service" })
-      .expect(200);
-    const latestAfterRollback = publicationService.resolve(run.flowId, { mode: "latest_published" });
+    expect(publicationService.resolve(draft.flowId, { mode: "pinned", version: 2 }).id).toBe(publicationV2.id);
+    const rollbackArgs = { action: "rollback" as const, projectId: project.id, flowId: draft.flowId,
+      version: 1, draftRevision: 2, approval: { confirmed: true } };
+    expect((await manage(handler, rollbackArgs)).approvalRequired).toBe(true);
+    const rollbackDraft = resultOf<{ draft: { draftRevision: number } }>(await manage(handler, rollbackArgs)).draft;
+    const rollbackPublish = { action: "publish" as const, projectId: project.id, flowId: draft.flowId,
+      draftRevision: rollbackDraft.draftRevision, publishedBy: "publisher-service", approval: { confirmed: true } };
+    await manage(handler, rollbackPublish); await manage(handler, rollbackPublish);
+    const latestAfterRollback = publicationService.resolve(draft.flowId, { mode: "latest_published" });
     expect(latestAfterRollback.version).toBe(3);
     expect(latestAfterRollback.graph.nodes.some((node) => node.id === "output-v1")).toBe(true);
-    expect(publicationService.resolve(run.flowId, { mode: "pinned", version: 2 }).graph.nodes.some((node) => node.id === "output-v2")).toBe(true);
-    expect(flowRepository.getRun(run.id)).toMatchObject({ version: 2, publicationId: publicationV2!.id });
+    expect(flowRepository.getRun(runId)).toMatchObject({ version: 2, publicationId: publicationV2.id });
 
+    await expect(customRuntime.execute({ projectId: project.id, nodeType: "custom.fixture-record-selector", version: 1,
+      input: {}, config: {}, credentialBindings: { jobs: "missing-credential" }, workspaceId: "missing", invocationId: "missing", correlationId: "missing" }))
+      .rejects.toThrow(/credential is missing/i);
+    await broker.rotate(project.id, credential.id, ROTATED_SECRET_CANARY);
+    const rotated = await broker.resolve({ projectId: project.id, bindingKey: "jobs-api", capability: "read", workspaceId: "rotation" });
+    await jobApi.authenticate(rotated.value, rotated.version);
+    expect(jobApi.authenticate).toHaveBeenCalledWith(ROTATED_SECRET_CANARY, 2);
+    diagnosticMode = true;
+    const diagnostics: CustomNodeExecutionResult = await customRuntime.execute({ projectId: project.id,
+      nodeType: "custom.fixture-record-selector", version: 1, input: {}, config: {}, credentialBindings: { jobs: credential.id },
+      workspaceId: "diagnostics", invocationId: "diagnostics", correlationId: "diagnostics" });
+    expect(JSON.stringify(diagnostics)).not.toContain(ROTATED_SECRET_CANARY);
+    expect(JSON.stringify(diagnostics)).toContain("[REDACTED]");
+    diagnosticMode = false;
     await expect(jobApi.unavailable()).rejects.toThrow(/jobs provider unavailable/i);
-    const unavailableEmailProvider: SideEffectProvider = {
-      send: vi.fn(async () => { throw new Error("mock email provider unavailable"); }),
-    };
-    const failedDelivery = await new OutboxService(new AutomationOutboxRepository(storage), unavailableEmailProvider, audit).dispatch({
-      projectId: project.id, flowId: run.flowId, publicationId: latestAfterRollback.id, runId: run.id,
-      nodeId: "send", logicalItem: "provider-unavailable", effectType: "email", payload: { to: "nobody@example.test" },
-    });
+    emailUnavailable = true;
+    const failedDelivery = await outboxService.dispatch({ projectId: project.id, flowId: draft.flowId,
+      publicationId: latestAfterRollback.id, runId, nodeId: "send-unavailable", logicalItem: "provider-unavailable",
+      effectType: "email", payload: { to: "nobody@example.test" } });
     expect(failedDelivery).toMatchObject({ status: "failed", attemptCount: 1 });
-
     broker.revoke(project.id, credential.id);
-    await expect(broker.resolve({ projectId: project.id, bindingKey: "jobs-api", capability: "read", workspaceId: "revoked" })).rejects.toThrow(/not active/i);
+    await expect(customRuntime.execute({ projectId: project.id, nodeType: "custom.fixture-record-selector", version: 1,
+      input: {}, config: {}, credentialBindings: { jobs: credential.id }, workspaceId: "revoked", invocationId: "revoked", correlationId: "revoked" }))
+      .rejects.toThrow(/not active/i);
+
     keyAvailable = false;
     await request(app).get("/health").set("Host", "localhost").expect(200, { status: "UP" });
     await request(app).get("/ready").set("Host", "localhost").expect(503, /mock key provider unavailable/i);
     await expect(readinessService.assertStartupReady()).rejects.toThrow(/key recovery is unavailable/i);
-
     logger.error("credentialed automation diagnostic", { apiKey: FIRST_SECRET_CANARY, authorization: `Bearer ${ROTATED_SECRET_CANARY}` });
     const auditResponse = await authenticated(request(app).get(`/api/admin/audit/export?projectId=${project.id}`)).expect(200);
+    const invocations = executionRepository.listExecutionInvocations({ projectId: project.id, limit: 100 });
+    const invocationMessages = invocations.flatMap((invocation) => executionRepository.listExecutionInvocationMessages(invocation.id));
     const observable = JSON.stringify({
-      routeBodies: [customNodeResponse.body, validationResponse.body, draftResponse.body, patchResponse.body, rollbackResponse.body],
-      audit: auditResponse.text,
-      logs: capturedLogs,
-      diagnostics: { processed: records.length, selected: selected.length, outbox: persistedOutbox, readiness: readinessService.snapshot() },
+      mcpResponses: [draftEnvelope, customValidation, patched, rollbackDraft],
+      graphs: [flowRepository.getFlow(draft.flowId)?.graph, latestAfterRollback.graph],
+      attempts: flowRepository.listNodeAttempts(runId), invocationMessages, audit: auditResponse.text,
+      logs: capturedLogs, diagnostics, runSummaries: [summary, flowRepository.getRun(runId)],
     });
     expect(observable).not.toContain(FIRST_SECRET_CANARY);
     expect(observable).not.toContain(ROTATED_SECRET_CANARY);
     expect(observable).not.toContain(SERVICE_TOKEN);
     expect(observable).toContain("[REDACTED]");
-    expect(jobApi.list).toHaveBeenCalledTimes(1);
-    expect(commandRunner).toHaveBeenCalled();
     storage.close();
   });
 });

From 674e2728a2da3d96d92e2db611dbaf4c266cd6e8 Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 09:06:18 +0000
Subject: [PATCH 17/25] fix(ci): resolve failing checks on
 task/feature-codux-21-t15-codex-cc6303cc-mrhipsze

---
 scripts/e2e/run-mockup-sprint-pentest.mjs | 10 ++++++++--
 tests/backend/ci/workflow-health.test.ts  |  3 +++
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/scripts/e2e/run-mockup-sprint-pentest.mjs b/scripts/e2e/run-mockup-sprint-pentest.mjs
index efe8ce72f6..53a811d62b 100644
--- a/scripts/e2e/run-mockup-sprint-pentest.mjs
+++ b/scripts/e2e/run-mockup-sprint-pentest.mjs
@@ -1668,8 +1668,14 @@ const invokedAsCli = process.argv[1]
   : false;
 
 if (invokedAsCli) {
-  main().catch((error) => {
+  main().then(() => {
+    // Playwright's Electron transport can leave IPC handles referenced on Windows
+    // after the app and child processes have closed. main() has already flushed
+    // summaries and awaited cleanup, so terminate the CLI instead of letting a
+    // stale transport keep the CI job alive until its outer timeout.
+    process.exit(0);
+  }).catch((error) => {
     console.error(redact(error?.stack || error?.message || String(error)));
-    process.exitCode = 1;
+    process.exit(1);
   });
 }
diff --git a/tests/backend/ci/workflow-health.test.ts b/tests/backend/ci/workflow-health.test.ts
index c7bcd2786d..f948322850 100644
--- a/tests/backend/ci/workflow-health.test.ts
+++ b/tests/backend/ci/workflow-health.test.ts
@@ -402,6 +402,9 @@ describe("GitHub workflow health", () => {
     expect(runnerScript).toContain("expected QA follow-up for");
     expect(runnerScript).toContain('resolveExpectedQaOutcomes(sprintReviews, expected.sprintOutcomes || [], "sprint completion")');
     expect(runnerScript).toContain("expected command ${commandExpectation.command} to exit");
+    expect(runnerScript).toContain("main().then(() => {");
+    expect(runnerScript).toContain("process.exit(0);");
+    expect(runnerScript).toContain("process.exit(1);");
 
     const qaDagValidationTask = scenarioScript.slice(
       scenarioScript.indexOf('key: "qa-dag-validation"'),

From 1030768671a587eb19f1c4e81cdc1cf615ca6be7 Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 09:31:53 +0000
Subject: [PATCH 18/25] feat(task T21): implement via codex

---
 docs-web/content/docs/developer-mcp-tools.mdx |  9 ++--
 docs-web/content/docs/registry.ts             |  4 +-
 .../docs/user-dashboard-node-flows.mdx        | 46 ++++++-------------
 .../content/docs/user-dashboard-nodes.mdx     | 32 ++++++++-----
 docs-web/developer/mcp-tools.md               |  9 ++--
 docs-web/user/dashboard/node-flows.md         | 46 ++++++-------------
 docs-web/user/dashboard/nodes.md              | 32 ++++++++-----
 docs/dashboard/node-flows.md                  | 26 ++++++-----
 docs/dashboard/nodes.md                       | 32 ++++++++-----
 docs/mcp/tools-and-contracts.md               |  2 +-
 10 files changed, 122 insertions(+), 116 deletions(-)

diff --git a/docs-web/content/docs/developer-mcp-tools.mdx b/docs-web/content/docs/developer-mcp-tools.mdx
index 785ad691b6..ccd081a3a0 100644
--- a/docs-web/content/docs/developer-mcp-tools.mdx
+++ b/docs-web/content/docs/developer-mcp-tools.mdx
@@ -200,9 +200,12 @@ Agents should build Code UX-adapted node flows rather than cloning n8n workflows
 should include dynamic widget schemas for editable graph inputs and node fields; callers can provide
 `widgets` as a graph-level `{ fields: [...] }` schema or as node-id keys mapped to node widget schemas.
 
-Executable node types are currently `input`, `set_fields`, `template`, `provider_prompt`,
-`http_request`, and `output`. Graph validation accepts structured drafts, but runtime execution rejects
-unsupported node types.
+The governed built-ins currently registered with executable handlers are `input`, `set_fields`,
+`template`, `provider_prompt`, `http_request`, `condition`, `switch`, `foreach`, `merge`, `delay`,
+`approval`, `email_draft`, `email_send`, `execute_subflow`, `webhook_trigger`, and `output`. A
+registered custom definition can execute only when its validated versioned manifest, immutable
+artifact, and custom-node runtime are available. Unknown, legacy, mockup, and non-executable
+definitions remain planned or unavailable and are rejected by runtime dispatch.
 
 Minimal create payload:
 
diff --git a/docs-web/content/docs/registry.ts b/docs-web/content/docs/registry.ts
index 29351c228c..c346b5dcaf 100644
--- a/docs-web/content/docs/registry.ts
+++ b/docs-web/content/docs/registry.ts
@@ -260,7 +260,7 @@ export const docsRegistry: Record<DocsSlug, DocsRegistryEntry> = {
     path: '/docs/user-dashboard-nodes',
     section: 'User Guide',
     title: "Nodes",
-    description: "The Nodes page (/nodes) opens the browser-local Nodes Canvas workspace for drafting Code UX workflow graphs. It does not require a selected project and does not call the node-flow backend APIs.",
+    description: "The Nodes page (/nodes) is the project-scoped backend workspace for authoring and operating governed node flows. Select a project to load its flow library, credential metadata, publications, and durable run history; w...",
   },
   'user-dashboard-nodes-canvas': {
     id: 'user-dashboard-nodes-canvas',
@@ -274,7 +274,7 @@ export const docsRegistry: Record<DocsSlug, DocsRegistryEntry> = {
     path: '/docs/user-dashboard-node-flows',
     section: 'User Guide',
     title: "Node Flows",
-    description: "The Nodes page (/nodes) is where dashboard users create and operate saved node-flow workflows for the active project. A node flow is a repeatable graph that can be validated, run manually, scheduled, inspected through...",
+    description: "The Nodes page (/nodes) is the project-scoped backend authoring, publication, and operations surface for canonical node flows. No selected project means no flow library, credential metadata, publications, or durable r...",
   },
   'user-dashboard-scheduler': {
     id: 'user-dashboard-scheduler',
diff --git a/docs-web/content/docs/user-dashboard-node-flows.mdx b/docs-web/content/docs/user-dashboard-node-flows.mdx
index 0b39ac2177..c3593cc4e5 100644
--- a/docs-web/content/docs/user-dashboard-node-flows.mdx
+++ b/docs-web/content/docs/user-dashboard-node-flows.mdx
@@ -1,47 +1,31 @@
 # Node Flows
 
-The **Nodes** page (`/nodes`) is where dashboard users create and operate saved node-flow workflows for the active project. A node flow is a repeatable graph that can be validated, run manually, scheduled, inspected through persisted runs, and attached to project agents as a reusable skill.
+The **Nodes** page (`/nodes`) is the project-scoped backend authoring, publication, and operations surface for canonical node flows. No selected project means no flow library, credential metadata, publications, or durable run history are requested.
 
-## Flow Library And Canvas
+## Library, Drafts, And Migration
 
-The flow library lists project-owned flows. Selecting one opens an editable graph canvas with nodes, directed edges, positions, and node JSON data. The canvas is built into Code UX and is not a generic n8n importer; runtime execution supports Code UX node types rather than arbitrary external workflow nodes.
+The flow library contains backend drafts and publications owned by the active project. Saves include the loaded draft revision, so a concurrent edit produces a visible conflict and never overwrites newer work.
 
-New editable canvas surfaces use a pure dashboard state module for typed nodes, ports, edges, config fields, selection, deterministic layout, validation issues, JSON serialization, and malformed-draft recovery. Its starter graph lays out trigger, agent, task, condition, and output nodes so workflows begin from a useful Code UX shape.
+The former browser graph at `codeux:nodes-canvas:v1` is eligible for one import into the selected project. Code UX normalizes it to Graph v2, creates an **Imported Nodes Canvas** backend draft, and only then removes the legacy value and records a project-specific marker. A failed import remains retryable, while a successful marker prevents duplicates. Browser storage is never the ongoing workflow source of truth.
 
-Agent-driven graph edits use a separate UI-free helper that accepts structured JSON commands for adding nodes, patching node fields, connecting ports, deleting graph entities, selecting entities, and replacing a graph from serialized JSON. The helper applies commands through the canvas reducer and returns deterministic summaries, diffs, and validation blockers.
+## Registry-Driven Editing And Credentials
 
-Side panels stay controlled by the page shell: the palette emits typed create-node actions, the inspector
-emits field/config/metadata changes for the selected node, edge details are read-only, and validation
-issues expose select/focus callbacks for the affected node or edge.
+The versioned node-definition registry supplies palette entries, typed ports, configuration and widget schemas, execution availability, capabilities, side effects, policies, and credential requirements. Selecting a definition loads its manifest and renders the inspector from that contract. Graphs reference a definition version and store non-secret configuration and credential ids; they do not contain custom-node source or resolved credentials.
 
-## Dynamic Widgets
+Credential slots display metadata-only states such as bound, missing, or denied and can request a binding. Secret values remain behind the credential broker and are excluded from graphs and browser output.
 
-The inspector renders widget schemas attached to the selected node. Supported field types are text, textarea, number, boolean, select, JSON, secret reference, and key-value entries. Graph-level input widgets describe manual or scheduled run input.
+The complete governed built-in set currently registered with executable handlers is `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, `condition`, `switch`, `foreach`, `merge`, `delay`, `approval`, `email_draft`, `email_send`, `execute_subflow`, `webhook_trigger`, and `output`.
 
-Use secret reference fields for credentials. Do not paste raw tokens, API keys, cookies, passwords, or private headers into widget defaults, node data, metadata, or run input.
+Registered custom definitions can execute only when their validated versioned manifest, immutable artifact, and custom-node runtime are available. Legacy `trigger`/`agent`/`task` canvas kinds, unknown or unregistered types, mockup entries, and definitions marked non-executable are planned or unavailable definitions, not executable handlers.
 
-## Validation
+## Governance And Publication
 
-Validation checks graph shape before saving: unique node ids, valid edge endpoints, acyclic edges, JSON-safe data, and valid widget field definitions. Validation issues are shown as field-level messages so you can repair the draft before saving.
+Draft review provides structural validation, policy findings, requested permissions, side-effect review, and a non-executing dry run. Publication requires the current draft revision, a valid governed review, and all required credentials. Each publication is an immutable snapshot; comparison and rollback operate on versioned history, and only a pinned or latest-published version can execute.
 
-A graph can be structurally valid even when it contains a future node type that the runtime cannot execute yet. Current executable node types are `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output`.
+## Durable Debugger And Scheduling
 
-## Running And Inspection
+The debugger reads persisted flow runs, node runs, attempt history, retry classifications and decisions, approval records, invocation links, timing, and redacted input and output. Pending approvals offer **Approve & continue** and **Reject** actions. A decision continues or terminates the same pinned run, and repeated decisions return its current durable state without duplicating a governed attempt or external send. The debugger also supports cancellation and safe retry.
 
-The manual run panel accepts JSON object input and starts a node-flow run. Runs persist both the parent flow result and per-node rows, including status, error messages, redacted input/output, and linked execution invocation ids when a provider or HTTP node is externally observable.
+Use the [Scheduler](/docs/user-dashboard-scheduler) to target a pinned or latest-published version. A flow can also be attached to a project agent preset as a reusable skill; removing the attachment does not remove the flow, publications, schedules, or run history.
 
-Rendered run payloads redact secret-shaped keys such as `apiKey`, `authorization`, `cookie`, `password`, `secret`, and `token`.
-
-The run debugger lists durable approvals beside node attempts. A pending item offers **Approve & continue** and **Reject** actions. The decision applies to the same pinned run, and repeated clicks return its current state without sending an approved external effect twice.
-
-## Agent Attachment
-
-A flow can be attached to a project agent preset as a repeatable skill with a name and description. Detaching removes only that binding; the flow, its graph, schedules, and run history remain in the project.
-
-## Scheduling
-
-Use the [Scheduler](/docs/user-dashboard-scheduler) page to run a saved node flow once or on a recurrence. Scheduled node-flow entries select a project-owned flow and may include optional JSON object input. Pause, resume, failure handling, and due-run behavior match the normal scheduler model.
-
-## Graph v2 boundary
-
-The dashboard edits the shared Graph v2 contract. The executable registry is limited to `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output`; planned palette concepts are not runtime handlers.
+Outside development builds, `/nodes` requires the Nodes feature flag plus the node-flow backend and automation-security prerequisites. Individual definitions can additionally require provider, credential-broker, egress, approval/outbox, webhook, or custom-runtime configuration. Catalog presence and feature visibility do not assert that an integration is configured or production-ready.
diff --git a/docs-web/content/docs/user-dashboard-nodes.mdx b/docs-web/content/docs/user-dashboard-nodes.mdx
index 923258a79e..cedf23159d 100644
--- a/docs-web/content/docs/user-dashboard-nodes.mdx
+++ b/docs-web/content/docs/user-dashboard-nodes.mdx
@@ -1,17 +1,27 @@
 # Nodes
 
-The **Nodes** page (`/nodes`) opens the browser-local Nodes Canvas workspace for drafting Code UX workflow graphs. It does not require a selected project and does not call the node-flow backend APIs.
+The **Nodes** page (`/nodes`) is the project-scoped backend workspace for authoring and operating governed node flows. Select a project to load its flow library, credential metadata, publications, and durable run history; without an active project, the page does not request node-flow data.
 
-Use it to:
+## Backend Workspace And Legacy Import
 
-- add trigger, agent, task, condition, and output nodes from the palette
-- select and move nodes on the canvas
-- edit selected node labels, descriptions, metadata intents, and config fields in the inspector
-- inspect selected edge source and target wiring
-- review local structural validation issues
-- import and export deterministic graph JSON
-- view command-friendly graph metadata for agent workflows
+Creating or saving a draft persists it in the selected project's canonical node-flow repository. Saves include the loaded draft revision, so a concurrent edit produces a visible conflict instead of overwriting newer work. Changing projects clears the current workspace before loading the next project's records.
 
-The graph is saved to browser `localStorage` under `codeux:nodes-canvas:v1`. There is no cloud sync, database persistence, or real workflow execution on this page.
+The former browser graph at `codeux:nodes-canvas:v1` is only a one-time migration source. On the first eligible load for a selected project, Code UX converts that graph to Graph v2 and creates an **Imported Nodes Canvas** backend draft. It removes the legacy value and records a project-specific marker only after creation succeeds; failed imports remain available for retry, and the marker prevents duplicate imports. Browser storage is not used for ongoing workflow persistence.
 
-For the full local canvas contract, see [Nodes Canvas](/docs/user-dashboard-nodes-canvas). For saved project-scoped node-flow runtime behavior, see [Node Flows](/docs/user-dashboard-node-flows).
+## Registry-Driven Editing And Execution
+
+The versioned node-definition registry drives palette entries, executable state, typed ports, configuration and widget schemas, credential slots, capabilities, side-effect classifications, and default policies. The inspector renders the selected manifest, while the graph stores its type/version reference, non-secret configuration, policies, and credential ids rather than custom source or secret values.
+
+The complete governed built-in set currently registered with executable handlers is `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, `condition`, `switch`, `foreach`, `merge`, `delay`, `approval`, `email_draft`, `email_send`, `execute_subflow`, `webhook_trigger`, and `output`.
+
+Registered custom definitions can execute only when their validated versioned manifest, immutable artifact, and custom-node runtime are available. Legacy `trigger`/`agent`/`task` canvas kinds, unknown or unregistered types, mockup entries, and definitions marked non-executable are planned or unavailable definitions, not executable handlers.
+
+## Review, Publication, And Debugging
+
+Validation and dry run report structural errors, requested capabilities, credential requirements, side-effect changes, and policy findings; dry run does not invoke handlers. Publication requires the current draft revision, a valid governed review, and every required credential binding. Published snapshots are immutable, and version comparison and rollback preserve that history. Only published versions run.
+
+The debugger reads persisted flow runs, node runs, attempts, retry decisions, approvals, invocation links, timing, and redacted input and output. Cancellation, safe retry, and approval decisions update the same durable pinned run rather than creating an unrelated execution. Scheduling targets a pinned or latest-published version from the [Scheduler](/docs/user-dashboard-scheduler).
+
+Outside development builds, the workspace requires the Nodes feature flag plus the node-flow backend and automation-security prerequisites. A definition can also require a configured provider, credential broker, allowed egress, approval/outbox services, webhook ingress, or custom-node runtime. Registry presence and feature visibility do not assert that an integration is configured or production-ready.
+
+For the detailed editing contract, see [Nodes Canvas](/docs/user-dashboard-nodes-canvas). For API behavior, publication, execution, and scheduling, see [Node Flows](/docs/user-dashboard-node-flows).
diff --git a/docs-web/developer/mcp-tools.md b/docs-web/developer/mcp-tools.md
index 7633d6ac16..2198cb93d5 100644
--- a/docs-web/developer/mcp-tools.md
+++ b/docs-web/developer/mcp-tools.md
@@ -200,9 +200,12 @@ Agents should build Code UX-adapted node flows rather than cloning n8n workflows
 should include dynamic widget schemas for editable graph inputs and node fields; callers can provide
 `widgets` as a graph-level `{ fields: [...] }` schema or as node-id keys mapped to node widget schemas.
 
-Executable node types are currently `input`, `set_fields`, `template`, `provider_prompt`,
-`http_request`, and `output`. Graph validation accepts structured drafts, but runtime execution rejects
-unsupported node types.
+The governed built-ins currently registered with executable handlers are `input`, `set_fields`,
+`template`, `provider_prompt`, `http_request`, `condition`, `switch`, `foreach`, `merge`, `delay`,
+`approval`, `email_draft`, `email_send`, `execute_subflow`, `webhook_trigger`, and `output`. A
+registered custom definition can execute only when its validated versioned manifest, immutable
+artifact, and custom-node runtime are available. Unknown, legacy, mockup, and non-executable
+definitions remain planned or unavailable and are rejected by runtime dispatch.
 
 Minimal create payload:
 
diff --git a/docs-web/user/dashboard/node-flows.md b/docs-web/user/dashboard/node-flows.md
index 0acfe45d15..efe7feebf2 100644
--- a/docs-web/user/dashboard/node-flows.md
+++ b/docs-web/user/dashboard/node-flows.md
@@ -1,47 +1,31 @@
 # Node Flows
 
-The **Nodes** page (`/nodes`) is where dashboard users create and operate saved node-flow workflows for the active project. A node flow is a repeatable graph that can be validated, run manually, scheduled, inspected through persisted runs, and attached to project agents as a reusable skill.
+The **Nodes** page (`/nodes`) is the project-scoped backend authoring, publication, and operations surface for canonical node flows. No selected project means no flow library, credential metadata, publications, or durable run history are requested.
 
-## Flow Library And Canvas
+## Library, Drafts, And Migration
 
-The flow library lists project-owned flows. Selecting one opens an editable graph canvas with nodes, directed edges, positions, and node JSON data. The canvas is built into Code UX and is not a generic n8n importer; runtime execution supports Code UX node types rather than arbitrary external workflow nodes.
+The flow library contains backend drafts and publications owned by the active project. Saves include the loaded draft revision, so a concurrent edit produces a visible conflict and never overwrites newer work.
 
-New editable canvas surfaces use a pure dashboard state module for typed nodes, ports, edges, config fields, selection, deterministic layout, validation issues, JSON serialization, and malformed-draft recovery. Its starter graph lays out trigger, agent, task, condition, and output nodes so workflows begin from a useful Code UX shape.
+The former browser graph at `codeux:nodes-canvas:v1` is eligible for one import into the selected project. Code UX normalizes it to Graph v2, creates an **Imported Nodes Canvas** backend draft, and only then removes the legacy value and records a project-specific marker. A failed import remains retryable, while a successful marker prevents duplicates. Browser storage is never the ongoing workflow source of truth.
 
-Agent-driven graph edits use a separate UI-free helper that accepts structured JSON commands for adding nodes, patching node fields, connecting ports, deleting graph entities, selecting entities, and replacing a graph from serialized JSON. The helper applies commands through the canvas reducer and returns deterministic summaries, diffs, and validation blockers.
+## Registry-Driven Editing And Credentials
 
-Side panels stay controlled by the page shell: the palette emits typed create-node actions, the inspector
-emits field/config/metadata changes for the selected node, edge details are read-only, and validation
-issues expose select/focus callbacks for the affected node or edge.
+The versioned node-definition registry supplies palette entries, typed ports, configuration and widget schemas, execution availability, capabilities, side effects, policies, and credential requirements. Selecting a definition loads its manifest and renders the inspector from that contract. Graphs reference a definition version and store non-secret configuration and credential ids; they do not contain custom-node source or resolved credentials.
 
-## Dynamic Widgets
+Credential slots display metadata-only states such as bound, missing, or denied and can request a binding. Secret values remain behind the credential broker and are excluded from graphs and browser output.
 
-The inspector renders widget schemas attached to the selected node. Supported field types are text, textarea, number, boolean, select, JSON, secret reference, and key-value entries. Graph-level input widgets describe manual or scheduled run input.
+The complete governed built-in set currently registered with executable handlers is `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, `condition`, `switch`, `foreach`, `merge`, `delay`, `approval`, `email_draft`, `email_send`, `execute_subflow`, `webhook_trigger`, and `output`.
 
-Use secret reference fields for credentials. Do not paste raw tokens, API keys, cookies, passwords, or private headers into widget defaults, node data, metadata, or run input.
+Registered custom definitions can execute only when their validated versioned manifest, immutable artifact, and custom-node runtime are available. Legacy `trigger`/`agent`/`task` canvas kinds, unknown or unregistered types, mockup entries, and definitions marked non-executable are planned or unavailable definitions, not executable handlers.
 
-## Validation
+## Governance And Publication
 
-Validation checks graph shape before saving: unique node ids, valid edge endpoints, acyclic edges, JSON-safe data, and valid widget field definitions. Validation issues are shown as field-level messages so you can repair the draft before saving.
+Draft review provides structural validation, policy findings, requested permissions, side-effect review, and a non-executing dry run. Publication requires the current draft revision, a valid governed review, and all required credentials. Each publication is an immutable snapshot; comparison and rollback operate on versioned history, and only a pinned or latest-published version can execute.
 
-A graph can be structurally valid even when it contains a future node type that the runtime cannot execute yet. Current executable node types are `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output`.
+## Durable Debugger And Scheduling
 
-## Running And Inspection
+The debugger reads persisted flow runs, node runs, attempt history, retry classifications and decisions, approval records, invocation links, timing, and redacted input and output. Pending approvals offer **Approve & continue** and **Reject** actions. A decision continues or terminates the same pinned run, and repeated decisions return its current durable state without duplicating a governed attempt or external send. The debugger also supports cancellation and safe retry.
 
-The manual run panel accepts JSON object input and starts a node-flow run. Runs persist both the parent flow result and per-node rows, including status, error messages, redacted input/output, and linked execution invocation ids when a provider or HTTP node is externally observable.
+Use the [Scheduler](./scheduler.md) to target a pinned or latest-published version. A flow can also be attached to a project agent preset as a reusable skill; removing the attachment does not remove the flow, publications, schedules, or run history.
 
-Rendered run payloads redact secret-shaped keys such as `apiKey`, `authorization`, `cookie`, `password`, `secret`, and `token`.
-
-The run debugger lists durable approvals beside node attempts. A pending item offers **Approve & continue** and **Reject** actions. The decision applies to the same pinned run, and repeated clicks return its current state without sending an approved external effect twice.
-
-## Agent Attachment
-
-A flow can be attached to a project agent preset as a repeatable skill with a name and description. Detaching removes only that binding; the flow, its graph, schedules, and run history remain in the project.
-
-## Scheduling
-
-Use the [Scheduler](./scheduler.md) page to run a saved node flow once or on a recurrence. Scheduled node-flow entries select a project-owned flow and may include optional JSON object input. Pause, resume, failure handling, and due-run behavior match the normal scheduler model.
-
-## Graph v2 boundary
-
-The dashboard edits the shared Graph v2 contract. The executable registry is limited to `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output`; planned palette concepts are not runtime handlers.
+Outside development builds, `/nodes` requires the Nodes feature flag plus the node-flow backend and automation-security prerequisites. Individual definitions can additionally require provider, credential-broker, egress, approval/outbox, webhook, or custom-runtime configuration. Catalog presence and feature visibility do not assert that an integration is configured or production-ready.
diff --git a/docs-web/user/dashboard/nodes.md b/docs-web/user/dashboard/nodes.md
index 4b2755fb6b..80c4cec3bc 100644
--- a/docs-web/user/dashboard/nodes.md
+++ b/docs-web/user/dashboard/nodes.md
@@ -1,17 +1,27 @@
 # Nodes
 
-The **Nodes** page (`/nodes`) opens the browser-local Nodes Canvas workspace for drafting Code UX workflow graphs. It does not require a selected project and does not call the node-flow backend APIs.
+The **Nodes** page (`/nodes`) is the project-scoped backend workspace for authoring and operating governed node flows. Select a project to load its flow library, credential metadata, publications, and durable run history; without an active project, the page does not request node-flow data.
 
-Use it to:
+## Backend Workspace And Legacy Import
 
-- add trigger, agent, task, condition, and output nodes from the palette
-- select and move nodes on the canvas
-- edit selected node labels, descriptions, metadata intents, and config fields in the inspector
-- inspect selected edge source and target wiring
-- review local structural validation issues
-- import and export deterministic graph JSON
-- view command-friendly graph metadata for agent workflows
+Creating or saving a draft persists it in the selected project's canonical node-flow repository. Saves include the loaded draft revision, so a concurrent edit produces a visible conflict instead of overwriting newer work. Changing projects clears the current workspace before loading the next project's records.
 
-The graph is saved to browser `localStorage` under `codeux:nodes-canvas:v1`. There is no cloud sync, database persistence, or real workflow execution on this page.
+The former browser graph at `codeux:nodes-canvas:v1` is only a one-time migration source. On the first eligible load for a selected project, Code UX converts that graph to Graph v2 and creates an **Imported Nodes Canvas** backend draft. It removes the legacy value and records a project-specific marker only after creation succeeds; failed imports remain available for retry, and the marker prevents duplicate imports. Browser storage is not used for ongoing workflow persistence.
 
-For the full local canvas contract, see [Nodes Canvas](./nodes-canvas.md). For saved project-scoped node-flow runtime behavior, see [Node Flows](./node-flows.md).
+## Registry-Driven Editing And Execution
+
+The versioned node-definition registry drives palette entries, executable state, typed ports, configuration and widget schemas, credential slots, capabilities, side-effect classifications, and default policies. The inspector renders the selected manifest, while the graph stores its type/version reference, non-secret configuration, policies, and credential ids rather than custom source or secret values.
+
+The complete governed built-in set currently registered with executable handlers is `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, `condition`, `switch`, `foreach`, `merge`, `delay`, `approval`, `email_draft`, `email_send`, `execute_subflow`, `webhook_trigger`, and `output`.
+
+Registered custom definitions can execute only when their validated versioned manifest, immutable artifact, and custom-node runtime are available. Legacy `trigger`/`agent`/`task` canvas kinds, unknown or unregistered types, mockup entries, and definitions marked non-executable are planned or unavailable definitions, not executable handlers.
+
+## Review, Publication, And Debugging
+
+Validation and dry run report structural errors, requested capabilities, credential requirements, side-effect changes, and policy findings; dry run does not invoke handlers. Publication requires the current draft revision, a valid governed review, and every required credential binding. Published snapshots are immutable, and version comparison and rollback preserve that history. Only published versions run.
+
+The debugger reads persisted flow runs, node runs, attempts, retry decisions, approvals, invocation links, timing, and redacted input and output. Cancellation, safe retry, and approval decisions update the same durable pinned run rather than creating an unrelated execution. Scheduling targets a pinned or latest-published version from the [Scheduler](./scheduler.md).
+
+Outside development builds, the workspace requires the Nodes feature flag plus the node-flow backend and automation-security prerequisites. A definition can also require a configured provider, credential broker, allowed egress, approval/outbox services, webhook ingress, or custom-node runtime. Registry presence and feature visibility do not assert that an integration is configured or production-ready.
+
+For the detailed editing contract, see [Nodes Canvas](./nodes-canvas.md). For API behavior, publication, execution, and scheduling, see [Node Flows](./node-flows.md).
diff --git a/docs/dashboard/node-flows.md b/docs/dashboard/node-flows.md
index 80c54871a6..54517209b3 100644
--- a/docs/dashboard/node-flows.md
+++ b/docs/dashboard/node-flows.md
@@ -1,29 +1,31 @@
 # Node Flows Dashboard
 
-The **Nodes** page (`/nodes`) is the project-scoped authoring and operations surface for canonical node flows. No selected project means no flow library, credentials, publications, or run history are requested.
+The **Nodes** page (`/nodes`) is the project-scoped backend authoring, publication, and operations surface for canonical node flows. No selected project means no flow library, credential metadata, publications, or durable run history are requested.
 
-## Library and drafts
+## Library, drafts, and migration
 
 The library loads through `GET /api/projects/:projectId/node-flows`. Drafts are created through `POST /api/projects/:projectId/node-flow-drafts` and saved through revision-checked `PATCH /api/node-flow-drafts/:flowId`. A stale revision produces a visible conflict and never overwrites newer work.
 
-The former browser canvas is eligible for one project-specific import. After a successful backend draft creation, its graph value is removed and a migration marker prevents duplicates. Browser storage is never used for ongoing persistence.
+The former browser graph at `codeux:nodes-canvas:v1` is eligible for one import into the selected project. Code UX normalizes it to Graph v2, creates an **Imported Nodes Canvas** backend draft, and only then removes the legacy value and records a project-specific marker. A failed import remains retryable, while a successful marker prevents duplicates. Browser storage is never the ongoing workflow source of truth.
 
-## Registry and credentials
+## Registry-driven editing and credentials
 
-`GET /api/node-flow-catalog` is the registry source for palette entries, typed ports, configuration and widget schemas, execution availability, capabilities, side effects, policies, and credential requirements. Selecting a definition loads its full versioned manifest. Graphs reference a definition version and do not contain custom-node source.
+`GET /api/node-flow-catalog` is the versioned registry source for palette entries, typed ports, configuration and widget schemas, execution availability, capabilities, side effects, policies, and credential requirements. Selecting a definition loads its manifest and renders the inspector from that contract. Graphs reference a definition version and store non-secret configuration and credential ids; they do not contain custom-node source or resolved credentials.
 
-The inspector displays credential slots as bound, missing, or denied and can request a binding. It displays credential metadata only; secret values never enter the graph or dashboard output.
+Credential slots display metadata-only states such as bound, missing, or denied and can request a binding. Secret values remain behind the credential broker and are excluded from graphs, browser output, logs, and documentation examples.
 
-The registered governed built-ins are `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, `condition`, `switch`, `foreach`, `merge`, `delay`, `approval`, `email_draft`, `email_send`, `execute_subflow`, `webhook_trigger`, and `output`. Registered, validated custom definitions can execute when their immutable artifact and runtime are available. Legacy canvas kinds, unregistered names, and definitions marked non-executable remain planning or unavailable definitions and cannot run.
+The complete governed built-in set currently registered with executable handlers is `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, `condition`, `switch`, `foreach`, `merge`, `delay`, `approval`, `email_draft`, `email_send`, `execute_subflow`, `webhook_trigger`, and `output`.
+
+Registered custom definitions can execute only when their validated versioned manifest, immutable artifact, and custom-node runtime are available. Legacy `trigger`/`agent`/`task` canvas kinds, unknown or unregistered types, mockup entries, and definitions marked non-executable are planned or unavailable definitions, not executable handlers.
 
 ## Governance and publication
 
-T06 draft endpoints provide structural validation, policy findings, requested permissions, side-effect review, dry runs, immutable publication, version comparison, and rollback. Dry runs never execute nodes. Only a valid draft with satisfied required credentials can publish, and only published versions execute.
+Draft review provides structural validation, policy findings, requested permissions, side-effect review, and a non-executing dry run. Publication requires the current draft revision, a valid governed review, and all required credentials. Each publication is an immutable snapshot; comparison and rollback operate on versioned history, and only a pinned or latest-published version can execute.
 
-## Run debugger and scheduling
+## Durable debugger and scheduling
 
-The debugger reads persisted runs, node runs, attempt history, and approval decisions. Pending approvals expose keyboard-accessible **Approve & continue** and **Reject** actions. A decision continues or terminates the same pinned run, and repeated clicks return its current durable state without duplicating the governed attempt or external send. The debugger also overlays node state, shows retry reasons and decisions, links invocation ids, reports timing, supports cancellation and safe retry, and redacts secret-shaped values before rendering. Scheduling is entered through `/scheduler`; scheduler execution also resolves published versions.
+The debugger reads persisted flow runs, node runs, attempt history, retry classifications and decisions, approval records, invocation links, timing, and redacted input and output. Pending approvals expose keyboard-accessible **Approve & continue** and **Reject** actions. A decision continues or terminates the same pinned run, and repeated decisions return its current durable state without duplicating a governed attempt or external send. The debugger also supports cancellation and safe retry.
 
-The layout stacks on small screens, preserves keyboard-visible focus, labels loading/error/empty states, and bounds long histories and JSON output with scrolling.
+Scheduling is entered through `/scheduler` and targets a pinned or latest-published version. A flow can also be attached to a project agent preset as a reusable skill; removing the attachment does not remove the flow, publications, schedules, or run history.
 
-Outside development, `/nodes` requires the Nodes feature flag plus the node-flow backend and automation-security prerequisites. Individual definitions can require additional provider, credential-broker, egress, approval/outbox, webhook, or custom-runtime configuration; catalog presence alone does not assert production readiness for an integration.
+Outside development builds, `/nodes` requires the Nodes feature flag plus the node-flow backend and automation-security prerequisites. Individual definitions can additionally require provider, credential-broker, egress, approval/outbox, webhook, or custom-runtime configuration. Catalog presence and feature visibility do not assert that an integration is configured or production-ready.
diff --git a/docs/dashboard/nodes.md b/docs/dashboard/nodes.md
index 78b5679e7b..675204f44f 100644
--- a/docs/dashboard/nodes.md
+++ b/docs/dashboard/nodes.md
@@ -1,17 +1,27 @@
 # Nodes
 
-The **Nodes** page (`/nodes`) opens the browser-local Nodes Canvas workspace for drafting Code UX workflow graphs. It does not require a selected project and does not call the node-flow backend APIs.
+The **Nodes** page (`/nodes`) is the project-scoped backend workspace for authoring and operating governed node flows. Select a project to load its flow library, credential metadata, publications, and durable run history; without an active project, the page does not request node-flow data.
 
-Use it to:
+## Backend workspace and legacy import
 
-- add trigger, agent, task, condition, and output nodes from the palette
-- select and move nodes on the canvas
-- edit selected node labels, descriptions, metadata intents, and config fields in the inspector
-- inspect selected edge source and target wiring
-- review local structural validation issues
-- import and export deterministic graph JSON
-- view command-friendly graph metadata for agent workflows
+Creating or saving a draft persists it in the selected project's canonical node-flow repository. Saves include the loaded draft revision, so a concurrent edit produces a visible conflict instead of overwriting newer work. Changing projects clears the current workspace before loading the next project's records.
 
-The graph is saved to browser `localStorage` under `codeux:nodes-canvas:v1`. There is no cloud sync, database persistence, or real workflow execution on this page.
+The former browser graph at `codeux:nodes-canvas:v1` is only a one-time migration source. On the first eligible load for a selected project, Code UX converts that graph to Graph v2 and creates an **Imported Nodes Canvas** backend draft. It removes the legacy value and records a project-specific marker only after creation succeeds; failed imports remain available for retry, and the marker prevents duplicate imports. Browser storage is not used for ongoing workflow persistence.
 
-For the full local canvas contract, see [Nodes Canvas](./nodes-canvas.md). For the saved project-scoped runtime, validation API, manual runs, scheduling, and agent-skill attachments, see [Node Flows Dashboard](./node-flows.md).
+## Registry-driven editing and execution
+
+The versioned node-definition registry drives palette entries, executable state, typed ports, configuration and widget schemas, credential slots, capabilities, side-effect classifications, and default policies. The inspector renders the selected manifest, while the graph stores its type/version reference, non-secret configuration, policies, and credential ids rather than custom source or secret values.
+
+The complete governed built-in set currently registered with executable handlers is `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, `condition`, `switch`, `foreach`, `merge`, `delay`, `approval`, `email_draft`, `email_send`, `execute_subflow`, `webhook_trigger`, and `output`.
+
+Registered custom definitions can execute only when their validated versioned manifest, immutable artifact, and custom-node runtime are available. Legacy `trigger`/`agent`/`task` canvas kinds, unknown or unregistered types, mockup entries, and definitions marked non-executable are planned or unavailable definitions, not executable handlers.
+
+## Review, publication, and debugging
+
+Validation and dry run report structural errors, requested capabilities, credential requirements, side-effect changes, and policy findings; dry run does not invoke handlers. Publication requires the current draft revision, a valid governed review, and every required credential binding. Published snapshots are immutable, and version comparison and rollback preserve that history. Only published versions run.
+
+The debugger reads persisted flow runs, node runs, attempts, retry decisions, approvals, invocation links, timing, and redacted input and output. Cancellation, safe retry, and approval decisions update the same durable pinned run rather than creating an unrelated execution. Scheduling targets a pinned or latest-published version from the [Scheduler](./scheduler.md).
+
+Outside development builds, the workspace requires the Nodes feature flag plus the node-flow backend and automation-security prerequisites. A definition can also require a configured provider, credential broker, allowed egress, approval/outbox services, webhook ingress, or custom-node runtime. Registry presence and feature visibility do not assert that an integration is configured or production-ready.
+
+For the detailed editing contract, see [Nodes Canvas](./nodes-canvas.md). For API behavior, publication, execution, and scheduling, see [Node Flows Dashboard](./node-flows.md).
diff --git a/docs/mcp/tools-and-contracts.md b/docs/mcp/tools-and-contracts.md
index f802016e77..b4d5c2c74f 100644
--- a/docs/mcp/tools-and-contracts.md
+++ b/docs/mcp/tools-and-contracts.md
@@ -438,7 +438,7 @@ The graph payload is the shared `NodeFlowGraph` contract:
 - `inputSchema`: optional graph-level widget schema for run input
 - `metadata`: optional JSON object
 
-Validation checks graph shape, unique node ids, edge endpoints, acyclicity, JSON-safe node data, widget schema fields, select options, finite numeric constraints, and default values that match field types. Runtime support is narrower than graph storage: executable node types are currently `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output`.
+Validation checks graph shape, unique node ids, edge endpoints, acyclicity, JSON-safe node data, widget schema fields, select options, finite numeric constraints, and default values that match field types. The governed built-ins currently registered with executable handlers are `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, `condition`, `switch`, `foreach`, `merge`, `delay`, `approval`, `email_draft`, `email_send`, `execute_subflow`, `webhook_trigger`, and `output`. A registered custom definition can execute only when its validated versioned manifest, immutable artifact, and custom-node runtime are available; unknown, legacy, mockup, and non-executable definitions remain planned or unavailable and are rejected by runtime dispatch.
 
 Agents should build Code UX-adapted flows from structured graph specs instead of cloning n8n workflows one-to-one. A good flow exposes the values an operator or agent should edit, keeps runtime behavior repeatable, names nodes by Code UX behavior, and validates every required field before saving. MCP callers can provide `widgets` as a graph-level `{ fields: [...] }` schema or as node-id keys mapped to each node's `widgetSchema`.
 

From 44928236a15fa8a8872c27425eea6460b6590993 Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 09:33:56 +0000
Subject: [PATCH 19/25] feat(task T18): implement via codex

---
 .../docs/developer-management-actions.mdx     |   4 +-
 docs-web/content/docs/developer-mcp-tools.mdx |   2 +
 docs-web/developer/management-actions.md      |   4 +-
 docs-web/developer/mcp-tools.md               |   2 +
 docs/mcp/tools-and-contracts.md               |   3 +
 src/mcp/management-tool-handler.ts            |   4 +-
 src/mcp/management/node-flow-actions.ts       |  27 +++-
 .../mcp/management-node-flow-actions.test.ts  | 122 +++++++++++++++++-
 8 files changed, 161 insertions(+), 7 deletions(-)

diff --git a/docs-web/content/docs/developer-management-actions.mdx b/docs-web/content/docs/developer-management-actions.mdx
index 8bf6fe17e6..d9a7e60866 100644
--- a/docs-web/content/docs/developer-management-actions.mdx
+++ b/docs-web/content/docs/developer-management-actions.mdx
@@ -122,10 +122,12 @@ Task create/update fields include `title`, `name`, `promptMarkdown`, `descriptio
 | Custom nodes | – | `create_custom_node`, `update_custom_node`, and `validate_custom_node` reuse the governed project/build services. |
 | Credentials | – | `request_credential` and `inspect_bindings` expose metadata and permission findings only. |
 | Review | – / ✅ | `dry_run` is side-effect free; `publish` and `rollback` require exact-payload approval; `compare_versions` returns structural summaries. |
-| Operations | – | `run`, `cancel`, `retry`, `inspect_run`, and `list_runs` enforce project ownership and publication selection. |
+| Operations | – | `run`, `cancel`, `retry`, `inspect_run`, and `list_runs` enforce project ownership and publication selection. Run, retry, and inspection summaries include durable redacted node attempts with attempt/retry outcomes, executor and invocation links, and artifact digests. |
 
 Compatibility aliases remain for legacy list/get/create/update/delete/validate/run/attach/detach calls. Legacy create/update auto-publish for backward compatibility; governed draft actions do not. Attachments grant the agent only `run_attached_flow`, never the full management surface.
 
+Attempt projections expose numbered status history, failure classifications, retry decisions, executor and execution-invocation identifiers, artifact digests, timestamps, and redacted input/output. They exclude credential values, credential-binding ids, and custom-node source. Attached agents continue to receive summary-only flow metadata rather than complete graphs.
+
 ---
 
 ## `scheduler`
diff --git a/docs-web/content/docs/developer-mcp-tools.mdx b/docs-web/content/docs/developer-mcp-tools.mdx
index 785ad691b6..05cbf01a46 100644
--- a/docs-web/content/docs/developer-mcp-tools.mdx
+++ b/docs-web/content/docs/developer-mcp-tools.mdx
@@ -194,6 +194,8 @@ memory remediation, or global scheduler destructive controls.
 
 `manage_node_flows` exposes governed project automation authoring through MCP. Draft patches require an optimistic `draftRevision`; conflicts return expected/actual revisions without writes. Validation and dry-run responses contain policy findings, required credentials, requested capabilities, side-effect diffs, and redacted summaries. Publication and rollback require exact-payload approval. Legacy CRUD/run/attach aliases remain compatible.
 
+Operational run, retry, and inspection responses include durable, numbered node attempts with statuses, failure classifications, retry decisions, executor and execution-invocation identifiers, artifact digests, timestamps, and redacted input/output. Credential values, credential-binding ids, and custom-node source are omitted. Attached agents still receive summary-only flow metadata and never complete graphs.
+
 Attached flows appear to the owning authenticated agent only as name, description, input schema, flow id, and the `run_attached_flow` operation. Calls enforce project ownership, attachment, publication, and credential policy and record agent/conversation provenance without exposing complete graphs or credential material.
 
 Agents should build Code UX-adapted node flows rather than cloning n8n workflows one-to-one. Graphs
diff --git a/docs-web/developer/management-actions.md b/docs-web/developer/management-actions.md
index 4ee6316e49..248fec50c9 100644
--- a/docs-web/developer/management-actions.md
+++ b/docs-web/developer/management-actions.md
@@ -122,10 +122,12 @@ Task create/update fields include `title`, `name`, `promptMarkdown`, `descriptio
 | Custom nodes | – | `create_custom_node`, `update_custom_node`, and `validate_custom_node` reuse the governed project/build services. |
 | Credentials | – | `request_credential` and `inspect_bindings` expose metadata and permission findings only. |
 | Review | – / ✅ | `dry_run` is side-effect free; `publish` and `rollback` require exact-payload approval; `compare_versions` returns structural summaries. |
-| Operations | – | `run`, `cancel`, `retry`, `inspect_run`, and `list_runs` enforce project ownership and publication selection. |
+| Operations | – | `run`, `cancel`, `retry`, `inspect_run`, and `list_runs` enforce project ownership and publication selection. Run, retry, and inspection summaries include durable redacted node attempts with attempt/retry outcomes, executor and invocation links, and artifact digests. |
 
 Compatibility aliases remain for legacy list/get/create/update/delete/validate/run/attach/detach calls. Legacy create/update auto-publish for backward compatibility; governed draft actions do not. Attachments grant the agent only `run_attached_flow`, never the full management surface.
 
+Attempt projections expose numbered status history, failure classifications, retry decisions, executor and execution-invocation identifiers, artifact digests, timestamps, and redacted input/output. They exclude credential values, credential-binding ids, and custom-node source. Attached agents continue to receive summary-only flow metadata rather than complete graphs.
+
 ---
 
 ## `scheduler`
diff --git a/docs-web/developer/mcp-tools.md b/docs-web/developer/mcp-tools.md
index 7633d6ac16..e806852d60 100644
--- a/docs-web/developer/mcp-tools.md
+++ b/docs-web/developer/mcp-tools.md
@@ -194,6 +194,8 @@ memory remediation, or global scheduler destructive controls.
 
 `manage_node_flows` exposes governed project automation authoring through MCP. Draft patches require an optimistic `draftRevision`; conflicts return expected/actual revisions without writes. Validation and dry-run responses contain policy findings, required credentials, requested capabilities, side-effect diffs, and redacted summaries. Publication and rollback require exact-payload approval. Legacy CRUD/run/attach aliases remain compatible.
 
+Operational run, retry, and inspection responses include durable, numbered node attempts with statuses, failure classifications, retry decisions, executor and execution-invocation identifiers, artifact digests, timestamps, and redacted input/output. Credential values, credential-binding ids, and custom-node source are omitted. Attached agents still receive summary-only flow metadata and never complete graphs.
+
 Attached flows appear to the owning authenticated agent only as name, description, input schema, flow id, and the `run_attached_flow` operation. Calls enforce project ownership, attachment, publication, and credential policy and record agent/conversation provenance without exposing complete graphs or credential material.
 
 Agents should build Code UX-adapted node flows rather than cloning n8n workflows one-to-one. Graphs
diff --git a/docs/mcp/tools-and-contracts.md b/docs/mcp/tools-and-contracts.md
index f802016e77..010cf9216c 100644
--- a/docs/mcp/tools-and-contracts.md
+++ b/docs/mcp/tools-and-contracts.md
@@ -431,6 +431,8 @@ New drafts are not executable until published. `patch_draft` requires the last o
 
 `dry_run` performs validation and policy simulation without executing nodes or side effects. It returns `executed: false`, redacted result metadata, and blockers such as missing or denied credential bindings. Credential actions return metadata only; decrypted credential values never cross the service or MCP response boundary. Custom-node validation reuses the governed project generator/build pipeline and returns checks, issues, capabilities, and credential slots rather than source bundles.
 
+Operational `run`, `retry`, and `inspect_run` responses include durable node-attempt history. Each governed attempt projection contains its attempt number and status, failure classification and retry decision, executor and execution-invocation identifiers, artifact digest, timestamps, and redacted input/output. Credential values, credential bindings, and custom-node source are excluded. `inspect_run` reloads attempts from durable storage, so successful attempts, retries, terminal failures, and `attention_required` decisions remain inspectable after the original call or a runtime restart.
+
 The graph payload is the shared `NodeFlowGraph` contract:
 
 - `nodes`: `{ id, type, title, description?, position?, widgetSchema?, data? }`
@@ -448,6 +450,7 @@ Secret-safe widget guidance:
 - do not put API keys, bearer tokens, cookies, passwords, or private headers in `graph.metadata`, `node.data`, widget defaults, run `input`, or examples
 - use placeholder references such as `settings.provider.default` or `secret://service/token`
 - treat MCP responses as redacted summaries; flow and run responses mask secret-shaped graph data, inputs, trigger payloads, node payloads, and outputs before returning them through MCP
+- treat attempt history as an operational summary: it exposes invocation links and artifact identity, but never credential values, credential-binding ids, or custom-node source
 
 Attach a flow as an agent skill:
 
diff --git a/src/mcp/management-tool-handler.ts b/src/mcp/management-tool-handler.ts
index 36e3870e22..4657ff32c9 100644
--- a/src/mcp/management-tool-handler.ts
+++ b/src/mcp/management-tool-handler.ts
@@ -72,7 +72,7 @@ import { SchedulerActions } from "./management/scheduler-actions.js";
 import { AgentSchedulerActions } from "./management/agent-scheduler-actions.js";
 import { SettingsActions } from "./management/settings-actions.js";
 import { AgentActions } from "./management/agent-actions.js";
-import { NodeFlowActions } from "./management/node-flow-actions.js";
+import { NodeFlowActions, formatRunSummary } from "./management/node-flow-actions.js";
 import { MemoryActions } from "./management/memory-actions.js";
 import { SkillActions } from "./management/skill-actions.js";
 import { ChatProviderActions } from "./management/chat-provider-actions.js";
@@ -473,7 +473,7 @@ export class ManagementToolHandler {
         conversationId: getCurrentMcpThreadId(),
         parameters: args.input,
       });
-      return { content: [{ type: "text", text: JSON.stringify({ result }, null, 2) }] };
+      return { content: [{ type: "text", text: JSON.stringify({ result: formatRunSummary(result) }, null, 2) }] };
     } catch (error) {
       return this.formatError("node_flows", "run_attached_flow", error);
     }
diff --git a/src/mcp/management/node-flow-actions.ts b/src/mcp/management/node-flow-actions.ts
index 997806ad6c..f1b89e274f 100644
--- a/src/mcp/management/node-flow-actions.ts
+++ b/src/mcp/management/node-flow-actions.ts
@@ -7,6 +7,7 @@ import type {
   NodeFlowJsonObject,
   NodeFlowJsonValue,
   NodeFlowNode,
+  NodeFlowNodeAttemptRecord,
   NodeFlowRecord,
   NodeFlowRunRecord,
   NodeFlowRunSummaryResponse,
@@ -313,6 +314,7 @@ export class NodeFlowActions {
           input: maskJsonObject(nodeRun.input),
           output: maskJsonObject(nodeRun.output),
         })),
+        attempts: this.nodeFlowService.listNodeAttempts(run.id).attempts.map(formatAttempt),
       },
     };
   }
@@ -451,7 +453,7 @@ function formatRun(run: NodeFlowRunRecord): Record<string, unknown> {
   };
 }
 
-function formatRunSummary(summary: NodeFlowRunSummaryResponse): Record<string, unknown> {
+export function formatRunSummary(summary: NodeFlowRunSummaryResponse): Record<string, unknown> {
   return {
     run: formatRun(summary.run),
     nodeRuns: summary.nodeRuns.map((nodeRun) => ({
@@ -459,10 +461,33 @@ function formatRunSummary(summary: NodeFlowRunSummaryResponse): Record<string, u
       input: maskJsonObject(nodeRun.input),
       output: maskJsonObject(nodeRun.output),
     })),
+    attempts: (summary.attempts ?? []).map(formatAttempt),
     output: maskJsonObject(summary.output),
   };
 }
 
+function formatAttempt(attempt: NodeFlowNodeAttemptRecord): Record<string, unknown> {
+  return {
+    id: attempt.id,
+    runId: attempt.runId,
+    nodeRunId: attempt.nodeRunId,
+    nodeId: attempt.nodeId,
+    attemptNumber: attempt.attemptNumber,
+    status: attempt.status,
+    executorId: attempt.executorId,
+    invocationId: attempt.invocationId,
+    artifactDigest: attempt.artifactDigest,
+    input: maskJsonObject(attempt.input),
+    output: maskJsonObject(attempt.output),
+    failureClassification: attempt.failureClassification,
+    retryDecision: attempt.retryDecision,
+    errorMessage: attempt.errorMessage,
+    startedAt: attempt.startedAt,
+    finishedAt: attempt.finishedAt,
+    createdAt: attempt.createdAt,
+  };
+}
+
 function maskGraph(graph: NodeFlowGraph): NodeFlowGraph {
   return {
     ...graph,
diff --git a/tests/backend/mcp/management-node-flow-actions.test.ts b/tests/backend/mcp/management-node-flow-actions.test.ts
index f6292447e7..d172627a8d 100644
--- a/tests/backend/mcp/management-node-flow-actions.test.ts
+++ b/tests/backend/mcp/management-node-flow-actions.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from "vitest";
 import { ManagementToolHandler } from "../../../src/mcp/management-tool-handler.js";
-import type { NodeFlowGraph, NodeFlowRecord } from "../../../src/contracts/node-flow-types.js";
+import type { NodeFlowGraph, NodeFlowNodeAttemptRecord, NodeFlowRecord } from "../../../src/contracts/node-flow-types.js";
 import { runWithMcpAgentContext } from "../../../src/server/mcp-agent-context.js";
 
 const validGraph: NodeFlowGraph = {
@@ -23,6 +23,28 @@ const flowRecord = (overrides: Partial<NodeFlowRecord> = {}): NodeFlowRecord =>
   ...overrides,
 });
 
+const attemptRecord = (overrides: Partial<NodeFlowNodeAttemptRecord> = {}): NodeFlowNodeAttemptRecord => ({
+  id: "attempt-1",
+  runId: "run-1",
+  nodeRunId: "node-run-1",
+  nodeId: "provider",
+  attemptNumber: 1,
+  status: "succeeded",
+  executorId: "executor-1",
+  invocationId: "invocation-1",
+  artifactDigest: "sha256:artifact-1",
+  input: { prompt: "Ship", apiKey: "secret-canary" },
+  output: { result: "done", authorization: "secret-canary" },
+  credentialIds: ["credential-1"],
+  failureClassification: null,
+  retryDecision: "stop",
+  errorMessage: null,
+  startedAt: "2026-07-07T00:00:00.000Z",
+  finishedAt: "2026-07-07T00:00:01.000Z",
+  createdAt: "2026-07-07T00:00:00.000Z",
+  ...overrides,
+});
+
 const createHandler = (nodeFlowService: Record<string, unknown>): ManagementToolHandler => new ManagementToolHandler({
   projectManagementRepository: {},
   sprintPreviewService: {},
@@ -78,6 +100,11 @@ describe("manage_node_flows", () => {
   });
 
   it("delegates runs to the node-flow runtime service through NodeFlowService", async () => {
+    const persistedAttempt = {
+      ...attemptRecord(),
+      customSource: "custom-source-canary",
+      sourceRevision: "source-revision-canary",
+    };
     const nodeFlowService = {
       runFlow: vi.fn(async () => ({
         run: {
@@ -98,6 +125,7 @@ describe("manage_node_flows", () => {
           updatedAt: "2026-07-07T00:00:01.000Z",
         },
         nodeRuns: [],
+        attempts: [persistedAttempt],
         output: { ok: true },
       })),
     };
@@ -117,6 +145,88 @@ describe("manage_node_flows", () => {
     });
     expect(parsed.result.run.id).toBe("run-1");
     expect(parsed.result.output).toEqual({ ok: true });
+    expect(parsed.result.attempts[0]).toMatchObject({
+      attemptNumber: 1,
+      status: "succeeded",
+      executorId: "executor-1",
+      invocationId: "invocation-1",
+      artifactDigest: "sha256:artifact-1",
+      input: { prompt: "Ship", apiKey: "[REDACTED]" },
+      output: { result: "done", authorization: "[REDACTED]" },
+      retryDecision: "stop",
+    });
+    expect(JSON.stringify(parsed)).not.toContain("secret-canary");
+    expect(JSON.stringify(parsed)).not.toContain("custom-source-canary");
+    expect(parsed.result.attempts[0]).not.toHaveProperty("credentialIds");
+    expect(parsed.result.attempts[0]).not.toHaveProperty("customSource");
+    expect(parsed.result.attempts[0]).not.toHaveProperty("sourceRevision");
+  });
+
+  it("inspects durable retries, terminal failures, and attention-required attempt decisions", async () => {
+    const attempts = [
+      attemptRecord({
+        id: "attempt-1",
+        attemptNumber: 1,
+        status: "failed",
+        failureClassification: "transient",
+        retryDecision: "retry",
+        invocationId: "invocation-retry-1",
+        artifactDigest: null,
+        output: null,
+        errorMessage: "Service temporarily unavailable",
+      }),
+      attemptRecord({
+        id: "attempt-2",
+        attemptNumber: 2,
+        status: "failed",
+        failureClassification: "permanent",
+        retryDecision: "stop",
+        invocationId: "invocation-retry-2",
+        artifactDigest: "sha256:failure-artifact",
+        errorMessage: "Request failed",
+      }),
+      attemptRecord({
+        id: "attempt-3",
+        nodeId: "external-write",
+        nodeRunId: "node-run-2",
+        attemptNumber: 1,
+        status: "failed",
+        failureClassification: "unknown_side_effect",
+        retryDecision: "attention_required",
+        invocationId: "invocation-attention-1",
+        artifactDigest: null,
+        errorMessage: "External outcome is unknown",
+      }),
+    ];
+    const nodeFlowService = {
+      getRun: vi.fn(() => ({
+        id: "run-1",
+        projectId: "project-1",
+        triggerPayload: null,
+        input: { password: "secret-canary" },
+        output: null,
+      })),
+      listNodeRuns: vi.fn(() => ({ nodeRuns: [] })),
+      listNodeAttempts: vi.fn(() => ({ attempts })),
+    };
+    const handler = createHandler(nodeFlowService);
+
+    const response = await handler.handleManageNodeFlows({
+      action: "inspect_run",
+      projectId: "project-1",
+      runId: "run-1",
+    });
+    const parsed = parseResponse(response);
+
+    expect(nodeFlowService.listNodeAttempts).toHaveBeenCalledWith("run-1");
+    expect(parsed.result.attempts).toEqual(expect.arrayContaining([
+      expect.objectContaining({ attemptNumber: 1, failureClassification: "transient", retryDecision: "retry", invocationId: "invocation-retry-1" }),
+      expect.objectContaining({ attemptNumber: 2, failureClassification: "permanent", retryDecision: "stop", invocationId: "invocation-retry-2", artifactDigest: "sha256:failure-artifact" }),
+      expect.objectContaining({ failureClassification: "unknown_side_effect", retryDecision: "attention_required", invocationId: "invocation-attention-1" }),
+    ]));
+    expect(parsed.result.run.input.password).toBe("[REDACTED]");
+    expect(JSON.stringify(parsed)).not.toContain("secret-canary");
+    expect(parsed.result.attempts.every((attempt: Record<string, unknown>) => !("credentialIds" in attempt))).toBe(true);
   });
 
   it("requires exact approval before deleting a flow", async () => {
@@ -195,6 +305,7 @@ describe("manage_node_flows", () => {
     const nodeFlowService = {
       get: vi.fn(() => flowRecord()),
       listAgentSkills: vi.fn(() => []),
+      validateDraft: vi.fn(() => ({ publishedVersion: 1, requiredCredentials: [] })),
     };
     const handler = createHandler(nodeFlowService);
 
@@ -205,6 +316,10 @@ describe("manage_node_flows", () => {
       apiToken: "[REDACTED]",
       visible: "ok",
     });
+
+    const agentResponse = await runWithMcpAgentContext("agent-1", "thread-1", () =>
+      handler.handleManageNodeFlows({ action: "get", flowId: "flow-1" }));
+    expect(parseResponse(agentResponse).result.flow).not.toHaveProperty("graph");
   });
 
   it("returns governed draft conflicts and structured dry-run findings", async () => {
@@ -239,7 +354,7 @@ describe("manage_node_flows", () => {
   });
 
   it("executes an attached flow with authenticated agent and conversation metadata", async () => {
-    const runFlow = vi.fn(async () => ({ run: { id: "run-1" }, nodeRuns: [], output: { ok: true } }));
+    const runFlow = vi.fn(async () => ({ run: { id: "run-1", triggerPayload: null, input: null, output: { ok: true } }, nodeRuns: [], attempts: [attemptRecord()], output: { ok: true } }));
     const handler = createHandler({
       listAgentSkillsForAgent: () => [{ flowId: "flow-1", skillName: "Review", description: "" }],
       get: () => ({ id: "flow-1", projectId: "project-1", graph: { nodes: [], edges: [] } }),
@@ -248,6 +363,9 @@ describe("manage_node_flows", () => {
     });
     const response = await runWithMcpAgentContext("agent-1", "thread-1", () => handler.handleRunAttachedFlow({ projectId: "project-1", flowId: "flow-1", input: { prompt: "review" } }));
     expect(parseResponse(response).result.run.id).toBe("run-1");
+    expect(parseResponse(response).result.attempts[0]).toMatchObject({ invocationId: "invocation-1", executorId: "executor-1" });
+    expect(JSON.stringify(parseResponse(response))).not.toContain("secret-canary");
+    expect(parseResponse(response).result.attempts[0]).not.toHaveProperty("credentialIds");
     expect(runFlow).toHaveBeenCalledWith("project-1", "flow-1", { prompt: "review" }, expect.objectContaining({
       triggerPayload: expect.objectContaining({ initiatingAgentId: "agent-1", conversationId: "thread-1" }),
     }));

From fcb7331f24030671e1af5fc18883bdf591773321 Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 09:37:05 +0000
Subject: [PATCH 20/25] feat(task T17): implement via codex

---
 dashboard/src/v2/NodesPage.tsx                | 63 ++++++++++--
 .../v2/components/nodes/NodeFlowInspector.tsx | 18 +++-
 dashboard/src/v2/lib/agent-preset-api.ts      |  4 +-
 .../docs/user-dashboard-node-flows.mdx        |  4 +
 .../docs/user-dashboard-nodes-canvas.mdx      |  4 +
 docs-web/user/dashboard/node-flows.md         |  4 +
 docs-web/user/dashboard/nodes-canvas.md       |  4 +
 docs/dashboard/node-flows.md                  |  6 ++
 docs/dashboard/nodes-canvas.md                |  4 +
 tests/dashboard/v2/nodes-page.test.tsx        | 96 ++++++++++++++++++-
 10 files changed, 195 insertions(+), 12 deletions(-)

diff --git a/dashboard/src/v2/NodesPage.tsx b/dashboard/src/v2/NodesPage.tsx
index 4af49b2dd2..6655475a8b 100644
--- a/dashboard/src/v2/NodesPage.tsx
+++ b/dashboard/src/v2/NodesPage.tsx
@@ -12,13 +12,14 @@ import { NodePalette } from "./components/nodes/NodePalette.js";
 import { NodeGovernancePanel } from "./components/nodes/NodeGovernancePanel.js";
 import { NodeRunDebugger } from "./components/nodes/NodeRunDebugger.js";
 import { useProjectData } from "./context/project-data.js";
-import type { AutomationApprovalRecord, NodeDefinitionManifest, NodeFlowDraftReview, NodeFlowGraph, NodeFlowNode, NodeFlowNodeAttemptRecord, NodeFlowNodeRunRecord, NodeFlowRecord, NodeFlowRunRecord } from "./types.js";
+import type { AgentPreset, AutomationApprovalRecord, NodeDefinitionManifest, NodeFlowDraftReview, NodeFlowGraph, NodeFlowNode, NodeFlowNodeAttemptRecord, NodeFlowNodeRunRecord, NodeFlowRecord, NodeFlowRunRecord, NodeFlowSkillAttachment } from "./types.js";
 import { createDefaultNodeFlowGraph, isNodeFlowDirty, updateNodeInGraph } from "./lib/node-flow-view-models.js";
 import { deserializeNodeCanvasGraphWithMigration, toCanonicalNodeFlowGraph } from "./lib/nodes-canvas-state.js";
+import { fetchAgentPresets } from "./lib/agent-preset-api.js";
 import {
-  cancelNodeFlowRun, compareNodeFlowVersions, createNodeFlowDraft, decideNodeFlowApproval, deleteNodeFlow, dryRunNodeFlowDraft,
+  attachNodeFlowToAgent, cancelNodeFlowRun, compareNodeFlowVersions, createNodeFlowDraft, decideNodeFlowApproval, deleteNodeFlow, detachNodeFlowFromAgent, dryRunNodeFlowDraft,
   fetchNodeDefinition, fetchNodeFlow, fetchNodeFlowApprovals, fetchNodeFlowAttempts, fetchNodeFlowCatalog, fetchNodeFlowNodeRuns,
-  fetchNodeFlowRuns, fetchNodeFlows, patchNodeFlowDraft, publishNodeFlowDraft, requestNodeFlowCredential,
+  fetchNodeFlowAgentSkills, fetchNodeFlowRuns, fetchNodeFlows, patchNodeFlowDraft, publishNodeFlowDraft, requestNodeFlowCredential,
   retryNodeFlowRun, rollbackNodeFlow, runNodeFlow, validateNodeFlowDraft,
   type NodeDefinitionSummary, type NodeFlowDryRunResponse, type NodeFlowVersionDiff,
 } from "./lib/node-flow-api.js";
@@ -31,8 +32,17 @@ export const NodesPage: FunctionComponent = () => {
   const { selectedProject, loading: projectLoading } = useProjectData();
   const projectId = selectedProject?.id ?? null;
   const projectRef = useRef(projectId); projectRef.current = projectId;
+  const flowRef = useRef<string | null>(null);
   const [flows, setFlows] = useState<NodeFlowRecord[]>([]);
   const [catalog, setCatalog] = useState<NodeDefinitionSummary[]>([]);
+  const [agents, setAgents] = useState<AgentPreset[]>([]);
+  const [attachments, setAttachments] = useState<NodeFlowSkillAttachment[]>([]);
+  const [attachAgentId, setAttachAgentId] = useState("");
+  const [agentsLoading, setAgentsLoading] = useState(false);
+  const [flowAttachmentsLoading, setFlowAttachmentsLoading] = useState(false);
+  const [attachmentBusy, setAttachmentBusy] = useState(false);
+  const [agentsError, setAgentsError] = useState<string | null>(null);
+  const [flowAttachmentsError, setFlowAttachmentsError] = useState<string | null>(null);
   const [selectedFlowId, setSelectedFlowId] = useState<string | null>(null);
   const [record, setRecord] = useState<NodeFlowRecord | null>(null);
   const [title, setTitle] = useState("");
@@ -58,10 +68,39 @@ export const NodesPage: FunctionComponent = () => {
   const dirty = isNodeFlowDirty(record, title, description, graph);
 
   const applyRecord = useCallback((flow: NodeFlowRecord): void => {
+    flowRef.current = flow.id;
     setRecord(flow); setSelectedFlowId(flow.id); setTitle(flow.title); setDescription(flow.description); setGraph(flow.graph);
     setSelectedNodeId(flow.graph.nodes[0]?.id ?? null); setReview(null); setDryRun(null); setDiff(null);
   }, []);
 
+  const loadAgents = useCallback(async (nextProjectId: string, signal?: AbortSignal): Promise<void> => {
+    setAgentsLoading(true); setAgentsError(null);
+    try {
+      const nextAgents = await fetchAgentPresets(nextProjectId, signal);
+      if (projectRef.current !== nextProjectId) return;
+      setAgents(nextAgents.filter((agent) => agent.projectId === nextProjectId));
+    } catch (requestError) {
+      if (!signal?.aborted && projectRef.current === nextProjectId) setAgentsError(errorMessage(requestError));
+    } finally {
+      if (!signal?.aborted && projectRef.current === nextProjectId) setAgentsLoading(false);
+    }
+  }, []);
+
+  const loadAttachments = useCallback(async (nextProjectId: string, flowId: string, signal?: AbortSignal): Promise<boolean> => {
+    setFlowAttachmentsLoading(true); setFlowAttachmentsError(null);
+    try {
+      const nextAttachments = await fetchNodeFlowAgentSkills(flowId, signal);
+      if (projectRef.current !== nextProjectId || flowRef.current !== flowId) return false;
+      setAttachments(nextAttachments.filter((attachment) => attachment.projectId === nextProjectId && attachment.flowId === flowId));
+      return true;
+    } catch (requestError) {
+      if (!signal?.aborted && projectRef.current === nextProjectId && flowRef.current === flowId) setFlowAttachmentsError(errorMessage(requestError));
+      return false;
+    } finally {
+      if (!signal?.aborted && projectRef.current === nextProjectId && flowRef.current === flowId) setFlowAttachmentsLoading(false);
+    }
+  }, []);
+
   const loadLibrary = useCallback(async (nextProjectId: string, signal?: AbortSignal): Promise<void> => {
     setLoading(true); setError(null);
     try {
@@ -88,11 +127,19 @@ export const NodesPage: FunctionComponent = () => {
   }, [applyRecord, selectedFlowId]);
 
   useEffect(() => {
-    setFlows([]); setRecord(null); setSelectedFlowId(null); setRuns([]); setError(null); setNotice(null);
+    flowRef.current = null;
+    setFlows([]); setRecord(null); setSelectedFlowId(null); setRuns([]); setAgents([]); setAttachments([]); setAttachAgentId(""); setAgentsLoading(false); setFlowAttachmentsLoading(false); setAttachmentBusy(false); setAgentsError(null); setFlowAttachmentsError(null); setError(null); setNotice(null);
     if (!projectId) return;
-    const controller = new AbortController(); void loadLibrary(projectId, controller.signal); return () => controller.abort();
+    const controller = new AbortController(); void loadLibrary(projectId, controller.signal); void loadAgents(projectId, controller.signal); return () => controller.abort();
   }, [projectId]);
 
+  useEffect(() => {
+    setAttachments([]); setAttachAgentId(""); setFlowAttachmentsLoading(false); setAttachmentBusy(false); setFlowAttachmentsError(null);
+    if (!projectId || !record) return;
+    flowRef.current = record.id;
+    const controller = new AbortController(); void loadAttachments(projectId, record.id, controller.signal); return () => controller.abort();
+  }, [projectId, record?.id]);
+
   useEffect(() => {
     if (!selectedNode?.definition) return;
     const key = `${selectedNode.definition.type}@${selectedNode.definition.version}`;
@@ -118,6 +165,10 @@ export const NodesPage: FunctionComponent = () => {
   const compare = (): void => { if (!projectId || !record || !review?.publishedVersion) return; const publishedVersion = review.publishedVersion; void act(async () => setDiff(await compareNodeFlowVersions(projectId, record.id, publishedVersion, record.version))); };
   const rollback = (): void => { if (!projectId || !record || !review?.publishedVersion) return; void act(async () => { const next = await rollbackNodeFlow(projectId, record.id, review.publishedVersion!, record.version); const flow = await fetchNodeFlow(record.id); applyRecord(flow); setReview(next); }); };
   const run = (): void => { if (!projectId || !record) return; void act(async () => { const result = await runNodeFlow(record.id, { projectId, input: {} }); setRuns((current) => [result.run, ...current]); setSelectedRunId(result.run.id); setNodeRuns(result.nodeRuns); setAttempts(result.attempts ?? []); }); };
+  const mutateAttachment = (action: () => Promise<unknown>, successNotice: string): void => { if (!projectId || !record) return; const activeProjectId = projectId; const activeFlowId = record.id; void (async () => { setAttachmentBusy(true); setFlowAttachmentsError(null); setNotice(null); try { await action(); if (projectRef.current !== activeProjectId || flowRef.current !== activeFlowId) return; const refreshed = await loadAttachments(activeProjectId, activeFlowId); if (refreshed && projectRef.current === activeProjectId && flowRef.current === activeFlowId) { setAttachAgentId(""); setNotice(successNotice); } } catch (requestError) { if (projectRef.current === activeProjectId && flowRef.current === activeFlowId) setFlowAttachmentsError(errorMessage(requestError)); } finally { if (projectRef.current === activeProjectId && flowRef.current === activeFlowId) setAttachmentBusy(false); } })(); };
+  const attachAgent = (): void => { if (!projectId || !record || !attachAgentId || !agents.some((agent) => agent.id === attachAgentId && agent.projectId === projectId)) return; const flowId = record.id; const agentPresetId = attachAgentId; mutateAttachment(() => attachNodeFlowToAgent(flowId, { agentPresetId }), "Flow attached to the selected project agent."); };
+  const detachAgent = (agentPresetId: string): void => { if (!record) return; const flowId = record.id; mutateAttachment(() => detachNodeFlowFromAgent(flowId, agentPresetId), "Flow detached from the project agent."); };
+  const retryAttachments = (): void => { if (!projectId || !record) return; void loadAgents(projectId); void loadAttachments(projectId, record.id); };
 
   if (projectLoading) return <PageContainer><div role="status" className="p-10 text-sm text-slate-500">Loading project workspace…</div></PageContainer>;
   if (!selectedProject) return <PageContainer><PageHeader icon={Workflow} eyebrow="Nodes" title="Automation workspace" subtitle="Select a project to load its governed node-flow library." /><EmptyState icon={<Workflow className="h-7 w-7" />} title="Select a project" description="Flows, credentials, publications, and run history are always scoped to a project." /></PageContainer>;
@@ -128,7 +179,7 @@ export const NodesPage: FunctionComponent = () => {
     <div className="flex min-w-0 flex-col gap-4 xl:flex-row"><NodeFlowLibrary flows={flows} selectedFlowId={selectedFlowId} loading={loading} onSelect={selectFlow} onCreate={createFlow} onDelete={(id) => void act(async () => { await deleteNodeFlow(id); await loadLibrary(selectedProject.id); })} />
       <div className="min-w-0 flex-1">{record ? <div className="mb-3 grid gap-3 sm:grid-cols-2"><label className="text-xs font-bold uppercase text-slate-500">Flow name<input className="mt-1 w-full rounded-xl border border-black/[0.08] bg-white/70 px-3 py-2 text-sm normal-case dark:border-white/[0.08] dark:bg-white/[0.04]" value={title} onInput={(event) => setTitle(event.currentTarget.value)} /></label><label className="text-xs font-bold uppercase text-slate-500">Description<input className="mt-1 w-full rounded-xl border border-black/[0.08] bg-white/70 px-3 py-2 text-sm normal-case dark:border-white/[0.08] dark:bg-white/[0.04]" value={description} onInput={(event) => setDescription(event.currentTarget.value)} /></label></div> : null}{record ? <NodeFlowCanvas graph={graph} selectedNodeId={selectedNodeId} onSelectNode={setSelectedNodeId} onMoveNode={(id, position) => setGraph((current) => updateNodeInGraph(current, id, { position }))} /> : <EmptyState icon={<Workflow className="h-7 w-7" />} title="No flows in this project" description="Create a draft to start from the canonical backend workspace." primaryAction={<Button onClick={createFlow}>Create draft</Button>} />}</div>
       <NodePalette definitions={catalog} loading={loading} disabled={!record || busy} onCreateNode={addNode} />
-      {record ? <NodeFlowInspector selectedNode={selectedNode} definition={selectedDefinition} validation={review ? { valid: review.valid, errors: review.validationIssues } : null} requiredCredentials={review?.requiredCredentials.filter((item) => item.nodeId === selectedNode?.id) ?? []} agents={[]} attachments={[]} attachAgentId="" onAttachAgentIdChange={() => undefined} onAttachAgent={() => undefined} onDetachAgent={() => undefined} onNodeChange={(id, update) => setGraph((current) => updateNodeInGraph(current, id, update))} onRequestCredential={(nodeId, slot) => { if (projectId && record) void act(async () => { await requestNodeFlowCredential(projectId, record.id, nodeId, slot); setNotice("Credential binding request recorded; secret material remains outside the graph."); }); }} /> : null}
+      {record ? <NodeFlowInspector selectedNode={selectedNode} definition={selectedDefinition} validation={review ? { valid: review.valid, errors: review.validationIssues } : null} requiredCredentials={review?.requiredCredentials.filter((item) => item.nodeId === selectedNode?.id) ?? []} agents={agents} attachments={attachments} attachAgentId={attachAgentId} attachmentsLoading={agentsLoading || flowAttachmentsLoading} attachmentError={flowAttachmentsError ?? agentsError} attaching={attachmentBusy} onAttachAgentIdChange={setAttachAgentId} onAttachAgent={attachAgent} onDetachAgent={detachAgent} onRetryAttachments={retryAttachments} onNodeChange={(id, update) => setGraph((current) => updateNodeInGraph(current, id, update))} onRequestCredential={(nodeId, slot) => { if (projectId && record) void act(async () => { await requestNodeFlowCredential(projectId, record.id, nodeId, slot); setNotice("Credential binding request recorded; secret material remains outside the graph."); }); }} /> : null}
     </div>
     {record ? <><NodeGovernancePanel review={review} dryRun={dryRun} diff={diff} busy={busy} onValidate={validate} onDryRun={runDry} onCompare={compare} onPublish={publish} onRollback={rollback} /><NodeRunDebugger runs={runs} selectedRunId={selectedRunId} nodeRuns={nodeRuns} attempts={attempts} approvals={approvals} busy={busy} onSelectRun={setSelectedRunId} onRefresh={() => void act(refreshRuns)} onCancel={() => { const active = runs.find((item) => item.id === selectedRunId); if (projectId && active) void act(async () => { await cancelNodeFlowRun(projectId, active.id); await refreshRuns(); }); }} onRetry={() => { const active = runs.find((item) => item.id === selectedRunId); if (projectId && active) void act(async () => { const result = await retryNodeFlowRun(projectId, active.id); setRuns((current) => [result.run, ...current]); setSelectedRunId(result.run.id); }); }} onApprovalDecision={(approvalId, decision) => void act(async () => { const result = await decideNodeFlowApproval(approvalId, decision); setRuns((current) => current.map((item) => item.id === result.run.id ? result.run : item)); setNodeRuns(result.nodeRuns); setAttempts(result.attempts ?? []); setApprovals((current) => current.map((item) => item.id === approvalId ? { ...item, status: result.status, decidedAt: result.decidedAt, decidedBy: result.decidedBy, decision: result.decision, updatedAt: result.updatedAt } : item)); })} /></> : null}
   </PageContainer>;
diff --git a/dashboard/src/v2/components/nodes/NodeFlowInspector.tsx b/dashboard/src/v2/components/nodes/NodeFlowInspector.tsx
index 2c12419d5c..fa2beb4799 100644
--- a/dashboard/src/v2/components/nodes/NodeFlowInspector.tsx
+++ b/dashboard/src/v2/components/nodes/NodeFlowInspector.tsx
@@ -22,10 +22,13 @@ interface NodeFlowInspectorProps {
   agents: AgentPreset[];
   attachments: NodeFlowSkillAttachment[];
   attachAgentId: string;
+  attachmentsLoading?: boolean;
+  attachmentError?: string | null;
   attaching?: boolean;
   onAttachAgentIdChange: (agentPresetId: string) => void;
   onAttachAgent: () => void;
   onDetachAgent: (agentPresetId: string) => void;
+  onRetryAttachments?: () => void;
   onNodeChange: (nodeId: string, update: Partial<NodeFlowNode>) => void;
   definition?: NodeDefinitionManifest | null;
   requiredCredentials?: NodeFlowRequiredCredential[];
@@ -40,10 +43,13 @@ export const NodeFlowInspector: FunctionComponent<NodeFlowInspectorProps> = ({
   agents,
   attachments,
   attachAgentId,
+  attachmentsLoading = false,
+  attachmentError = null,
   attaching = false,
   onAttachAgentIdChange,
   onAttachAgent,
   onDetachAgent,
+  onRetryAttachments,
   onNodeChange,
   definition = null,
   requiredCredentials = [],
@@ -135,6 +141,13 @@ export const NodeFlowInspector: FunctionComponent<NodeFlowInspectorProps> = ({
 
       <section className="flex flex-col gap-3 border-t border-black/[0.06] pt-4 dark:border-white/[0.06]" aria-labelledby="node-agent-attachments-heading">
         <h3 id="node-agent-attachments-heading" className="text-xs font-bold uppercase tracking-[0.16em] text-slate-500 dark:text-slate-400">Agent Attachments</h3>
+        {attachmentsLoading ? <p role="status" className="text-xs text-slate-500 dark:text-slate-400">Loading project agents and flow attachments…</p> : null}
+        {attachmentError ? (
+          <div role="alert" className="rounded-xl border border-status-red/25 bg-status-red/[0.07] p-3 text-xs text-status-red">
+            {attachmentError}
+            {onRetryAttachments ? <button type="button" className="ml-2 font-bold underline focus:outline-none focus-visible:ring-2 focus-visible:ring-signal-500/40" onClick={onRetryAttachments}>Retry</button> : null}
+          </div>
+        ) : null}
         <div className="flex gap-2">
           <select
             aria-label="Agent preset"
@@ -143,14 +156,14 @@ export const NodeFlowInspector: FunctionComponent<NodeFlowInspectorProps> = ({
             onChange={(event) => onAttachAgentIdChange(event.currentTarget.value)}
           >
             <option value="">Select agent</option>
-            {agents.map((agent) => (
+            {agents.filter((agent) => !attachments.some((attachment) => attachment.agentPresetId === agent.id)).map((agent) => (
               <option key={agent.id} value={agent.id}>{agent.name}</option>
             ))}
           </select>
           <button
             type="button"
             aria-label="Attach node flow to agent"
-            disabled={!attachAgentId || attaching}
+            disabled={!attachAgentId || attaching || attachmentsLoading}
             onClick={onAttachAgent}
             className="flex h-10 w-10 shrink-0 items-center justify-center rounded-xl bg-signal-500 text-white transition hover:bg-signal-400 focus:outline-none focus-visible:ring-2 focus-visible:ring-signal-500/40 disabled:opacity-50 dark:text-void-900"
           >
@@ -172,6 +185,7 @@ export const NodeFlowInspector: FunctionComponent<NodeFlowInspectorProps> = ({
                   <button
                     type="button"
                     aria-label={`Detach ${agent?.name ?? attachment.agentPresetId}`}
+                    disabled={attaching}
                     className="flex h-8 w-8 items-center justify-center rounded-lg text-slate-400 transition hover:bg-status-red/[0.08] hover:text-status-red focus:outline-none focus-visible:ring-2 focus-visible:ring-signal-500/40"
                     onClick={() => onDetachAgent(attachment.agentPresetId)}
                   >
diff --git a/dashboard/src/v2/lib/agent-preset-api.ts b/dashboard/src/v2/lib/agent-preset-api.ts
index 5e765760fa..78926338dc 100644
--- a/dashboard/src/v2/lib/agent-preset-api.ts
+++ b/dashboard/src/v2/lib/agent-preset-api.ts
@@ -17,8 +17,8 @@ import type {
 } from "../../../../src/contracts/skill-types.js";
 import { fetchJson } from "../../lib/api/fetch-json.js";
 
-export const fetchAgentPresets = async (projectId: string): Promise<AgentPreset[]> => {
-  return fetchJson<AgentPreset[]>(`/api/projects/${encodeURIComponent(projectId)}/agent-presets`);
+export const fetchAgentPresets = async (projectId: string, signal?: AbortSignal): Promise<AgentPreset[]> => {
+  return fetchJson<AgentPreset[]>(`/api/projects/${encodeURIComponent(projectId)}/agent-presets`, { signal });
 };
 
 export const fetchBaseAgentUpdateNotices = async (projectId: string): Promise<BaseAgentUpdateNotice[]> => {
diff --git a/docs-web/content/docs/user-dashboard-node-flows.mdx b/docs-web/content/docs/user-dashboard-node-flows.mdx
index 0b39ac2177..42f7e9fd97 100644
--- a/docs-web/content/docs/user-dashboard-node-flows.mdx
+++ b/docs-web/content/docs/user-dashboard-node-flows.mdx
@@ -38,6 +38,10 @@ The run debugger lists durable approvals beside node attempts. A pending item of
 
 A flow can be attached to a project agent preset as a repeatable skill with a name and description. Detaching removes only that binding; the flow, its graph, schedules, and run history remain in the project.
 
+The Nodes workspace loads the selected project's agent presets together with the selected flow's existing bindings. Already attached agents are removed from the selector. Attach and detach actions are keyboard accessible, use the governed APIs, and refresh the binding list after success. Switching projects or flows clears selection and stale attachment state. A failed load or mutation leaves known bindings visible and exposes a retry action.
+
+The inspector displays attachment metadata only. An attached agent receives the narrow `run_attached_flow` operation, which still verifies project ownership, the binding, publication state, and credential policy without granting graph inspection, credential access, or `manage_node_flows`.
+
 ## Scheduling
 
 Use the [Scheduler](/docs/user-dashboard-scheduler) page to run a saved node flow once or on a recurrence. Scheduled node-flow entries select a project-owned flow and may include optional JSON object input. Pause, resume, failure handling, and due-run behavior match the normal scheduler model.
diff --git a/docs-web/content/docs/user-dashboard-nodes-canvas.mdx b/docs-web/content/docs/user-dashboard-nodes-canvas.mdx
index b8325b4b49..70f45970f2 100644
--- a/docs-web/content/docs/user-dashboard-nodes-canvas.mdx
+++ b/docs-web/content/docs/user-dashboard-nodes-canvas.mdx
@@ -26,6 +26,8 @@ Validated custom definitions can also execute after their immutable artifact and
 
 Credential slots display metadata-only status such as bound, missing, or denied and can submit a binding request. Secret values remain behind the credential broker and are not returned to the graph or browser.
 
+The selected flow also loads the active project's agent presets and current flow attachments. Attaching and detaching use the governed node-flow APIs and refresh the binding list after each successful mutation. Project or flow changes clear the prior selection and discard late responses from the old scope. Loading and retryable failure states remain visible while the inspector receives only agent and attachment metadata.
+
 Validation and dry run report graph issues, requested capabilities, credential requirements, side-effect differences, and policy findings. Dry run does not execute nodes. Publication requires the current draft revision, a valid graph and policy review, and all required credentials bound. Published snapshots are immutable; the workspace can compare versions or restore a prior version into a new draft revision.
 
 ## Runs and schedules
@@ -35,3 +37,5 @@ Only published versions run. The debugger shows redacted run output, flow and no
 Use the [Scheduler](/docs/user-dashboard-scheduler) to schedule a pinned or latest-published flow version. Provider, HTTP, approval-gated email, webhook, and custom-node execution each require their corresponding configured runtime and security services.
 
 Outside development builds, the workspace is available only when the Nodes feature flag, node-flow backend prerequisite, and automation-security prerequisite are enabled. These gates expose the feature; they do not assert that every external integration is configured for production.
+
+Attached agents receive only the governed `run_attached_flow` capability for the project-owned binding. Runtime still verifies ownership, attachment identity, publication state, and credential policy and does not expose the graph, credentials, or broader node-flow management operations.
diff --git a/docs-web/user/dashboard/node-flows.md b/docs-web/user/dashboard/node-flows.md
index 0acfe45d15..f61b7be223 100644
--- a/docs-web/user/dashboard/node-flows.md
+++ b/docs-web/user/dashboard/node-flows.md
@@ -38,6 +38,10 @@ The run debugger lists durable approvals beside node attempts. A pending item of
 
 A flow can be attached to a project agent preset as a repeatable skill with a name and description. Detaching removes only that binding; the flow, its graph, schedules, and run history remain in the project.
 
+The Nodes workspace loads the selected project's agent presets together with the selected flow's existing bindings. Already attached agents are removed from the selector. Attach and detach actions are keyboard accessible, use the governed APIs, and refresh the binding list after success. Switching projects or flows clears selection and stale attachment state. A failed load or mutation leaves known bindings visible and exposes a retry action.
+
+The inspector displays attachment metadata only. An attached agent receives the narrow `run_attached_flow` operation, which still verifies project ownership, the binding, publication state, and credential policy without granting graph inspection, credential access, or `manage_node_flows`.
+
 ## Scheduling
 
 Use the [Scheduler](./scheduler.md) page to run a saved node flow once or on a recurrence. Scheduled node-flow entries select a project-owned flow and may include optional JSON object input. Pause, resume, failure handling, and due-run behavior match the normal scheduler model.
diff --git a/docs-web/user/dashboard/nodes-canvas.md b/docs-web/user/dashboard/nodes-canvas.md
index d6425dbf6a..15e2247532 100644
--- a/docs-web/user/dashboard/nodes-canvas.md
+++ b/docs-web/user/dashboard/nodes-canvas.md
@@ -26,6 +26,8 @@ Validated custom definitions can also execute after their immutable artifact and
 
 Credential slots display metadata-only status such as bound, missing, or denied and can submit a binding request. Secret values remain behind the credential broker and are not returned to the graph or browser.
 
+The selected flow also loads the active project's agent presets and current flow attachments. Attaching and detaching use the governed node-flow APIs and refresh the binding list after each successful mutation. Project or flow changes clear the prior selection and discard late responses from the old scope. Loading and retryable failure states remain visible while the inspector receives only agent and attachment metadata.
+
 Validation and dry run report graph issues, requested capabilities, credential requirements, side-effect differences, and policy findings. Dry run does not execute nodes. Publication requires the current draft revision, a valid graph and policy review, and all required credentials bound. Published snapshots are immutable; the workspace can compare versions or restore a prior version into a new draft revision.
 
 ## Runs and schedules
@@ -35,3 +37,5 @@ Only published versions run. The debugger shows redacted run output, flow and no
 Use the [Scheduler](./scheduler.md) to schedule a pinned or latest-published flow version. Provider, HTTP, approval-gated email, webhook, and custom-node execution each require their corresponding configured runtime and security services.
 
 Outside development builds, the workspace is available only when the Nodes feature flag, node-flow backend prerequisite, and automation-security prerequisite are enabled. These gates expose the feature; they do not assert that every external integration is configured for production.
+
+Attached agents receive only the governed `run_attached_flow` capability for the project-owned binding. Runtime still verifies ownership, attachment identity, publication state, and credential policy and does not expose the graph, credentials, or broader node-flow management operations.
diff --git a/docs/dashboard/node-flows.md b/docs/dashboard/node-flows.md
index 80c54871a6..3b3269c300 100644
--- a/docs/dashboard/node-flows.md
+++ b/docs/dashboard/node-flows.md
@@ -26,4 +26,10 @@ The debugger reads persisted runs, node runs, attempt history, and approval deci
 
 The layout stacks on small screens, preserves keyboard-visible focus, labels loading/error/empty states, and bounds long histories and JSON output with scrolling.
 
+## Agent attachments
+
+For the selected flow, the workspace loads project-owned agent presets and existing attachments. The selector excludes agents already attached, and attach/detach buttons are native keyboard controls with visible focus treatment. Every mutation uses the governed flow attachment API and refreshes the selected flow's bindings afterward. Changing projects or flows clears the prior selection and attachment state; late responses from the old scope are ignored. Load and mutation failures leave known bindings visible and provide a retry action.
+
+The inspector receives agent names and attachment metadata only. An attachment exposes only the narrow `run_attached_flow` capability to that project agent; execution continues to verify ownership, the binding, an immutable publication, and credential policy without exposing graph or secret material.
+
 Outside development, `/nodes` requires the Nodes feature flag plus the node-flow backend and automation-security prerequisites. Individual definitions can require additional provider, credential-broker, egress, approval/outbox, webhook, or custom-runtime configuration; catalog presence alone does not assert production readiness for an integration.
diff --git a/docs/dashboard/nodes-canvas.md b/docs/dashboard/nodes-canvas.md
index 8b1fb81a55..6ff97288e7 100644
--- a/docs/dashboard/nodes-canvas.md
+++ b/docs/dashboard/nodes-canvas.md
@@ -14,6 +14,8 @@ The versioned definition registry supplies the palette, executable state, typed
 
 Credential slots show metadata-only states such as bound, missing, or denied and can submit a binding request. Secret material stays behind the credential broker and is excluded from graphs, browser output, logs, and examples.
 
+The selected flow also loads the active project's agent presets and its current flow-to-agent attachments. Attachment controls remain page-owned and pass only preset and attachment metadata into the inspector. Attaching or detaching calls the governed node-flow attachment routes and then reloads the selected flow's bindings; switching projects or flows clears the prior selection and ignores stale responses. Loading and retryable failure states remain visible without exposing graphs, credentials, or broader node-flow management capability to an attached agent.
+
 Validation and dry run report structural issues, requested capabilities, credential requirements, side-effect differences, and policy findings. Dry run is review-only and does not execute nodes. Publication requires the current draft revision, a valid graph with no error-level policy findings, and all declared credential requirements bound. Publications are immutable; comparison and rollback operate on versioned snapshots.
 
 ## Executable definitions
@@ -27,3 +29,5 @@ Validated custom definitions may also execute after their versioned manifest and
 Only published versions run. The debugger shows redacted run output, graph and node states, attempts, retry classifications and decisions, approval state, invocation links, timing, cancellation, and safe retry controls. Approval decisions resume or terminate the same pinned durable run. Scheduling is entered through the Scheduler page and targets a pinned or latest-published version.
 
 Outside development builds, the workspace is exposed only when the Nodes feature flag and both node-flow backend and automation-security prerequisites are enabled. Execution also depends on the services required by a definition: for example, a configured provider for `provider_prompt`, allowed egress for `http_request`, approval and outbox services for governed email sending, webhook configuration for webhook ingress, and the custom-node runtime for registered custom definitions. Availability is not a claim that every integration is configured for production.
+
+An attached agent receives only the governed `run_attached_flow` capability for that project-owned binding. Runtime execution still verifies project ownership, publication state, attachment identity, and credential policy; attachment never grants graph inspection, credential access, or the broader `manage_node_flows` surface.
diff --git a/tests/dashboard/v2/nodes-page.test.tsx b/tests/dashboard/v2/nodes-page.test.tsx
index e7579cbc71..17989fe8be 100644
--- a/tests/dashboard/v2/nodes-page.test.tsx
+++ b/tests/dashboard/v2/nodes-page.test.tsx
@@ -8,17 +8,23 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { NODES_CANVAS_STORAGE_KEY, NodesPage } from "../../../dashboard/src/v2/NodesPage.js";
 import { ProjectDataContext } from "../../../dashboard/src/v2/context/project-data.js";
 
-const api = vi.hoisted(() => ({ fetchNodeFlows: vi.fn(), fetchNodeFlowCatalog: vi.fn(), createNodeFlowDraft: vi.fn(), fetchNodeFlow: vi.fn(), fetchNodeFlowRuns: vi.fn(), fetchNodeFlowNodeRuns: vi.fn(), fetchNodeFlowAttempts: vi.fn(), fetchNodeFlowApprovals: vi.fn(), decideNodeFlowApproval: vi.fn(), patchNodeFlowDraft: vi.fn(), fetchNodeDefinition: vi.fn(), validateNodeFlowDraft: vi.fn(), deleteNodeFlow: vi.fn() }));
+const api = vi.hoisted(() => ({ fetchNodeFlows: vi.fn(), fetchNodeFlowCatalog: vi.fn(), createNodeFlowDraft: vi.fn(), fetchNodeFlow: vi.fn(), fetchNodeFlowRuns: vi.fn(), fetchNodeFlowNodeRuns: vi.fn(), fetchNodeFlowAttempts: vi.fn(), fetchNodeFlowApprovals: vi.fn(), fetchNodeFlowAgentSkills: vi.fn(), attachNodeFlowToAgent: vi.fn(), detachNodeFlowFromAgent: vi.fn(), decideNodeFlowApproval: vi.fn(), patchNodeFlowDraft: vi.fn(), fetchNodeDefinition: vi.fn(), validateNodeFlowDraft: vi.fn(), deleteNodeFlow: vi.fn() }));
+const agentApi = vi.hoisted(() => ({ fetchAgentPresets: vi.fn() }));
 vi.mock("../../../dashboard/src/v2/lib/node-flow-api.js", async (original) => ({ ...(await original()), ...api }));
+vi.mock("../../../dashboard/src/v2/lib/agent-preset-api.js", async (original) => ({ ...(await original()), ...agentApi }));
 vi.mock("../../../dashboard/src/v2/hooks/use-reduced-motion.js", () => ({ useReducedMotion: () => true, useResolvedMotionDuration: <T,>(value: T): T => value }));
 
 const flow = { id: "flow-1", projectId: "project-1", title: "Release automation", description: "Governed", graph: { schemaVersion: 2 as const, nodes: [{ id: "input-1", type: "input", title: "Input", definition: { type: "input", version: 1 }, position: { x: 40, y: 40 } }], edges: [] }, version: 2, createdAt: "2026-01-01T00:00:00.000Z", updatedAt: "2026-01-01T00:00:00.000Z" };
+const agentOne = { id: "agent-1", projectId: "project-1", name: "Release Agent", description: "", instructionMarkdown: "", labels: [], sourcePath: null, sourceScope: null, sourceUpdatedAt: null, sourceImportedAt: null, sourceExists: false, syncStatus: "in_sync", createdAt: "2026-01-01T00:00:00.000Z", updatedAt: "2026-01-01T00:00:00.000Z" };
+const agentTwo = { ...agentOne, id: "agent-2", name: "QA Agent" };
+const attachmentOne = { flowId: "flow-1", projectId: "project-1", agentPresetId: "agent-1", skillName: "Release automation", description: "Governed", createdAt: "2026-01-01T00:00:00.000Z", updatedAt: "2026-01-01T00:00:00.000Z" };
+const attachmentTwo = { ...attachmentOne, agentPresetId: "agent-2" };
 const context = { projects: [{ id: "project-1", name: "Test project" }], selectedProjectId: "project-1", selectedProject: { id: "project-1", name: "Test project" }, loading: false, error: null, refreshProjects: async () => undefined, selectProject: async () => undefined, createProject: async () => { throw new Error("unused"); }, updateProject: async () => { throw new Error("unused"); }, deleteProject: async () => undefined };
 
 describe("NodesPage governed workspace", () => {
   const review = { flowId: "flow-1", projectId: "project-1", name: "Release automation", description: "Governed", draftRevision: 2, nodeCount: 1, edgeCount: 0, valid: true, validationIssues: [], policyFindings: [], requiredCredentials: [], requestedCapabilities: [], sideEffectDiffs: [], publishedVersion: 1 };
   beforeEach(() => { api.validateNodeFlowDraft.mockResolvedValue(review); });
-  beforeEach(() => { window.localStorage.clear(); api.fetchNodeFlows.mockResolvedValue({ flows: [flow] }); api.fetchNodeFlowCatalog.mockResolvedValue({ nodes: [{ type: "input", version: 1, executable: true, executionKind: "local", label: "Input", description: "Input", category: "Core", credentials: [], capabilities: [], sideEffect: "none", ports: [] }] }); api.fetchNodeFlowRuns.mockResolvedValue({ runs: [] }); api.fetchNodeFlowNodeRuns.mockResolvedValue({ nodeRuns: [] }); api.fetchNodeFlowAttempts.mockResolvedValue({ attempts: [] }); api.fetchNodeFlowApprovals.mockResolvedValue({ approvals: [] }); api.fetchNodeDefinition.mockResolvedValue({ type: "input", version: 1, executable: true, executionKind: "local", configurationSchema: { type: "object" }, ui: { label: "Input", description: "Input", category: "Core", widgetSchema: { fields: [] } }, ports: [], credentials: [], capabilities: [], sideEffect: "none", defaultPolicy: {}, documentation: "", deprecation: { deprecated: false } }); });
+  beforeEach(() => { window.localStorage.clear(); api.fetchNodeFlows.mockResolvedValue({ flows: [flow] }); api.fetchNodeFlowCatalog.mockResolvedValue({ nodes: [{ type: "input", version: 1, executable: true, executionKind: "local", label: "Input", description: "Input", category: "Core", credentials: [], capabilities: [], sideEffect: "none", ports: [] }] }); agentApi.fetchAgentPresets.mockResolvedValue([agentOne, agentTwo]); api.fetchNodeFlowAgentSkills.mockResolvedValue([attachmentOne]); api.attachNodeFlowToAgent.mockResolvedValue(attachmentTwo); api.detachNodeFlowFromAgent.mockResolvedValue(undefined); api.fetchNodeFlowRuns.mockResolvedValue({ runs: [] }); api.fetchNodeFlowNodeRuns.mockResolvedValue({ nodeRuns: [] }); api.fetchNodeFlowAttempts.mockResolvedValue({ attempts: [] }); api.fetchNodeFlowApprovals.mockResolvedValue({ approvals: [] }); api.fetchNodeDefinition.mockResolvedValue({ type: "input", version: 1, executable: true, executionKind: "local", configurationSchema: { type: "object" }, ui: { label: "Input", description: "Input", category: "Core", widgetSchema: { fields: [] } }, ports: [], credentials: [], capabilities: [], sideEffect: "none", defaultPolicy: {}, documentation: "", deprecation: { deprecated: false } }); });
   afterEach(() => { cleanup(); vi.clearAllMocks(); });
 
   it("loads a project flow library and registry-backed editor", async () => {
@@ -28,6 +34,92 @@ describe("NodesPage governed workspace", () => {
     expect(screen.getByRole("heading", { name: "Node catalog" })).toBeInTheDocument();
     expect(screen.getByText("Run debugger")).toBeInTheDocument();
     expect(api.fetchNodeFlows).toHaveBeenCalledWith("project-1", expect.any(AbortSignal));
+    expect(agentApi.fetchAgentPresets).toHaveBeenCalledWith("project-1", expect.any(AbortSignal));
+    expect(api.fetchNodeFlowAgentSkills).toHaveBeenCalledWith("flow-1", expect.any(AbortSignal));
+    expect(screen.getByText("Release Agent")).toBeInTheDocument();
+    expect(screen.getByText("Release automation", { selector: "p" })).toBeInTheDocument();
+  });
+
+  it("shows an explicit loading state while project agents are loading", async () => {
+    let resolveAgents!: (agents: typeof agentOne[]) => void;
+    agentApi.fetchAgentPresets.mockReturnValueOnce(new Promise((resolve) => { resolveAgents = resolve; }));
+    render(<ProjectDataContext.Provider value={context as never}><NodesPage /></ProjectDataContext.Provider>);
+    expect(await screen.findByText("Loading project agents and flow attachments…")).toBeInTheDocument();
+    resolveAgents([agentOne]);
+    await waitFor(() => expect(screen.queryByText("Loading project agents and flow attachments…")).not.toBeInTheDocument());
+  });
+
+  it("attaches the selected project agent and refreshes flow attachments", async () => {
+    const user = userEvent.setup();
+    api.fetchNodeFlowAgentSkills.mockResolvedValueOnce([attachmentOne]).mockResolvedValueOnce([attachmentOne, attachmentTwo]);
+    render(<ProjectDataContext.Provider value={context as never}><NodesPage /></ProjectDataContext.Provider>);
+    await screen.findByText("Release Agent");
+    await user.selectOptions(screen.getByRole("combobox", { name: "Agent preset" }), "agent-2");
+    await user.click(screen.getByRole("button", { name: "Attach node flow to agent" }));
+    await waitFor(() => expect(api.attachNodeFlowToAgent).toHaveBeenCalledWith("flow-1", { agentPresetId: "agent-2" }));
+    expect(await screen.findByText("Flow attached to the selected project agent.")).toBeInTheDocument();
+    expect(api.fetchNodeFlowAgentSkills).toHaveBeenCalledTimes(2);
+    expect(screen.getByText("QA Agent")).toBeInTheDocument();
+    expect((screen.getByRole("combobox", { name: "Agent preset" }) as HTMLSelectElement).value).toBe("");
+  });
+
+  it("detaches an attached agent and refreshes flow attachments", async () => {
+    const user = userEvent.setup();
+    api.fetchNodeFlowAgentSkills.mockResolvedValueOnce([attachmentOne]).mockResolvedValueOnce([]);
+    render(<ProjectDataContext.Provider value={context as never}><NodesPage /></ProjectDataContext.Provider>);
+    await user.click(await screen.findByRole("button", { name: "Detach Release Agent" }));
+    await waitFor(() => expect(api.detachNodeFlowFromAgent).toHaveBeenCalledWith("flow-1", "agent-1"));
+    expect(await screen.findByText("No agents attached.")).toBeInTheDocument();
+    expect(api.fetchNodeFlowAgentSkills).toHaveBeenCalledTimes(2);
+  });
+
+  it("clears attachment selection and loads only the newly selected project's agents and bindings", async () => {
+    const user = userEvent.setup();
+    const flowTwo = { ...flow, id: "flow-2", projectId: "project-2", title: "Project two flow" };
+    const agentThree = { ...agentOne, id: "agent-3", projectId: "project-2", name: "Project Two Agent" };
+    api.fetchNodeFlows.mockImplementation(async (projectId: string) => ({ flows: [projectId === "project-1" ? flow : flowTwo] }));
+    agentApi.fetchAgentPresets.mockImplementation(async (projectId: string) => projectId === "project-1" ? [agentOne, agentTwo] : [agentThree]);
+    api.fetchNodeFlowAgentSkills.mockImplementation(async (flowId: string) => flowId === "flow-1" ? [attachmentOne] : []);
+    const { rerender } = render(<ProjectDataContext.Provider value={context as never}><NodesPage /></ProjectDataContext.Provider>);
+    await screen.findByText("Release Agent");
+    await user.selectOptions(screen.getByRole("combobox", { name: "Agent preset" }), "agent-2");
+    const projectTwoContext = { ...context, projects: [{ id: "project-2", name: "Second project" }], selectedProjectId: "project-2", selectedProject: { id: "project-2", name: "Second project" } };
+    rerender(<ProjectDataContext.Provider value={projectTwoContext as never}><NodesPage /></ProjectDataContext.Provider>);
+    expect(await screen.findByText("Project two flow")).toBeInTheDocument();
+    expect(screen.getByRole("combobox", { name: "Agent preset" })).toHaveValue("");
+    expect(screen.getByRole("option", { name: "Project Two Agent" })).toBeInTheDocument();
+    expect(screen.queryByText("Release Agent")).not.toBeInTheDocument();
+    expect(agentApi.fetchAgentPresets).toHaveBeenLastCalledWith("project-2", expect.any(AbortSignal));
+    expect(api.fetchNodeFlowAgentSkills).toHaveBeenLastCalledWith("flow-2", expect.any(AbortSignal));
+  });
+
+  it("keeps existing bindings visible and exposes retry when an attachment API fails", async () => {
+    const user = userEvent.setup();
+    api.attachNodeFlowToAgent.mockRejectedValueOnce(new Error("Attachment service unavailable"));
+    render(<ProjectDataContext.Provider value={context as never}><NodesPage /></ProjectDataContext.Provider>);
+    await screen.findByText("Release Agent");
+    await user.selectOptions(screen.getByRole("combobox", { name: "Agent preset" }), "agent-2");
+    await user.click(screen.getByRole("button", { name: "Attach node flow to agent" }));
+    expect(await screen.findByRole("alert")).toHaveTextContent("Attachment service unavailable");
+    expect(screen.getByText("Release Agent")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Retry" })).toBeInTheDocument();
+  });
+
+  it("supports keyboard activation for attach and detach controls", async () => {
+    const user = userEvent.setup();
+    api.fetchNodeFlowAgentSkills.mockResolvedValueOnce([attachmentOne]).mockResolvedValueOnce([attachmentOne, attachmentTwo]).mockResolvedValueOnce([attachmentTwo]);
+    render(<ProjectDataContext.Provider value={context as never}><NodesPage /></ProjectDataContext.Provider>);
+    await screen.findByText("Release Agent");
+    await user.selectOptions(screen.getByRole("combobox", { name: "Agent preset" }), "agent-2");
+    const attachButton = screen.getByRole("button", { name: "Attach node flow to agent" });
+    attachButton.focus();
+    expect(attachButton).toHaveFocus();
+    await user.keyboard("{Enter}");
+    const detachButton = await screen.findByRole("button", { name: "Detach Release Agent" });
+    detachButton.focus();
+    expect(detachButton).toHaveFocus();
+    await user.keyboard("{Enter}");
+    await waitFor(() => expect(api.detachNodeFlowFromAgent).toHaveBeenCalledWith("flow-1", "agent-1"));
   });
 
   it("imports legacy localStorage once and removes it as a source of truth", async () => {

From 2b1be27278869c74298eb4e38bdde49ab5ad96d4 Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 09:38:29 +0000
Subject: [PATCH 21/25] feat(task T16): implement via codex

---
 docs-web/architecture/node-flow-foundation.md |   2 +-
 docs-web/architecture/node-flows.md           |   2 +-
 .../architecture-node-flow-foundation.mdx     |   2 +-
 .../content/docs/architecture-node-flows.mdx  |   2 +-
 docs/architecture/node-flow-foundation.md     |   3 +
 docs/architecture/node-flows.md               |   4 +-
 src/domain/node-flows/node-flow-migrators.ts  | 101 +++--
 src/domain/node-flows/node-flow-validation.ts | 400 +++++++++++++++---
 .../node-flows/node-flow-migrators.test.ts    |  27 ++
 .../node-flows/node-flow-validation.test.ts   |  98 +++++
 10 files changed, 536 insertions(+), 105 deletions(-)

diff --git a/docs-web/architecture/node-flow-foundation.md b/docs-web/architecture/node-flow-foundation.md
index b18fd8f0cd..5d5d7119bd 100644
--- a/docs-web/architecture/node-flow-foundation.md
+++ b/docs-web/architecture/node-flow-foundation.md
@@ -18,7 +18,7 @@ A validated custom definition becomes executable only after its immutable artifa
 
 ## Validation, policy, and secrets
 
-Validation resolves each definition and checks configuration, port handles and schemas, policies, graph bounds, and cycles. It rejects plaintext secret-shaped fields and generated or custom source in graph JSON. The dashboard receives credential binding ids and metadata-only states; resolved values remain behind the credential broker. Credential values and secret-shaped payloads are redacted before invocation messages, attempts, diagnostics, route responses, and debugger output are persisted or rendered.
+Validation resolves each definition and checks configuration, port handles and schemas, policies, graph bounds, and cycles. Migrated Graph v1 and canonical Graph v2 inputs fail closed: malformed nodes, edges, ports, credential bindings, definition references, capabilities, policies, schemas, and metadata produce deterministic field-level issues at their original paths without discarding safe siblings. Repeated validation preserves issue ordering. It rejects plaintext secret-shaped fields and generated or custom source in graph JSON. The dashboard receives credential binding ids and metadata-only states; resolved values remain behind the credential broker. Credential values and secret-shaped payloads are redacted before invocation messages, attempts, diagnostics, route responses, and debugger output are persisted or rendered.
 
 Draft review reports requested capabilities, side effects, credential status, policy findings, and a non-executing dry run. Publication requires the current `draftRevision`, a valid graph and policy review, and every required credential binding. Runs select an immutable pinned or latest-published snapshot.
 
diff --git a/docs-web/architecture/node-flows.md b/docs-web/architecture/node-flows.md
index 12573fb52e..2faeb20b43 100644
--- a/docs-web/architecture/node-flows.md
+++ b/docs-web/architecture/node-flows.md
@@ -21,7 +21,7 @@ Authenticated dashboard routes resolve persisted project ownership from flow, ru
 | `webhook_trigger` | Emits secret-authenticated webhook input. |
 | `output` | Selects the result. |
 
-These are the executable definitions. Other custom palette concepts remain non-executable until a versioned handler is registered. Graph v1 migration preserves the legacy snapshot and appends deterministic v2.
+These are the executable definitions. Other custom palette concepts remain non-executable until a versioned handler is registered. Graph v1 migration preserves the legacy snapshot and appends deterministic v2. Both migrated v1 and canonical v2 graphs are validated as untrusted input: malformed nested members fail closed with stable paths at their original array indices, valid siblings are retained where safe, and repeated validation returns the same ordered issues instead of throwing.
 
 Execution uses immutable publications rather than the mutable editor row. Runs select a pinned publication or the latest published version, then use durable queue claims, leases, bounded quotas, timeout/cancellation propagation, and numbered retry attempts. Expired external attempts with unknown outcomes require operator attention and are not silently replayed. See [Node Flow Durable Execution](./node-flow-durable-execution.md).
 
diff --git a/docs-web/content/docs/architecture-node-flow-foundation.mdx b/docs-web/content/docs/architecture-node-flow-foundation.mdx
index b18fd8f0cd..5d5d7119bd 100644
--- a/docs-web/content/docs/architecture-node-flow-foundation.mdx
+++ b/docs-web/content/docs/architecture-node-flow-foundation.mdx
@@ -18,7 +18,7 @@ A validated custom definition becomes executable only after its immutable artifa
 
 ## Validation, policy, and secrets
 
-Validation resolves each definition and checks configuration, port handles and schemas, policies, graph bounds, and cycles. It rejects plaintext secret-shaped fields and generated or custom source in graph JSON. The dashboard receives credential binding ids and metadata-only states; resolved values remain behind the credential broker. Credential values and secret-shaped payloads are redacted before invocation messages, attempts, diagnostics, route responses, and debugger output are persisted or rendered.
+Validation resolves each definition and checks configuration, port handles and schemas, policies, graph bounds, and cycles. Migrated Graph v1 and canonical Graph v2 inputs fail closed: malformed nodes, edges, ports, credential bindings, definition references, capabilities, policies, schemas, and metadata produce deterministic field-level issues at their original paths without discarding safe siblings. Repeated validation preserves issue ordering. It rejects plaintext secret-shaped fields and generated or custom source in graph JSON. The dashboard receives credential binding ids and metadata-only states; resolved values remain behind the credential broker. Credential values and secret-shaped payloads are redacted before invocation messages, attempts, diagnostics, route responses, and debugger output are persisted or rendered.
 
 Draft review reports requested capabilities, side effects, credential status, policy findings, and a non-executing dry run. Publication requires the current `draftRevision`, a valid graph and policy review, and every required credential binding. Runs select an immutable pinned or latest-published snapshot.
 
diff --git a/docs-web/content/docs/architecture-node-flows.mdx b/docs-web/content/docs/architecture-node-flows.mdx
index f846041fde..5088f8aca8 100644
--- a/docs-web/content/docs/architecture-node-flows.mdx
+++ b/docs-web/content/docs/architecture-node-flows.mdx
@@ -21,7 +21,7 @@ Authenticated dashboard routes resolve persisted project ownership from flow, ru
 | `webhook_trigger` | Emits secret-authenticated webhook input. |
 | `output` | Selects the result. |
 
-These are the executable definitions. Other custom palette concepts remain non-executable until a versioned handler is registered. Graph v1 migration preserves the legacy snapshot and appends deterministic v2.
+These are the executable definitions. Other custom palette concepts remain non-executable until a versioned handler is registered. Graph v1 migration preserves the legacy snapshot and appends deterministic v2. Both migrated v1 and canonical v2 graphs are validated as untrusted input: malformed nested members fail closed with stable paths at their original array indices, valid siblings are retained where safe, and repeated validation returns the same ordered issues instead of throwing.
 
 Execution uses immutable publications rather than the mutable editor row. Runs select a pinned publication or the latest published version, then use durable queue claims, leases, bounded quotas, timeout/cancellation propagation, and numbered retry attempts. Expired external attempts with unknown outcomes require operator attention and are not silently replayed. See [Node Flow Durable Execution](/docs/architecture-node-flow-durable-execution).
 
diff --git a/docs/architecture/node-flow-foundation.md b/docs/architecture/node-flow-foundation.md
index 0160fc5227..9d9d99f833 100644
--- a/docs/architecture/node-flow-foundation.md
+++ b/docs/architecture/node-flow-foundation.md
@@ -26,9 +26,12 @@ Run records are persisted as `NodeFlowRunRecord` and `NodeFlowNodeRunRecord`. Bo
 - the graph is acyclic and has a deterministic execution order
 - widget fields have required id, label, type, and select option metadata
 - widget default values are JSON-safe and match the field type
+- malformed v1 and v2 node, edge, port, credential-binding, definition-reference, capability, policy, schema, and metadata members produce stable issues at their original paths
 
 Invalid graphs throw a `ValidationError` with field-level details when persistence is attempted. The validation route returns the same structured issue list without writing data.
 
+Normalization is fail closed and entry oriented. It retains safe siblings, does not renumber issue paths after rejecting an earlier array member, and returns issues in deterministic traversal order so repeated validation is stable.
+
 ## Runtime
 
 `src/services/node-flow-runtime-service.ts` executes the current flow version after revalidating the graph. It creates a parent `execution_invocations` row with `type = "node_flow"`, then runs nodes in the validator's topological order.
diff --git a/docs/architecture/node-flows.md b/docs/architecture/node-flows.md
index 0dd621f925..e43ec92522 100644
--- a/docs/architecture/node-flows.md
+++ b/docs/architecture/node-flows.md
@@ -35,6 +35,8 @@ A `NodeFlowGraph` contains:
 
 Validation is owned by `src/domain/node-flows/node-flow-validation.ts`. It normalizes ids, labels, positions, widget defaults, and graph shape; rejects missing node/edge arrays; rejects duplicate node ids; rejects edges that point at missing nodes; requires at least one node; and rejects cycles. Widget validation supports `text`, `textarea`, `number`, `boolean`, `select`, `json`, `secretRef`, and `keyValue` fields.
 
+Migration and validation treat persisted Graph v1 and canonical Graph v2 as untrusted input. Malformed collection members are rejected at their original index, such as `nodes[1].ports[0]` or `edges[2]`, while structurally valid siblings remain available to the rest of normalization. Definition references, credential bindings, capabilities, policies, port and graph schemas, and JSON metadata emit deterministic field-level issues instead of throwing. Revalidating the same graph produces the same ordered issue list.
+
 Validation requires every node's type/version reference to resolve through the registry and rejects unknown definitions. Runtime execution then dispatches according to the registered definition's executable state and execution kind; a planning concept is not runnable merely because it has a string type.
 
 The dashboard uses the same backend-owned Graph v2 record as the runtime. The selected project controls library loading; no project means no flow, credential, publication, or run requests. The versioned registry drives palette entries, typed ports, configuration widgets, credential slots, capabilities, side-effect review, and policies. Draft saves use optimistic `draftRevision` checks and surface conflicts without overwriting the newer record.
@@ -119,7 +121,7 @@ Graph v2 is the single workflow model used by backend, MCP, runtime, and dashboa
 
 The executable registry contains the original deterministic/provider/HTTP nodes plus `condition`, `switch`, `foreach`, `merge`, `delay`, `approval`, `email_draft`, `email_send`, `execute_subflow`, and `webhook_trigger`. Unregistered custom types remain non-executable.
 
-Backend Graph v1 migration retains the exact prior version and appends deterministic v2. Browser canvas v1 migration returns the untouched legacy snapshot separately from the normalized graph.
+Backend Graph v1 migration retains the exact prior version and appends deterministic v2. Invalid legacy members are carried across the migration boundary so validation can report their original paths rather than silently dropping them. Browser canvas v1 migration returns the untouched legacy snapshot separately from the normalized graph.
 
 ## Dashboard and security prerequisites
 
diff --git a/src/domain/node-flows/node-flow-migrators.ts b/src/domain/node-flows/node-flow-migrators.ts
index 527ae746c3..009379563f 100644
--- a/src/domain/node-flows/node-flow-migrators.ts
+++ b/src/domain/node-flows/node-flow-migrators.ts
@@ -13,58 +13,91 @@ export interface NodeFlowMigrationResult<TLegacy = unknown> {
   legacySnapshot: TLegacy | null;
 }
 
-const cloneJson = <T>(value: T): T => JSON.parse(JSON.stringify(value)) as T;
+function cloneUntrusted<T>(value: T, seen = new WeakMap<object, unknown>()): T {
+  if (!value || typeof value !== "object") return value;
+  const cached = seen.get(value);
+  if (cached !== undefined) return cached as T;
+  if (Array.isArray(value)) {
+    const clone: unknown[] = [];
+    seen.set(value, clone);
+    value.forEach((entry) => clone.push(cloneUntrusted(entry, seen)));
+    return clone as T;
+  }
+  const clone: Record<string, unknown> = {};
+  seen.set(value, clone);
+  Object.entries(value).forEach(([key, entry]) => {
+    clone[key] = cloneUntrusted(entry, seen);
+  });
+  return clone as T;
+}
 
 export function migrateNodeFlowGraph(graph: unknown): NodeFlowMigrationResult<NodeFlowGraph> {
   if (isRecord(graph) && graph.schemaVersion === NODE_FLOW_SCHEMA_VERSION) {
-    return { graph: cloneJson(graph as unknown as NodeFlowGraph), migrated: false, legacySnapshot: null };
+    return { graph: cloneUntrusted(graph) as unknown as NodeFlowGraph, migrated: false, legacySnapshot: null };
   }
 
-  const legacy = isRecord(graph) ? cloneJson(graph as unknown as NodeFlowGraph) : { nodes: [], edges: [] };
-  const nodes = Array.isArray(legacy.nodes) ? legacy.nodes.map(migrateNode) : [];
-  const definitionByNode = new Map(nodes.map((node) => [node.id, resolveLatestNodeDefinition(node.type)]));
-  const edges = Array.isArray(legacy.edges) ? legacy.edges.map((edge) => ({
-    ...edge,
-    ...(edge.fromHandle ? {} : { fromHandle: definitionByNode.get(edge.fromNodeId)?.ports.find((port) => port.direction === "output")?.id }),
-    ...(edge.toHandle ? {} : { toHandle: definitionByNode.get(edge.toNodeId)?.ports.find((port) => port.direction === "input")?.id }),
-  })) : [];
+  const legacy = isRecord(graph) ? cloneUntrusted(graph) : {};
+  const nodes = Array.isArray(legacy.nodes)
+    ? legacy.nodes.map((node) => isRecord(node) ? migrateNode(node) : node)
+    : legacy.nodes;
+  const definitionByNode = new Map(
+    (Array.isArray(nodes) ? nodes : [])
+      .filter(isRecord)
+      .map((node) => [stringValue(node.id), resolveLatestNodeDefinition(stringValue(node.type))]),
+  );
+  const edges = Array.isArray(legacy.edges) ? legacy.edges.map((edge) => {
+    if (!isRecord(edge)) return edge;
+    const fromNodeId = stringValue(edge.fromNodeId);
+    const toNodeId = stringValue(edge.toNodeId);
+    return {
+      ...edge,
+      ...(edge.fromHandle ? {} : { fromHandle: definitionByNode.get(fromNodeId)?.ports.find((port) => port.direction === "output")?.id }),
+      ...(edge.toHandle ? {} : { toHandle: definitionByNode.get(toNodeId)?.ports.find((port) => port.direction === "input")?.id }),
+    };
+  }) : legacy.edges;
 
   return {
     migrated: true,
-    legacySnapshot: legacy,
+    legacySnapshot: legacy as unknown as NodeFlowGraph,
     graph: {
       schemaVersion: NODE_FLOW_SCHEMA_VERSION,
       nodes,
       edges,
-      ...(legacy.inputSchema ? { inputSchema: legacy.inputSchema } : {}),
-      ...(legacy.schemas ? { schemas: legacy.schemas } : {}),
-      ...(legacy.metadata ? { metadata: legacy.metadata } : {}),
-      ...(legacy.publication ? { publication: legacy.publication } : {}),
-    },
+      ...(legacy.inputSchema !== undefined ? { inputSchema: legacy.inputSchema } : {}),
+      ...(legacy.schemas !== undefined ? { schemas: legacy.schemas } : {}),
+      ...(legacy.metadata !== undefined ? { metadata: legacy.metadata } : {}),
+      ...(legacy.publication !== undefined ? { publication: legacy.publication } : {}),
+    } as unknown as NodeFlowGraph,
   };
 }
 
-function migrateNode(node: NodeFlowNode): NodeFlowNode {
-  const definition = node.definition
-    ? resolveLatestNodeDefinition(node.definition.type)
-    : resolveLatestNodeDefinition(node.type);
+function migrateNode(node: Record<string, unknown>): NodeFlowNode {
+  const definition = isRecord(node.definition)
+    ? resolveLatestNodeDefinition(stringValue(node.definition.type))
+    : resolveLatestNodeDefinition(stringValue(node.type));
   return {
-    ...node,
-    definition: node.definition ?? { type: node.type, version: definition?.version ?? 1 },
-    ports: node.ports ?? definition?.ports.map((port) => cloneJson(port)) ?? [],
-    credentialBindings: node.credentialBindings ?? [],
-    policy: node.policy ?? (definition ? cloneJson(definition.defaultPolicy) : {}),
-    capabilities: node.capabilities ?? [...(definition?.capabilities ?? [])],
-    sideEffect: node.sideEffect ?? definition?.sideEffect ?? "none",
-    disabled: node.disabled ?? false,
-  };
+    ...node as unknown as NodeFlowNode,
+    definition: node.definition !== undefined
+      ? node.definition as NodeFlowNode["definition"]
+      : { type: stringValue(node.type), version: definition?.version ?? 1 },
+    ports: node.ports !== undefined
+      ? node.ports as NodeFlowNode["ports"]
+      : definition?.ports.map((port) => cloneUntrusted(port)) ?? [],
+    credentialBindings: node.credentialBindings !== undefined ? node.credentialBindings : [],
+    policy: node.policy !== undefined
+      ? node.policy as NodeFlowNode["policy"]
+      : definition ? cloneUntrusted(definition.defaultPolicy) : {},
+    capabilities: node.capabilities !== undefined ? node.capabilities : [...(definition?.capabilities ?? [])],
+    sideEffect: node.sideEffect !== undefined ? node.sideEffect : definition?.sideEffect ?? "none",
+    disabled: node.disabled !== undefined ? node.disabled : false,
+  } as NodeFlowNode;
 }
 
 export function migrateNodeCanvasGraphV1(graph: unknown): NodeFlowMigrationResult<unknown> {
   if (isRecord(graph) && graph.schemaVersion === NODE_FLOW_SCHEMA_VERSION && Array.isArray(graph.nodes) && graph.nodes.every(isCanonicalNode)) {
     return migrateNodeFlowGraph(graph);
   }
-  const legacySnapshot = cloneJson(graph);
+  const legacySnapshot = cloneUntrusted(graph);
   const legacy = isRecord(graph) ? graph : {};
   const nodes = Array.isArray(legacy.nodes) ? legacy.nodes.filter(isRecord).map((node): NodeFlowNode => ({
     id: stringValue(node.id),
@@ -87,7 +120,7 @@ export function migrateNodeCanvasGraphV1(graph: unknown): NodeFlowMigrationResul
   return {
     migrated: true,
     legacySnapshot,
-    graph: { schemaVersion: NODE_FLOW_SCHEMA_VERSION, nodes, edges, metadata: { canvasSelection: jsonValue(legacy.selection) } },
+    graph: { schemaVersion: NODE_FLOW_SCHEMA_VERSION, nodes, edges, metadata: { canvasSelection: untrustedJsonValue(legacy.selection) } },
   };
 }
 
@@ -98,11 +131,11 @@ function readPorts(value: unknown, direction: "input" | "output") {
 }
 
 function canvasNodeData(node: Record<string, unknown>): NodeFlowJsonObject {
-  const config = Array.isArray(node.config) ? Object.fromEntries(node.config.filter(isRecord).map((entry) => [stringValue(entry.id), jsonValue(entry.value)]).filter(([id]) => id)) : {};
-  return { config, canvasMetadata: jsonValue(node.metadata) };
+  const config = Array.isArray(node.config) ? Object.fromEntries(node.config.filter(isRecord).map((entry) => [stringValue(entry.id), untrustedJsonValue(entry.value)]).filter(([id]) => id)) : {};
+  return { config, canvasMetadata: untrustedJsonValue(node.metadata) };
 }
 
-const jsonValue = (value: unknown): NodeFlowJsonValue => JSON.parse(JSON.stringify(value ?? null)) as NodeFlowJsonValue;
+const untrustedJsonValue = (value: unknown): NodeFlowJsonValue => cloneUntrusted(value ?? null) as NodeFlowJsonValue;
 const endpointValue = (value: unknown, key: string): string => isRecord(value) ? stringValue(value[key]) : "";
 const stringValue = (value: unknown): string => typeof value === "string" ? value : "";
 const isRecord = (value: unknown): value is Record<string, unknown> => Boolean(value) && typeof value === "object" && !Array.isArray(value);
diff --git a/src/domain/node-flows/node-flow-validation.ts b/src/domain/node-flows/node-flow-validation.ts
index ad98c35254..a7407b3a2f 100644
--- a/src/domain/node-flows/node-flow-validation.ts
+++ b/src/domain/node-flows/node-flow-validation.ts
@@ -5,6 +5,10 @@ import type {
   NodeFlowJsonObject,
   NodeFlowJsonValue,
   NodeFlowNode,
+  NodeFlowPort,
+  NodeFlowExecutionPolicy,
+  NodeFlowDefinitionReference,
+  NodeFlowSchemas,
   NodeFlowValidationIssue,
   NodeFlowValidationResponse,
   NodeFlowValueSchema,
@@ -30,6 +34,9 @@ const WIDGET_FIELD_TYPES = new Set<NodeWidgetFieldType>([
   "secretRef",
   "keyValue",
 ]);
+const VALUE_SCHEMA_TYPES = new Set<NodeFlowValueSchema["type"]>([
+  "any", "object", "array", "string", "number", "boolean", "null",
+]);
 
 export class NodeFlowValidationError extends ValidationError {
   readonly details: NodeFlowValidationIssue[];
@@ -96,6 +103,135 @@ function isPlainJsonObject(value: unknown): value is Record<string, NodeFlowJson
     && isJsonValue(value);
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function normalizeJsonValue(
+  value: unknown,
+  path: string,
+  issues: NodeFlowValidationIssue[],
+  ancestors = new Set<object>(),
+): NodeFlowJsonValue | undefined {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (!value || typeof value !== "object") {
+    issues.push(issue(path, "invalid_json_value", "Value must be JSON-serializable and finite."));
+    return undefined;
+  }
+  if (ancestors.has(value)) {
+    issues.push(issue(path, "invalid_json_value", "Value must not contain circular references."));
+    return undefined;
+  }
+  ancestors.add(value);
+  if (Array.isArray(value)) {
+    const normalized = value.map((entry, index) => normalizeJsonValue(entry, `${path}[${index}]`, issues, ancestors) ?? null);
+    ancestors.delete(value);
+    return normalized;
+  }
+  const normalized: NodeFlowJsonObject = {};
+  Object.entries(value).forEach(([key, entry]) => {
+    const normalizedEntry = normalizeJsonValue(entry, `${path}.${key}`, issues, ancestors);
+    if (normalizedEntry !== undefined) normalized[key] = normalizedEntry;
+  });
+  ancestors.delete(value);
+  return normalized;
+}
+
+function normalizeJsonObject(
+  value: unknown,
+  path: string,
+  code: string,
+  message: string,
+  issues: NodeFlowValidationIssue[],
+): NodeFlowJsonObject | undefined {
+  if (!isRecord(value)) {
+    issues.push(issue(path, code, message));
+    return undefined;
+  }
+  return normalizeJsonValue(value, path, issues) as NodeFlowJsonObject;
+}
+
+function normalizeValueSchema(
+  value: unknown,
+  path: string,
+  issues: NodeFlowValidationIssue[],
+  ancestors = new Set<object>(),
+): NodeFlowValueSchema | null {
+  if (!isRecord(value)) {
+    issues.push(issue(path, "invalid_value_schema", "Value schema must be an object."));
+    return null;
+  }
+  if (ancestors.has(value)) {
+    issues.push(issue(path, "invalid_value_schema", "Value schema must not contain circular references."));
+    return null;
+  }
+  ancestors.add(value);
+  if (!VALUE_SCHEMA_TYPES.has(value.type as NodeFlowValueSchema["type"])) {
+    issues.push(issue(`${path}.type`, "invalid_schema_type", "Value schema type is invalid."));
+    ancestors.delete(value);
+    return null;
+  }
+  const schema: NodeFlowValueSchema = { type: value.type as NodeFlowValueSchema["type"] };
+  if (value.description !== undefined) {
+    if (typeof value.description === "string") schema.description = value.description.trim();
+    else issues.push(issue(`${path}.description`, "invalid_schema_description", "Value schema description must be a string."));
+  }
+  if (value.required !== undefined) {
+    if (!Array.isArray(value.required)) {
+      issues.push(issue(`${path}.required`, "invalid_schema_required", "Value schema required must be an array."));
+    } else {
+      schema.required = value.required.flatMap((entry, index) => {
+        const required = trimmedString(entry);
+        if (!required) {
+          issues.push(issue(`${path}.required[${index}]`, "invalid_schema_required", "Required property name must be a non-empty string."));
+          return [];
+        }
+        return [required];
+      });
+    }
+  }
+  if (value.properties !== undefined) {
+    if (!isRecord(value.properties)) {
+      issues.push(issue(`${path}.properties`, "invalid_schema_properties", "Value schema properties must be an object."));
+    } else {
+      const properties: Record<string, NodeFlowValueSchema> = {};
+      Object.entries(value.properties).forEach(([key, property]) => {
+        const normalized = normalizeValueSchema(property, `${path}.properties.${key}`, issues, ancestors);
+        if (normalized) properties[key] = normalized;
+      });
+      schema.properties = properties;
+    }
+  }
+  if (value.items !== undefined) {
+    const items = normalizeValueSchema(value.items, `${path}.items`, issues, ancestors);
+    if (items) schema.items = items;
+  }
+  ancestors.delete(value);
+  return schema;
+}
+
+function normalizeGraphSchemas(
+  value: unknown,
+  issues: NodeFlowValidationIssue[],
+): NodeFlowSchemas | undefined {
+  if (value === undefined) return undefined;
+  if (!isRecord(value)) {
+    issues.push(issue("schemas", "invalid_schemas", "Graph schemas must be an object."));
+    return undefined;
+  }
+  const schemas: NodeFlowSchemas = {};
+  if (value.input !== undefined) {
+    const input = normalizeValueSchema(value.input, "schemas.input", issues);
+    if (input) schemas.input = input;
+  }
+  if (value.output !== undefined) {
+    const output = normalizeValueSchema(value.output, "schemas.output", issues);
+    if (output) schemas.output = output;
+  }
+  return schemas;
+}
+
 function validateDefaultValue(
   field: NodeWidgetField,
   fieldPath: string,
@@ -259,41 +395,78 @@ function containsForbiddenGraphValue(value: NodeFlowJsonValue): boolean {
 }
 
 function validatePolicy(
-  policy: NodeFlowNode["policy"],
+  policy: unknown,
   path: string,
   issues: NodeFlowValidationIssue[],
-): void {
-  if (!policy) return;
+): NodeFlowExecutionPolicy | undefined {
+  if (policy === undefined) return undefined;
+  if (!isRecord(policy)) {
+    issues.push(issue(path, "invalid_policy", "Node policy must be an object."));
+    return undefined;
+  }
+  const normalized: NodeFlowExecutionPolicy = {};
   const retry = policy.retry;
-  if (retry && (!Number.isInteger(retry.maxAttempts) || retry.maxAttempts < 1 || retry.maxAttempts > 10)) {
+  if (retry !== undefined && !isRecord(retry)) {
+    issues.push(issue(`${path}.retry`, "invalid_retry_policy", "Retry policy must be an object."));
+  }
+  if (isRecord(retry) && (!Number.isInteger(retry.maxAttempts) || (retry.maxAttempts as number) < 1 || (retry.maxAttempts as number) > 10)) {
     issues.push(issue(`${path}.retry.maxAttempts`, "invalid_retry_policy", "Retry maxAttempts must be an integer from 1 to 10."));
   }
-  if (retry && (!Number.isFinite(retry.backoffMs) || retry.backoffMs < 0 || retry.backoffMs > 300_000)) {
+  if (isRecord(retry) && (!Number.isFinite(retry.backoffMs) || (retry.backoffMs as number) < 0 || (retry.backoffMs as number) > 300_000)) {
     issues.push(issue(`${path}.retry.backoffMs`, "invalid_retry_policy", "Retry backoffMs must be between 0 and 300000."));
   }
-  if (retry?.maxBackoffMs !== undefined && (!Number.isFinite(retry.maxBackoffMs) || retry.maxBackoffMs < retry.backoffMs)) {
+  if (isRecord(retry) && retry.maxBackoffMs !== undefined && (!Number.isFinite(retry.maxBackoffMs) || (retry.maxBackoffMs as number) < (retry.backoffMs as number))) {
     issues.push(issue(`${path}.retry.maxBackoffMs`, "invalid_retry_policy", "Retry maxBackoffMs must be at least backoffMs."));
   }
-  if (policy.timeout && (!Number.isInteger(policy.timeout.timeoutMs) || policy.timeout.timeoutMs < 1 || policy.timeout.timeoutMs > 300_000)) {
+  if (isRecord(retry)) {
+    normalized.retry = {
+      maxAttempts: Number.isInteger(retry.maxAttempts) ? retry.maxAttempts as number : 1,
+      backoffMs: typeof retry.backoffMs === "number" && Number.isFinite(retry.backoffMs) ? retry.backoffMs : 0,
+      ...(typeof retry.maxBackoffMs === "number" && Number.isFinite(retry.maxBackoffMs) ? { maxBackoffMs: retry.maxBackoffMs } : {}),
+    };
+  }
+  if (policy.timeout !== undefined && !isRecord(policy.timeout)) {
+    issues.push(issue(`${path}.timeout`, "invalid_timeout_policy", "Timeout policy must be an object."));
+  }
+  if (isRecord(policy.timeout) && (!Number.isInteger(policy.timeout.timeoutMs) || (policy.timeout.timeoutMs as number) < 1 || (policy.timeout.timeoutMs as number) > 300_000)) {
     issues.push(issue(`${path}.timeout.timeoutMs`, "invalid_timeout_policy", "Timeout must be an integer from 1 to 300000 milliseconds."));
   }
+  if (isRecord(policy.timeout)) {
+    normalized.timeout = { timeoutMs: Number.isInteger(policy.timeout.timeoutMs) ? policy.timeout.timeoutMs as number : 1 };
+  }
+  return normalized;
 }
 
 function validateCredentialBindings(
-  node: NodeFlowNode,
+  value: unknown,
   nodePath: string,
   allowedSlots: string[],
   issues: NodeFlowValidationIssue[],
-): void {
+): NodeFlowNode["credentialBindings"] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) {
+    issues.push(issue(`${nodePath}.credentialBindings`, "invalid_credential_bindings", "Credential bindings must be an array."));
+    return [];
+  }
   const slots = new Set<string>();
-  (node.credentialBindings ?? []).forEach((binding, index) => {
+  const normalized: NonNullable<NodeFlowNode["credentialBindings"]> = [];
+  value.forEach((binding, index) => {
     const path = `${nodePath}.credentialBindings[${index}]`;
-    if (!trimmedString(binding.slot)) issues.push(issue(`${path}.slot`, "required", "Credential slot is required."));
-    if (!trimmedString(binding.credentialId)) issues.push(issue(`${path}.credentialId`, "required", "Credential binding must reference a credential id."));
-    if (slots.has(binding.slot)) issues.push(issue(`${path}.slot`, "duplicate_credential_slot", `Duplicate credential slot: ${binding.slot}`));
-    if (!allowedSlots.includes(binding.slot)) issues.push(issue(`${path}.slot`, "unknown_credential_slot", `Definition does not declare credential slot: ${binding.slot}`));
-    slots.add(binding.slot);
+    if (!isRecord(binding)) {
+      issues.push(issue(path, "invalid_credential_binding", "Credential binding must be an object."));
+      return;
+    }
+    const slot = trimmedString(binding.slot);
+    const credentialId = trimmedString(binding.credentialId);
+    if (!slot) issues.push(issue(`${path}.slot`, "required", "Credential slot is required."));
+    if (!credentialId) issues.push(issue(`${path}.credentialId`, "required", "Credential binding must reference a credential id."));
+    if (!slot || !credentialId) return;
+    if (slots.has(slot)) issues.push(issue(`${path}.slot`, "duplicate_credential_slot", `Duplicate credential slot: ${slot}`));
+    if (!allowedSlots.includes(slot)) issues.push(issue(`${path}.slot`, "unknown_credential_slot", `Definition does not declare credential slot: ${slot}`));
+    slots.add(slot);
+    normalized.push({ slot, credentialId });
   });
+  return normalized;
 }
 
 function validateConfiguration(
@@ -324,9 +497,93 @@ function matchesValueSchema(value: NodeFlowJsonValue, type: NodeFlowValueSchema[
   return typeof value === type;
 }
 
-function normalizeNode(rawNode: NodeFlowNode, index: number, issues: NodeFlowValidationIssue[]): NodeFlowNode | null {
+function normalizeDefinitionReference(
+  value: unknown,
+  fallbackType: string,
+  path: string,
+  issues: NodeFlowValidationIssue[],
+): { reference: NodeFlowDefinitionReference; structurallyValid: boolean } {
+  if (value === undefined) return { reference: { type: fallbackType, version: 1 }, structurallyValid: true };
+  if (!isRecord(value)) {
+    issues.push(issue(path, "invalid_definition_reference", "Node definition reference must be an object."));
+    return { reference: { type: fallbackType, version: 1 }, structurallyValid: false };
+  }
+  const type = trimmedString(value.type);
+  const version = value.version;
+  if (!type) issues.push(issue(`${path}.type`, "required", "Node definition type is required."));
+  if (!Number.isInteger(version) || (version as number) < 1) {
+    issues.push(issue(`${path}.version`, "invalid_definition_version", "Node definition version must be a positive integer."));
+  }
+  return {
+    reference: { type: type ?? fallbackType, version: Number.isInteger(version) && (version as number) > 0 ? version as number : 1 },
+    structurallyValid: Boolean(type) && Number.isInteger(version) && (version as number) > 0,
+  };
+}
+
+function normalizePorts(
+  value: unknown,
+  fallback: readonly NodeFlowPort[],
+  nodePath: string,
+  issues: NodeFlowValidationIssue[],
+): NodeFlowPort[] {
+  if (value === undefined) return fallback.map((port) => ({ ...port }));
+  if (!Array.isArray(value)) {
+    issues.push(issue(`${nodePath}.ports`, "invalid_ports", "Node ports must be an array."));
+    return [];
+  }
+  const portIds = new Set<string>();
+  const normalized: NodeFlowPort[] = [];
+  value.forEach((port, portIndex) => {
+    const portPath = `${nodePath}.ports[${portIndex}]`;
+    if (!isRecord(port)) {
+      issues.push(issue(portPath, "invalid_port", "Port must be an object."));
+      return;
+    }
+    const id = trimmedString(port.id);
+    if (!id) issues.push(issue(`${portPath}.id`, "required", "Port id is required."));
+    if (id && portIds.has(id)) issues.push(issue(`${portPath}.id`, "duplicate_port_id", `Duplicate port id: ${id}`));
+    if (id) portIds.add(id);
+    const direction = port.direction === "input" || port.direction === "output" ? port.direction : null;
+    if (!direction) issues.push(issue(`${portPath}.direction`, "invalid_port_direction", "Port direction must be input or output."));
+    const schema = normalizeValueSchema(port.schema, `${portPath}.schema`, issues);
+    if (port.required !== undefined && typeof port.required !== "boolean") {
+      issues.push(issue(`${portPath}.required`, "invalid_port_required", "Port required must be a boolean."));
+    }
+    const cardinality = port.cardinality === undefined || port.cardinality === "one" || port.cardinality === "many"
+      ? port.cardinality
+      : null;
+    if (cardinality === null) issues.push(issue(`${portPath}.cardinality`, "invalid_port_cardinality", "Port cardinality must be one or many."));
+    if (!id || !direction || !schema) return;
+    normalized.push({
+      id,
+      direction,
+      schema,
+      ...(typeof port.required === "boolean" ? { required: port.required } : {}),
+      ...(cardinality ? { cardinality } : {}),
+    });
+  });
+  return normalized;
+}
+
+function normalizeCapabilities(value: unknown, path: string, issues: NodeFlowValidationIssue[]): string[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value)) {
+    issues.push(issue(path, "invalid_capabilities", "Node capabilities must be an array."));
+    return [];
+  }
+  return value.flatMap((entry, index) => {
+    const capability = trimmedString(entry);
+    if (!capability) {
+      issues.push(issue(`${path}[${index}]`, "invalid_capability", "Capability must be a non-empty string."));
+      return [];
+    }
+    return [capability];
+  });
+}
+
+function normalizeNode(rawNode: unknown, index: number, issues: NodeFlowValidationIssue[]): NodeFlowNode | null {
   const nodePath = `nodes[${index}]`;
-  if (!rawNode || typeof rawNode !== "object" || Array.isArray(rawNode)) {
+  if (!isRecord(rawNode)) {
     issues.push(issue(nodePath, "invalid_node", "Node must be an object."));
     return null;
   }
@@ -346,8 +603,8 @@ function normalizeNode(rawNode: NodeFlowNode, index: number, issues: NodeFlowVal
     return null;
   }
 
-  const widgetSchema = normalizeWidgetSchema(rawNode.widgetSchema, `${nodePath}.widgetSchema`, issues);
-  const position = rawNode.position
+  const widgetSchema = normalizeWidgetSchema(rawNode.widgetSchema as NodeWidgetSchema | undefined, `${nodePath}.widgetSchema`, issues);
+  const position = isRecord(rawNode.position)
     && typeof rawNode.position.x === "number"
     && Number.isFinite(rawNode.position.x)
     && typeof rawNode.position.y === "number"
@@ -357,61 +614,64 @@ function normalizeNode(rawNode: NodeFlowNode, index: number, issues: NodeFlowVal
   if (rawNode.position !== undefined && !position) {
     issues.push(issue(`${nodePath}.position`, "invalid_position", `Node ${id} position must include finite x and y numbers.`));
   }
-  if (rawNode.data !== undefined && !isPlainJsonObject(rawNode.data)) {
-    issues.push(issue(`${nodePath}.data`, "invalid_data", `Node ${id} data must be a JSON object.`));
-  }
+  const data = rawNode.data === undefined
+    ? undefined
+    : normalizeJsonObject(rawNode.data, `${nodePath}.data`, "invalid_data", `Node ${id} data must be a JSON object.`, issues);
 
-  const definitionRef = rawNode.definition ?? { type, version: 1 };
-  const definition = resolveNodeDefinition(definitionRef.type, definitionRef.version);
-  if (definitionRef.type !== type) {
+  const { reference: definitionRef, structurallyValid: validDefinitionRef } = normalizeDefinitionReference(
+    rawNode.definition,
+    type,
+    `${nodePath}.definition`,
+    issues,
+  );
+  const definition = validDefinitionRef ? resolveNodeDefinition(definitionRef.type, definitionRef.version) : undefined;
+  if (validDefinitionRef && definitionRef.type !== type) {
     issues.push(issue(`${nodePath}.definition.type`, "definition_type_mismatch", "Node type must match its definition reference."));
   }
-  if (!definition) {
+  if (validDefinitionRef && !definition) {
     issues.push(issue(`${nodePath}.definition`, "unknown_node_definition", `Unknown node definition: ${definitionRef.type}@${definitionRef.version}`));
   }
   if (definition && rawNode.sideEffect !== undefined && rawNode.sideEffect !== definition.sideEffect) {
     issues.push(issue(`${nodePath}.sideEffect`, "definition_metadata_mismatch", "Node side effect must match its definition."));
   }
-  if (definition && rawNode.capabilities !== undefined && [...rawNode.capabilities].sort().join("\0") !== [...definition.capabilities].sort().join("\0")) {
+  const capabilities = normalizeCapabilities(rawNode.capabilities, `${nodePath}.capabilities`, issues);
+  if (definition && capabilities !== undefined && [...capabilities].sort().join("\0") !== [...definition.capabilities].sort().join("\0")) {
     issues.push(issue(`${nodePath}.capabilities`, "definition_metadata_mismatch", "Node capabilities must match its definition."));
   }
-  const ports = rawNode.ports ?? definition?.ports ?? [];
-  const portIds = new Set<string>();
-  ports.forEach((port, portIndex) => {
-    const portPath = `${nodePath}.ports[${portIndex}]`;
-    if (!trimmedString(port.id)) issues.push(issue(`${portPath}.id`, "required", "Port id is required."));
-    if (portIds.has(port.id)) issues.push(issue(`${portPath}.id`, "duplicate_port_id", `Duplicate port id: ${port.id}`));
-    portIds.add(port.id);
-    if (port.direction !== "input" && port.direction !== "output") issues.push(issue(`${portPath}.direction`, "invalid_port_direction", "Port direction must be input or output."));
-  });
-  validatePolicy(rawNode.policy, `${nodePath}.policy`, issues);
-  validateCredentialBindings(rawNode, nodePath, definition?.credentials.map((credential) => credential.slot) ?? [], issues);
-  if (rawNode.data && containsForbiddenGraphValue(rawNode.data)) {
+  const ports = normalizePorts(rawNode.ports, definition?.ports ?? [], nodePath, issues);
+  const policy = validatePolicy(rawNode.policy, `${nodePath}.policy`, issues);
+  const credentialBindings = validateCredentialBindings(
+    rawNode.credentialBindings,
+    nodePath,
+    definition?.credentials.map((credential) => credential.slot) ?? [],
+    issues,
+  );
+  if (data && containsForbiddenGraphValue(data)) {
     issues.push(issue(`${nodePath}.data`, "unsafe_graph_data", "Graph data cannot contain raw secrets or custom source code."));
   }
-  if (definition) validateConfiguration(isPlainJsonObject(rawNode.data) ? rawNode.data : {}, definition.configurationSchema, nodePath, issues);
+  if (definition) validateConfiguration(data ?? {}, definition.configurationSchema, nodePath, issues);
 
   return {
     id,
     type,
     title: title ?? id,
-    ...(rawNode.description !== undefined ? { description: String(rawNode.description).trim() } : {}),
+    ...(typeof rawNode.description === "string" ? { description: rawNode.description.trim() } : {}),
     ...(widgetSchema ? { widgetSchema } : {}),
     ...(position ? { position } : {}),
-    ...(rawNode.data !== undefined && isPlainJsonObject(rawNode.data) ? { data: rawNode.data } : {}),
+    ...(data ? { data } : {}),
     definition: definitionRef,
     ports,
-    credentialBindings: rawNode.credentialBindings ?? [],
-    policy: rawNode.policy ?? definition?.defaultPolicy ?? {},
-    capabilities: definition?.capabilities ?? rawNode.capabilities ?? [],
-    sideEffect: definition?.sideEffect ?? rawNode.sideEffect ?? "none",
-    disabled: rawNode.disabled ?? false,
+    credentialBindings,
+    policy: policy ?? definition?.defaultPolicy ?? {},
+    capabilities: definition?.capabilities ?? capabilities ?? [],
+    sideEffect: definition?.sideEffect ?? (rawNode.sideEffect as NodeFlowNode["sideEffect"] ?? "none"),
+    disabled: typeof rawNode.disabled === "boolean" ? rawNode.disabled : false,
   };
 }
 
-function normalizeEdge(rawEdge: NodeFlowEdge, index: number, issues: NodeFlowValidationIssue[]): NodeFlowEdge | null {
+function normalizeEdge(rawEdge: unknown, index: number, issues: NodeFlowValidationIssue[]): NodeFlowEdge | null {
   const edgePath = `edges[${index}]`;
-  if (!rawEdge || typeof rawEdge !== "object" || Array.isArray(rawEdge)) {
+  if (!isRecord(rawEdge)) {
     issues.push(issue(edgePath, "invalid_edge", "Edge must be an object."));
     return null;
   }
@@ -500,9 +760,11 @@ export function validateNodeFlowGraph(graph: unknown): NodeFlowValidationRespons
   const nodes = Array.isArray(rawGraph.nodes)
     ? rawGraph.nodes.map((node, index) => normalizeNode(node, index, issues)).filter((node): node is NodeFlowNode => Boolean(node))
     : [];
-  const edges = Array.isArray(rawGraph.edges)
-    ? rawGraph.edges.map((edge, index) => normalizeEdge(edge, index, issues)).filter((edge): edge is NodeFlowEdge => Boolean(edge))
+  const normalizedEdges = Array.isArray(rawGraph.edges)
+    ? rawGraph.edges.map((edge, index) => ({ edge: normalizeEdge(edge, index, issues), sourceIndex: index }))
+      .filter((entry): entry is { edge: NodeFlowEdge; sourceIndex: number } => Boolean(entry.edge))
     : [];
+  const edges = normalizedEdges.map((entry) => entry.edge);
 
   if (nodes.length === 0) {
     issues.push(issue("nodes", "required", "Node flow graph requires at least one node."));
@@ -516,28 +778,29 @@ export function validateNodeFlowGraph(graph: unknown): NodeFlowValidationRespons
     nodeIds.add(node.id);
   }
 
-  edges.forEach((edge, index) => {
+  normalizedEdges.forEach(({ edge, sourceIndex }) => {
     if (!nodeIds.has(edge.fromNodeId)) {
-      issues.push(issue(`edges[${index}].fromNodeId`, "invalid_edge_endpoint", `Edge source node does not exist: ${edge.fromNodeId}`));
+      issues.push(issue(`edges[${sourceIndex}].fromNodeId`, "invalid_edge_endpoint", `Edge source node does not exist: ${edge.fromNodeId}`));
     }
     if (!nodeIds.has(edge.toNodeId)) {
-      issues.push(issue(`edges[${index}].toNodeId`, "invalid_edge_endpoint", `Edge target node does not exist: ${edge.toNodeId}`));
+      issues.push(issue(`edges[${sourceIndex}].toNodeId`, "invalid_edge_endpoint", `Edge target node does not exist: ${edge.toNodeId}`));
     }
     const source = nodes.find((node) => node.id === edge.fromNodeId);
     const target = nodes.find((node) => node.id === edge.toNodeId);
     if (source && edge.fromHandle && !source.ports?.some((port) => port.id === edge.fromHandle && port.direction === "output")) {
-      issues.push(issue(`edges[${index}].fromHandle`, "invalid_source_port", `Source port does not exist or is not an output: ${edge.fromHandle}`));
+      issues.push(issue(`edges[${sourceIndex}].fromHandle`, "invalid_source_port", `Source port does not exist or is not an output: ${edge.fromHandle}`));
     }
     if (target && edge.toHandle && !target.ports?.some((port) => port.id === edge.toHandle && port.direction === "input")) {
-      issues.push(issue(`edges[${index}].toHandle`, "invalid_target_port", `Target port does not exist or is not an input: ${edge.toHandle}`));
+      issues.push(issue(`edges[${sourceIndex}].toHandle`, "invalid_target_port", `Target port does not exist or is not an input: ${edge.toHandle}`));
     }
   });
 
   const inputSchema = normalizeWidgetSchema(rawGraph.inputSchema, "inputSchema", issues);
-  if (rawGraph.metadata !== undefined && !isPlainJsonObject(rawGraph.metadata)) {
-    issues.push(issue("metadata", "invalid_metadata", "Node flow graph metadata must be a JSON object."));
-  }
-  if (rawGraph.metadata && containsForbiddenGraphValue(rawGraph.metadata)) {
+  const schemas = normalizeGraphSchemas(rawGraph.schemas, issues);
+  const metadata = rawGraph.metadata === undefined
+    ? undefined
+    : normalizeJsonObject(rawGraph.metadata, "metadata", "invalid_metadata", "Node flow graph metadata must be a JSON object.", issues);
+  if (metadata && containsForbiddenGraphValue(metadata)) {
     issues.push(issue("metadata", "unsafe_graph_metadata", "Graph metadata cannot contain raw secrets or custom source code."));
   }
   validatePublication(rawGraph.publication, issues);
@@ -547,8 +810,8 @@ export function validateNodeFlowGraph(graph: unknown): NodeFlowValidationRespons
     nodes,
     edges,
     ...(inputSchema ? { inputSchema } : {}),
-    ...(rawGraph.schemas ? { schemas: rawGraph.schemas } : {}),
-    ...(rawGraph.metadata !== undefined && isPlainJsonObject(rawGraph.metadata) ? { metadata: rawGraph.metadata } : {}),
+    ...(schemas ? { schemas } : {}),
+    ...(metadata ? { metadata } : {}),
     ...(rawGraph.publication ? { publication: rawGraph.publication } : {}),
   };
   const executionOrder = computeExecutionOrder(nodes, edges, issues);
@@ -561,16 +824,21 @@ export function validateNodeFlowGraph(graph: unknown): NodeFlowValidationRespons
 }
 
 function validatePublication(
-  publication: NodeFlowGraph["publication"],
+  publication: unknown,
   issues: NodeFlowValidationIssue[],
 ): void {
-  if (!publication) return;
+  if (publication === undefined) return;
+  if (!isRecord(publication)) {
+    issues.push(issue("publication", "invalid_publication", "Publication metadata must be an object."));
+    return;
+  }
   if (!trimmedString(publication.publicationId)) issues.push(issue("publication.publicationId", "required", "Publication id is required."));
   if (!trimmedString(publication.publishedBy)) issues.push(issue("publication.publishedBy", "required", "Publication author is required."));
-  if (!trimmedString(publication.publishedAt) || !Number.isFinite(Date.parse(publication.publishedAt))) {
+  const publishedAt = trimmedString(publication.publishedAt);
+  if (!publishedAt || !Number.isFinite(Date.parse(publishedAt))) {
     issues.push(issue("publication.publishedAt", "invalid_publication", "Publication timestamp must be ISO-compatible."));
   }
-  if (!Number.isInteger(publication.sourceVersion) || publication.sourceVersion < 1) {
+  if (!Number.isInteger(publication.sourceVersion) || (publication.sourceVersion as number) < 1) {
     issues.push(issue("publication.sourceVersion", "invalid_publication", "Publication sourceVersion must be a positive integer."));
   }
 }
diff --git a/tests/backend/domain/node-flows/node-flow-migrators.test.ts b/tests/backend/domain/node-flows/node-flow-migrators.test.ts
index 5ee0b0727a..e8aaef1fe8 100644
--- a/tests/backend/domain/node-flows/node-flow-migrators.test.ts
+++ b/tests/backend/domain/node-flows/node-flow-migrators.test.ts
@@ -28,4 +28,31 @@ describe("node flow migrators", () => {
     expect(result.graph.metadata).toEqual({ canvasSelection: legacy.selection });
     expect(JSON.stringify(result.graph)).not.toContain("legacySnapshot");
   });
+
+  it("preserves malformed v1 entries for field-level validation without throwing", () => {
+    const legacy = {
+      nodes: [null, { id: "start", type: "input", title: "Start", ports: [null], credentialBindings: [null] }],
+      edges: [null],
+    };
+
+    const result = migrateNodeFlowGraph(legacy);
+
+    expect(result.graph.nodes).toHaveLength(2);
+    expect(result.graph.nodes[0]).toBeNull();
+    expect(result.graph.nodes[1]?.ports?.[0]).toBeNull();
+    expect(result.graph.nodes[1]?.credentialBindings?.[0]).toBeNull();
+    expect(result.graph.edges[0]).toBeNull();
+  });
+
+  it("clones malformed canonical graphs deterministically without JSON serialization", () => {
+    const metadata: Record<string, unknown> = { valid: true, invalid: undefined };
+    metadata.circular = metadata;
+    const graph = { schemaVersion: 2, nodes: [], edges: [], metadata };
+
+    const result = migrateNodeFlowGraph(graph);
+
+    expect(result.migrated).toBe(false);
+    expect(result.graph.metadata).not.toBe(metadata);
+    expect((result.graph.metadata as Record<string, unknown>).circular).toBe(result.graph.metadata);
+  });
 });
diff --git a/tests/backend/domain/node-flows/node-flow-validation.test.ts b/tests/backend/domain/node-flows/node-flow-validation.test.ts
index 2e56cc6bbb..0c4d681008 100644
--- a/tests/backend/domain/node-flows/node-flow-validation.test.ts
+++ b/tests/backend/domain/node-flows/node-flow-validation.test.ts
@@ -112,4 +112,102 @@ describe("node flow validation", () => {
 
     expect(validateNodeFlowGraph(graph).executionOrder).toEqual(["a", "z"]);
   });
+
+  it("fails closed on malformed canonical nested values with stable field paths", () => {
+    const graph = {
+      schemaVersion: 2,
+      nodes: [
+        null,
+        {
+          id: "start",
+          type: "input",
+          title: "Start",
+          definition: { type: "input", version: 1 },
+          ports: [null, { id: "out", direction: "output", schema: { type: "any" } }],
+          credentialBindings: [null],
+          capabilities: [null],
+          policy: { retry: null },
+        },
+      ],
+      edges: [null, { fromNodeId: "start", toNodeId: "missing", fromHandle: "out" }],
+      schemas: {
+        input: { type: "object", properties: { valid: { type: "string" }, invalid: null } },
+        output: null,
+      },
+      metadata: { valid: true, nested: { invalid: undefined } },
+    };
+
+    const first = validateNodeFlowGraph(graph);
+    const second = validateNodeFlowGraph(graph);
+
+    expect(first).toEqual(second);
+    expect(first.valid).toBe(false);
+    expect(first.errors).toEqual(expect.arrayContaining([
+      expect.objectContaining({ field: "nodes[0]", code: "invalid_node" }),
+      expect.objectContaining({ field: "nodes[1].ports[0]", code: "invalid_port" }),
+      expect.objectContaining({ field: "nodes[1].credentialBindings[0]", code: "invalid_credential_binding" }),
+      expect.objectContaining({ field: "nodes[1].capabilities[0]", code: "invalid_capability" }),
+      expect.objectContaining({ field: "nodes[1].policy.retry", code: "invalid_retry_policy" }),
+      expect.objectContaining({ field: "edges[0]", code: "invalid_edge" }),
+      expect.objectContaining({ field: "edges[1].toNodeId", code: "invalid_edge_endpoint" }),
+      expect.objectContaining({ field: "schemas.input.properties.invalid", code: "invalid_value_schema" }),
+      expect.objectContaining({ field: "schemas.output", code: "invalid_value_schema" }),
+      expect.objectContaining({ field: "metadata.nested.invalid", code: "invalid_json_value" }),
+    ]));
+  });
+
+  it("reports malformed Graph v1 references and collections without throwing", () => {
+    const graph = {
+      nodes: [
+        null,
+        {
+          id: "start",
+          type: "input",
+          title: "Start",
+          definition: { type: "input", version: "invalid" },
+          ports: null,
+          credentialBindings: null,
+          capabilities: null,
+          policy: null,
+        },
+      ],
+      edges: [null],
+    };
+
+    const result = validateNodeFlowGraph(graph);
+
+    expect(result.errors).toEqual(expect.arrayContaining([
+      expect.objectContaining({ field: "nodes[0]", code: "invalid_node" }),
+      expect.objectContaining({ field: "nodes[1].definition.version", code: "invalid_definition_version" }),
+      expect.objectContaining({ field: "nodes[1].ports", code: "invalid_ports" }),
+      expect.objectContaining({ field: "nodes[1].credentialBindings", code: "invalid_credential_bindings" }),
+      expect.objectContaining({ field: "nodes[1].capabilities", code: "invalid_capabilities" }),
+      expect.objectContaining({ field: "nodes[1].policy", code: "invalid_policy" }),
+      expect.objectContaining({ field: "edges[0]", code: "invalid_edge" }),
+    ]));
+  });
+
+  it.each([
+    [{ schemaVersion: 2, nodes: null, edges: [] }, "nodes"],
+    [{ nodes: [], edges: "invalid" }, "edges"],
+  ])("rejects malformed graph arrays at their root path", (graph, field) => {
+    expect(validateNodeFlowGraph(graph).errors).toContainEqual(expect.objectContaining({ field, code: "required" }));
+  });
+
+  it("rejects circular metadata at the repeated field path without throwing", () => {
+    const graph = validGraph() as unknown as Record<string, unknown>;
+    const metadata: Record<string, unknown> = { safe: true };
+    metadata.circular = metadata;
+    graph.schemaVersion = 2;
+    graph.metadata = metadata;
+
+    const first = validateNodeFlowGraph(graph);
+    const second = validateNodeFlowGraph(graph);
+
+    expect(first).toEqual(second);
+    expect(first.errors).toContainEqual(expect.objectContaining({
+      field: "metadata.circular",
+      code: "invalid_json_value",
+    }));
+  });
 });

From ac0991b91a5a19e1b7bf633a8bbfbd2832a8f774 Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 09:41:27 +0000
Subject: [PATCH 22/25] feat(task T20): implement via codex

---
 .../node-flow-builtins-and-security.md        |   4 +-
 .../node-flow-durable-execution.md            |   4 +-
 ...ecture-node-flow-builtins-and-security.mdx |   4 +-
 ...chitecture-node-flow-durable-execution.mdx |   4 +-
 .../docs/user-dashboard-node-flows.mdx        |   2 +
 docs-web/user/dashboard/node-flows.md         |   2 +
 .../node-flow-builtins-and-security.md        |   4 +-
 .../node-flow-durable-execution.md            |   4 +-
 docs/dashboard/node-flows.md                  |   2 +
 src/contracts/node-flow-types.ts              |   3 +
 .../node-flows/node-definition-registry.ts    |   2 +-
 src/repositories/db/app-db-migrations.ts      |  48 +++-
 src/repositories/db/app-db-schema.ts          |   1 +
 src/repositories/node-flow-repository.ts      |  16 +-
 src/services/node-flow-runtime-service.ts     | 264 +++++++++++++++++-
 .../node-flows/builtins/builtin-executors.ts  |  10 +-
 .../node-flows/node-flow-attempt-service.ts   |   5 +-
 .../node-flows/node-flow-recovery-service.ts  |   6 +-
 .../services/node-flow-builtins.test.ts       |   2 +
 .../node-flow-runtime-service.test.ts         | 123 ++++++++
 20 files changed, 470 insertions(+), 40 deletions(-)

diff --git a/docs-web/architecture/node-flow-builtins-and-security.md b/docs-web/architecture/node-flow-builtins-and-security.md
index 3c98e077e8..80324199ed 100644
--- a/docs-web/architecture/node-flow-builtins-and-security.md
+++ b/docs-web/architecture/node-flow-builtins-and-security.md
@@ -5,7 +5,7 @@ The governed catalog adds deterministic branches, bounded collection processing,
 ## Control and integration nodes
 
 - `condition` selects `true` or `false`; `switch` selects one named case or `default`. Unselected branches persist as skipped node runs.
-- `foreach` accepts no more than 1,000 items. `merge` supports `object`, `array`, and `first` strategies.
+- `foreach` rejects inputs above its configured bound (never more than 1,000), then runs downstream nodes once per deterministic logical item. Configured concurrency defaults to one and is capped at 64; zero items explicitly select `empty`. `merge` supports `object`, `array`, and `first` strategies.
 - `delay` is cancellable and capped at one hour. `execute_subflow` requires same-project ownership, rejects direct self-reference, and caps depth at eight.
 - `approval` persists an idempotent operator decision and continues the exact pinned run after approval. `email_draft` never sends. `email_send` requires approval and uses the idempotent outbox.
 - `webhook_trigger` emits payloads accepted through secret-authenticated webhook ingress.
@@ -20,6 +20,8 @@ Every redirect is manually revalidated. DNS is checked for private results and r
 
 Pending approvals preserve the run, governed node, logical item, and numbered attempt. Approved decisions resume at that node boundary; rejected and expired decisions terminate durably. Repeated decisions and restart recovery do not create a second approval request, attempt, or external delivery.
 
+Foreach descendant node runs and attempts persist item-specific inputs and logical identity. Retries remain item-local, completed siblings are reconstructed rather than replayed after restart, and aggregation preserves input order.
+
 OAuth authorization uses PKCE S256 and short-lived AES-256-GCM state tied to an allowlisted callback origin. Tokens live behind the connection store, rotate on refresh, enforce scopes and expiry, and are never written into graph JSON or agent-visible output. Revocation, reconnect, and health checks expose no token values.
 
 Approvals are unique per run, node, and logical item. Outbox entries use a unique key derived from publication, run, node, and logical item, and store the provider message id after success. A restart while an entry is sending changes it to `attention_required`; Code UX does not automatically replay an unknown provider outcome.
diff --git a/docs-web/architecture/node-flow-durable-execution.md b/docs-web/architecture/node-flow-durable-execution.md
index 2fb818f283..3d22eec217 100644
--- a/docs-web/architecture/node-flow-durable-execution.md
+++ b/docs-web/architecture/node-flow-durable-execution.md
@@ -4,8 +4,8 @@ Node flows execute immutable published snapshots. A run explicitly pins a publis
 
 Distributed runners are authenticated service principals with `automation_runner` and explicit project scope. Queue claims use a database compare-and-set lease, and heartbeats renew only for the current owner. Outbox idempotency combines publication, run, node, and logical item, so restart reconstruction returns prior sent rows instead of duplicating external effects. Unknown outcomes require attention; approvals, attempts, credential access, and delivery emit redacted correlation audit records.
 
-Runs are durably queued and leased with bounded global and project concurrency. Node attempts retain attempt number, executor and invocation identity, artifact digest, redacted payloads, credential ids, failure class, and retry decision. Retryable failures use bounded exponential backoff and jitter, while cancellation and timeout signals propagate to provider and HTTP work.
+Runs are durably queued and leased with bounded global and project concurrency. Node attempts retain logical-item identity, item-local attempt number, executor and invocation identity, artifact digest, redacted payloads, credential ids, failure class, and retry decision. Retryable failures use bounded exponential backoff and jitter, while cancellation and timeout signals propagate to provider and HTTP work.
 
-On restart, expired pre-invocation work is safely requeued. Work with an external invocation and an unknown outcome moves to `attention_required` and is never silently replayed. Pending approvals stay paused; persisted approvals continue the same run and pinned publication, while rejected or expired decisions fail the governed node and run durably. Credential values are resolved only for the active node and are not retained in run history or diagnostics.
+On restart, expired pre-invocation work is safely requeued. Work with an external invocation and an unknown outcome moves to `attention_required` and is never silently replayed. Pending approvals stay paused; persisted approvals continue the same run, pinned publication, and logical item while completed Foreach siblings are reconstructed without replay. Rejected or expired decisions fail the governed node and run durably. Credential values are resolved only for the active node and are not retained in run history or diagnostics.
 
 Approval continuation compare-and-set claims the waiting run, reconstructs prior outputs and branch choices, and reuses the waiting node attempt. Repeated decisions or explicit resume requests therefore return the current durable run state without creating another attempt or outbox delivery.
diff --git a/docs-web/content/docs/architecture-node-flow-builtins-and-security.mdx b/docs-web/content/docs/architecture-node-flow-builtins-and-security.mdx
index 3c98e077e8..80324199ed 100644
--- a/docs-web/content/docs/architecture-node-flow-builtins-and-security.mdx
+++ b/docs-web/content/docs/architecture-node-flow-builtins-and-security.mdx
@@ -5,7 +5,7 @@ The governed catalog adds deterministic branches, bounded collection processing,
 ## Control and integration nodes
 
 - `condition` selects `true` or `false`; `switch` selects one named case or `default`. Unselected branches persist as skipped node runs.
-- `foreach` accepts no more than 1,000 items. `merge` supports `object`, `array`, and `first` strategies.
+- `foreach` rejects inputs above its configured bound (never more than 1,000), then runs downstream nodes once per deterministic logical item. Configured concurrency defaults to one and is capped at 64; zero items explicitly select `empty`. `merge` supports `object`, `array`, and `first` strategies.
 - `delay` is cancellable and capped at one hour. `execute_subflow` requires same-project ownership, rejects direct self-reference, and caps depth at eight.
 - `approval` persists an idempotent operator decision and continues the exact pinned run after approval. `email_draft` never sends. `email_send` requires approval and uses the idempotent outbox.
 - `webhook_trigger` emits payloads accepted through secret-authenticated webhook ingress.
@@ -20,6 +20,8 @@ Every redirect is manually revalidated. DNS is checked for private results and r
 
 Pending approvals preserve the run, governed node, logical item, and numbered attempt. Approved decisions resume at that node boundary; rejected and expired decisions terminate durably. Repeated decisions and restart recovery do not create a second approval request, attempt, or external delivery.
 
+Foreach descendant node runs and attempts persist item-specific inputs and logical identity. Retries remain item-local, completed siblings are reconstructed rather than replayed after restart, and aggregation preserves input order.
+
 OAuth authorization uses PKCE S256 and short-lived AES-256-GCM state tied to an allowlisted callback origin. Tokens live behind the connection store, rotate on refresh, enforce scopes and expiry, and are never written into graph JSON or agent-visible output. Revocation, reconnect, and health checks expose no token values.
 
 Approvals are unique per run, node, and logical item. Outbox entries use a unique key derived from publication, run, node, and logical item, and store the provider message id after success. A restart while an entry is sending changes it to `attention_required`; Code UX does not automatically replay an unknown provider outcome.
diff --git a/docs-web/content/docs/architecture-node-flow-durable-execution.mdx b/docs-web/content/docs/architecture-node-flow-durable-execution.mdx
index 2fb818f283..3d22eec217 100644
--- a/docs-web/content/docs/architecture-node-flow-durable-execution.mdx
+++ b/docs-web/content/docs/architecture-node-flow-durable-execution.mdx
@@ -4,8 +4,8 @@ Node flows execute immutable published snapshots. A run explicitly pins a publis
 
 Distributed runners are authenticated service principals with `automation_runner` and explicit project scope. Queue claims use a database compare-and-set lease, and heartbeats renew only for the current owner. Outbox idempotency combines publication, run, node, and logical item, so restart reconstruction returns prior sent rows instead of duplicating external effects. Unknown outcomes require attention; approvals, attempts, credential access, and delivery emit redacted correlation audit records.
 
-Runs are durably queued and leased with bounded global and project concurrency. Node attempts retain attempt number, executor and invocation identity, artifact digest, redacted payloads, credential ids, failure class, and retry decision. Retryable failures use bounded exponential backoff and jitter, while cancellation and timeout signals propagate to provider and HTTP work.
+Runs are durably queued and leased with bounded global and project concurrency. Node attempts retain logical-item identity, item-local attempt number, executor and invocation identity, artifact digest, redacted payloads, credential ids, failure class, and retry decision. Retryable failures use bounded exponential backoff and jitter, while cancellation and timeout signals propagate to provider and HTTP work.
 
-On restart, expired pre-invocation work is safely requeued. Work with an external invocation and an unknown outcome moves to `attention_required` and is never silently replayed. Pending approvals stay paused; persisted approvals continue the same run and pinned publication, while rejected or expired decisions fail the governed node and run durably. Credential values are resolved only for the active node and are not retained in run history or diagnostics.
+On restart, expired pre-invocation work is safely requeued. Work with an external invocation and an unknown outcome moves to `attention_required` and is never silently replayed. Pending approvals stay paused; persisted approvals continue the same run, pinned publication, and logical item while completed Foreach siblings are reconstructed without replay. Rejected or expired decisions fail the governed node and run durably. Credential values are resolved only for the active node and are not retained in run history or diagnostics.
 
 Approval continuation compare-and-set claims the waiting run, reconstructs prior outputs and branch choices, and reuses the waiting node attempt. Repeated decisions or explicit resume requests therefore return the current durable run state without creating another attempt or outbox delivery.
diff --git a/docs-web/content/docs/user-dashboard-node-flows.mdx b/docs-web/content/docs/user-dashboard-node-flows.mdx
index 0b39ac2177..9df955e584 100644
--- a/docs-web/content/docs/user-dashboard-node-flows.mdx
+++ b/docs-web/content/docs/user-dashboard-node-flows.mdx
@@ -34,6 +34,8 @@ Rendered run payloads redact secret-shaped keys such as `apiKey`, `authorization
 
 The run debugger lists durable approvals beside node attempts. A pending item offers **Approve & continue** and **Reject** actions. The decision applies to the same pinned run, and repeated clicks return its current state without sending an approved external effect twice.
 
+Foreach executes the selected downstream branch once per deterministic logical item. The node's `concurrency` setting bounds active items, `maxItems` rejects oversized inputs, and zero items explicitly select the `empty` branch. Item-specific inputs, retries, cancellation, approvals, and external-effect identity are persisted so restart continuation does not replay completed items or duplicate sends.
+
 ## Agent Attachment
 
 A flow can be attached to a project agent preset as a repeatable skill with a name and description. Detaching removes only that binding; the flow, its graph, schedules, and run history remain in the project.
diff --git a/docs-web/user/dashboard/node-flows.md b/docs-web/user/dashboard/node-flows.md
index 0acfe45d15..e032ca1305 100644
--- a/docs-web/user/dashboard/node-flows.md
+++ b/docs-web/user/dashboard/node-flows.md
@@ -34,6 +34,8 @@ Rendered run payloads redact secret-shaped keys such as `apiKey`, `authorization
 
 The run debugger lists durable approvals beside node attempts. A pending item offers **Approve & continue** and **Reject** actions. The decision applies to the same pinned run, and repeated clicks return its current state without sending an approved external effect twice.
 
+Foreach executes the selected downstream branch once per deterministic logical item. The node's `concurrency` setting bounds active items, `maxItems` rejects oversized inputs, and zero items explicitly select the `empty` branch. Item-specific inputs, retries, cancellation, approvals, and external-effect identity are persisted so restart continuation does not replay completed items or duplicate sends.
+
 ## Agent Attachment
 
 A flow can be attached to a project agent preset as a repeatable skill with a name and description. Detaching removes only that binding; the flow, its graph, schedules, and run history remain in the project.
diff --git a/docs/architecture/node-flow-builtins-and-security.md b/docs/architecture/node-flow-builtins-and-security.md
index d59181c764..4cb15afeba 100644
--- a/docs/architecture/node-flow-builtins-and-security.md
+++ b/docs/architecture/node-flow-builtins-and-security.md
@@ -8,7 +8,7 @@ The governed built-in catalog extends publication-based node-flow execution with
 | --- | --- |
 | `condition` | Evaluates a bounded operator and selects exactly the `true` or `false` output port. Unselected branches persist as skipped node runs. |
 | `switch` | Evaluates no more than 100 configured cases and selects one named case or `default`. |
-| `foreach` | Validates an array and emits at most 1,000 items. Inputs above the configured bound fail before fan-out. |
+| `foreach` | Validates an array, rejects inputs above the configured bound (at most 1,000), and executes the selected downstream branch once per logical item with bounded concurrency. |
 | `merge` | Combines active upstream values with `object`, `array`, or `first` strategy. |
 | `delay` | Waits for a cancellable duration from zero through one hour. |
 | `approval` | Creates or reuses a durable approval keyed by run, node, and logical item. |
@@ -19,6 +19,8 @@ The governed built-in catalog extends publication-based node-flow execution with
 
 The existing `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output` nodes retain their previous contracts. Typed manifest ports identify branch handles, many-valued merge inputs, and trigger outputs. Branch routing only runs a node when at least one incoming edge is active, allowing merges to join a selected path without treating an unselected sibling as a failure.
 
+Foreach assigns deterministic logical-item identities from the published node id and item index. Each downstream node run and numbered attempt persists that identity together with the item-specific input. The `concurrency` setting defaults to one and is capped at 64; `maxItems` is a rejection bound rather than a truncation rule. A zero-item input selects `empty`, while the `items` branch is persisted as skipped. Per-item failures retain their own retry history, successful siblings are not replayed during approval or restart continuation, and aggregated output preserves input order.
+
 ## Governed egress
 
 `EgressPolicyService` is the single request boundary for HTTP nodes and future custom-node network calls. HTTPS is required by default. A node must explicitly opt into HTTP, and even then private networking remains blocked. The service rejects credentials embedded in URLs; loopback, private, link-local, carrier-grade NAT, benchmarking, multicast, and cloud-metadata addresses; metadata hostnames; restricted raw headers; and ports or hosts outside configured allowlists.
diff --git a/docs/architecture/node-flow-durable-execution.md b/docs/architecture/node-flow-durable-execution.md
index c07bfdb48b..90426e3c6d 100644
--- a/docs/architecture/node-flow-durable-execution.md
+++ b/docs/architecture/node-flow-durable-execution.md
@@ -6,11 +6,11 @@ Node-flow execution is publication based. Saving a flow appends an immutable ver
 
 Runs move through `queued`, `running`, `approval_waiting`, `retry_waiting`, `attention_required`, and terminal `succeeded`, `failed`, or `cancelled` states. A queue claim assigns an executor, lease expiry, and heartbeat. Global and per-project limits bound active claims. Cancellation and node timeouts propagate through `AbortSignal`.
 
-Every node execution creates a numbered attempt with executor identity, optional execution invocation id, SHA-256 output digest, redacted input/output, credential ids, failure classification, and retry decision. Retryable timeout, quota, and transient failures use the publication policy's bounded exponential backoff and jitter. Credential values are resolved only at the node boundary and are never written to run, attempt, invocation, or diagnostic records.
+Every node execution creates a numbered attempt with executor identity, logical-item identity, optional execution invocation id, SHA-256 output digest, redacted input/output, credential ids, failure classification, and retry decision. Foreach descendants have independent node runs and attempt numbering per logical item, while ordinary execution uses the backward-compatible `default` item. Retryable timeout, quota, and transient failures use the publication policy's bounded exponential backoff and jitter. Credential values are resolved only at the node boundary and are never written to run, attempt, invocation, or diagnostic records.
 
 ## Recovery contract
 
-Startup recovery scans queued and waiting work plus running work with expired leases. A pre-invocation attempt can be requeued safely without inserting a duplicate attempt. An expired attempt with an invocation id has an unknown externally observable outcome and moves to `attention_required`; Code UX does not silently replay it. Pending approvals remain `approval_waiting`. A persisted approved decision is resumed during startup on the same run and pinned publication, while rejected or expired decisions durably fail the waiting run and governed node.
+Startup recovery scans queued and waiting work plus running work with expired leases. A pre-invocation attempt can be requeued safely without inserting a duplicate attempt. An expired attempt with an invocation id has an unknown externally observable outcome and moves to `attention_required`; Code UX does not silently replay it. Pending approvals remain `approval_waiting`. A persisted approved decision is matched to its waiting node and logical item, then resumed on the same run and pinned publication; completed sibling items are reconstructed from their persisted outputs instead of replayed. Rejected or expired decisions durably fail the waiting run and close other waiting item attempts.
 
 The relevant tables are `node_flow_publications`, `node_flow_runs`, `node_flow_node_runs`, and `node_flow_node_attempts`. Attempt history is available at `GET /api/node-flow-runs/:runId/attempts` and contains only redacted payloads and credential identifiers.
 
diff --git a/docs/dashboard/node-flows.md b/docs/dashboard/node-flows.md
index 80c54871a6..df6ad00e14 100644
--- a/docs/dashboard/node-flows.md
+++ b/docs/dashboard/node-flows.md
@@ -24,6 +24,8 @@ T06 draft endpoints provide structural validation, policy findings, requested pe
 
 The debugger reads persisted runs, node runs, attempt history, and approval decisions. Pending approvals expose keyboard-accessible **Approve & continue** and **Reject** actions. A decision continues or terminates the same pinned run, and repeated clicks return its current durable state without duplicating the governed attempt or external send. The debugger also overlays node state, shows retry reasons and decisions, links invocation ids, reports timing, supports cancellation and safe retry, and redacts secret-shaped values before rendering. Scheduling is entered through `/scheduler`; scheduler execution also resolves published versions.
 
+Foreach runs persist one downstream node run and attempt sequence per deterministic logical item. Item inputs, retries, cancellation, approvals, and side-effect identity survive restart; concurrency is bounded by the node configuration. Empty collections select the explicit `empty` branch and persist the item branch as skipped, while oversized collections fail instead of being truncated.
+
 The layout stacks on small screens, preserves keyboard-visible focus, labels loading/error/empty states, and bounds long histories and JSON output with scrolling.
 
 Outside development, `/nodes` requires the Nodes feature flag plus the node-flow backend and automation-security prerequisites. Individual definitions can require additional provider, credential-broker, egress, approval/outbox, webhook, or custom-runtime configuration; catalog presence alone does not assert production readiness for an integration.
diff --git a/src/contracts/node-flow-types.ts b/src/contracts/node-flow-types.ts
index 4cf590bddd..60f9d55452 100644
--- a/src/contracts/node-flow-types.ts
+++ b/src/contracts/node-flow-types.ts
@@ -329,6 +329,7 @@ export interface NodeFlowNodeRunRecord {
   flowId: string;
   projectId: string;
   nodeId: string;
+  logicalItem: string;
   status: NodeFlowNodeRunStatus;
   executionInvocationId: string | null;
   input: NodeFlowJsonObject | null;
@@ -345,6 +346,7 @@ export interface NodeFlowNodeAttemptRecord {
   runId: string;
   nodeRunId: string;
   nodeId: string;
+  logicalItem: string;
   attemptNumber: number;
   status: NodeFlowNodeRunStatus;
   executorId: string;
@@ -408,6 +410,7 @@ export interface CreateNodeFlowNodeRunInput {
   flowId: string;
   projectId: string;
   nodeId: string;
+  logicalItem?: string;
   status?: NodeFlowNodeRunStatus;
   executionInvocationId?: string | null;
   input?: NodeFlowJsonObject | null;
diff --git a/src/domain/node-flows/node-definition-registry.ts b/src/domain/node-flows/node-definition-registry.ts
index 960b1f3702..02f0a9c0a1 100644
--- a/src/domain/node-flows/node-definition-registry.ts
+++ b/src/domain/node-flows/node-definition-registry.ts
@@ -97,7 +97,7 @@ const manifests: NodeDefinitionManifest[] = [
     fields: [field("path", "Value path", "text"), field("cases", "Cases", "json")],
     ports: [dataPort("input", "input"), { ...dataPort("case", "output"), cardinality: "many" }, dataPort("default", "output")] }),
   builtin({ type: "foreach", label: "Foreach", description: "Emits a bounded list for deterministic fan-out.", category: "control",
-    properties: { path: { type: "string" }, maxItems: { type: "number" } }, fields: [field("path", "Items path", "text"), field("maxItems", "Maximum items", "number")],
+    properties: { path: { type: "string" }, maxItems: { type: "number" }, concurrency: { type: "number" } }, fields: [field("path", "Items path", "text"), field("maxItems", "Maximum items", "number"), field("concurrency", "Concurrency", "number")],
     ports: [dataPort("input", "input"), { ...dataPort("items", "output"), schema: { type: "array", items: { type: "any" } } }, dataPort("empty", "output")] }),
   builtin({ type: "merge", label: "Merge", description: "Combines upstream values with an explicit strategy.", category: "transform",
     properties: { strategy: { type: "string" } }, fields: [field("strategy", "Strategy", "select")],
diff --git a/src/repositories/db/app-db-migrations.ts b/src/repositories/db/app-db-migrations.ts
index f557b4dc10..e4508fcd33 100644
--- a/src/repositories/db/app-db-migrations.ts
+++ b/src/repositories/db/app-db-migrations.ts
@@ -241,6 +241,7 @@ export function ensureNodeFlowTables(db: DatabaseAdapter): void {
       flow_id TEXT NOT NULL,
       project_id TEXT NOT NULL,
       node_id TEXT NOT NULL,
+      logical_item TEXT NOT NULL DEFAULT 'default',
       status TEXT NOT NULL,
       execution_invocation_id TEXT,
       input_json TEXT,
@@ -278,6 +279,7 @@ export function ensureNodeFlowTables(db: DatabaseAdapter): void {
       run_id TEXT NOT NULL,
       node_run_id TEXT NOT NULL,
       node_id TEXT NOT NULL,
+      logical_item TEXT NOT NULL DEFAULT 'default',
       attempt_number INTEGER NOT NULL,
       status TEXT NOT NULL,
       executor_id TEXT NOT NULL,
@@ -294,7 +296,7 @@ export function ensureNodeFlowTables(db: DatabaseAdapter): void {
       created_at TEXT NOT NULL,
       FOREIGN KEY (run_id) REFERENCES node_flow_runs(id) ON DELETE CASCADE,
       FOREIGN KEY (node_run_id) REFERENCES node_flow_node_runs(id) ON DELETE CASCADE,
-      UNIQUE (run_id, node_id, attempt_number)
+      UNIQUE (run_id, node_id, logical_item, attempt_number)
     )
   `);
 
@@ -306,6 +308,8 @@ export function ensureNodeFlowTables(db: DatabaseAdapter): void {
   ensureColumn(db, "node_flow_runs", "heartbeat_at", "TEXT");
   ensureColumn(db, "node_flow_runs", "cancel_requested_at", "TEXT");
   ensureColumn(db, "node_flow_node_runs", "execution_invocation_id", "TEXT");
+  ensureColumn(db, "node_flow_node_runs", "logical_item", "TEXT NOT NULL DEFAULT 'default'");
+  migrateNodeFlowAttemptsLogicalItems(db);
 
   ensureIndex(db, "idx_node_flows_project_updated", "node_flows", "project_id, updated_at DESC");
   ensureIndex(db, "idx_node_flow_versions_flow_version", "node_flow_versions", "flow_id, version DESC");
@@ -316,7 +320,47 @@ export function ensureNodeFlowTables(db: DatabaseAdapter): void {
   ensureIndex(db, "idx_node_flow_publications_latest", "node_flow_publications", "flow_id, version DESC");
   ensureIndex(db, "idx_node_flow_runs_queue", "node_flow_runs", "status, lease_expires_at, created_at ASC");
   ensureIndex(db, "idx_node_flow_runs_project_status", "node_flow_runs", "project_id, status");
-  ensureIndex(db, "idx_node_flow_attempts_run_node", "node_flow_node_attempts", "run_id, node_id, attempt_number");
+  db.exec("DROP INDEX IF EXISTS idx_node_flow_attempts_run_node");
+  ensureIndex(db, "idx_node_flow_attempts_run_node", "node_flow_node_attempts", "run_id, node_id, logical_item, attempt_number");
+}
+
+function migrateNodeFlowAttemptsLogicalItems(db: DatabaseAdapter): void {
+  const columns = getTableColumns(db, "node_flow_node_attempts");
+  if (columns.has("logical_item")) return;
+  db.exec("PRAGMA foreign_keys = OFF");
+  try {
+    db.exec("BEGIN");
+    db.exec(`
+      CREATE TABLE node_flow_node_attempts_new (
+        id TEXT PRIMARY KEY, run_id TEXT NOT NULL, node_run_id TEXT NOT NULL, node_id TEXT NOT NULL,
+        logical_item TEXT NOT NULL DEFAULT 'default', attempt_number INTEGER NOT NULL, status TEXT NOT NULL,
+        executor_id TEXT NOT NULL, invocation_id TEXT, artifact_digest TEXT, input_json TEXT, output_json TEXT,
+        credential_ids_json TEXT NOT NULL DEFAULT '[]', failure_classification TEXT, retry_decision TEXT,
+        error_message TEXT, started_at TEXT NOT NULL, finished_at TEXT, created_at TEXT NOT NULL,
+        FOREIGN KEY (run_id) REFERENCES node_flow_runs(id) ON DELETE CASCADE,
+        FOREIGN KEY (node_run_id) REFERENCES node_flow_node_runs(id) ON DELETE CASCADE,
+        UNIQUE (run_id, node_id, logical_item, attempt_number)
+      )
+    `);
+    db.exec(`
+      INSERT INTO node_flow_node_attempts_new (
+        id, run_id, node_run_id, node_id, logical_item, attempt_number, status, executor_id,
+        invocation_id, artifact_digest, input_json, output_json, credential_ids_json,
+        failure_classification, retry_decision, error_message, started_at, finished_at, created_at
+      ) SELECT id, run_id, node_run_id, node_id, 'default', attempt_number, status, executor_id,
+        invocation_id, artifact_digest, input_json, output_json, credential_ids_json,
+        failure_classification, retry_decision, error_message, started_at, finished_at, created_at
+      FROM node_flow_node_attempts
+    `);
+    db.exec("DROP TABLE node_flow_node_attempts");
+    db.exec("ALTER TABLE node_flow_node_attempts_new RENAME TO node_flow_node_attempts");
+    db.exec("COMMIT");
+  } catch (error) {
+    db.exec("ROLLBACK");
+    throw error;
+  } finally {
+    db.exec("PRAGMA foreign_keys = ON");
+  }
 }
 
 export function ensureAutomationGovernanceTables(db: DatabaseAdapter): void {
diff --git a/src/repositories/db/app-db-schema.ts b/src/repositories/db/app-db-schema.ts
index 112a8b562e..11a01e2682 100644
--- a/src/repositories/db/app-db-schema.ts
+++ b/src/repositories/db/app-db-schema.ts
@@ -778,6 +778,7 @@ CREATE TABLE IF NOT EXISTS node_flow_node_runs (
         flow_id TEXT NOT NULL,
         project_id TEXT NOT NULL,
         node_id TEXT NOT NULL,
+        logical_item TEXT NOT NULL DEFAULT 'default',
         status TEXT NOT NULL,
         execution_invocation_id TEXT,
         input_json TEXT,
diff --git a/src/repositories/node-flow-repository.ts b/src/repositories/node-flow-repository.ts
index 10d3cf3fbe..8f3b6fb14e 100644
--- a/src/repositories/node-flow-repository.ts
+++ b/src/repositories/node-flow-repository.ts
@@ -89,6 +89,7 @@ interface NodeFlowPublicationRow {
 
 interface NodeFlowAttemptRow {
   id: string; run_id: string; node_run_id: string; node_id: string; attempt_number: number | string;
+  logical_item: string;
   status: string; executor_id: string; invocation_id: string | null; artifact_digest: string | null;
   input_json: string | null; output_json: string | null; credential_ids_json: string;
   failure_classification: string | null; retry_decision: string | null; error_message: string | null;
@@ -101,6 +102,7 @@ interface NodeFlowNodeRunRow {
   flow_id: string;
   project_id: string;
   node_id: string;
+  logical_item: string;
   status: string;
   execution_invocation_id: string | null;
   input_json: string | null;
@@ -459,8 +461,8 @@ export class NodeFlowRepository {
 
   createNodeAttempt(input: Omit<NodeFlowNodeAttemptRecord, "id" | "createdAt">): NodeFlowNodeAttemptRecord {
     const id = randomUUID(); const now = new Date().toISOString();
-    this.db.prepare(`INSERT INTO node_flow_node_attempts (id, run_id, node_run_id, node_id, attempt_number, status, executor_id, invocation_id, artifact_digest, input_json, output_json, credential_ids_json, failure_classification, retry_decision, error_message, started_at, finished_at, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-      .run(id, input.runId, input.nodeRunId, input.nodeId, input.attemptNumber, input.status, input.executorId, input.invocationId, input.artifactDigest, this.serializeNullableJson(input.input), this.serializeNullableJson(input.output), JSON.stringify(input.credentialIds), input.failureClassification, input.retryDecision, input.errorMessage, input.startedAt, input.finishedAt, now);
+    this.db.prepare(`INSERT INTO node_flow_node_attempts (id, run_id, node_run_id, node_id, logical_item, attempt_number, status, executor_id, invocation_id, artifact_digest, input_json, output_json, credential_ids_json, failure_classification, retry_decision, error_message, started_at, finished_at, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+      .run(id, input.runId, input.nodeRunId, input.nodeId, input.logicalItem?.trim() || "default", input.attemptNumber, input.status, input.executorId, input.invocationId, input.artifactDigest, this.serializeNullableJson(input.input), this.serializeNullableJson(input.output), JSON.stringify(input.credentialIds), input.failureClassification, input.retryDecision, input.errorMessage, input.startedAt, input.finishedAt, now);
     return requireRecord(this.getNodeAttempt(id), "Node flow node attempt", id);
   }
 
@@ -472,7 +474,7 @@ export class NodeFlowRepository {
   }
 
   listNodeAttempts(runId: string): NodeFlowNodeAttemptRecord[] {
-    return (this.db.prepare(`SELECT * FROM node_flow_node_attempts WHERE run_id = ? ORDER BY node_id, attempt_number`).all(runId) as unknown as NodeFlowAttemptRow[]).map((row) => this.mapAttemptRow(row));
+    return (this.db.prepare(`SELECT * FROM node_flow_node_attempts WHERE run_id = ? ORDER BY node_id, logical_item, attempt_number`).all(runId) as unknown as NodeFlowAttemptRow[]).map((row) => this.mapAttemptRow(row));
   }
 
   createNodeRun(input: CreateNodeFlowNodeRunInput): NodeFlowNodeRunRecord {
@@ -484,15 +486,16 @@ export class NodeFlowRepository {
     const id = randomUUID();
     this.db.prepare(`
       INSERT INTO node_flow_node_runs (
-        id, run_id, flow_id, project_id, node_id, status, execution_invocation_id,
+        id, run_id, flow_id, project_id, node_id, logical_item, status, execution_invocation_id,
         input_json, output_json, error_message, started_at, finished_at, created_at, updated_at
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(
       id,
       input.runId,
       input.flowId,
       input.projectId,
       input.nodeId,
+      input.logicalItem?.trim() || "default",
       input.status || "pending",
       input.executionInvocationId ?? null,
       input.input ? this.serializeJson(input.input) : null,
@@ -753,6 +756,7 @@ export class NodeFlowRepository {
       flowId: row.flow_id,
       projectId: row.project_id,
       nodeId: row.node_id,
+      logicalItem: row.logical_item || "default",
       status: row.status as NodeFlowNodeRunRecord["status"],
       executionInvocationId: row.execution_invocation_id,
       input: this.parseObject(row.input_json),
@@ -772,7 +776,7 @@ export class NodeFlowRepository {
   private mapAttemptRow(row: NodeFlowAttemptRow): NodeFlowNodeAttemptRecord {
     let credentialIds: string[] = [];
     try { const parsed = JSON.parse(row.credential_ids_json) as unknown; if (Array.isArray(parsed)) credentialIds = parsed.filter((item): item is string => typeof item === "string"); } catch { /* legacy row */ }
-    return { id: row.id, runId: row.run_id, nodeRunId: row.node_run_id, nodeId: row.node_id, attemptNumber: toNumber(row.attempt_number), status: row.status as NodeFlowNodeRunRecord["status"], executorId: row.executor_id, invocationId: row.invocation_id, artifactDigest: row.artifact_digest, input: this.parseObject(row.input_json), output: this.parseObject(row.output_json), credentialIds, failureClassification: row.failure_classification as NodeFlowFailureClassification | null, retryDecision: row.retry_decision as NodeFlowNodeAttemptRecord["retryDecision"], errorMessage: row.error_message, startedAt: row.started_at, finishedAt: row.finished_at, createdAt: row.created_at };
+    return { id: row.id, runId: row.run_id, nodeRunId: row.node_run_id, nodeId: row.node_id, logicalItem: row.logical_item || "default", attemptNumber: toNumber(row.attempt_number), status: row.status as NodeFlowNodeRunRecord["status"], executorId: row.executor_id, invocationId: row.invocation_id, artifactDigest: row.artifact_digest, input: this.parseObject(row.input_json), output: this.parseObject(row.output_json), credentialIds, failureClassification: row.failure_classification as NodeFlowFailureClassification | null, retryDecision: row.retry_decision as NodeFlowNodeAttemptRecord["retryDecision"], errorMessage: row.error_message, startedAt: row.started_at, finishedAt: row.finished_at, createdAt: row.created_at };
   }
 
   private publishProjectStructureRefresh(projectId: string): void {
diff --git a/src/services/node-flow-runtime-service.ts b/src/services/node-flow-runtime-service.ts
index a89f7dab9c..2ede546adc 100644
--- a/src/services/node-flow-runtime-service.ts
+++ b/src/services/node-flow-runtime-service.ts
@@ -16,7 +16,7 @@ import { NodeFlowQueueService } from "./node-flows/node-flow-queue-service.js";
 import { NodeFlowAttemptService } from "./node-flows/node-flow-attempt-service.js";
 import { NodeFlowLeaseService } from "./node-flows/node-flow-lease-service.js";
 import { EgressPolicyService } from "./node-flows/egress-policy-service.js";
-import { BuiltinExecutors } from "./node-flows/builtins/builtin-executors.js";
+import { BuiltinExecutors, MAX_FOREACH_CONCURRENCY } from "./node-flows/builtins/builtin-executors.js";
 import type { ApprovalService } from "./node-flows/approval-service.js";
 import { ApprovalRequiredError } from "./node-flows/approval-service.js";
 import { UnknownSideEffectOutcomeError, type OutboxService } from "./node-flows/outbox-service.js";
@@ -79,6 +79,9 @@ interface RuntimeContext {
   publicationId: string;
   subflowDepth: number;
   resolvedCredentialValues: string[];
+  logicalItem: string;
+  item?: NodeFlowJsonValue;
+  itemIndex?: number;
 }
 
 interface NodeExecutionResult {
@@ -198,13 +201,15 @@ export class NodeFlowRuntimeService {
       throw new ValidationError("Approval scope does not match its node flow run.");
     }
     if (run.status !== "approval_waiting") return this.summarizeRun(run.id);
-    const waitingNode = this.deps.nodeFlowRepository.listNodeRuns(run.id).find((candidate) => candidate.status === "approval_waiting");
-    if (!waitingNode || waitingNode.nodeId !== approval.nodeId) {
+    const waitingNode = this.deps.nodeFlowRepository.listNodeRuns(run.id)
+      .find((candidate) => candidate.status === "approval_waiting" && candidate.nodeId === approval.nodeId
+        && (candidate.logicalItem === approval.logicalItem || candidate.logicalItem === "default"));
+    if (!waitingNode) {
       throw new ValidationError("Approval does not match the governed node currently waiting in this run.");
     }
     if (approval.status === "pending") throw new ValidationError(`Approval ${approval.id} is still pending.`);
     if (approval.status === "rejected" || approval.status === "expired") {
-      return this.terminateApprovalRun(run, approval.nodeId, approval.status);
+      return this.terminateApprovalRun(run, approval.nodeId, approval.logicalItem, approval.status);
     }
     if (run.cancelRequestedAt) return this.terminateCancelledRun(run);
     const publication = new NodeFlowPublicationService(this.deps.nodeFlowRepository).resolve(run.flowId, { mode: "pinned", version: run.version });
@@ -256,13 +261,14 @@ export class NodeFlowRuntimeService {
       publicationId: publication.id,
       subflowDepth: options.subflowDepth ?? 0,
       resolvedCredentialValues: [],
+      logicalItem: "default",
     };
 
     const persistedNodeRuns = this.deps.nodeFlowRepository.listNodeRuns(run.id);
     const persistedByNode = new Map<string, NodeFlowNodeRunRecord>();
-    for (const persisted of persistedNodeRuns) persistedByNode.set(persisted.nodeId, persisted);
+    for (const persisted of persistedNodeRuns) persistedByNode.set(nodeRunKey(persisted.nodeId, persisted.logicalItem), persisted);
     for (const node of graph.nodes) {
-      const persisted = persistedByNode.get(node.id);
+      const persisted = persistedByNode.get(nodeRunKey(node.id, "default"));
       if (!persisted?.output || !["succeeded", "failed"].includes(persisted.status)) continue;
       context.outputs.set(node.id, persisted.output);
       const selectedPorts = inferSelectedPorts(node, persisted.output);
@@ -270,6 +276,7 @@ export class NodeFlowRuntimeService {
     }
 
     const blockedNodes = new Set<string>();
+    const fanoutHandledNodes = new Set<string>();
     let terminalStatus: NodeFlowRunRecord["status"] = "succeeded";
     let terminalError: string | null = null;
 
@@ -279,8 +286,18 @@ export class NodeFlowRuntimeService {
       if (!node) {
         continue;
       }
-      const persistedNodeRun = persistedByNode.get(node.id);
+      const persistedNodeRun = persistedByNode.get(nodeRunKey(node.id, "default"));
+      if (fanoutHandledNodes.has(node.id)) continue;
       if (persistedNodeRun && ["succeeded", "failed", "skipped", "cancelled"].includes(persistedNodeRun.status)) {
+        if (node.type === "foreach" && persistedNodeRun.status === "succeeded") {
+          const fanout = await this.executeForeachFanout(context, node, publication, persistedNodeRun.output ?? {}, persistedNodeRuns);
+          if (fanout.handled) {
+            for (const descendant of context.descendants.get(node.id) ?? []) fanoutHandledNodes.add(descendant);
+            terminalStatus = fanout.status;
+            terminalError = fanout.error;
+            if (terminalStatus !== "succeeded") break;
+          }
+        }
         continue;
       }
       if (options.signal?.aborted || this.deps.nodeFlowRepository.getRun(run.id)?.cancelRequestedAt) {
@@ -317,6 +334,7 @@ export class NodeFlowRuntimeService {
           flowId,
           projectId,
           nodeId: node.id,
+          logicalItem: context.logicalItem,
           status: "running",
           input: nodeInput,
           startedAt: new Date().toISOString(),
@@ -356,6 +374,9 @@ export class NodeFlowRuntimeService {
         context.outputs.set(node.id, safeOutput);
         if (result.selectedPorts) context.selectedPorts.set(node.id, new Set(result.selectedPorts));
         attemptService.succeed(attempt, safeOutput, result.invocationId);
+        this.deps.auditService?.recordSystem({ action: "automation.attempt.succeeded", resourceType: "node_flow_attempt", resourceId: attempt.id,
+          projectId: context.projectId, outcome: "succeeded", metadata: { runId: context.runId, flowId: context.flowId, nodeId: node.id,
+            logicalItem: context.logicalItem, attemptNumber: attempt.attemptNumber } });
         this.deps.auditService?.recordSystem({ action: "automation.attempt.succeeded", resourceType: "node_flow_attempt", resourceId: attempt.id, projectId, outcome: "succeeded", metadata: { runId: run.id, flowId, nodeId: node.id, attemptNumber: attempt.attemptNumber } });
         this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, {
           status: "succeeded",
@@ -363,6 +384,14 @@ export class NodeFlowRuntimeService {
           output: safeOutput,
           finishedAt: new Date().toISOString(),
         });
+        if (node.type === "foreach") {
+          const fanout = await this.executeForeachFanout(context, node, publication, safeOutput, persistedNodeRuns);
+          if (fanout.handled) {
+            for (const descendant of context.descendants.get(node.id) ?? []) fanoutHandledNodes.add(descendant);
+            terminalStatus = fanout.status;
+            terminalError = fanout.error;
+          }
+        }
         break;
       } catch (error) {
         const message = redactCredentialText(error instanceof Error ? error.message : String(error), context.resolvedCredentialValues);
@@ -440,7 +469,7 @@ export class NodeFlowRuntimeService {
       leaseExpiresAt: null,
     });
     this.deps.executionRepository.updateExecutionInvocation(parentInvocationId, {
-      status: terminalStatus === "succeeded" ? "completed" : terminalStatus === "attention_required" ? "failed" : terminalStatus === "approval_waiting" ? "running" : terminalStatus,
+      status: terminalStatus === "succeeded" ? "completed" : terminalStatus === "approval_waiting" ? "running" : terminalStatus === "cancelled" ? "cancelled" : "failed",
       errorMessage: terminalStatus === "approval_waiting" ? null : terminalError,
       finishedAt,
     });
@@ -466,12 +495,188 @@ export class NodeFlowRuntimeService {
     };
   }
 
-  private terminateApprovalRun(run: NodeFlowRunRecord, nodeId: string, status: "rejected" | "expired"): NodeFlowRunSummaryResponse {
+  private async executeForeachFanout(
+    parent: RuntimeContext,
+    foreachNode: NodeFlowNode,
+    publication: NodeFlowPublicationRecord,
+    foreachOutput: NodeFlowJsonObject,
+    persistedNodeRuns: NodeFlowNodeRunRecord[],
+  ): Promise<{ handled: boolean; status: NodeFlowRunRecord["status"]; error: string | null }> {
+    const items = Array.isArray(foreachOutput.items) ? foreachOutput.items : [];
+    if (items.length === 0) return { handled: false, status: "succeeded", error: null };
+    const rawConcurrency = Number(readNodeConfig(foreachNode).concurrency ?? 1);
+    const concurrency = Math.max(1, Math.min(MAX_FOREACH_CONCURRENCY, Number.isFinite(rawConcurrency) ? Math.floor(rawConcurrency) : 1));
+    const descendantIds = parent.descendants.get(foreachNode.id) ?? new Set<string>();
+    const order = parent.order.filter((nodeId) => descendantIds.has(nodeId));
+    const itemOutputs: Array<Map<string, NodeFlowJsonObject> | undefined> = new Array(items.length);
+    const outcomes = await mapWithConcurrency(items, concurrency, async (item, index) => {
+      const logicalItem = `${foreachNode.id}:${index}`;
+      const context: RuntimeContext = {
+        ...parent,
+        outputs: new Map(parent.outputs),
+        selectedPorts: new Map([...parent.selectedPorts].map(([nodeId, ports]) => [nodeId, new Set(ports)])),
+        options: { ...parent.options },
+        currentAttemptId: undefined,
+        resolvedCredentialValues: [],
+        logicalItem,
+        item,
+        itemIndex: index,
+      };
+      context.outputs.set(foreachNode.id, { item, index, count: items.length, logicalItem });
+      context.selectedPorts.set(foreachNode.id, new Set(["items"]));
+      const persistedByNode = new Map(persistedNodeRuns
+        .filter((record) => record.logicalItem === logicalItem)
+        .map((record) => [record.nodeId, record]));
+      for (const record of persistedByNode.values()) {
+        if (record.output && ["succeeded", "failed"].includes(record.status)) {
+          context.outputs.set(record.nodeId, record.output);
+          const node = context.graph.nodes.find((candidate) => candidate.id === record.nodeId);
+          const selectedPorts = node ? inferSelectedPorts(node, record.output) : null;
+          if (selectedPorts) context.selectedPorts.set(record.nodeId, selectedPorts);
+        }
+      }
+      const blocked = new Set<string>();
+      let itemError = [...persistedByNode.values()].find((record) => record.status === "failed"
+        && context.graph.nodes.find((node) => node.id === record.nodeId)?.data?.continueOnError !== true)?.errorMessage ?? null;
+      for (const nodeId of order) {
+        const node = context.graph.nodes.find((candidate) => candidate.id === nodeId);
+        if (!node) continue;
+        const persisted = persistedByNode.get(node.id);
+        if (persisted && ["succeeded", "failed", "skipped", "cancelled"].includes(persisted.status)) continue;
+        if (context.options.signal?.aborted || this.deps.nodeFlowRepository.getRun(context.runId)?.cancelRequestedAt) {
+          await this.persistSkippedNode(context, node, "cancelled", "Node flow run was cancelled.");
+          return { status: "cancelled" as const, error: "Node flow run was cancelled." };
+        }
+        if (blocked.has(node.id)) {
+          await this.persistSkippedNode(context, node, "skipped", "Skipped because this logical item's upstream node failed.");
+          continue;
+        }
+        if (this.isInactiveBranch(context, node.id)) {
+          await this.persistSkippedNode(context, node, "skipped", "Skipped because this logical item's incoming branch was not selected.");
+          continue;
+        }
+        if (node.disabled) {
+          await this.persistSkippedNode(context, node, "skipped", "Skipped because the node is disabled.");
+          continue;
+        }
+        const result = await this.executeLogicalItemNode(context, node, publication, persisted);
+        if (result.status === "approval_waiting" || result.status === "attention_required" || result.status === "cancelled") {
+          return result;
+        }
+        if (result.status === "failed" && node.data?.continueOnError !== true) {
+          itemError ??= result.error;
+          for (const descendant of context.descendants.get(node.id) ?? []) blocked.add(descendant);
+        }
+      }
+      itemOutputs[index] = context.outputs;
+      return { status: itemError ? "failed" as const : "succeeded" as const, error: itemError };
+    });
+
+    for (const nodeId of order) {
+      const values = itemOutputs.map((outputs) => outputs?.get(nodeId) ?? null);
+      parent.outputs.set(nodeId, { items: values, count: items.length });
+    }
+    const priority: NodeFlowRunRecord["status"][] = ["attention_required", "cancelled", "approval_waiting", "failed"];
+    const terminal = priority.find((status) => outcomes.some((outcome) => outcome.status === status));
+    const error = outcomes.find((outcome) => outcome.status === terminal)?.error ?? null;
+    return { handled: true, status: terminal ?? "succeeded", error };
+  }
+
+  private async executeLogicalItemNode(
+    context: RuntimeContext,
+    node: NodeFlowNode,
+    publication: NodeFlowPublicationRecord,
+    persisted?: NodeFlowNodeRunRecord,
+  ): Promise<{ status: NodeFlowRunRecord["status"]; error: string | null }> {
+    const nodeInput = maskSecrets(this.buildNodeInput(context, node.id));
+    const resumable = persisted && ["running", "retry_waiting", "approval_waiting"].includes(persisted.status);
+    const nodeRun = resumable
+      ? this.deps.nodeFlowRepository.updateNodeRun(persisted.id, { status: "running", input: nodeInput, errorMessage: null })
+      : this.deps.nodeFlowRepository.createNodeRun({ runId: context.runId, flowId: context.flowId, projectId: context.projectId,
+        nodeId: node.id, logicalItem: context.logicalItem, status: "running", input: nodeInput, startedAt: new Date().toISOString() });
+    const attemptService = new NodeFlowAttemptService(this.deps.nodeFlowRepository);
+    const retryPolicy = { ...publication.policy.retry, ...(node.policy?.retry ?? {}) };
+    let executionAttempt = this.deps.nodeFlowRepository.listNodeAttempts(context.runId)
+      .filter((attempt) => attempt.nodeRunId === nodeRun.id && attempt.status !== "approval_waiting" && !(attempt.status === "running" && attempt.invocationId === null)).length;
+    let waitingAttempt = this.deps.nodeFlowRepository.listNodeAttempts(context.runId)
+      .find((attempt) => attempt.nodeRunId === nodeRun.id && attempt.status === "approval_waiting");
+    let interruptedAttempt = this.deps.nodeFlowRepository.listNodeAttempts(context.runId)
+      .find((attempt) => attempt.nodeRunId === nodeRun.id && attempt.status === "running" && attempt.invocationId === null);
+    while (executionAttempt < retryPolicy.maxAttempts) {
+      executionAttempt += 1;
+      clearResolvedCredentials(context);
+      const attempt = waitingAttempt
+        ? this.deps.nodeFlowRepository.updateNodeAttempt(waitingAttempt.id, { status: "running", errorMessage: null, finishedAt: null })
+        : interruptedAttempt
+          ? this.deps.nodeFlowRepository.updateNodeAttempt(interruptedAttempt.id, { status: "running", errorMessage: null, finishedAt: null })
+          : attemptService.start(nodeRun, context.executorId, nodeInput, (node.credentialBindings ?? []).map((binding) => binding.credentialId));
+      waitingAttempt = undefined;
+      interruptedAttempt = undefined;
+      context.currentAttemptId = attempt.id;
+      const timeoutMs = node.policy?.timeout?.timeoutMs ?? publication.policy.defaultTimeoutMs;
+      const timeoutController = new AbortController();
+      const parentAbort = (): void => timeoutController.abort(context.options.signal?.reason);
+      context.options.signal?.addEventListener("abort", parentAbort, { once: true });
+      const timeout = setTimeout(() => timeoutController.abort(new Error(`Node ${node.id} timed out after ${timeoutMs}ms.`)), timeoutMs);
+      const previousOptions = context.options;
+      context.options = { ...context.options, signal: timeoutController.signal };
+      try {
+        const result = await this.executeNode(context, node, nodeRun);
+        const safeOutput = redactCredentialJson(result.output, context.resolvedCredentialValues);
+        context.outputs.set(node.id, safeOutput);
+        if (result.selectedPorts) context.selectedPorts.set(node.id, new Set(result.selectedPorts));
+        attemptService.succeed(attempt, safeOutput, result.invocationId);
+        this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, { status: "succeeded", executionInvocationId: result.invocationId ?? nodeRun.executionInvocationId,
+          output: safeOutput, finishedAt: new Date().toISOString() });
+        return { status: "succeeded", error: null };
+      } catch (error) {
+        const message = redactCredentialText(error instanceof Error ? error.message : String(error), context.resolvedCredentialValues);
+        const classification = classifyFailure(error, previousOptions.signal?.aborted === true, timeoutController.signal.aborted);
+        if (error instanceof ApprovalRequiredError) {
+          this.deps.nodeFlowRepository.updateNodeAttempt(attempt.id, { status: "approval_waiting", errorMessage: message, retryDecision: null, finishedAt: null });
+          this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, { status: "approval_waiting", errorMessage: message, finishedAt: null });
+          return { status: "approval_waiting", error: message };
+        }
+        this.deps.auditService?.recordSystem({ action: "automation.attempt.failed", resourceType: "node_flow_attempt", resourceId: attempt.id,
+          projectId: context.projectId, outcome: "failed", metadata: { runId: context.runId, flowId: context.flowId, nodeId: node.id,
+            logicalItem: context.logicalItem, attemptNumber: attempt.attemptNumber, classification } });
+        const retryable = retryPolicy.retryableClasses.includes(classification) && executionAttempt < retryPolicy.maxAttempts;
+        const invocationId = this.deps.nodeFlowRepository.listNodeAttempts(context.runId).find((candidate) => candidate.id === attempt.id)?.invocationId;
+        attemptService.fail(attempt, classification, message, retryable, invocationId);
+        if (retryable) {
+          this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, { status: "retry_waiting", errorMessage: message });
+          await delay(retryDelay(retryPolicy.backoffMs, retryPolicy.maxBackoffMs ?? retryPolicy.backoffMs, retryPolicy.jitterRatio ?? 0, executionAttempt), previousOptions.signal);
+          this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, { status: "running", errorMessage: null });
+          continue;
+        }
+        const status = classification === "unknown_side_effect" ? "attention_required" : classification === "cancelled" ? "cancelled" : "failed";
+        const failureOutput = { error: message };
+        context.outputs.set(node.id, failureOutput);
+        this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, { status: status === "attention_required" ? "attention_required" : status,
+          output: maskSecrets(failureOutput), errorMessage: message, finishedAt: new Date().toISOString() });
+        return { status, error: message };
+      } finally {
+        clearTimeout(timeout);
+        previousOptions.signal?.removeEventListener("abort", parentAbort);
+        context.options = previousOptions;
+        clearResolvedCredentials(context);
+      }
+    }
+    return { status: "failed", error: `Logical item ${context.logicalItem} exhausted its retry budget.` };
+  }
+
+  private terminateApprovalRun(run: NodeFlowRunRecord, nodeId: string, logicalItem: string, status: "rejected" | "expired"): NodeFlowRunSummaryResponse {
     const message = `Approval for node ${nodeId} was ${status}.`;
-    const nodeRun = this.deps.nodeFlowRepository.listNodeRuns(run.id).find((candidate) => candidate.nodeId === nodeId && candidate.status === "approval_waiting");
+    const nodeRun = this.deps.nodeFlowRepository.listNodeRuns(run.id).find((candidate) => candidate.nodeId === nodeId && (candidate.logicalItem === logicalItem || candidate.logicalItem === "default") && candidate.status === "approval_waiting");
     if (nodeRun) this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, { status: "failed", errorMessage: message, finishedAt: new Date().toISOString() });
-    const attempt = this.deps.nodeFlowRepository.listNodeAttempts(run.id).find((candidate) => candidate.nodeId === nodeId && candidate.status === "approval_waiting");
+    const attempt = this.deps.nodeFlowRepository.listNodeAttempts(run.id).find((candidate) => candidate.nodeId === nodeId && (candidate.logicalItem === logicalItem || candidate.logicalItem === "default") && candidate.status === "approval_waiting");
     if (attempt) this.deps.nodeFlowRepository.updateNodeAttempt(attempt.id, { status: "failed", failureClassification: "permanent", retryDecision: "stop", errorMessage: message, finishedAt: new Date().toISOString() });
+    for (const waitingNode of this.deps.nodeFlowRepository.listNodeRuns(run.id).filter((candidate) => candidate.status === "approval_waiting" && candidate.id !== nodeRun?.id)) {
+      this.deps.nodeFlowRepository.updateNodeRun(waitingNode.id, { status: "cancelled", errorMessage: message, finishedAt: new Date().toISOString() });
+    }
+    for (const waitingAttempt of this.deps.nodeFlowRepository.listNodeAttempts(run.id).filter((candidate) => candidate.status === "approval_waiting" && candidate.id !== attempt?.id)) {
+      this.deps.nodeFlowRepository.updateNodeAttempt(waitingAttempt.id, { status: "cancelled", failureClassification: "cancelled", retryDecision: "stop", errorMessage: message, finishedAt: new Date().toISOString() });
+    }
     const updated = this.deps.nodeFlowRepository.updateRun(run.id, { status: "failed", errorMessage: message, finishedAt: new Date().toISOString(), leaseOwner: null, leaseExpiresAt: null });
     if (updated.executionInvocationId) this.deps.executionRepository.updateExecutionInvocation(updated.executionInvocationId, { status: "failed", errorMessage: message, finishedAt: updated.finishedAt });
     return this.summarizeRun(updated.id);
@@ -479,10 +684,12 @@ export class NodeFlowRuntimeService {
 
   private terminateCancelledRun(run: NodeFlowRunRecord): NodeFlowRunSummaryResponse {
     const message = "Node flow run was cancelled while waiting for approval.";
-    const nodeRun = this.deps.nodeFlowRepository.listNodeRuns(run.id).find((candidate) => candidate.status === "approval_waiting");
-    if (nodeRun) this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, { status: "cancelled", errorMessage: message, finishedAt: new Date().toISOString() });
-    const attempt = this.deps.nodeFlowRepository.listNodeAttempts(run.id).find((candidate) => candidate.status === "approval_waiting");
-    if (attempt) this.deps.nodeFlowRepository.updateNodeAttempt(attempt.id, { status: "cancelled", failureClassification: "cancelled", retryDecision: "stop", errorMessage: message, finishedAt: new Date().toISOString() });
+    for (const nodeRun of this.deps.nodeFlowRepository.listNodeRuns(run.id).filter((candidate) => candidate.status === "approval_waiting")) {
+      this.deps.nodeFlowRepository.updateNodeRun(nodeRun.id, { status: "cancelled", errorMessage: message, finishedAt: new Date().toISOString() });
+    }
+    for (const attempt of this.deps.nodeFlowRepository.listNodeAttempts(run.id).filter((candidate) => candidate.status === "approval_waiting")) {
+      this.deps.nodeFlowRepository.updateNodeAttempt(attempt.id, { status: "cancelled", failureClassification: "cancelled", retryDecision: "stop", errorMessage: message, finishedAt: new Date().toISOString() });
+    }
     const updated = this.deps.nodeFlowRepository.updateRun(run.id, { status: "cancelled", errorMessage: message, finishedAt: new Date().toISOString(), leaseOwner: null, leaseExpiresAt: null });
     if (updated.executionInvocationId) this.deps.executionRepository.updateExecutionInvocation(updated.executionInvocationId, { status: "cancelled", errorMessage: message, finishedAt: updated.finishedAt });
     return this.summarizeRun(updated.id);
@@ -572,6 +779,7 @@ export class NodeFlowRuntimeService {
           config: evaluateTemplates(readNodeConfig(node), context) as NodeFlowJsonObject,
           upstream: this.buildUpstreamObject(context, node.id), flowInput: context.input,
           signal: context.options.signal, subflowDepth: context.subflowDepth,
+          logicalItem: context.logicalItem,
           redactJson: (value) => redactCredentialJson(value, context.resolvedCredentialValues),
           redactText: (value) => redactCredentialText(value, context.resolvedCredentialValues),
         });
@@ -865,6 +1073,7 @@ export class NodeFlowRuntimeService {
       flowInput: context.input,
       upstream,
       nodes: Object.fromEntries(context.outputs),
+      ...(context.itemIndex === undefined ? {} : { item: context.item ?? null, itemIndex: context.itemIndex, logicalItem: context.logicalItem }),
     };
   }
 
@@ -917,6 +1126,7 @@ export class NodeFlowRuntimeService {
       flowId: context.flowId,
       projectId: context.projectId,
       nodeId: node.id,
+      logicalItem: context.logicalItem,
       status,
       input: maskSecrets(this.buildNodeInput(context, node.id)),
       errorMessage: message,
@@ -1007,6 +1217,7 @@ function inferSelectedPorts(node: NodeFlowNode, output: NodeFlowJsonObject): Set
   if (node.type === "condition" && typeof output.matched === "boolean") return new Set([output.matched ? "true" : "false"]);
   if (node.type === "switch" && typeof output.selectedCase === "string") return new Set([output.selectedCase]);
   if (node.type === "approval" && output.approved === true) return new Set(["approved"]);
+  if (node.type === "foreach" && Array.isArray(output.items)) return new Set([output.items.length > 0 ? "items" : "empty"]);
   return null;
 }
 
@@ -1040,9 +1251,32 @@ function contextToObject(context: RuntimeContext): NodeFlowJsonObject {
   return {
     input: context.input,
     nodes: Object.fromEntries(context.outputs),
+    ...(context.itemIndex === undefined ? {} : { item: context.item ?? null, itemIndex: context.itemIndex, logicalItem: context.logicalItem }),
   };
 }
 
+function nodeRunKey(nodeId: string, logicalItem: string): string {
+  return `${nodeId}\0${logicalItem}`;
+}
+
+async function mapWithConcurrency<T, R>(
+  values: readonly T[],
+  concurrency: number,
+  worker: (value: T, index: number) => Promise<R>,
+): Promise<R[]> {
+  const results = new Array<R>(values.length);
+  let nextIndex = 0;
+  const runners = Array.from({ length: Math.min(concurrency, values.length) }, async () => {
+    while (nextIndex < values.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      results[index] = await worker(values[index]!, index);
+    }
+  });
+  await Promise.all(runners);
+  return results;
+}
+
 function readPath(value: unknown, path: string): unknown {
   return path.split(".").reduce<unknown>((current, segment) => {
     if (current === undefined || current === null) {
diff --git a/src/services/node-flows/builtins/builtin-executors.ts b/src/services/node-flows/builtins/builtin-executors.ts
index 5fdf65eb0c..431f6e1e02 100644
--- a/src/services/node-flows/builtins/builtin-executors.ts
+++ b/src/services/node-flows/builtins/builtin-executors.ts
@@ -4,6 +4,7 @@ import type { ApprovalService } from "../approval-service.js";
 import { UnknownSideEffectOutcomeError, type OutboxService } from "../outbox-service.js";
 
 export const MAX_FOREACH_ITEMS = 1_000;
+export const MAX_FOREACH_CONCURRENCY = 64;
 export const MAX_SUBFLOW_DEPTH = 8;
 export const MAX_DELAY_MS = 60 * 60_000;
 
@@ -11,6 +12,7 @@ export interface BuiltinExecutionContext {
   projectId: string; flowId: string; publicationId: string; runId: string; nodeId: string;
   config: NodeFlowJsonObject; upstream: NodeFlowJsonObject; flowInput: NodeFlowJsonObject;
   signal?: AbortSignal; subflowDepth: number;
+  logicalItem: string;
   redactJson?: (value: NodeFlowJsonObject) => NodeFlowJsonObject;
   redactText?: (value: string) => string;
 }
@@ -43,7 +45,7 @@ export class BuiltinExecutors {
   private executeApproval(context: BuiltinExecutionContext): BuiltinExecutionResult {
     if (!this.deps.approvalService) throw new ValidationError("Approval service is not configured.");
     const approval = this.deps.approvalService.requireApproval({ projectId: context.projectId, flowId: context.flowId,
-      runId: context.runId, nodeId: context.nodeId, logicalItem: readString(context.config.logicalItem) ?? "default",
+      runId: context.runId, nodeId: context.nodeId, logicalItem: effectiveLogicalItem(context),
       request: { summary: readString(context.config.summary) ?? "Approval required", payload: context.upstream } });
     return { output: { approved: true, approvalId: approval.id, ...context.upstream }, selectedPorts: ["approved"] };
   }
@@ -52,7 +54,7 @@ export class BuiltinExecutors {
     if (!this.deps.approvalService || !this.deps.outboxService) throw new ValidationError("Email side-effect services are not configured.");
     const rawDraft = buildEmail(context);
     const draft = context.redactJson?.(rawDraft) ?? rawDraft;
-    const logicalItem = readString(context.config.logicalItem) ?? "default";
+    const logicalItem = effectiveLogicalItem(context);
     this.deps.approvalService.requireApproval({ projectId: context.projectId, flowId: context.flowId, runId: context.runId,
       nodeId: context.nodeId, logicalItem, request: { effectType: "email", draft } });
     const sent = await this.deps.outboxService.dispatch({ projectId: context.projectId, flowId: context.flowId,
@@ -75,6 +77,10 @@ export class BuiltinExecutors {
   }
 }
 
+function effectiveLogicalItem(context: BuiltinExecutionContext): string {
+  return context.logicalItem === "default" ? readString(context.config.logicalItem) ?? "default" : context.logicalItem;
+}
+
 function executeCondition(context: BuiltinExecutionContext): BuiltinExecutionResult {
   const actual = readPath({ input: context.flowInput, upstream: context.upstream }, readString(context.config.path) ?? "upstream");
   const expected = context.config.value;
diff --git a/src/services/node-flows/node-flow-attempt-service.ts b/src/services/node-flows/node-flow-attempt-service.ts
index cad3afb9f6..8d3280dc6c 100644
--- a/src/services/node-flows/node-flow-attempt-service.ts
+++ b/src/services/node-flows/node-flow-attempt-service.ts
@@ -7,8 +7,9 @@ export class NodeFlowAttemptService {
   constructor(private readonly repository: NodeFlowRepository) {}
 
   start(nodeRun: NodeFlowNodeRunRecord, executorId: string, input: NodeFlowJsonObject, credentialIds: string[]): NodeFlowNodeAttemptRecord {
-    const attemptNumber = this.repository.listNodeAttempts(nodeRun.runId).filter((attempt) => attempt.nodeId === nodeRun.nodeId).length + 1;
-    return this.repository.createNodeAttempt({ runId: nodeRun.runId, nodeRunId: nodeRun.id, nodeId: nodeRun.nodeId, attemptNumber, status: "running", executorId, invocationId: null, artifactDigest: null, input, output: null, credentialIds, failureClassification: null, retryDecision: null, errorMessage: null, startedAt: new Date().toISOString(), finishedAt: null });
+    const attemptNumber = this.repository.listNodeAttempts(nodeRun.runId)
+      .filter((attempt) => attempt.nodeId === nodeRun.nodeId && attempt.logicalItem === nodeRun.logicalItem).length + 1;
+    return this.repository.createNodeAttempt({ runId: nodeRun.runId, nodeRunId: nodeRun.id, nodeId: nodeRun.nodeId, logicalItem: nodeRun.logicalItem, attemptNumber, status: "running", executorId, invocationId: null, artifactDigest: null, input, output: null, credentialIds, failureClassification: null, retryDecision: null, errorMessage: null, startedAt: new Date().toISOString(), finishedAt: null });
   }
 
   succeed(attempt: NodeFlowNodeAttemptRecord, output: NodeFlowJsonObject, invocationId?: string | null): NodeFlowNodeAttemptRecord {
diff --git a/src/services/node-flows/node-flow-recovery-service.ts b/src/services/node-flows/node-flow-recovery-service.ts
index 6b8a2e63f6..dcdc353d48 100644
--- a/src/services/node-flows/node-flow-recovery-service.ts
+++ b/src/services/node-flows/node-flow-recovery-service.ts
@@ -36,11 +36,11 @@ export class NodeFlowRecoveryService {
     const resumed: NodeFlowRunRecord[] = [];
     const waitingRuns = this.repository.listRecoverableRuns().filter((run) => run.status === "approval_waiting");
     for (const run of waitingRuns) {
-      const waitingNode = this.repository.listNodeRuns(run.id).find((candidate) => candidate.status === "approval_waiting");
-      if (!waitingNode) continue;
+      const waitingNodes = this.repository.listNodeRuns(run.id).filter((candidate) => candidate.status === "approval_waiting");
       const approval = this.approvalService.listForRun(run.id)
         .map((candidate) => this.approvalService!.get(candidate.id) ?? candidate)
-        .find((candidate) => candidate.nodeId === waitingNode.nodeId && candidate.status !== "pending");
+        .find((candidate) => candidate.status !== "pending" && waitingNodes.some((node) => node.nodeId === candidate.nodeId
+          && (node.logicalItem === candidate.logicalItem || node.logicalItem === "default")));
       if (!approval) continue;
       const summary = await this.runtimeService.resumeApproval(run.projectId, approval.id, run.id);
       resumed.push(summary.run);
diff --git a/tests/backend/services/node-flow-builtins.test.ts b/tests/backend/services/node-flow-builtins.test.ts
index 5134bcbb69..4e3992094d 100644
--- a/tests/backend/services/node-flow-builtins.test.ts
+++ b/tests/backend/services/node-flow-builtins.test.ts
@@ -16,6 +16,8 @@ describe("governed built-in executors", () => {
     const executors = new BuiltinExecutors();
     await expect(executors.execute("foreach", { ...base, upstream: { items: Array(MAX_FOREACH_ITEMS + 1).fill(null) }, config: { path: "upstream.items" } }))
       .rejects.toThrow(/bounded item limit/i);
+    await expect(executors.execute("foreach", { ...base, upstream: { items: [1, 2, 3] }, config: { path: "upstream.items", maxItems: 2 } }))
+      .rejects.toThrow(/bounded item limit of 2/i);
     await expect(executors.execute("delay", { ...base, config: { delayMs: 3_600_001 } })).rejects.toThrow(/Delay must be between/i);
   });
 
diff --git a/tests/backend/services/node-flow-runtime-service.test.ts b/tests/backend/services/node-flow-runtime-service.test.ts
index 3ef14dfcf6..8bf00721c3 100644
--- a/tests/backend/services/node-flow-runtime-service.test.ts
+++ b/tests/backend/services/node-flow-runtime-service.test.ts
@@ -595,4 +595,127 @@ describe("NodeFlowRuntimeService", () => {
     const messages = executionRepository.listExecutionInvocationMessages(result.run.executionInvocationId!);
     expect(JSON.stringify(messages)).not.toContain("secret-token");
   });
+
+  it.each([
+    { items: [] as number[], expectedItems: 0, expectedEmpty: "succeeded", expectedWorker: ["default"] },
+    { items: [7], expectedItems: 1, expectedEmpty: "skipped", expectedWorker: ["foreach:0"] },
+    { items: [1, 2, 3], expectedItems: 3, expectedEmpty: "skipped", expectedWorker: ["foreach:0", "foreach:1", "foreach:2"] },
+  ])("executes zero, one, and many Foreach items durably: $items", async ({ items, expectedItems, expectedEmpty, expectedWorker }) => {
+    const { dir, projectRepository, nodeFlowRepository, runtime } = await createRuntime();
+    const project = projectRepository.createProject({ name: "Foreach cardinality", sourceType: "local", sourceRef: dir });
+    const flow = nodeFlowRepository.createFlow(project.id, { title: "Foreach cardinality", graph: {
+      nodes: [
+        { id: "foreach", type: "foreach", title: "Foreach", data: { path: "input.items", concurrency: 2 } },
+        { id: "worker", type: "set_fields", title: "Worker", data: { fields: { value: "{{item}}", index: "{{itemIndex}}" } } },
+        { id: "empty", type: "set_fields", title: "Empty", data: { fields: { empty: true } } },
+        { id: "output", type: "output", title: "Output" },
+      ],
+      edges: [
+        { fromNodeId: "foreach", fromHandle: "items", toNodeId: "worker" },
+        { fromNodeId: "foreach", fromHandle: "empty", toNodeId: "empty" },
+        { fromNodeId: "worker", toNodeId: "output" },
+        { fromNodeId: "empty", toNodeId: "output" },
+      ],
+    } });
+
+    const result = await runtime.runFlow(project.id, flow.id, { items });
+    const workerRuns = result.nodeRuns.filter((record) => record.nodeId === "worker");
+    expect(result.run.status).toBe("succeeded");
+    expect(workerRuns.map((record) => record.logicalItem)).toEqual(expectedWorker);
+    expect(workerRuns.filter((record) => record.status === "succeeded")).toHaveLength(expectedItems);
+    expect(result.nodeRuns.find((record) => record.nodeId === "empty")?.status).toBe(expectedEmpty);
+    if (items.length > 0) {
+      expect(workerRuns.map((record) => record.input?.item)).toEqual(items);
+      expect(result.attempts?.filter((attempt) => attempt.nodeId === "worker").map((attempt) => [attempt.logicalItem, attempt.attemptNumber]))
+        .toEqual(expectedWorker.map((logicalItem) => [logicalItem, 1]));
+    }
+  });
+
+  it("bounds Foreach concurrency and isolates per-item retries and failures", async () => {
+    let active = 0;
+    let maximumActive = 0;
+    const attempts = new Map<string, number>();
+    const executeProvider = vi.fn().mockImplementation(async ({ prompt }: { prompt: string }) => {
+      active += 1;
+      maximumActive = Math.max(maximumActive, active);
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      active -= 1;
+      const count = (attempts.get(prompt) ?? 0) + 1;
+      attempts.set(prompt, count);
+      if (prompt === "2" && count === 1) throw new Error("503 retry item two");
+      if (prompt === "3") throw new Error("permanent item three");
+      return { ok: true, stdout: prompt, stderr: "", code: 0, text: prompt, nativeSessionId: null,
+        usageTelemetry: { transcriptText: prompt, inputTokens: 0, cachedInputTokens: 0, outputTokens: 0, reasoningOutputTokens: 0, totalTokens: 0, usageSource: "reported", rawUsageJson: null } };
+    });
+    const { dir, projectRepository, nodeFlowRepository, runtime } = await createRuntime({ executeProvider } as Partial<ProviderExecutionService>);
+    const project = projectRepository.createProject({ name: "Foreach concurrency", sourceType: "local", sourceRef: dir });
+    const flow = nodeFlowRepository.createFlow(project.id, { title: "Foreach concurrency", graph: {
+      nodes: [
+        { id: "foreach", type: "foreach", title: "Foreach", data: { path: "input.items", concurrency: 2 } },
+        { id: "prompt", type: "provider_prompt", title: "Prompt", data: { provider: "mockup-cli", prompt: "{{item}}" },
+          policy: { retry: { maxAttempts: 2, backoffMs: 0, maxBackoffMs: 0 } } },
+      ],
+      edges: [{ fromNodeId: "foreach", fromHandle: "items", toNodeId: "prompt" }],
+    } });
+
+    const result = await runtime.runFlow(project.id, flow.id, { items: [1, 2, 3, 4] });
+    expect(result.run.status).toBe("failed");
+    expect(maximumActive).toBe(2);
+    expect(result.nodeRuns.filter((record) => record.nodeId === "prompt" && record.status === "succeeded")).toHaveLength(3);
+    expect(result.attempts?.filter((attempt) => attempt.logicalItem === "foreach:1").map((attempt) => attempt.attemptNumber)).toEqual([1, 2]);
+    expect(result.attempts?.filter((attempt) => attempt.logicalItem === "foreach:2")).toHaveLength(1);
+  });
+
+  it("cancels active logical items and persists their cancellation identity", async () => {
+    const controller = new AbortController();
+    const executeProvider = vi.fn().mockImplementation(async () => {
+      controller.abort("cancel foreach");
+      throw new Error("foreach provider cancelled");
+    });
+    const { dir, projectRepository, nodeFlowRepository, runtime } = await createRuntime({ executeProvider } as Partial<ProviderExecutionService>);
+    const project = projectRepository.createProject({ name: "Foreach cancellation", sourceType: "local", sourceRef: dir });
+    const flow = nodeFlowRepository.createFlow(project.id, { title: "Foreach cancellation", graph: {
+      nodes: [
+        { id: "foreach", type: "foreach", title: "Foreach", data: { path: "input.items" } },
+        { id: "prompt", type: "provider_prompt", title: "Prompt", data: { provider: "mockup-cli", prompt: "{{item}}" } },
+      ], edges: [{ fromNodeId: "foreach", fromHandle: "items", toNodeId: "prompt" }],
+    } });
+    const result = await runtime.runFlow(project.id, flow.id, { items: [1] }, { signal: controller.signal });
+    expect(result.run.status).toBe("cancelled");
+    expect(result.nodeRuns.find((record) => record.nodeId === "prompt")).toMatchObject({ logicalItem: "foreach:0", status: "cancelled" });
+    expect(result.attempts?.find((attempt) => attempt.nodeId === "prompt")).toMatchObject({ logicalItem: "foreach:0", failureClassification: "cancelled" });
+  });
+
+  it("recovers approval-gated Foreach sends without duplicate side effects", async () => {
+    const initialProvider = new MockSideEffectProvider();
+    const setup = await createRuntime(undefined, undefined, undefined, initialProvider);
+    const project = setup.projectRepository.createProject({ name: "Foreach approval recovery", sourceType: "local", sourceRef: setup.dir });
+    const flow = setup.nodeFlowRepository.createFlow(project.id, { title: "Foreach sends", graph: {
+      nodes: [
+        { id: "foreach", type: "foreach", title: "Foreach", data: { path: "input.items", concurrency: 2 } },
+        { id: "send", type: "email_send", title: "Send", data: { to: "ops@example.test", subject: "Item {{item}}", body: "Body {{item}}" } },
+      ], edges: [{ fromNodeId: "foreach", fromHandle: "items", toNodeId: "send" }],
+    } });
+    const waiting = await setup.runtime.runFlow(project.id, flow.id, { items: ["a", "b"] });
+    const approvals = setup.approvalService!.listForRun(waiting.run.id);
+    expect(waiting.run.status).toBe("approval_waiting");
+    expect(approvals.map((approval) => approval.logicalItem).sort()).toEqual(["foreach:0", "foreach:1"]);
+    for (const approval of approvals) setup.approvalService!.approve(approval.id, "operator");
+
+    const restartedProvider = new MockSideEffectProvider();
+    const restartedRuntime = new NodeFlowRuntimeService({
+      nodeFlowRepository: new NodeFlowRepository(setup.storage), executionRepository: new ExecutionRepository(setup.storage),
+      projectManagementRepository: new ProjectManagementRepository(setup.storage), settingsRepository: new SettingsRepository(path.join(setup.dir, "foreach-restart.db")),
+      approvalService: new ApprovalService(new AutomationApprovalRepository(setup.storage)),
+      outboxService: new OutboxService(new AutomationOutboxRepository(setup.storage), restartedProvider), getDashboardSettings: () => DEFAULT_DASHBOARD_SETTINGS,
+    });
+    const completed = await restartedRuntime.resumeApproval(project.id, approvals[0]!.id, waiting.run.id);
+    const replay = await restartedRuntime.resumeApproval(project.id, approvals[0]!.id, waiting.run.id);
+    expect(completed.run.status).toBe("succeeded");
+    expect(replay.run.status).toBe("succeeded");
+    expect(restartedProvider.sends).toHaveLength(2);
+    expect(new Set(new AutomationOutboxRepository(setup.storage).listForRun(waiting.run.id).map((record) => record.idempotencyKey)).size).toBe(2);
+    expect(completed.attempts?.filter((attempt) => attempt.nodeId === "send").map((attempt) => [attempt.logicalItem, attempt.attemptNumber]))
+      .toEqual([["foreach:0", 1], ["foreach:1", 1]]);
+  });
 });

From e4bb163f3aaf0b8b777550861d17ffdfce2004d6 Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 09:42:43 +0000
Subject: [PATCH 23/25] feat(task T19): implement via codex

---
 docs-web/architecture/custom-nodes.md         |   6 +-
 .../node-flow-builtins-and-security.md        |   4 +-
 .../docs/architecture-custom-nodes.mdx        |   6 +-
 ...ecture-node-flow-builtins-and-security.mdx |   4 +-
 docs/architecture/custom-nodes.md             |   8 +-
 .../node-flow-builtins-and-security.md        |   4 +-
 src/contracts/custom-node-types.ts            |   4 +
 .../custom-nodes/custom-node-build-service.ts |  11 +-
 .../custom-nodes/custom-node-egress-broker.ts | 139 +++++++++++++
 .../custom-node-project-service.ts            |  15 +-
 .../custom-node-runtime-service.ts            |  74 ++++---
 .../services/custom-node-services.test.ts     | 187 ++++++++++++++++++
 12 files changed, 419 insertions(+), 43 deletions(-)
 create mode 100644 src/services/custom-nodes/custom-node-egress-broker.ts

diff --git a/docs-web/architecture/custom-nodes.md b/docs-web/architecture/custom-nodes.md
index 904d7b70a2..c30db621c6 100644
--- a/docs-web/architecture/custom-nodes.md
+++ b/docs-web/architecture/custom-nodes.md
@@ -8,7 +8,7 @@ Custom execution is available only for an immutable published type/version and o
 
 ## Generated package and validation
 
-Packages live at `.code-ux/nodes/<node-id>/` and include a manifest, exact package metadata, frozen pnpm lockfile, strict TypeScript configuration, typed local SDK, `src/index.ts`, an isolated runner, deterministic tests, fixtures, and a multi-stage Dockerfile.
+Packages live at `.code-ux/nodes/<node-id>/` and include a manifest, exact package metadata, frozen pnpm lockfile, strict TypeScript configuration, typed local SDK, `src/index.ts`, an isolated runner, deterministic tests, fixtures, and a multi-stage Dockerfile. The Dockerfile and runner must match their trusted generated versions during validation.
 
 The SDK exposes immutable input/config, correlation and invocation ids, cancellation, a redacting logger, deterministic clock, bounded HTTP and credential slots, temporary storage, and artifacts. It does not expose the project path, host environment, raw filesystem, subprocesses, Docker, or raw networking.
 
@@ -20,9 +20,9 @@ A passed revision produces an immutable content-addressed envelope with source a
 
 Published images run as non-root with a read-only root, all capabilities dropped, `no-new-privileges`, optional seccomp/AppArmor profiles, bounded CPU/memory/PIDs/time/stdout, and a size-limited no-exec tmpfs. The runtime uses `--network none` and mounts neither the project nor the Docker socket nor persistent run state.
 
-Each invocation receives a fresh mode-`0600` stdin envelope. Credential values come only from the existing project-scoped `CredentialBroker`; they are never added to the environment, image, labels, cache keys, graph JSON, or persistent volume. The envelope and scratch state are deleted after the run.
+Each invocation receives a fresh mode-`0600` stdin envelope. Credential values come only from the existing project-scoped `CredentialBroker`; they are never added to the environment, image, labels, cache keys, graph JSON, persistent volume, or egress broker configuration. Credential values and the bridge token are redacted from captured results. The envelope and scratch state are deleted after the run.
 
-HTTP remains fail closed unless a transport backed by the existing `EgressPolicyService` is supplied. The default runner rejects HTTP rather than enabling bridge or host networking. Any future transport must preserve the existing host/port allowlists, DNS and redirect revalidation, response-size, timeout, retry, and rate bounds.
+When `network.http` is declared, the runtime mounts a per-invocation authenticated Unix-socket broker into the network-none container. The generated runner sends typed SDK requests over that socket, and every request passes through the shared `EgressPolicyService`: HTTPS/HTTP opt-in, host and port allowlists, DNS/private-network and redirect revalidation, restricted headers, bounded content type and size, timeout, retry, and rate policies all apply. Undeclared nodes receive no bridge reference or mount and fail closed; Docker bridge and host networking remain disabled.
 
 The parent validates the output schema and recursively replaces resolved credential values in outputs, logs, traces, and diagnostics before persistence. Content-addressed image caching therefore retains immutable code only, not credentials or cross-run mutable state.
 
diff --git a/docs-web/architecture/node-flow-builtins-and-security.md b/docs-web/architecture/node-flow-builtins-and-security.md
index 3c98e077e8..a22d1affc2 100644
--- a/docs-web/architecture/node-flow-builtins-and-security.md
+++ b/docs-web/architecture/node-flow-builtins-and-security.md
@@ -12,10 +12,12 @@ The governed catalog adds deterministic branches, bounded collection processing,
 
 ## Network policy
 
-HTTP nodes and future custom nodes use the same `EgressPolicyService`. HTTPS is required unless HTTP is explicitly enabled. Private, loopback, link-local, metadata, multicast, and other non-public addresses remain blocked in both modes. Credentials in URLs and raw restricted headers are rejected.
+HTTP nodes and custom nodes use the same `EgressPolicyService`. HTTPS is required unless HTTP is explicitly enabled. Private, loopback, link-local, metadata, multicast, and other non-public addresses remain blocked in both modes. Credentials in URLs and raw restricted headers are rejected.
 
 Every redirect is manually revalidated. DNS is checked for private results and rebinding. Host and port allowlists, response-size and content-type limits, propagated cancellation and timeouts, capped retries, idempotency requirements for unsafe retry, normalized headers, and per-key rate windows keep requests bounded.
 
+Custom-node containers remain network-none. A declared `network.http` capability adds only a per-invocation authenticated Unix-socket mount that delegates typed requests to this policy service; undeclared nodes receive neither the socket nor its token.
+
 ## OAuth, approvals, and outbox
 
 Pending approvals preserve the run, governed node, logical item, and numbered attempt. Approved decisions resume at that node boundary; rejected and expired decisions terminate durably. Repeated decisions and restart recovery do not create a second approval request, attempt, or external delivery.
diff --git a/docs-web/content/docs/architecture-custom-nodes.mdx b/docs-web/content/docs/architecture-custom-nodes.mdx
index 904d7b70a2..c30db621c6 100644
--- a/docs-web/content/docs/architecture-custom-nodes.mdx
+++ b/docs-web/content/docs/architecture-custom-nodes.mdx
@@ -8,7 +8,7 @@ Custom execution is available only for an immutable published type/version and o
 
 ## Generated package and validation
 
-Packages live at `.code-ux/nodes/<node-id>/` and include a manifest, exact package metadata, frozen pnpm lockfile, strict TypeScript configuration, typed local SDK, `src/index.ts`, an isolated runner, deterministic tests, fixtures, and a multi-stage Dockerfile.
+Packages live at `.code-ux/nodes/<node-id>/` and include a manifest, exact package metadata, frozen pnpm lockfile, strict TypeScript configuration, typed local SDK, `src/index.ts`, an isolated runner, deterministic tests, fixtures, and a multi-stage Dockerfile. The Dockerfile and runner must match their trusted generated versions during validation.
 
 The SDK exposes immutable input/config, correlation and invocation ids, cancellation, a redacting logger, deterministic clock, bounded HTTP and credential slots, temporary storage, and artifacts. It does not expose the project path, host environment, raw filesystem, subprocesses, Docker, or raw networking.
 
@@ -20,9 +20,9 @@ A passed revision produces an immutable content-addressed envelope with source a
 
 Published images run as non-root with a read-only root, all capabilities dropped, `no-new-privileges`, optional seccomp/AppArmor profiles, bounded CPU/memory/PIDs/time/stdout, and a size-limited no-exec tmpfs. The runtime uses `--network none` and mounts neither the project nor the Docker socket nor persistent run state.
 
-Each invocation receives a fresh mode-`0600` stdin envelope. Credential values come only from the existing project-scoped `CredentialBroker`; they are never added to the environment, image, labels, cache keys, graph JSON, or persistent volume. The envelope and scratch state are deleted after the run.
+Each invocation receives a fresh mode-`0600` stdin envelope. Credential values come only from the existing project-scoped `CredentialBroker`; they are never added to the environment, image, labels, cache keys, graph JSON, persistent volume, or egress broker configuration. Credential values and the bridge token are redacted from captured results. The envelope and scratch state are deleted after the run.
 
-HTTP remains fail closed unless a transport backed by the existing `EgressPolicyService` is supplied. The default runner rejects HTTP rather than enabling bridge or host networking. Any future transport must preserve the existing host/port allowlists, DNS and redirect revalidation, response-size, timeout, retry, and rate bounds.
+When `network.http` is declared, the runtime mounts a per-invocation authenticated Unix-socket broker into the network-none container. The generated runner sends typed SDK requests over that socket, and every request passes through the shared `EgressPolicyService`: HTTPS/HTTP opt-in, host and port allowlists, DNS/private-network and redirect revalidation, restricted headers, bounded content type and size, timeout, retry, and rate policies all apply. Undeclared nodes receive no bridge reference or mount and fail closed; Docker bridge and host networking remain disabled.
 
 The parent validates the output schema and recursively replaces resolved credential values in outputs, logs, traces, and diagnostics before persistence. Content-addressed image caching therefore retains immutable code only, not credentials or cross-run mutable state.
 
diff --git a/docs-web/content/docs/architecture-node-flow-builtins-and-security.mdx b/docs-web/content/docs/architecture-node-flow-builtins-and-security.mdx
index 3c98e077e8..a22d1affc2 100644
--- a/docs-web/content/docs/architecture-node-flow-builtins-and-security.mdx
+++ b/docs-web/content/docs/architecture-node-flow-builtins-and-security.mdx
@@ -12,10 +12,12 @@ The governed catalog adds deterministic branches, bounded collection processing,
 
 ## Network policy
 
-HTTP nodes and future custom nodes use the same `EgressPolicyService`. HTTPS is required unless HTTP is explicitly enabled. Private, loopback, link-local, metadata, multicast, and other non-public addresses remain blocked in both modes. Credentials in URLs and raw restricted headers are rejected.
+HTTP nodes and custom nodes use the same `EgressPolicyService`. HTTPS is required unless HTTP is explicitly enabled. Private, loopback, link-local, metadata, multicast, and other non-public addresses remain blocked in both modes. Credentials in URLs and raw restricted headers are rejected.
 
 Every redirect is manually revalidated. DNS is checked for private results and rebinding. Host and port allowlists, response-size and content-type limits, propagated cancellation and timeouts, capped retries, idempotency requirements for unsafe retry, normalized headers, and per-key rate windows keep requests bounded.
 
+Custom-node containers remain network-none. A declared `network.http` capability adds only a per-invocation authenticated Unix-socket mount that delegates typed requests to this policy service; undeclared nodes receive neither the socket nor its token.
+
 ## OAuth, approvals, and outbox
 
 Pending approvals preserve the run, governed node, logical item, and numbered attempt. Approved decisions resume at that node boundary; rejected and expired decisions terminate durably. Repeated decisions and restart recovery do not create a second approval request, attempt, or external delivery.
diff --git a/docs/architecture/custom-nodes.md b/docs/architecture/custom-nodes.md
index 78a6ea816e..32ee0d7378 100644
--- a/docs/architecture/custom-nodes.md
+++ b/docs/architecture/custom-nodes.md
@@ -13,7 +13,7 @@ An unpublished type/version is absent from the executable node-definition regist
 
 ## Package contract
 
-`CustomNodeProjectService` generates `.code-ux/nodes/<node-id>/` with `node.json`, exact package metadata, a frozen pnpm lockfile, strict TypeScript configuration, `src/index.ts`, a local typed SDK, an isolated stdio runner, deterministic tests, fixtures, and a multi-stage Dockerfile.
+`CustomNodeProjectService` generates `.code-ux/nodes/<node-id>/` with `node.json`, exact package metadata, a frozen pnpm lockfile, strict TypeScript configuration, `src/index.ts`, a local typed SDK, an isolated stdio runner, deterministic tests, fixtures, and a multi-stage Dockerfile. Both the Dockerfile and generated runner must remain byte-for-byte equal to their trusted generated versions during validation.
 
 The handler receives only `NodeExecutionContext`: immutable JSON input/config, correlation and invocation ids, an abort signal, a redacting logger, a deterministic clock, bounded HTTP and credential slots, tmpfs-backed temporary storage, and artifact writing. It does not receive a project path, process environment, host filesystem handle, subprocess API, Docker handle, or raw network client.
 
@@ -46,9 +46,11 @@ The audit hook is intentionally injected so custom nodes consume the governed de
 - a fresh stdin credential/input envelope and a fresh tmpfs scratch directory per invocation
 - Docker logging disabled; bounded stdout/stderr are captured by the parent
 
-Credential values are resolved through the existing `CredentialBroker` using the project, credential id, workspace, and required capability. They are never placed in an image layer, image label, cache key, graph, or process environment. The temporary stdin file is mode `0600`, removed after the invocation, and its in-memory values are cleared.
+Credential values are resolved through the existing `CredentialBroker` using the project, credential id, workspace, and required capability. They are never placed in an image layer, image label, cache key, graph, process environment, or broker configuration. The temporary stdin file is mode `0600`, removed after the invocation, and its in-memory values are cleared. Credential values and the ephemeral bridge token are exact-value redaction inputs for structured output, diagnostics, and captured logs.
 
-The SDK's HTTP authority is fail closed unless a transport backed by the existing `EgressPolicyService` is supplied. The default network-none runner rejects HTTP calls; it never falls back to Docker bridge networking or a second allowlist. A future broker transport must retain the T02 host/port, DNS-rebinding, redirect, response-size, timeout, retry, and rate policies before enabling `network.http` publication.
+For a manifest that declares `network.http`, the runtime starts a per-invocation Unix-socket broker, mounts only that socket directory read-only into the network-none container, and supplies an ephemeral authenticated bridge reference in the stdin envelope. The generated runner sends SDK requests over that socket; it cannot open Internet connections directly. A node without the capability receives no bridge reference or mount and fails closed.
+
+Every bridged request goes through the shared `EgressPolicyService` with the manifest's host and port allowlists, HTTPS default and explicit HTTP opt-in, double DNS resolution and private-network blocking, redirect revalidation, restricted request headers, bounded content types and response size, timeout, retry, and per-project/node rate policy. The broker accepts only bounded typed messages, authenticates its random per-run token with constant-time comparison, and disappears with the run directory after execution. Policy failures are returned to the runner as errors and never enable Docker bridge or host networking.
 
 Outputs are schema-checked before persistence. Resolved credential canaries are recursively redacted from JSON output and replaced in logs and diagnostics. Run directories are unique and deleted after each invocation, so image caching retains only immutable code and cannot retain plaintext credentials or mutable run state.
 
diff --git a/docs/architecture/node-flow-builtins-and-security.md b/docs/architecture/node-flow-builtins-and-security.md
index d59181c764..49474e3e6b 100644
--- a/docs/architecture/node-flow-builtins-and-security.md
+++ b/docs/architecture/node-flow-builtins-and-security.md
@@ -21,10 +21,12 @@ The existing `input`, `set_fields`, `template`, `provider_prompt`, `http_request
 
 ## Governed egress
 
-`EgressPolicyService` is the single request boundary for HTTP nodes and future custom-node network calls. HTTPS is required by default. A node must explicitly opt into HTTP, and even then private networking remains blocked. The service rejects credentials embedded in URLs; loopback, private, link-local, carrier-grade NAT, benchmarking, multicast, and cloud-metadata addresses; metadata hostnames; restricted raw headers; and ports or hosts outside configured allowlists.
+`EgressPolicyService` is the single request boundary for HTTP nodes and custom-node network calls. HTTPS is required by default. A node must explicitly opt into HTTP, and even then private networking remains blocked. The service rejects credentials embedded in URLs; loopback, private, link-local, carrier-grade NAT, benchmarking, multicast, and cloud-metadata addresses; metadata hostnames; restricted raw headers; and ports or hosts outside configured allowlists.
 
 Each redirect is handled manually and fully revalidated. DNS is resolved twice before dispatch, and a changed or newly private result is treated as rebinding. Cross-origin redirects remove credential headers. Response bodies are streamed into a bounded buffer, content types are allowlisted, timeouts and caller cancellation propagate, retry counts are capped, unsafe methods require an idempotency key before retry, and an in-process rate window bounds requests per project and host.
 
+Custom-node containers retain `--network none`. When `network.http` is declared, a per-invocation authenticated Unix socket exposes only this policy service; the socket directory is the sole additional read-only mount. Undeclared nodes receive no socket or bridge token. The broker accepts bounded typed messages and applies the published custom-node HTTP policy to every request.
+
 ## OAuth boundary
 
 `OAuthBroker` implements authorization-code flow with PKCE S256. Authorization state is authenticated AES-256-GCM ciphertext containing a short expiry, callback origin, redirect URI, verifier, connection id, and nonce. Callback origins must be explicitly allowlisted and match the state. Token exchange and refresh results are stored behind an `OAuthConnectionStore`; access and refresh tokens are returned only to provider-bound execution code, never to graph JSON or agent-visible output.
diff --git a/src/contracts/custom-node-types.ts b/src/contracts/custom-node-types.ts
index 0181a20880..de8c742b19 100644
--- a/src/contracts/custom-node-types.ts
+++ b/src/contracts/custom-node-types.ts
@@ -32,6 +32,10 @@ export interface CustomNodeResourceLimits {
 export interface CustomNodeHttpPolicy {
   allowedHosts: string[];
   allowedPorts?: number[];
+  allowHttp?: boolean;
+  maxRedirects?: number;
+  allowedContentTypes?: string[];
+  maxRetries?: number;
   maxRequests: number;
   timeoutMs: number;
   maxResponseBytes: number;
diff --git a/src/services/custom-nodes/custom-node-build-service.ts b/src/services/custom-nodes/custom-node-build-service.ts
index 7225c87ee3..fe0bfc63ea 100644
--- a/src/services/custom-nodes/custom-node-build-service.ts
+++ b/src/services/custom-nodes/custom-node-build-service.ts
@@ -92,6 +92,7 @@ export class CustomNodeBuildService {
       runCheck("lockfile-verification", checks, issues, () => verifyLockfile(bundle.get("pnpm-lock.yaml"), dependencies));
       runCheck("trusted-build-recipe", checks, issues, () => {
         if (bundle.get("Dockerfile") !== createCustomNodeDockerfile()) throw new ValidationError("Custom node Dockerfile must match the trusted generated build recipe.");
+        if (bundle.get("src/runner.ts") !== this.projectService.generatedRunnerSource()) throw new ValidationError("Custom node runner must match the trusted generated bridge.");
       });
       runCheck("resource-policy", checks, issues, () => validateResourcePolicy(manifest));
 
@@ -288,7 +289,15 @@ function validateResourcePolicy(manifest: CustomNodeManifest): void {
   if (!Number.isInteger(resources.scratchMb) || resources.scratchMb < 1 || resources.scratchMb > 256) throw new ValidationError("Custom node scratch limit is invalid.");
   if (manifest.http) {
     if (!manifest.http.allowedHosts.length || manifest.http.allowedHosts.some((host) => !/^[a-z0-9.-]+$/i.test(host))) throw new ValidationError("Custom node HTTP hosts must be explicit DNS names.");
-    if (manifest.http.maxRequests < 1 || manifest.http.maxRequests > 100 || manifest.http.timeoutMs > resources.timeoutMs || manifest.http.maxResponseBytes > resources.maxOutputBytes) throw new ValidationError("Custom node HTTP policy exceeds resource bounds.");
+    if (manifest.http.allowedPorts?.some((port) => !Number.isInteger(port) || port < 1 || port > 65_535)) throw new ValidationError("Custom node HTTP ports must be valid TCP ports.");
+    if (manifest.http.allowedContentTypes?.some((contentType) => !/^[a-z0-9!#$&^_.+-]+\/(?:[a-z0-9!#$&^_.+-]+)?$/i.test(contentType))) throw new ValidationError("Custom node HTTP content types are invalid.");
+    if (manifest.http.maxRedirects !== undefined && (!Number.isInteger(manifest.http.maxRedirects) || manifest.http.maxRedirects < 0 || manifest.http.maxRedirects > 10)) throw new ValidationError("Custom node HTTP redirect limit is invalid.");
+    if (manifest.http.maxRetries !== undefined && (!Number.isInteger(manifest.http.maxRetries) || manifest.http.maxRetries < 0 || manifest.http.maxRetries > 5)) throw new ValidationError("Custom node HTTP retry limit is invalid.");
+    if (!Number.isInteger(manifest.http.maxRequests) || manifest.http.maxRequests < 1 || manifest.http.maxRequests > 100
+      || !Number.isInteger(manifest.http.timeoutMs) || manifest.http.timeoutMs < 1 || manifest.http.timeoutMs > resources.timeoutMs
+      || !Number.isInteger(manifest.http.maxResponseBytes) || manifest.http.maxResponseBytes < 1 || manifest.http.maxResponseBytes > resources.maxOutputBytes) {
+      throw new ValidationError("Custom node HTTP policy exceeds resource bounds.");
+    }
   }
 }
 
diff --git a/src/services/custom-nodes/custom-node-egress-broker.ts b/src/services/custom-nodes/custom-node-egress-broker.ts
new file mode 100644
index 0000000000..e178ef0b71
--- /dev/null
+++ b/src/services/custom-nodes/custom-node-egress-broker.ts
@@ -0,0 +1,139 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import * as fs from "node:fs/promises";
+import { createServer, type Server, type Socket } from "node:net";
+import * as path from "node:path";
+import type { CustomNodeHttpPolicy, CustomNodeHttpRequest, CustomNodeHttpResponse } from "../../contracts/custom-node-types.js";
+import { ValidationError } from "../../repositories/repository-utils.js";
+import type { EgressPolicy, EgressPolicyService } from "../node-flows/egress-policy-service.js";
+
+export const CUSTOM_NODE_EGRESS_SOCKET_DIRECTORY = "/run/codeux-egress";
+const CUSTOM_NODE_EGRESS_SOCKET = `${CUSTOM_NODE_EGRESS_SOCKET_DIRECTORY}/egress.sock`;
+const MAX_BRIDGE_REQUEST_BYTES = 2 * 1024 * 1024;
+const ALLOWED_METHODS = new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"]);
+
+interface BridgeRequest {
+  token: string;
+  request: CustomNodeHttpRequest;
+}
+
+interface BridgeResponse {
+  ok: boolean;
+  response?: CustomNodeHttpResponse;
+  error?: string;
+}
+
+export interface CustomNodeEgressBrokerOptions {
+  service: EgressPolicyService;
+  policy: CustomNodeHttpPolicy;
+  socketDirectory: string;
+  rateLimitKey: string;
+}
+
+/** A per-invocation Unix-socket bridge into the shared host egress policy. */
+export class CustomNodeEgressBroker {
+  readonly token = randomBytes(32).toString("hex");
+  readonly containerSocketPath = CUSTOM_NODE_EGRESS_SOCKET;
+  private server: Server | undefined;
+  private readonly socketPath: string;
+
+  constructor(private readonly options: CustomNodeEgressBrokerOptions) {
+    this.socketPath = path.join(options.socketDirectory, "egress.sock");
+  }
+
+  async start(): Promise<void> {
+    await fs.mkdir(this.options.socketDirectory, { recursive: true, mode: 0o755 });
+    await fs.rm(this.socketPath, { force: true });
+    const server = createServer({ allowHalfOpen: true }, (socket) => this.handleConnection(socket));
+    this.server = server;
+    await new Promise<void>((resolve, reject) => {
+      const onError = (error: Error): void => { server.off("listening", onListening); reject(error); };
+      const onListening = (): void => { server.off("error", onError); resolve(); };
+      server.once("error", onError);
+      server.once("listening", onListening);
+      server.listen(this.socketPath);
+    });
+    await fs.chmod(this.socketPath, 0o666);
+  }
+
+  async close(): Promise<void> {
+    const server = this.server;
+    this.server = undefined;
+    if (server) await new Promise<void>((resolve) => server.close(() => resolve()));
+    await fs.rm(this.socketPath, { force: true });
+  }
+
+  private handleConnection(socket: Socket): void {
+    const chunks: Buffer[] = [];
+    let size = 0;
+    socket.on("data", (chunk: Buffer) => {
+      size += chunk.byteLength;
+      if (size > MAX_BRIDGE_REQUEST_BYTES) {
+        socket.destroy(new ValidationError("Custom node HTTP bridge request exceeded its size limit."));
+        return;
+      }
+      chunks.push(chunk);
+    });
+    socket.once("end", () => {
+      void this.respond(socket, Buffer.concat(chunks).toString("utf8"));
+    });
+    socket.on("error", () => undefined);
+  }
+
+  private async respond(socket: Socket, payload: string): Promise<void> {
+    let bridgeResponse: BridgeResponse;
+    try {
+      const parsed = JSON.parse(payload) as unknown;
+      if (!isBridgeRequest(parsed) || !safeTokenEquals(parsed.token, this.token)) {
+        throw new ValidationError("Custom node HTTP bridge request is unauthorized or invalid.");
+      }
+      const response = await this.options.service.request({
+        ...parsed.request,
+        policy: toEgressPolicy(this.options.policy),
+        rateLimitKey: this.options.rateLimitKey,
+      });
+      bridgeResponse = {
+        ok: true,
+        response: { status: response.status, headers: response.headers, body: response.text() },
+      };
+    } catch (error) {
+      bridgeResponse = { ok: false, error: error instanceof Error ? error.message : "Custom node HTTP request failed." };
+    }
+    socket.end(JSON.stringify(bridgeResponse));
+  }
+}
+
+function toEgressPolicy(policy: CustomNodeHttpPolicy): EgressPolicy {
+  return {
+    allowHttp: policy.allowHttp,
+    allowedHosts: policy.allowedHosts,
+    allowedPorts: policy.allowedPorts,
+    maxRedirects: policy.maxRedirects,
+    maxResponseBytes: policy.maxResponseBytes,
+    allowedContentTypes: policy.allowedContentTypes,
+    timeoutMs: policy.timeoutMs,
+    maxRetries: policy.maxRetries,
+    requestsPerMinute: policy.maxRequests,
+  };
+}
+
+function isBridgeRequest(value: unknown): value is BridgeRequest {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const candidate = value as Record<string, unknown>;
+  if (typeof candidate.token !== "string" || !candidate.request || typeof candidate.request !== "object" || Array.isArray(candidate.request)) return false;
+  const request = candidate.request as Record<string, unknown>;
+  return typeof request.url === "string"
+    && (request.method === undefined || (typeof request.method === "string" && ALLOWED_METHODS.has(request.method)))
+    && (request.body === undefined || typeof request.body === "string")
+    && (request.headers === undefined || isStringRecord(request.headers));
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value)
+    && Object.values(value as Record<string, unknown>).every((entry) => typeof entry === "string");
+}
+
+function safeTokenEquals(left: string, right: string): boolean {
+  const leftBytes = Buffer.from(left);
+  const rightBytes = Buffer.from(right);
+  return leftBytes.byteLength === rightBytes.byteLength && timingSafeEqual(leftBytes, rightBytes);
+}
diff --git a/src/services/custom-nodes/custom-node-project-service.ts b/src/services/custom-nodes/custom-node-project-service.ts
index 2aebbfde0f..708f3593c6 100644
--- a/src/services/custom-nodes/custom-node-project-service.ts
+++ b/src/services/custom-nodes/custom-node-project-service.ts
@@ -21,6 +21,10 @@ export interface GeneratedCustomNodeProject {
 }
 
 export class CustomNodeProjectService {
+  generatedRunnerSource(): string {
+    return runnerSource();
+  }
+
   async generate(input: GenerateCustomNodeProjectInput): Promise<GeneratedCustomNodeProject> {
     const nodeId = input.nodeId.trim();
     if (!NODE_ID_PATTERN.test(nodeId)) {
@@ -131,7 +135,16 @@ function sdkSource(): string {
 }
 
 function runnerSource(): string {
-  return `import * as fs from "node:fs/promises";\nimport * as crypto from "node:crypto";\nimport * as path from "node:path";\nimport { run } from "./index.js";\nimport type { Json, JsonObject, NodeExecutionContext } from "./sdk.js";\nconst scratch = "/tmp/codeux"; const chunks: Buffer[] = []; for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));\nconst envelope = JSON.parse(Buffer.concat(chunks).toString("utf8")) as { input: JsonObject; config: JsonObject; correlationId: string; invocationId: string; credentials: Record<string, string>; now: string };\nconst secrets = Object.values(envelope.credentials); const redactText = (value: string): string => { let text = value; for (const secret of secrets) if (secret) text = text.split(secret).join("[REDACTED]"); return text; }; const redactJson = (value: Json): Json => typeof value === "string" ? redactText(value) : Array.isArray(value) ? value.map(redactJson) : value && typeof value === "object" ? Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, redactJson(entry)])) : value;\nconst log = (level: string, message: string, fields?: JsonObject): void => process.stderr.write(JSON.stringify({ level, message: redactText(message), fields: fields ? redactJson(fields) : undefined, correlationId: envelope.correlationId }) + "\\n");\nconst safePath = (value: string): string => { const target = path.resolve(scratch, value); if (target !== scratch && !target.startsWith(scratch + path.sep)) throw new Error("temporary storage path escaped scratch"); return target; };\nconst context: NodeExecutionContext = { input: Object.freeze(envelope.input), config: Object.freeze(envelope.config), correlationId: envelope.correlationId, invocationId: envelope.invocationId, signal: new AbortController().signal, logger: { debug: (m,f) => log("debug",m,f), info: (m,f) => log("info",m,f), warn: (m,f) => log("warn",m,f), error: (m,f) => log("error",m,f) }, clock: { now: () => envelope.now }, http: { request: async () => { throw new Error("HTTP requires the Code UX egress broker and is unavailable in a network-none runner"); } }, credentials: { get: async (slot) => { const value = envelope.credentials[slot]; if (!value) throw new Error("credential slot is unavailable"); return value; } }, temporaryStorage: { read: async (file) => fs.readFile(safePath(file)).catch(() => null), write: async (file, content) => { const target = safePath(file); await fs.mkdir(path.dirname(target), { recursive: true }); await fs.writeFile(target, content); } }, artifacts: { write: async (name, content) => { const target = safePath("artifacts/" + name); await fs.mkdir(path.dirname(target), { recursive: true }); await fs.writeFile(target, content); const bytes = typeof content === "string" ? Buffer.from(content) : content; return { name, digest: "sha256:" + crypto.createHash("sha256").update(bytes).digest("hex"), size: bytes.byteLength }; } } };\ntry { const output = await run(context); process.stdout.write(JSON.stringify(output)); } catch (error) { log("error", error instanceof Error ? error.message : String(error)); process.exitCode = 1; }\n`;
+  return runnerTemplateSource()
+    .replace(
+      'const log = (level: string, message: string, fields?: JsonObject): void => process.stderr.write(JSON.stringify({ level, message: redactText(message), fields: fields ? redactJson(fields) : undefined, correlationId: envelope.correlationId }) + "\\n");',
+      'const log = (level: string, message: string, fields?: JsonObject): void => { process.stderr.write(JSON.stringify({ level, message: redactText(message), fields: fields ? redactJson(fields) : undefined, correlationId: envelope.correlationId }) + "\\n"); };',
+    )
+    .replace('socket.on("data", (chunk) => response.push(chunk));', 'socket.on("data", (chunk) => response.push(Buffer.from(chunk)));');
+}
+
+function runnerTemplateSource(): string {
+  return `import * as fs from "node:fs/promises";\nimport * as crypto from "node:crypto";\nimport * as net from "node:net";\nimport * as path from "node:path";\nimport { run } from "./index.js";\nimport type { Json, JsonObject, NodeExecutionContext } from "./sdk.js";\nconst scratch = "/tmp/codeux"; const chunks: Buffer[] = []; for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));\nconst envelope = JSON.parse(Buffer.concat(chunks).toString("utf8")) as { input: JsonObject; config: JsonObject; correlationId: string; invocationId: string; credentials: Record<string, string>; now: string; egress?: { socketPath: string; token: string } };\nconst secrets = [...Object.values(envelope.credentials), ...(envelope.egress ? [envelope.egress.token] : [])]; const redactText = (value: string): string => { let text = value; for (const secret of secrets) if (secret) text = text.split(secret).join("[REDACTED]"); return text; }; const redactJson = (value: Json): Json => typeof value === "string" ? redactText(value) : Array.isArray(value) ? value.map(redactJson) : value && typeof value === "object" ? Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, redactJson(entry)])) : value;\nconst log = (level: string, message: string, fields?: JsonObject): void => process.stderr.write(JSON.stringify({ level, message: redactText(message), fields: fields ? redactJson(fields) : undefined, correlationId: envelope.correlationId }) + "\\n");\nconst safePath = (value: string): string => { const target = path.resolve(scratch, value); if (target !== scratch && !target.startsWith(scratch + path.sep)) throw new Error("temporary storage path escaped scratch"); return target; };\nconst httpRequest: NodeExecutionContext["http"]["request"] = async (request) => { if (!envelope.egress) throw new Error("network.http capability is not declared"); const responseText = await new Promise<string>((resolve, reject) => { const socket = net.createConnection(envelope.egress!.socketPath); const response: Buffer[] = []; socket.on("connect", () => socket.end(JSON.stringify({ token: envelope.egress!.token, request }))); socket.on("data", (chunk) => response.push(chunk)); socket.on("end", () => resolve(Buffer.concat(response).toString("utf8"))); socket.on("error", reject); }); const result = JSON.parse(responseText) as { ok: boolean; response?: { status: number; headers: Record<string, string>; body: string }; error?: string }; if (!result.ok || !result.response) throw new Error(result.error ?? "HTTP bridge request failed"); return result.response; };\nconst context: NodeExecutionContext = { input: Object.freeze(envelope.input), config: Object.freeze(envelope.config), correlationId: envelope.correlationId, invocationId: envelope.invocationId, signal: new AbortController().signal, logger: { debug: (m,f) => log("debug",m,f), info: (m,f) => log("info",m,f), warn: (m,f) => log("warn",m,f), error: (m,f) => log("error",m,f) }, clock: { now: () => envelope.now }, http: { request: httpRequest }, credentials: { get: async (slot) => { const value = envelope.credentials[slot]; if (!value) throw new Error("credential slot is unavailable"); return value; } }, temporaryStorage: { read: async (file) => fs.readFile(safePath(file)).catch(() => null), write: async (file, content) => { const target = safePath(file); await fs.mkdir(path.dirname(target), { recursive: true }); await fs.writeFile(target, content); } }, artifacts: { write: async (name, content) => { const target = safePath("artifacts/" + name); await fs.mkdir(path.dirname(target), { recursive: true }); await fs.writeFile(target, content); const bytes = typeof content === "string" ? Buffer.from(content) : content; return { name, digest: "sha256:" + crypto.createHash("sha256").update(bytes).digest("hex"), size: bytes.byteLength }; } } };\ntry { const output = await run(context); process.stdout.write(JSON.stringify(output)); } catch (error) { log("error", error instanceof Error ? error.message : String(error)); process.exitCode = 1; }\n`;
 }
 
 export function createCustomNodeDockerfile(): string {
diff --git a/src/services/custom-nodes/custom-node-runtime-service.ts b/src/services/custom-nodes/custom-node-runtime-service.ts
index f184828106..6ebe66dc58 100644
--- a/src/services/custom-nodes/custom-node-runtime-service.ts
+++ b/src/services/custom-nodes/custom-node-runtime-service.ts
@@ -14,6 +14,7 @@ import { DOCKER_DROP_ALL_CAPS_ARGS, DOCKER_NETWORK_NONE_ARGS, DOCKER_NO_NEW_PRIV
 import { runCommandStrict, type CommandResult } from "../cli-process-runner.js";
 import type { CredentialBroker } from "../credentials/credential-broker.js";
 import type { EgressPolicyService } from "../node-flows/egress-policy-service.js";
+import { CUSTOM_NODE_EGRESS_SOCKET_DIRECTORY, CustomNodeEgressBroker } from "./custom-node-egress-broker.js";
 
 export const CUSTOM_NODE_CONTAINER_SCRATCH = "/tmp/codeux";
 
@@ -22,6 +23,7 @@ export interface CustomNodeDockerPlanInput {
   containerName: string;
   seccompProfile?: string;
   appArmorProfile?: string;
+  egressSocketDirectory?: string;
 }
 
 export function buildCustomNodeDockerRunArgs(input: CustomNodeDockerPlanInput): string[] {
@@ -45,6 +47,9 @@ export function buildCustomNodeDockerRunArgs(input: CustomNodeDockerPlanInput):
   ];
   if (input.seccompProfile) args.push("--security-opt", `seccomp=${input.seccompProfile}`);
   if (input.appArmorProfile) args.push("--security-opt", `apparmor=${input.appArmorProfile}`);
+  if (input.egressSocketDirectory) {
+    args.push("--mount", `type=bind,src=${input.egressSocketDirectory},dst=${CUSTOM_NODE_EGRESS_SOCKET_DIRECTORY},readonly`);
+  }
   args.push(input.artifact.runtimeImageDigest);
   return args;
 }
@@ -71,12 +76,23 @@ export class CustomNodeRuntimeService {
       throw new EntityNotFoundError(`Published custom node not found: ${request.nodeType}@${request.version}`);
     }
     const { artifact } = resolved;
-    await this.validateDeclaredEgress(artifact.manifest);
+    const httpPolicy = artifact.manifest.capabilities.includes("network.http")
+      ? requireHttpPolicy(artifact.manifest)
+      : undefined;
     const credentials = await this.resolveCredentials(artifact.manifest, request);
-    const secrets = Object.values(credentials);
     const runDirectory = await fs.mkdtemp(path.join(os.tmpdir(), "code-ux-custom-node-run-"));
+    const egressBroker = httpPolicy
+      ? new CustomNodeEgressBroker({
+        service: this.deps.egressPolicyService,
+        policy: httpPolicy,
+        socketDirectory: path.join(runDirectory, "egress"),
+        rateLimitKey: `${request.projectId}:${request.nodeType}`,
+      })
+      : undefined;
+    const secrets = [...Object.values(credentials), ...(egressBroker ? [egressBroker.token] : [])];
     try {
       if (process.platform !== "win32") await fs.chmod(runDirectory, 0o700);
+      await egressBroker?.start();
       const envelope = {
         input: request.input,
         config: request.config,
@@ -84,6 +100,7 @@ export class CustomNodeRuntimeService {
         invocationId: request.invocationId,
         credentials,
         now: new Date().toISOString(),
+        egress: egressBroker ? { socketPath: egressBroker.containerSocketPath, token: egressBroker.token } : undefined,
       };
       const inputPath = path.join(runDirectory, "input.json");
       await fs.writeFile(inputPath, JSON.stringify(envelope), { mode: 0o600 });
@@ -93,6 +110,7 @@ export class CustomNodeRuntimeService {
         containerName: containerName(request.invocationId),
         seccompProfile: this.deps.seccompProfile,
         appArmorProfile: this.deps.appArmorProfile,
+        egressSocketDirectory: egressBroker ? path.join(runDirectory, "egress") : undefined,
       });
       const runner = this.deps.commandRunner ?? (async (command, args, cwd, options) => runCommandStrict(command, args, cwd, process.env, options));
       const result = await runner("docker", dockerArgs, process.cwd(), {
@@ -117,43 +135,41 @@ export class CustomNodeRuntimeService {
       };
     } finally {
       for (const key of Object.keys(credentials)) credentials[key] = "";
+      await egressBroker?.close();
       await fs.rm(runDirectory, { recursive: true, force: true });
     }
   }
 
   private async resolveCredentials(manifest: CustomNodeManifest, request: CustomNodeExecutionRequest): Promise<Record<string, string>> {
     const resolved: Record<string, string> = {};
-    for (const slot of manifest.credentials) {
-      const bindingKey = request.credentialBindings[slot.slot];
-      if (!bindingKey) {
-        if (slot.required) throw new ValidationError(`Required custom node credential slot is not bound: ${slot.slot}`);
-        continue;
+    try {
+      for (const slot of manifest.credentials) {
+        const bindingKey = request.credentialBindings[slot.slot];
+        if (!bindingKey) {
+          if (slot.required) throw new ValidationError(`Required custom node credential slot is not bound: ${slot.slot}`);
+          continue;
+        }
+        const credential = await this.deps.credentialBroker.resolveCredentialId({
+          projectId: request.projectId,
+          bindingKey,
+          credentialId: bindingKey,
+          capability: slot.requiredCapability,
+          workspaceId: request.workspaceId,
+        });
+        resolved[slot.slot] = credential.value;
       }
-      const credential = await this.deps.credentialBroker.resolveCredentialId({
-        projectId: request.projectId,
-        bindingKey,
-        credentialId: bindingKey,
-        capability: slot.requiredCapability,
-        workspaceId: request.workspaceId,
-      });
-      resolved[slot.slot] = credential.value;
+      return resolved;
+    } catch (error) {
+      for (const key of Object.keys(resolved)) resolved[key] = "";
+      throw error;
     }
-    return resolved;
   }
 
-  private async validateDeclaredEgress(manifest: CustomNodeManifest): Promise<void> {
-    if (!manifest.capabilities.includes("network.http")) return;
-    if (!manifest.http) throw new ValidationError("Published custom node is missing its bounded HTTP policy.");
-    for (const host of manifest.http.allowedHosts) {
-      await this.deps.egressPolicyService.validateUrl(`https://${host}`, {
-        allowedHosts: manifest.http.allowedHosts,
-        allowedPorts: manifest.http.allowedPorts ?? [443],
-        timeoutMs: manifest.http.timeoutMs,
-        maxResponseBytes: manifest.http.maxResponseBytes,
-        requestsPerMinute: manifest.http.maxRequests,
-      });
-    }
-  }
+}
+
+function requireHttpPolicy(manifest: CustomNodeManifest): NonNullable<CustomNodeManifest["http"]> {
+  if (!manifest.http) throw new ValidationError("Published custom node is missing its bounded HTTP policy.");
+  return manifest.http;
 }
 
 function containerName(invocationId: string): string {
diff --git a/tests/backend/services/custom-node-services.test.ts b/tests/backend/services/custom-node-services.test.ts
index 3443ed9751..f7e835b20a 100644
--- a/tests/backend/services/custom-node-services.test.ts
+++ b/tests/backend/services/custom-node-services.test.ts
@@ -2,6 +2,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
+import { createConnection } from "node:net";
 import type { CustomNodeArtifact, CustomNodeManifest, CustomNodeValidationReport } from "../../../src/contracts/custom-node-types.js";
 import { resolveNodeDefinition } from "../../../src/domain/node-flows/node-definition-registry.js";
 import { AppDbStorage } from "../../../src/repositories/app-db-storage.js";
@@ -11,6 +12,7 @@ import { CustomNodeBuildService } from "../../../src/services/custom-nodes/custo
 import { CustomNodeProjectService } from "../../../src/services/custom-nodes/custom-node-project-service.js";
 import { buildCustomNodeDockerRunArgs, CustomNodeRuntimeService } from "../../../src/services/custom-nodes/custom-node-runtime-service.js";
 import type { CommandResult } from "../../../src/services/cli-process-runner.js";
+import { EgressPolicyService } from "../../../src/services/node-flows/egress-policy-service.js";
 
 const temporaryDirectories: string[] = [];
 const result = (stdout = "", stderr = ""): CommandResult => ({ ok: true, code: 0, stdout, stderr });
@@ -54,6 +56,9 @@ describe("custom node project and build services", () => {
     expect(resolveNodeDefinition("custom.fixture-node", 1)?.executionKind).toBe("custom");
     expect(artifact.digest).toBe(validation.artifact?.digest);
     await expect(fs.readFile(path.join(setup.root, ".code-ux", "nodes", "fixture-node", "src", "sdk.ts"), "utf8")).resolves.toContain("NodeExecutionContext");
+    const runner = await fs.readFile(path.join(setup.root, ".code-ux", "nodes", "fixture-node", "src", "runner.ts"), "utf8");
+    expect(runner).toContain("net.createConnection");
+    expect(runner).not.toContain("HTTP requires the Code UX egress broker and is unavailable");
     setup.storage.close();
   });
 
@@ -137,8 +142,190 @@ describe("custom node Docker plan and runtime security", () => {
     await expect(runtime.execute({ projectId: setup.projectId, nodeType: "custom.gated-node", version: 1, input: {}, config: {}, credentialBindings: {}, workspaceId: "run", invocationId: "invocation", correlationId: "correlation" })).rejects.toThrow(/feature gate/i);
     setup.storage.close();
   });
+
+  it("bridges declared HTTP through the shared egress policy while retaining network-none isolation", async () => {
+    const fetchMock = vi.fn(async () => new Response("accepted", { status: 200, headers: { "content-type": "text/plain" } }));
+    const scenario = await networkRuntime("allowed-http", fetchMock);
+    const execution = await scenario.execute({ url: "https://api.example.test/jobs" });
+
+    expect(execution.output).toEqual({ status: 200, body: "accepted" });
+    expect(scenario.dockerArgs).toEqual(expect.arrayContaining(["--network", "none", "--mount"]));
+    expect(scenario.dockerArgs.join(" ")).not.toContain("--network bridge");
+    expect(fetchMock).toHaveBeenCalledOnce();
+    scenario.storage.close();
+  });
+
+  it("permits plain HTTP only when the manifest explicitly opts in", async () => {
+    const fetchMock = vi.fn(async () => new Response("accepted", { status: 200, headers: { "content-type": "text/plain" } }));
+    const scenario = await networkRuntime("allowed-plain-http", fetchMock, { allowHttp: true, allowedPorts: [80] });
+    await expect(scenario.execute({ url: "http://api.example.test/jobs" })).resolves.toMatchObject({ output: { status: 200, body: "accepted" } });
+    expect(fetchMock).toHaveBeenCalledOnce();
+    scenario.storage.close();
+  });
+
+  it.each([
+    {
+      name: "SSRF to a loopback address",
+      request: { url: "https://127.0.0.1/data" },
+      policy: { allowedHosts: ["127.0.0.1"] },
+      error: /private|loopback|metadata/i,
+    },
+    {
+      name: "plain HTTP without opt-in",
+      request: { url: "http://api.example.test/data" },
+      policy: { allowedPorts: [80] },
+      error: /HTTPS unless HTTP is explicitly enabled/i,
+    },
+    {
+      name: "a restricted authorization header",
+      request: { url: "https://api.example.test/data", headers: { Authorization: "Bearer secret" } },
+      error: /header is restricted/i,
+    },
+  ])("fails closed for $name", async ({ request, policy, error }) => {
+    const fetchMock = vi.fn(async () => new Response("should not run", { headers: { "content-type": "text/plain" } }));
+    const scenario = await networkRuntime(`blocked-${temporaryDirectories.length}`, fetchMock, policy);
+    await expect(scenario.execute(request)).rejects.toThrow(error);
+    expect(fetchMock).not.toHaveBeenCalled();
+    scenario.storage.close();
+  });
+
+  it("revalidates redirects and rejects a redirect to a private destination", async () => {
+    const fetchMock = vi.fn(async () => new Response(null, { status: 302, headers: { location: "https://127.0.0.1/metadata" } }));
+    const scenario = await networkRuntime("blocked-redirect", fetchMock, { allowedHosts: ["api.example.test", "127.0.0.1"] });
+    await expect(scenario.execute({ url: "https://api.example.test/start" })).rejects.toThrow(/private|loopback|metadata/i);
+    expect(fetchMock).toHaveBeenCalledOnce();
+    scenario.storage.close();
+  });
+
+  it.each([
+    {
+      name: "an oversized response",
+      fetch: async () => new Response("12345", { headers: { "content-type": "text/plain", "content-length": "5" } }),
+      policy: { maxResponseBytes: 4 },
+      error: /size limit/i,
+    },
+    {
+      name: "a disallowed response content type",
+      fetch: async () => new Response("<html>", { headers: { "content-type": "text/html" } }),
+      policy: { allowedContentTypes: ["application/json"] },
+      error: /content type is not allowed/i,
+    },
+  ])("fails closed for $name", async ({ fetch, policy, error }) => {
+    const scenario = await networkRuntime(`response-${temporaryDirectories.length}`, vi.fn(fetch), policy);
+    await expect(scenario.execute({ url: "https://api.example.test/data" })).rejects.toThrow(error);
+    scenario.storage.close();
+  });
+
+  it("propagates request timeouts through the bridge", async () => {
+    const fetchMock = vi.fn(async (_url: string | URL | Request, init?: RequestInit) => new Promise<Response>((_resolve, reject) => {
+      init?.signal?.addEventListener("abort", () => reject(init.signal?.reason), { once: true });
+    }));
+    const scenario = await networkRuntime("timeout-http", fetchMock, { timeoutMs: 5 });
+    await expect(scenario.execute({ url: "https://api.example.test/slow" })).rejects.toThrow(/timed out/i);
+    scenario.storage.close();
+  });
+
+  it("bounds retries and fails closed after the declared retry count", async () => {
+    const fetchMock = vi.fn(async () => { throw new Error("upstream unavailable"); });
+    const scenario = await networkRuntime("retry-http", fetchMock, { maxRetries: 2 });
+    await expect(scenario.execute({ url: "https://api.example.test/jobs" })).rejects.toThrow(/upstream unavailable/i);
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    scenario.storage.close();
+  });
+
+  it("enforces the declared per-minute request rate", async () => {
+    const fetchMock = vi.fn(async () => new Response("ok", { headers: { "content-type": "text/plain" } }));
+    const scenario = await networkRuntime("rate-http", fetchMock, { maxRequests: 1 });
+    await scenario.execute({ url: "https://api.example.test/first" });
+    await expect(scenario.execute({ url: "https://api.example.test/second" })).rejects.toThrow(/rate limit/i);
+    expect(fetchMock).toHaveBeenCalledOnce();
+    scenario.storage.close();
+  });
+
+  it("does not create a broker or mount for undeclared network access", async () => {
+    const setup = await fixture("undeclared-http");
+    const artifact = artifactFixture("undeclared-http", `sha256:${"f".repeat(64)}`, setup.projectId);
+    publishArtifact(setup.repository, artifact);
+    const fetchMock = vi.fn();
+    const commandRunner = vi.fn(async (_command: string, args: string[], _cwd: string, options: { stdinFile?: string }): Promise<CommandResult> => {
+      expect(args).not.toContain("--mount");
+      const envelope = JSON.parse(await fs.readFile(options.stdinFile!, "utf8")) as { egress?: unknown };
+      expect(envelope.egress).toBeUndefined();
+      throw new Error("network.http capability is not declared");
+    });
+    const runtime = new CustomNodeRuntimeService({ repository: setup.repository, credentialBroker: {} as never, egressPolicyService: new EgressPolicyService({ fetch: fetchMock }), featureEnabled: true, commandRunner });
+    await expect(runtime.execute(executionRequest(setup.projectId, "undeclared-http"))).rejects.toThrow(/not declared/i);
+    expect(fetchMock).not.toHaveBeenCalled();
+    setup.storage.close();
+  });
 });
 
+type HttpRequestFixture = { url: string; method?: string; headers?: Record<string, string>; body?: string };
+
+async function networkRuntime(
+  nodeId: string,
+  fetchMock: typeof fetch,
+  policyOverrides: Partial<NonNullable<CustomNodeManifest["http"]>> = {},
+): Promise<{
+  storage: AppDbStorage;
+  dockerArgs: string[];
+  execute(request: HttpRequestFixture): Promise<Awaited<ReturnType<CustomNodeRuntimeService["execute"]>>>;
+}> {
+  const setup = await fixture(nodeId);
+  const artifact = artifactFixture(nodeId, `sha256:${"f".repeat(64)}`, setup.projectId);
+  artifact.manifest.capabilities = ["network.http"];
+  artifact.manifest.http = {
+    allowedHosts: ["api.example.test"], maxRequests: 10, timeoutMs: 1_000, maxResponseBytes: 1_024,
+    ...policyOverrides,
+  };
+  publishArtifact(setup.repository, artifact);
+  let dockerArgs: string[] = [];
+  const commandRunner = vi.fn(async (_command: string, args: string[], _cwd: string, options: { stdinFile?: string }): Promise<CommandResult> => {
+    dockerArgs = args;
+    const envelope = JSON.parse(await fs.readFile(options.stdinFile!, "utf8")) as { input: { request: HttpRequestFixture }; egress?: { token: string } };
+    if (!envelope.egress) throw new Error("network.http capability is not declared");
+    const mount = args.find((arg) => arg.startsWith("type=bind,src=") && arg.includes(`dst=/run/codeux-egress`));
+    if (!mount) throw new Error("egress socket mount is unavailable");
+    const socketDirectory = mount.slice("type=bind,src=".length, mount.indexOf(",dst="));
+    const bridge = await bridgeRequest(path.join(socketDirectory, "egress.sock"), envelope.egress.token, envelope.input.request);
+    if (!bridge.ok || !bridge.response) throw new Error(bridge.error ?? "HTTP bridge request failed");
+    return result(JSON.stringify({ status: bridge.response.status, body: bridge.response.body }));
+  });
+  const runtime = new CustomNodeRuntimeService({
+    repository: setup.repository,
+    credentialBroker: {} as never,
+    egressPolicyService: new EgressPolicyService({ fetch: fetchMock, lookup: async () => [{ address: "8.8.8.8", family: 4 }] }),
+    featureEnabled: true,
+    commandRunner,
+  });
+  return {
+    storage: setup.storage,
+    get dockerArgs() { return dockerArgs; },
+    execute: (request) => runtime.execute({ ...executionRequest(setup.projectId, nodeId), input: { request } }),
+  };
+}
+
+async function bridgeRequest(socketPath: string, token: string, request: HttpRequestFixture): Promise<{ ok: boolean; response?: { status: number; headers: Record<string, string>; body: string }; error?: string }> {
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(socketPath);
+    const chunks: Buffer[] = [];
+    socket.on("connect", () => socket.end(JSON.stringify({ token, request })));
+    socket.on("data", (chunk) => chunks.push(chunk));
+    socket.on("end", () => resolve(JSON.parse(Buffer.concat(chunks).toString("utf8")) as { ok: boolean; response?: { status: number; headers: Record<string, string>; body: string }; error?: string }));
+    socket.on("error", reject);
+  });
+}
+
+function publishArtifact(repository: CustomNodeRepository, artifact: CustomNodeArtifact): void {
+  repository.beginValidation(artifact.nodeId);
+  repository.completeValidation(artifact.nodeId, artifact.validationReport, artifact);
+  repository.publish(artifact.nodeId, "publisher");
+}
+
+function executionRequest(projectId: string, nodeId: string) {
+  return { projectId, nodeType: `custom.${nodeId}`, version: 1, input: {}, config: {}, credentialBindings: {}, workspaceId: "run", invocationId: `invocation-${nodeId}`, correlationId: "correlation" };
+}
+
 function artifactFixture(nodeId: string, runtimeImageDigest: string, projectId = "project"): CustomNodeArtifact {
   const generatedManifest: CustomNodeManifest = {
     schemaVersion: 1, id: nodeId, nodeType: `custom.${nodeId}`, version: 1, name: "Test", description: "",

From 2967be7e822836e63cc33100208eff6d9a95bbec Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 10:11:27 +0000
Subject: [PATCH 24/25] feat(task T22): implement via codex

---
 docs-web/architecture/custom-nodes.md         |   6 +-
 .../docs/architecture-custom-nodes.mdx        |   6 +-
 docs/architecture/custom-nodes.md             |   8 +-
 src/contracts/custom-node-types.ts            |   4 +
 .../custom-nodes/custom-node-build-service.ts |  12 +-
 .../custom-nodes/custom-node-egress-broker.ts | 140 ++++++++++
 .../custom-node-project-service.ts            |  15 +-
 .../custom-node-runtime-service.ts            |  80 +++---
 .../services/custom-node-services.test.ts     | 240 ++++++++++++++++++
 9 files changed, 471 insertions(+), 40 deletions(-)
 create mode 100644 src/services/custom-nodes/custom-node-egress-broker.ts

diff --git a/docs-web/architecture/custom-nodes.md b/docs-web/architecture/custom-nodes.md
index 904d7b70a2..c30db621c6 100644
--- a/docs-web/architecture/custom-nodes.md
+++ b/docs-web/architecture/custom-nodes.md
@@ -8,7 +8,7 @@ Custom execution is available only for an immutable published type/version and o
 
 ## Generated package and validation
 
-Packages live at `.code-ux/nodes/<node-id>/` and include a manifest, exact package metadata, frozen pnpm lockfile, strict TypeScript configuration, typed local SDK, `src/index.ts`, an isolated runner, deterministic tests, fixtures, and a multi-stage Dockerfile.
+Packages live at `.code-ux/nodes/<node-id>/` and include a manifest, exact package metadata, frozen pnpm lockfile, strict TypeScript configuration, typed local SDK, `src/index.ts`, an isolated runner, deterministic tests, fixtures, and a multi-stage Dockerfile. The Dockerfile and runner must match their trusted generated versions during validation.
 
 The SDK exposes immutable input/config, correlation and invocation ids, cancellation, a redacting logger, deterministic clock, bounded HTTP and credential slots, temporary storage, and artifacts. It does not expose the project path, host environment, raw filesystem, subprocesses, Docker, or raw networking.
 
@@ -20,9 +20,9 @@ A passed revision produces an immutable content-addressed envelope with source a
 
 Published images run as non-root with a read-only root, all capabilities dropped, `no-new-privileges`, optional seccomp/AppArmor profiles, bounded CPU/memory/PIDs/time/stdout, and a size-limited no-exec tmpfs. The runtime uses `--network none` and mounts neither the project nor the Docker socket nor persistent run state.
 
-Each invocation receives a fresh mode-`0600` stdin envelope. Credential values come only from the existing project-scoped `CredentialBroker`; they are never added to the environment, image, labels, cache keys, graph JSON, or persistent volume. The envelope and scratch state are deleted after the run.
+Each invocation receives a fresh mode-`0600` stdin envelope. Credential values come only from the existing project-scoped `CredentialBroker`; they are never added to the environment, image, labels, cache keys, graph JSON, persistent volume, or egress broker configuration. Credential values and the bridge token are redacted from captured results. The envelope and scratch state are deleted after the run.
 
-HTTP remains fail closed unless a transport backed by the existing `EgressPolicyService` is supplied. The default runner rejects HTTP rather than enabling bridge or host networking. Any future transport must preserve the existing host/port allowlists, DNS and redirect revalidation, response-size, timeout, retry, and rate bounds.
+When `network.http` is declared, the runtime mounts a per-invocation authenticated Unix-socket broker into the network-none container. The generated runner sends typed SDK requests over that socket, and every request passes through the shared `EgressPolicyService`: HTTPS/HTTP opt-in, host and port allowlists, DNS/private-network and redirect revalidation, restricted headers, bounded content type and size, timeout, retry, and rate policies all apply. Undeclared nodes receive no bridge reference or mount and fail closed; Docker bridge and host networking remain disabled.
 
 The parent validates the output schema and recursively replaces resolved credential values in outputs, logs, traces, and diagnostics before persistence. Content-addressed image caching therefore retains immutable code only, not credentials or cross-run mutable state.
 
diff --git a/docs-web/content/docs/architecture-custom-nodes.mdx b/docs-web/content/docs/architecture-custom-nodes.mdx
index 904d7b70a2..c30db621c6 100644
--- a/docs-web/content/docs/architecture-custom-nodes.mdx
+++ b/docs-web/content/docs/architecture-custom-nodes.mdx
@@ -8,7 +8,7 @@ Custom execution is available only for an immutable published type/version and o
 
 ## Generated package and validation
 
-Packages live at `.code-ux/nodes/<node-id>/` and include a manifest, exact package metadata, frozen pnpm lockfile, strict TypeScript configuration, typed local SDK, `src/index.ts`, an isolated runner, deterministic tests, fixtures, and a multi-stage Dockerfile.
+Packages live at `.code-ux/nodes/<node-id>/` and include a manifest, exact package metadata, frozen pnpm lockfile, strict TypeScript configuration, typed local SDK, `src/index.ts`, an isolated runner, deterministic tests, fixtures, and a multi-stage Dockerfile. The Dockerfile and runner must match their trusted generated versions during validation.
 
 The SDK exposes immutable input/config, correlation and invocation ids, cancellation, a redacting logger, deterministic clock, bounded HTTP and credential slots, temporary storage, and artifacts. It does not expose the project path, host environment, raw filesystem, subprocesses, Docker, or raw networking.
 
@@ -20,9 +20,9 @@ A passed revision produces an immutable content-addressed envelope with source a
 
 Published images run as non-root with a read-only root, all capabilities dropped, `no-new-privileges`, optional seccomp/AppArmor profiles, bounded CPU/memory/PIDs/time/stdout, and a size-limited no-exec tmpfs. The runtime uses `--network none` and mounts neither the project nor the Docker socket nor persistent run state.
 
-Each invocation receives a fresh mode-`0600` stdin envelope. Credential values come only from the existing project-scoped `CredentialBroker`; they are never added to the environment, image, labels, cache keys, graph JSON, or persistent volume. The envelope and scratch state are deleted after the run.
+Each invocation receives a fresh mode-`0600` stdin envelope. Credential values come only from the existing project-scoped `CredentialBroker`; they are never added to the environment, image, labels, cache keys, graph JSON, persistent volume, or egress broker configuration. Credential values and the bridge token are redacted from captured results. The envelope and scratch state are deleted after the run.
 
-HTTP remains fail closed unless a transport backed by the existing `EgressPolicyService` is supplied. The default runner rejects HTTP rather than enabling bridge or host networking. Any future transport must preserve the existing host/port allowlists, DNS and redirect revalidation, response-size, timeout, retry, and rate bounds.
+When `network.http` is declared, the runtime mounts a per-invocation authenticated Unix-socket broker into the network-none container. The generated runner sends typed SDK requests over that socket, and every request passes through the shared `EgressPolicyService`: HTTPS/HTTP opt-in, host and port allowlists, DNS/private-network and redirect revalidation, restricted headers, bounded content type and size, timeout, retry, and rate policies all apply. Undeclared nodes receive no bridge reference or mount and fail closed; Docker bridge and host networking remain disabled.
 
 The parent validates the output schema and recursively replaces resolved credential values in outputs, logs, traces, and diagnostics before persistence. Content-addressed image caching therefore retains immutable code only, not credentials or cross-run mutable state.
 
diff --git a/docs/architecture/custom-nodes.md b/docs/architecture/custom-nodes.md
index 78a6ea816e..32ee0d7378 100644
--- a/docs/architecture/custom-nodes.md
+++ b/docs/architecture/custom-nodes.md
@@ -13,7 +13,7 @@ An unpublished type/version is absent from the executable node-definition regist
 
 ## Package contract
 
-`CustomNodeProjectService` generates `.code-ux/nodes/<node-id>/` with `node.json`, exact package metadata, a frozen pnpm lockfile, strict TypeScript configuration, `src/index.ts`, a local typed SDK, an isolated stdio runner, deterministic tests, fixtures, and a multi-stage Dockerfile.
+`CustomNodeProjectService` generates `.code-ux/nodes/<node-id>/` with `node.json`, exact package metadata, a frozen pnpm lockfile, strict TypeScript configuration, `src/index.ts`, a local typed SDK, an isolated stdio runner, deterministic tests, fixtures, and a multi-stage Dockerfile. Both the Dockerfile and generated runner must remain byte-for-byte equal to their trusted generated versions during validation.
 
 The handler receives only `NodeExecutionContext`: immutable JSON input/config, correlation and invocation ids, an abort signal, a redacting logger, a deterministic clock, bounded HTTP and credential slots, tmpfs-backed temporary storage, and artifact writing. It does not receive a project path, process environment, host filesystem handle, subprocess API, Docker handle, or raw network client.
 
@@ -46,9 +46,11 @@ The audit hook is intentionally injected so custom nodes consume the governed de
 - a fresh stdin credential/input envelope and a fresh tmpfs scratch directory per invocation
 - Docker logging disabled; bounded stdout/stderr are captured by the parent
 
-Credential values are resolved through the existing `CredentialBroker` using the project, credential id, workspace, and required capability. They are never placed in an image layer, image label, cache key, graph, or process environment. The temporary stdin file is mode `0600`, removed after the invocation, and its in-memory values are cleared.
+Credential values are resolved through the existing `CredentialBroker` using the project, credential id, workspace, and required capability. They are never placed in an image layer, image label, cache key, graph, process environment, or broker configuration. The temporary stdin file is mode `0600`, removed after the invocation, and its in-memory values are cleared. Credential values and the ephemeral bridge token are exact-value redaction inputs for structured output, diagnostics, and captured logs.
 
-The SDK's HTTP authority is fail closed unless a transport backed by the existing `EgressPolicyService` is supplied. The default network-none runner rejects HTTP calls; it never falls back to Docker bridge networking or a second allowlist. A future broker transport must retain the T02 host/port, DNS-rebinding, redirect, response-size, timeout, retry, and rate policies before enabling `network.http` publication.
+For a manifest that declares `network.http`, the runtime starts a per-invocation Unix-socket broker, mounts only that socket directory read-only into the network-none container, and supplies an ephemeral authenticated bridge reference in the stdin envelope. The generated runner sends SDK requests over that socket; it cannot open Internet connections directly. A node without the capability receives no bridge reference or mount and fails closed.
+
+Every bridged request goes through the shared `EgressPolicyService` with the manifest's host and port allowlists, HTTPS default and explicit HTTP opt-in, double DNS resolution and private-network blocking, redirect revalidation, restricted request headers, bounded content types and response size, timeout, retry, and per-project/node rate policy. The broker accepts only bounded typed messages, authenticates its random per-run token with constant-time comparison, and disappears with the run directory after execution. Policy failures are returned to the runner as errors and never enable Docker bridge or host networking.
 
 Outputs are schema-checked before persistence. Resolved credential canaries are recursively redacted from JSON output and replaced in logs and diagnostics. Run directories are unique and deleted after each invocation, so image caching retains only immutable code and cannot retain plaintext credentials or mutable run state.
 
diff --git a/src/contracts/custom-node-types.ts b/src/contracts/custom-node-types.ts
index 0181a20880..de8c742b19 100644
--- a/src/contracts/custom-node-types.ts
+++ b/src/contracts/custom-node-types.ts
@@ -32,6 +32,10 @@ export interface CustomNodeResourceLimits {
 export interface CustomNodeHttpPolicy {
   allowedHosts: string[];
   allowedPorts?: number[];
+  allowHttp?: boolean;
+  maxRedirects?: number;
+  allowedContentTypes?: string[];
+  maxRetries?: number;
   maxRequests: number;
   timeoutMs: number;
   maxResponseBytes: number;
diff --git a/src/services/custom-nodes/custom-node-build-service.ts b/src/services/custom-nodes/custom-node-build-service.ts
index 7225c87ee3..5c1710172c 100644
--- a/src/services/custom-nodes/custom-node-build-service.ts
+++ b/src/services/custom-nodes/custom-node-build-service.ts
@@ -92,6 +92,7 @@ export class CustomNodeBuildService {
       runCheck("lockfile-verification", checks, issues, () => verifyLockfile(bundle.get("pnpm-lock.yaml"), dependencies));
       runCheck("trusted-build-recipe", checks, issues, () => {
         if (bundle.get("Dockerfile") !== createCustomNodeDockerfile()) throw new ValidationError("Custom node Dockerfile must match the trusted generated build recipe.");
+        if (bundle.get("src/runner.ts") !== this.projectService.generatedRunnerSource()) throw new ValidationError("Custom node runner must match the trusted generated bridge.");
       });
       runCheck("resource-policy", checks, issues, () => validateResourcePolicy(manifest));
 
@@ -288,7 +289,16 @@ function validateResourcePolicy(manifest: CustomNodeManifest): void {
   if (!Number.isInteger(resources.scratchMb) || resources.scratchMb < 1 || resources.scratchMb > 256) throw new ValidationError("Custom node scratch limit is invalid.");
   if (manifest.http) {
     if (!manifest.http.allowedHosts.length || manifest.http.allowedHosts.some((host) => !/^[a-z0-9.-]+$/i.test(host))) throw new ValidationError("Custom node HTTP hosts must be explicit DNS names.");
-    if (manifest.http.maxRequests < 1 || manifest.http.maxRequests > 100 || manifest.http.timeoutMs > resources.timeoutMs || manifest.http.maxResponseBytes > resources.maxOutputBytes) throw new ValidationError("Custom node HTTP policy exceeds resource bounds.");
+    if (manifest.http.allowHttp !== undefined && typeof manifest.http.allowHttp !== "boolean") throw new ValidationError("Custom node HTTP opt-in must be a boolean.");
+    if (manifest.http.allowedPorts?.some((port) => !Number.isInteger(port) || port < 1 || port > 65_535)) throw new ValidationError("Custom node HTTP ports must be valid TCP ports.");
+    if (manifest.http.allowedContentTypes?.some((contentType) => !/^[a-z0-9!#$&^_.+-]+\/(?:[a-z0-9!#$&^_.+-]+)?$/i.test(contentType))) throw new ValidationError("Custom node HTTP content types are invalid.");
+    if (manifest.http.maxRedirects !== undefined && (!Number.isInteger(manifest.http.maxRedirects) || manifest.http.maxRedirects < 0 || manifest.http.maxRedirects > 10)) throw new ValidationError("Custom node HTTP redirect limit is invalid.");
+    if (manifest.http.maxRetries !== undefined && (!Number.isInteger(manifest.http.maxRetries) || manifest.http.maxRetries < 0 || manifest.http.maxRetries > 5)) throw new ValidationError("Custom node HTTP retry limit is invalid.");
+    if (!Number.isInteger(manifest.http.maxRequests) || manifest.http.maxRequests < 1 || manifest.http.maxRequests > 100
+      || !Number.isInteger(manifest.http.timeoutMs) || manifest.http.timeoutMs < 1 || manifest.http.timeoutMs > resources.timeoutMs
+      || !Number.isInteger(manifest.http.maxResponseBytes) || manifest.http.maxResponseBytes < 1 || manifest.http.maxResponseBytes > resources.maxOutputBytes) {
+      throw new ValidationError("Custom node HTTP policy exceeds resource bounds.");
+    }
   }
 }
 
diff --git a/src/services/custom-nodes/custom-node-egress-broker.ts b/src/services/custom-nodes/custom-node-egress-broker.ts
new file mode 100644
index 0000000000..2fcecd60d1
--- /dev/null
+++ b/src/services/custom-nodes/custom-node-egress-broker.ts
@@ -0,0 +1,140 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import * as fs from "node:fs/promises";
+import { createServer, type Server, type Socket } from "node:net";
+import * as path from "node:path";
+import type { CustomNodeHttpPolicy, CustomNodeHttpRequest, CustomNodeHttpResponse } from "../../contracts/custom-node-types.js";
+import { ValidationError } from "../../repositories/repository-utils.js";
+import type { EgressPolicy, EgressPolicyService } from "../node-flows/egress-policy-service.js";
+
+export const CUSTOM_NODE_EGRESS_SOCKET_DIRECTORY = "/run/codeux-egress";
+const CUSTOM_NODE_EGRESS_SOCKET = `${CUSTOM_NODE_EGRESS_SOCKET_DIRECTORY}/egress.sock`;
+const MAX_BRIDGE_REQUEST_BYTES = 2 * 1024 * 1024;
+const ALLOWED_METHODS = new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"]);
+
+interface BridgeRequest {
+  token: string;
+  request: CustomNodeHttpRequest;
+}
+
+interface BridgeResponse {
+  ok: boolean;
+  response?: CustomNodeHttpResponse;
+  error?: string;
+}
+
+export interface CustomNodeEgressBrokerOptions {
+  service: EgressPolicyService;
+  policy: CustomNodeHttpPolicy;
+  socketDirectory: string;
+  rateLimitKey: string;
+}
+
+/** A per-invocation Unix-socket bridge into the shared host egress policy. */
+export class CustomNodeEgressBroker {
+  readonly token = randomBytes(32).toString("hex");
+  readonly containerSocketPath = CUSTOM_NODE_EGRESS_SOCKET;
+  private server: Server | undefined;
+  private readonly socketPath: string;
+
+  constructor(private readonly options: CustomNodeEgressBrokerOptions) {
+    this.socketPath = path.join(options.socketDirectory, "egress.sock");
+  }
+
+  async start(): Promise<void> {
+    await fs.mkdir(this.options.socketDirectory, { recursive: true, mode: 0o755 });
+    await fs.rm(this.socketPath, { force: true });
+    const server = createServer({ allowHalfOpen: true }, (socket) => this.handleConnection(socket));
+    this.server = server;
+    await new Promise<void>((resolve, reject) => {
+      const onError = (error: Error): void => { server.off("listening", onListening); reject(error); };
+      const onListening = (): void => { server.off("error", onError); resolve(); };
+      server.once("error", onError);
+      server.once("listening", onListening);
+      server.listen(this.socketPath);
+    });
+    await fs.chmod(this.socketPath, 0o666);
+  }
+
+  async close(): Promise<void> {
+    const server = this.server;
+    this.server = undefined;
+    if (server) await new Promise<void>((resolve) => server.close(() => resolve()));
+    await fs.rm(this.socketPath, { force: true });
+  }
+
+  private handleConnection(socket: Socket): void {
+    const chunks: Buffer[] = [];
+    let size = 0;
+    socket.on("data", (chunk: Buffer) => {
+      size += chunk.byteLength;
+      if (size > MAX_BRIDGE_REQUEST_BYTES) {
+        socket.destroy(new ValidationError("Custom node HTTP bridge request exceeded its size limit."));
+        return;
+      }
+      chunks.push(chunk);
+    });
+    socket.once("end", () => {
+      void this.respond(socket, Buffer.concat(chunks).toString("utf8"));
+    });
+    socket.on("error", () => undefined);
+  }
+
+  private async respond(socket: Socket, payload: string): Promise<void> {
+    let bridgeResponse: BridgeResponse;
+    try {
+      const parsed = JSON.parse(payload) as unknown;
+      if (!isBridgeRequest(parsed) || !safeTokenEquals(parsed.token, this.token)) {
+        throw new ValidationError("Custom node HTTP bridge request is unauthorized or invalid.");
+      }
+      const response = await this.options.service.request({
+        ...parsed.request,
+        policy: toEgressPolicy(this.options.policy),
+        rateLimitKey: this.options.rateLimitKey,
+      });
+      bridgeResponse = {
+        ok: true,
+        response: { status: response.status, headers: response.headers, body: response.text() },
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Custom node HTTP request failed.";
+      bridgeResponse = { ok: false, error: message.split(this.token).join("[REDACTED]") };
+    }
+    socket.end(JSON.stringify(bridgeResponse));
+  }
+}
+
+function toEgressPolicy(policy: CustomNodeHttpPolicy): EgressPolicy {
+  return {
+    allowHttp: policy.allowHttp,
+    allowedHosts: policy.allowedHosts,
+    allowedPorts: policy.allowedPorts,
+    maxRedirects: policy.maxRedirects,
+    maxResponseBytes: policy.maxResponseBytes,
+    allowedContentTypes: policy.allowedContentTypes,
+    timeoutMs: policy.timeoutMs,
+    maxRetries: policy.maxRetries,
+    requestsPerMinute: policy.maxRequests,
+  };
+}
+
+function isBridgeRequest(value: unknown): value is BridgeRequest {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const candidate = value as Record<string, unknown>;
+  if (typeof candidate.token !== "string" || !candidate.request || typeof candidate.request !== "object" || Array.isArray(candidate.request)) return false;
+  const request = candidate.request as Record<string, unknown>;
+  return typeof request.url === "string"
+    && (request.method === undefined || (typeof request.method === "string" && ALLOWED_METHODS.has(request.method)))
+    && (request.body === undefined || typeof request.body === "string")
+    && (request.headers === undefined || isStringRecord(request.headers));
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value)
+    && Object.values(value as Record<string, unknown>).every((entry) => typeof entry === "string");
+}
+
+function safeTokenEquals(left: string, right: string): boolean {
+  const leftBytes = Buffer.from(left);
+  const rightBytes = Buffer.from(right);
+  return leftBytes.byteLength === rightBytes.byteLength && timingSafeEqual(leftBytes, rightBytes);
+}
diff --git a/src/services/custom-nodes/custom-node-project-service.ts b/src/services/custom-nodes/custom-node-project-service.ts
index 2aebbfde0f..708f3593c6 100644
--- a/src/services/custom-nodes/custom-node-project-service.ts
+++ b/src/services/custom-nodes/custom-node-project-service.ts
@@ -21,6 +21,10 @@ export interface GeneratedCustomNodeProject {
 }
 
 export class CustomNodeProjectService {
+  generatedRunnerSource(): string {
+    return runnerSource();
+  }
+
   async generate(input: GenerateCustomNodeProjectInput): Promise<GeneratedCustomNodeProject> {
     const nodeId = input.nodeId.trim();
     if (!NODE_ID_PATTERN.test(nodeId)) {
@@ -131,7 +135,16 @@ function sdkSource(): string {
 }
 
 function runnerSource(): string {
-  return `import * as fs from "node:fs/promises";\nimport * as crypto from "node:crypto";\nimport * as path from "node:path";\nimport { run } from "./index.js";\nimport type { Json, JsonObject, NodeExecutionContext } from "./sdk.js";\nconst scratch = "/tmp/codeux"; const chunks: Buffer[] = []; for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));\nconst envelope = JSON.parse(Buffer.concat(chunks).toString("utf8")) as { input: JsonObject; config: JsonObject; correlationId: string; invocationId: string; credentials: Record<string, string>; now: string };\nconst secrets = Object.values(envelope.credentials); const redactText = (value: string): string => { let text = value; for (const secret of secrets) if (secret) text = text.split(secret).join("[REDACTED]"); return text; }; const redactJson = (value: Json): Json => typeof value === "string" ? redactText(value) : Array.isArray(value) ? value.map(redactJson) : value && typeof value === "object" ? Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, redactJson(entry)])) : value;\nconst log = (level: string, message: string, fields?: JsonObject): void => process.stderr.write(JSON.stringify({ level, message: redactText(message), fields: fields ? redactJson(fields) : undefined, correlationId: envelope.correlationId }) + "\\n");\nconst safePath = (value: string): string => { const target = path.resolve(scratch, value); if (target !== scratch && !target.startsWith(scratch + path.sep)) throw new Error("temporary storage path escaped scratch"); return target; };\nconst context: NodeExecutionContext = { input: Object.freeze(envelope.input), config: Object.freeze(envelope.config), correlationId: envelope.correlationId, invocationId: envelope.invocationId, signal: new AbortController().signal, logger: { debug: (m,f) => log("debug",m,f), info: (m,f) => log("info",m,f), warn: (m,f) => log("warn",m,f), error: (m,f) => log("error",m,f) }, clock: { now: () => envelope.now }, http: { request: async () => { throw new Error("HTTP requires the Code UX egress broker and is unavailable in a network-none runner"); } }, credentials: { get: async (slot) => { const value = envelope.credentials[slot]; if (!value) throw new Error("credential slot is unavailable"); return value; } }, temporaryStorage: { read: async (file) => fs.readFile(safePath(file)).catch(() => null), write: async (file, content) => { const target = safePath(file); await fs.mkdir(path.dirname(target), { recursive: true }); await fs.writeFile(target, content); } }, artifacts: { write: async (name, content) => { const target = safePath("artifacts/" + name); await fs.mkdir(path.dirname(target), { recursive: true }); await fs.writeFile(target, content); const bytes = typeof content === "string" ? Buffer.from(content) : content; return { name, digest: "sha256:" + crypto.createHash("sha256").update(bytes).digest("hex"), size: bytes.byteLength }; } } };\ntry { const output = await run(context); process.stdout.write(JSON.stringify(output)); } catch (error) { log("error", error instanceof Error ? error.message : String(error)); process.exitCode = 1; }\n`;
+  return runnerTemplateSource()
+    .replace(
+      'const log = (level: string, message: string, fields?: JsonObject): void => process.stderr.write(JSON.stringify({ level, message: redactText(message), fields: fields ? redactJson(fields) : undefined, correlationId: envelope.correlationId }) + "\\n");',
+      'const log = (level: string, message: string, fields?: JsonObject): void => { process.stderr.write(JSON.stringify({ level, message: redactText(message), fields: fields ? redactJson(fields) : undefined, correlationId: envelope.correlationId }) + "\\n"); };',
+    )
+    .replace('socket.on("data", (chunk) => response.push(chunk));', 'socket.on("data", (chunk) => response.push(Buffer.from(chunk)));');
+}
+
+function runnerTemplateSource(): string {
+  return `import * as fs from "node:fs/promises";\nimport * as crypto from "node:crypto";\nimport * as net from "node:net";\nimport * as path from "node:path";\nimport { run } from "./index.js";\nimport type { Json, JsonObject, NodeExecutionContext } from "./sdk.js";\nconst scratch = "/tmp/codeux"; const chunks: Buffer[] = []; for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));\nconst envelope = JSON.parse(Buffer.concat(chunks).toString("utf8")) as { input: JsonObject; config: JsonObject; correlationId: string; invocationId: string; credentials: Record<string, string>; now: string; egress?: { socketPath: string; token: string } };\nconst secrets = [...Object.values(envelope.credentials), ...(envelope.egress ? [envelope.egress.token] : [])]; const redactText = (value: string): string => { let text = value; for (const secret of secrets) if (secret) text = text.split(secret).join("[REDACTED]"); return text; }; const redactJson = (value: Json): Json => typeof value === "string" ? redactText(value) : Array.isArray(value) ? value.map(redactJson) : value && typeof value === "object" ? Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, redactJson(entry)])) : value;\nconst log = (level: string, message: string, fields?: JsonObject): void => process.stderr.write(JSON.stringify({ level, message: redactText(message), fields: fields ? redactJson(fields) : undefined, correlationId: envelope.correlationId }) + "\\n");\nconst safePath = (value: string): string => { const target = path.resolve(scratch, value); if (target !== scratch && !target.startsWith(scratch + path.sep)) throw new Error("temporary storage path escaped scratch"); return target; };\nconst httpRequest: NodeExecutionContext["http"]["request"] = async (request) => { if (!envelope.egress) throw new Error("network.http capability is not declared"); const responseText = await new Promise<string>((resolve, reject) => { const socket = net.createConnection(envelope.egress!.socketPath); const response: Buffer[] = []; socket.on("connect", () => socket.end(JSON.stringify({ token: envelope.egress!.token, request }))); socket.on("data", (chunk) => response.push(chunk)); socket.on("end", () => resolve(Buffer.concat(response).toString("utf8"))); socket.on("error", reject); }); const result = JSON.parse(responseText) as { ok: boolean; response?: { status: number; headers: Record<string, string>; body: string }; error?: string }; if (!result.ok || !result.response) throw new Error(result.error ?? "HTTP bridge request failed"); return result.response; };\nconst context: NodeExecutionContext = { input: Object.freeze(envelope.input), config: Object.freeze(envelope.config), correlationId: envelope.correlationId, invocationId: envelope.invocationId, signal: new AbortController().signal, logger: { debug: (m,f) => log("debug",m,f), info: (m,f) => log("info",m,f), warn: (m,f) => log("warn",m,f), error: (m,f) => log("error",m,f) }, clock: { now: () => envelope.now }, http: { request: httpRequest }, credentials: { get: async (slot) => { const value = envelope.credentials[slot]; if (!value) throw new Error("credential slot is unavailable"); return value; } }, temporaryStorage: { read: async (file) => fs.readFile(safePath(file)).catch(() => null), write: async (file, content) => { const target = safePath(file); await fs.mkdir(path.dirname(target), { recursive: true }); await fs.writeFile(target, content); } }, artifacts: { write: async (name, content) => { const target = safePath("artifacts/" + name); await fs.mkdir(path.dirname(target), { recursive: true }); await fs.writeFile(target, content); const bytes = typeof content === "string" ? Buffer.from(content) : content; return { name, digest: "sha256:" + crypto.createHash("sha256").update(bytes).digest("hex"), size: bytes.byteLength }; } } };\ntry { const output = await run(context); process.stdout.write(JSON.stringify(output)); } catch (error) { log("error", error instanceof Error ? error.message : String(error)); process.exitCode = 1; }\n`;
 }
 
 export function createCustomNodeDockerfile(): string {
diff --git a/src/services/custom-nodes/custom-node-runtime-service.ts b/src/services/custom-nodes/custom-node-runtime-service.ts
index f184828106..4e2ff2c351 100644
--- a/src/services/custom-nodes/custom-node-runtime-service.ts
+++ b/src/services/custom-nodes/custom-node-runtime-service.ts
@@ -14,6 +14,7 @@ import { DOCKER_DROP_ALL_CAPS_ARGS, DOCKER_NETWORK_NONE_ARGS, DOCKER_NO_NEW_PRIV
 import { runCommandStrict, type CommandResult } from "../cli-process-runner.js";
 import type { CredentialBroker } from "../credentials/credential-broker.js";
 import type { EgressPolicyService } from "../node-flows/egress-policy-service.js";
+import { CUSTOM_NODE_EGRESS_SOCKET_DIRECTORY, CustomNodeEgressBroker } from "./custom-node-egress-broker.js";
 
 export const CUSTOM_NODE_CONTAINER_SCRATCH = "/tmp/codeux";
 
@@ -22,6 +23,7 @@ export interface CustomNodeDockerPlanInput {
   containerName: string;
   seccompProfile?: string;
   appArmorProfile?: string;
+  egressSocketDirectory?: string;
 }
 
 export function buildCustomNodeDockerRunArgs(input: CustomNodeDockerPlanInput): string[] {
@@ -45,6 +47,9 @@ export function buildCustomNodeDockerRunArgs(input: CustomNodeDockerPlanInput):
   ];
   if (input.seccompProfile) args.push("--security-opt", `seccomp=${input.seccompProfile}`);
   if (input.appArmorProfile) args.push("--security-opt", `apparmor=${input.appArmorProfile}`);
+  if (input.egressSocketDirectory) {
+    args.push("--mount", `type=bind,src=${input.egressSocketDirectory},dst=${CUSTOM_NODE_EGRESS_SOCKET_DIRECTORY},readonly`);
+  }
   args.push(input.artifact.runtimeImageDigest);
   return args;
 }
@@ -71,12 +76,23 @@ export class CustomNodeRuntimeService {
       throw new EntityNotFoundError(`Published custom node not found: ${request.nodeType}@${request.version}`);
     }
     const { artifact } = resolved;
-    await this.validateDeclaredEgress(artifact.manifest);
+    const httpPolicy = artifact.manifest.capabilities.includes("network.http")
+      ? requireHttpPolicy(artifact.manifest)
+      : undefined;
     const credentials = await this.resolveCredentials(artifact.manifest, request);
-    const secrets = Object.values(credentials);
     const runDirectory = await fs.mkdtemp(path.join(os.tmpdir(), "code-ux-custom-node-run-"));
+    const egressBroker = httpPolicy
+      ? new CustomNodeEgressBroker({
+        service: this.deps.egressPolicyService,
+        policy: httpPolicy,
+        socketDirectory: path.join(runDirectory, "egress"),
+        rateLimitKey: `${request.projectId}:${request.nodeType}`,
+      })
+      : undefined;
+    const secrets = [...Object.values(credentials), ...(egressBroker ? [egressBroker.token] : [])];
     try {
       if (process.platform !== "win32") await fs.chmod(runDirectory, 0o700);
+      await egressBroker?.start();
       const envelope = {
         input: request.input,
         config: request.config,
@@ -84,6 +100,7 @@ export class CustomNodeRuntimeService {
         invocationId: request.invocationId,
         credentials,
         now: new Date().toISOString(),
+        egress: egressBroker ? { socketPath: egressBroker.containerSocketPath, token: egressBroker.token } : undefined,
       };
       const inputPath = path.join(runDirectory, "input.json");
       await fs.writeFile(inputPath, JSON.stringify(envelope), { mode: 0o600 });
@@ -93,6 +110,7 @@ export class CustomNodeRuntimeService {
         containerName: containerName(request.invocationId),
         seccompProfile: this.deps.seccompProfile,
         appArmorProfile: this.deps.appArmorProfile,
+        egressSocketDirectory: egressBroker ? path.join(runDirectory, "egress") : undefined,
       });
       const runner = this.deps.commandRunner ?? (async (command, args, cwd, options) => runCommandStrict(command, args, cwd, process.env, options));
       const result = await runner("docker", dockerArgs, process.cwd(), {
@@ -115,45 +133,44 @@ export class CustomNodeRuntimeService {
         logs: redactSecrets(result.stderr, secrets),
         diagnostics: JSON.stringify(safeOutput),
       };
+    } catch (error) {
+      throw redactExecutionError(error, secrets);
     } finally {
       for (const key of Object.keys(credentials)) credentials[key] = "";
+      await egressBroker?.close();
       await fs.rm(runDirectory, { recursive: true, force: true });
     }
   }
 
   private async resolveCredentials(manifest: CustomNodeManifest, request: CustomNodeExecutionRequest): Promise<Record<string, string>> {
     const resolved: Record<string, string> = {};
-    for (const slot of manifest.credentials) {
-      const bindingKey = request.credentialBindings[slot.slot];
-      if (!bindingKey) {
-        if (slot.required) throw new ValidationError(`Required custom node credential slot is not bound: ${slot.slot}`);
-        continue;
+    try {
+      for (const slot of manifest.credentials) {
+        const bindingKey = request.credentialBindings[slot.slot];
+        if (!bindingKey) {
+          if (slot.required) throw new ValidationError(`Required custom node credential slot is not bound: ${slot.slot}`);
+          continue;
+        }
+        const credential = await this.deps.credentialBroker.resolveCredentialId({
+          projectId: request.projectId,
+          bindingKey,
+          credentialId: bindingKey,
+          capability: slot.requiredCapability,
+          workspaceId: request.workspaceId,
+        });
+        resolved[slot.slot] = credential.value;
       }
-      const credential = await this.deps.credentialBroker.resolveCredentialId({
-        projectId: request.projectId,
-        bindingKey,
-        credentialId: bindingKey,
-        capability: slot.requiredCapability,
-        workspaceId: request.workspaceId,
-      });
-      resolved[slot.slot] = credential.value;
+      return resolved;
+    } catch (error) {
+      for (const key of Object.keys(resolved)) resolved[key] = "";
+      throw error;
     }
-    return resolved;
   }
+}
 
-  private async validateDeclaredEgress(manifest: CustomNodeManifest): Promise<void> {
-    if (!manifest.capabilities.includes("network.http")) return;
-    if (!manifest.http) throw new ValidationError("Published custom node is missing its bounded HTTP policy.");
-    for (const host of manifest.http.allowedHosts) {
-      await this.deps.egressPolicyService.validateUrl(`https://${host}`, {
-        allowedHosts: manifest.http.allowedHosts,
-        allowedPorts: manifest.http.allowedPorts ?? [443],
-        timeoutMs: manifest.http.timeoutMs,
-        maxResponseBytes: manifest.http.maxResponseBytes,
-        requestsPerMinute: manifest.http.maxRequests,
-      });
-    }
-  }
+function requireHttpPolicy(manifest: CustomNodeManifest): NonNullable<CustomNodeManifest["http"]> {
+  if (!manifest.http) throw new ValidationError("Published custom node is missing its bounded HTTP policy.");
+  return manifest.http;
 }
 
 function containerName(invocationId: string): string {
@@ -184,6 +201,11 @@ export function redactSecrets(value: string, secrets: readonly string[]): string
   return redacted;
 }
 
+function redactExecutionError(error: unknown, secrets: readonly string[]): Error {
+  const message = redactSecrets(error instanceof Error ? error.message : String(error), secrets);
+  return error instanceof ValidationError ? new ValidationError(message) : new Error(message);
+}
+
 function redactJson(value: NodeFlowJsonValue, secrets: readonly string[]): NodeFlowJsonValue {
   if (typeof value === "string") return redactSecrets(value, secrets);
   if (Array.isArray(value)) return value.map((entry) => redactJson(entry, secrets));
diff --git a/tests/backend/services/custom-node-services.test.ts b/tests/backend/services/custom-node-services.test.ts
index 3443ed9751..8c89016b1a 100644
--- a/tests/backend/services/custom-node-services.test.ts
+++ b/tests/backend/services/custom-node-services.test.ts
@@ -2,6 +2,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
+import { createConnection } from "node:net";
 import type { CustomNodeArtifact, CustomNodeManifest, CustomNodeValidationReport } from "../../../src/contracts/custom-node-types.js";
 import { resolveNodeDefinition } from "../../../src/domain/node-flows/node-definition-registry.js";
 import { AppDbStorage } from "../../../src/repositories/app-db-storage.js";
@@ -11,6 +12,7 @@ import { CustomNodeBuildService } from "../../../src/services/custom-nodes/custo
 import { CustomNodeProjectService } from "../../../src/services/custom-nodes/custom-node-project-service.js";
 import { buildCustomNodeDockerRunArgs, CustomNodeRuntimeService } from "../../../src/services/custom-nodes/custom-node-runtime-service.js";
 import type { CommandResult } from "../../../src/services/cli-process-runner.js";
+import { EgressPolicyService } from "../../../src/services/node-flows/egress-policy-service.js";
 
 const temporaryDirectories: string[] = [];
 const result = (stdout = "", stderr = ""): CommandResult => ({ ok: true, code: 0, stdout, stderr });
@@ -54,6 +56,9 @@ describe("custom node project and build services", () => {
     expect(resolveNodeDefinition("custom.fixture-node", 1)?.executionKind).toBe("custom");
     expect(artifact.digest).toBe(validation.artifact?.digest);
     await expect(fs.readFile(path.join(setup.root, ".code-ux", "nodes", "fixture-node", "src", "sdk.ts"), "utf8")).resolves.toContain("NodeExecutionContext");
+    const runner = await fs.readFile(path.join(setup.root, ".code-ux", "nodes", "fixture-node", "src", "runner.ts"), "utf8");
+    expect(runner).toContain("net.createConnection");
+    expect(runner).not.toContain("HTTP requires the Code UX egress broker and is unavailable");
     setup.storage.close();
   });
 
@@ -89,6 +94,20 @@ describe("custom node project and build services", () => {
     expect(commandRunner).not.toHaveBeenCalled();
     setup.storage.close();
   });
+
+  it("rejects a modified generated runner before Docker execution", async () => {
+    const setup = await fixture("runner-tamper");
+    const runnerPath = path.join(setup.root, ".code-ux", "nodes", "runner-tamper", "src", "runner.ts");
+    await fs.appendFile(runnerPath, "\n// untrusted modification\n");
+    const commandRunner = vi.fn(async (): Promise<CommandResult> => result());
+    const validation = await new CustomNodeBuildService({ repository: setup.repository, projectService: setup.projectService, commandRunner })
+      .validateAndBuild({ projectRoot: setup.root, nodeId: "runner-tamper", creator: "test", invocationId: "invocation", correlationId: "correlation" });
+    expect(validation.report.issues).toEqual(expect.arrayContaining([
+      expect.objectContaining({ check: "trusted-build-recipe", message: expect.stringMatching(/trusted generated bridge/i) }),
+    ]));
+    expect(commandRunner).not.toHaveBeenCalled();
+    setup.storage.close();
+  });
 });
 
 describe("custom node Docker plan and runtime security", () => {
@@ -137,8 +156,229 @@ describe("custom node Docker plan and runtime security", () => {
     await expect(runtime.execute({ projectId: setup.projectId, nodeType: "custom.gated-node", version: 1, input: {}, config: {}, credentialBindings: {}, workspaceId: "run", invocationId: "invocation", correlationId: "correlation" })).rejects.toThrow(/feature gate/i);
     setup.storage.close();
   });
+
+  it("bridges declared HTTP through the shared egress policy while retaining network-none isolation", async () => {
+    const fetchMock = vi.fn(async () => new Response("accepted", { status: 200, headers: { "content-type": "text/plain" } }));
+    const scenario = await networkRuntime("allowed-http", fetchMock);
+    const execution = await scenario.execute({ url: "https://api.example.test/jobs" });
+
+    expect(execution.output).toEqual({ status: 200, body: "accepted" });
+    expect(scenario.dockerArgs).toEqual(expect.arrayContaining(["--network", "none", "--mount"]));
+    expect(scenario.dockerArgs.join(" ")).not.toContain("--network bridge");
+    expect(fetchMock).toHaveBeenCalledOnce();
+    scenario.storage.close();
+  });
+
+  it("permits plain HTTP only when the manifest explicitly opts in", async () => {
+    const fetchMock = vi.fn(async () => new Response("accepted", { status: 200, headers: { "content-type": "text/plain" } }));
+    const scenario = await networkRuntime("allowed-plain-http", fetchMock, { allowHttp: true, allowedPorts: [80] });
+    await expect(scenario.execute({ url: "http://api.example.test/jobs" })).resolves.toMatchObject({ output: { status: 200, body: "accepted" } });
+    expect(fetchMock).toHaveBeenCalledOnce();
+    scenario.storage.close();
+  });
+
+  it.each([
+    {
+      name: "SSRF to a loopback address",
+      request: { url: "https://127.0.0.1/data" },
+      policy: { allowedHosts: ["127.0.0.1"] },
+      error: /private|loopback|metadata/i,
+    },
+    {
+      name: "plain HTTP without opt-in",
+      request: { url: "http://api.example.test/data" },
+      policy: { allowedPorts: [80] },
+      error: /HTTPS unless HTTP is explicitly enabled/i,
+    },
+    {
+      name: "a restricted authorization header",
+      request: { url: "https://api.example.test/data", headers: { Authorization: "Bearer secret" } },
+      error: /header is restricted/i,
+    },
+  ])("fails closed for $name", async ({ request, policy, error }) => {
+    const fetchMock = vi.fn(async () => new Response("should not run", { headers: { "content-type": "text/plain" } }));
+    const scenario = await networkRuntime(`blocked-${temporaryDirectories.length}`, fetchMock, policy);
+    await expect(scenario.execute(request)).rejects.toThrow(error);
+    expect(fetchMock).not.toHaveBeenCalled();
+    scenario.storage.close();
+  });
+
+  it("revalidates redirects and rejects a redirect to a private destination", async () => {
+    const fetchMock = vi.fn(async () => new Response(null, { status: 302, headers: { location: "https://127.0.0.1/metadata" } }));
+    const scenario = await networkRuntime("blocked-redirect", fetchMock, { allowedHosts: ["api.example.test", "127.0.0.1"] });
+    await expect(scenario.execute({ url: "https://api.example.test/start" })).rejects.toThrow(/private|loopback|metadata/i);
+    expect(fetchMock).toHaveBeenCalledOnce();
+    scenario.storage.close();
+  });
+
+  it("rejects DNS rebinding before a bridged request reaches the network", async () => {
+    let lookups = 0;
+    const fetchMock = vi.fn(async () => new Response("should not run", { headers: { "content-type": "text/plain" } }));
+    const scenario = await networkRuntime(
+      "blocked-rebinding",
+      fetchMock,
+      {},
+      async () => [{ address: ++lookups === 1 ? "8.8.8.8" : "127.0.0.1", family: 4 }],
+    );
+    await expect(scenario.execute({ url: "https://api.example.test/data" })).rejects.toThrow(/rebinding/i);
+    expect(fetchMock).not.toHaveBeenCalled();
+    scenario.storage.close();
+  });
+
+  it.each([
+    {
+      name: "an oversized response",
+      fetch: async () => new Response("12345", { headers: { "content-type": "text/plain", "content-length": "5" } }),
+      policy: { maxResponseBytes: 4 },
+      error: /size limit/i,
+    },
+    {
+      name: "a disallowed response content type",
+      fetch: async () => new Response("<html>", { headers: { "content-type": "text/html" } }),
+      policy: { allowedContentTypes: ["application/json"] },
+      error: /content type is not allowed/i,
+    },
+  ])("fails closed for $name", async ({ fetch, policy, error }) => {
+    const scenario = await networkRuntime(`response-${temporaryDirectories.length}`, vi.fn(fetch), policy);
+    await expect(scenario.execute({ url: "https://api.example.test/data" })).rejects.toThrow(error);
+    scenario.storage.close();
+  });
+
+  it("propagates request timeouts through the bridge", async () => {
+    const fetchMock = vi.fn(async (_url: string | URL | Request, init?: RequestInit) => new Promise<Response>((_resolve, reject) => {
+      init?.signal?.addEventListener("abort", () => reject(init.signal?.reason), { once: true });
+    }));
+    const scenario = await networkRuntime("timeout-http", fetchMock, { timeoutMs: 5 });
+    await expect(scenario.execute({ url: "https://api.example.test/slow" })).rejects.toThrow(/timed out/i);
+    scenario.storage.close();
+  });
+
+  it("bounds retries and fails closed after the declared retry count", async () => {
+    const fetchMock = vi.fn(async () => { throw new Error("upstream unavailable"); });
+    const scenario = await networkRuntime("retry-http", fetchMock, { maxRetries: 2 });
+    await expect(scenario.execute({ url: "https://api.example.test/jobs" })).rejects.toThrow(/upstream unavailable/i);
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    scenario.storage.close();
+  });
+
+  it("enforces the declared per-minute request rate", async () => {
+    const fetchMock = vi.fn(async () => new Response("ok", { headers: { "content-type": "text/plain" } }));
+    const scenario = await networkRuntime("rate-http", fetchMock, { maxRequests: 1 });
+    await scenario.execute({ url: "https://api.example.test/first" });
+    await expect(scenario.execute({ url: "https://api.example.test/second" })).rejects.toThrow(/rate limit/i);
+    expect(fetchMock).toHaveBeenCalledOnce();
+    scenario.storage.close();
+  });
+
+  it("does not create a broker or mount for undeclared network access", async () => {
+    const setup = await fixture("undeclared-http");
+    const artifact = artifactFixture("undeclared-http", `sha256:${"f".repeat(64)}`, setup.projectId);
+    publishArtifact(setup.repository, artifact);
+    const fetchMock = vi.fn();
+    const commandRunner = vi.fn(async (_command: string, args: string[], _cwd: string, options: { stdinFile?: string }): Promise<CommandResult> => {
+      expect(args).not.toContain("--mount");
+      const envelope = JSON.parse(await fs.readFile(options.stdinFile!, "utf8")) as { egress?: unknown };
+      expect(envelope.egress).toBeUndefined();
+      throw new Error("network.http capability is not declared");
+    });
+    const runtime = new CustomNodeRuntimeService({ repository: setup.repository, credentialBroker: {} as never, egressPolicyService: new EgressPolicyService({ fetch: fetchMock }), featureEnabled: true, commandRunner });
+    await expect(runtime.execute(executionRequest(setup.projectId, "undeclared-http"))).rejects.toThrow(/not declared/i);
+    expect(fetchMock).not.toHaveBeenCalled();
+    setup.storage.close();
+  });
+
+  it("redacts the per-invocation bridge token from outputs, logs, diagnostics, and errors", async () => {
+    const setup = await fixture("bridge-redaction");
+    const artifact = artifactFixture("bridge-redaction", `sha256:${"f".repeat(64)}`, setup.projectId);
+    artifact.manifest.capabilities = ["network.http"];
+    artifact.manifest.http = { allowedHosts: ["api.example.test"], maxRequests: 1, timeoutMs: 1_000, maxResponseBytes: 1_024 };
+    publishArtifact(setup.repository, artifact);
+    let fail = false;
+    const commandRunner = vi.fn(async (_command: string, _args: string[], _cwd: string, options: { stdinFile?: string }): Promise<CommandResult> => {
+      const envelope = JSON.parse(await fs.readFile(options.stdinFile!, "utf8")) as { egress: { token: string } };
+      if (fail) throw new Error(`runner failed with ${envelope.egress.token}`);
+      return result(JSON.stringify({ token: envelope.egress.token }), `log ${envelope.egress.token}`);
+    });
+    const runtime = new CustomNodeRuntimeService({ repository: setup.repository, credentialBroker: {} as never, egressPolicyService: new EgressPolicyService(), featureEnabled: true, commandRunner });
+    const request = executionRequest(setup.projectId, "bridge-redaction");
+    await expect(runtime.execute(request)).resolves.toMatchObject({
+      output: { token: "[REDACTED]" },
+      logs: "log [REDACTED]",
+      diagnostics: "{\"token\":\"[REDACTED]\"}",
+    });
+    fail = true;
+    await expect(runtime.execute({ ...request, invocationId: "invocation-bridge-redaction-error" })).rejects.toThrow("runner failed with [REDACTED]");
+    setup.storage.close();
+  });
 });
 
+type HttpRequestFixture = { url: string; method?: string; headers?: Record<string, string>; body?: string };
+
+async function networkRuntime(
+  nodeId: string,
+  fetchMock: typeof fetch,
+  policyOverrides: Partial<NonNullable<CustomNodeManifest["http"]>> = {},
+  lookup: (hostname: string) => Promise<Array<{ address: string; family: number }>> = async () => [{ address: "8.8.8.8", family: 4 }],
+): Promise<{
+  storage: AppDbStorage;
+  dockerArgs: string[];
+  execute(request: HttpRequestFixture): Promise<Awaited<ReturnType<CustomNodeRuntimeService["execute"]>>>;
+}> {
+  const setup = await fixture(nodeId);
+  const artifact = artifactFixture(nodeId, `sha256:${"f".repeat(64)}`, setup.projectId);
+  artifact.manifest.capabilities = ["network.http"];
+  artifact.manifest.http = {
+    allowedHosts: ["api.example.test"], maxRequests: 10, timeoutMs: 1_000, maxResponseBytes: 1_024,
+    ...policyOverrides,
+  };
+  publishArtifact(setup.repository, artifact);
+  let dockerArgs: string[] = [];
+  const commandRunner = vi.fn(async (_command: string, args: string[], _cwd: string, options: { stdinFile?: string }): Promise<CommandResult> => {
+    dockerArgs = args;
+    const envelope = JSON.parse(await fs.readFile(options.stdinFile!, "utf8")) as { input: { request: HttpRequestFixture }; egress?: { token: string } };
+    if (!envelope.egress) throw new Error("network.http capability is not declared");
+    const mount = args.find((arg) => arg.startsWith("type=bind,src=") && arg.includes(`dst=/run/codeux-egress`));
+    if (!mount) throw new Error("egress socket mount is unavailable");
+    const socketDirectory = mount.slice("type=bind,src=".length, mount.indexOf(",dst="));
+    const bridge = await bridgeRequest(path.join(socketDirectory, "egress.sock"), envelope.egress.token, envelope.input.request);
+    if (!bridge.ok || !bridge.response) throw new Error(bridge.error ?? "HTTP bridge request failed");
+    return result(JSON.stringify({ status: bridge.response.status, body: bridge.response.body }));
+  });
+  const runtime = new CustomNodeRuntimeService({
+    repository: setup.repository,
+    credentialBroker: {} as never,
+    egressPolicyService: new EgressPolicyService({ fetch: fetchMock, lookup }),
+    featureEnabled: true,
+    commandRunner,
+  });
+  return {
+    storage: setup.storage,
+    get dockerArgs() { return dockerArgs; },
+    execute: (request) => runtime.execute({ ...executionRequest(setup.projectId, nodeId), input: { request } }),
+  };
+}
+
+async function bridgeRequest(socketPath: string, token: string, request: HttpRequestFixture): Promise<{ ok: boolean; response?: { status: number; headers: Record<string, string>; body: string }; error?: string }> {
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(socketPath);
+    const chunks: Buffer[] = [];
+    socket.on("connect", () => socket.end(JSON.stringify({ token, request })));
+    socket.on("data", (chunk) => chunks.push(chunk));
+    socket.on("end", () => resolve(JSON.parse(Buffer.concat(chunks).toString("utf8")) as { ok: boolean; response?: { status: number; headers: Record<string, string>; body: string }; error?: string }));
+    socket.on("error", reject);
+  });
+}
+
+function publishArtifact(repository: CustomNodeRepository, artifact: CustomNodeArtifact): void {
+  repository.beginValidation(artifact.nodeId);
+  repository.completeValidation(artifact.nodeId, artifact.validationReport, artifact);
+  repository.publish(artifact.nodeId, "publisher");
+}
+
+function executionRequest(projectId: string, nodeId: string) {
+  return { projectId, nodeType: `custom.${nodeId}`, version: 1, input: {}, config: {}, credentialBindings: {}, workspaceId: "run", invocationId: `invocation-${nodeId}`, correlationId: "correlation" };
+}
+
 function artifactFixture(nodeId: string, runtimeImageDigest: string, projectId = "project"): CustomNodeArtifact {
   const generatedManifest: CustomNodeManifest = {
     schemaVersion: 1, id: nodeId, nodeType: `custom.${nodeId}`, version: 1, name: "Test", description: "",

From 20a38ebc81b04a37710a42269b2bee867cf9c35a Mon Sep 17 00:00:00 2001
From: Code UX <agents@codeux.ai>
Date: Sun, 12 Jul 2026 10:34:02 +0000
Subject: [PATCH 25/25] feat(task T23): implement via codex

---
 dashboard/src/v2/NodesPage.tsx                |  99 +++++++++++++++-
 .../v2/components/nodes/NodeFlowInspector.tsx |  25 +++-
 .../v2/lib/__tests__/agent-preset-api.test.ts |  15 +++
 dashboard/src/v2/lib/agent-preset-api.ts      |   4 +-
 .../docs/user-dashboard-node-flows.mdx        |   4 +
 .../docs/user-dashboard-nodes-canvas.mdx      |   2 +
 .../content/docs/user-dashboard-nodes.mdx     |   2 +
 docs-web/user/dashboard/node-flows.md         |   4 +
 docs-web/user/dashboard/nodes-canvas.md       |   2 +
 docs-web/user/dashboard/nodes.md              |   2 +
 docs/dashboard/node-flows.md                  |   4 +
 docs/dashboard/nodes.md                       |   2 +
 tests/dashboard/v2/nodes-page.test.tsx        | 111 +++++++++++++++++-
 13 files changed, 262 insertions(+), 14 deletions(-)

diff --git a/dashboard/src/v2/NodesPage.tsx b/dashboard/src/v2/NodesPage.tsx
index 4af49b2dd2..6edabbf16d 100644
--- a/dashboard/src/v2/NodesPage.tsx
+++ b/dashboard/src/v2/NodesPage.tsx
@@ -12,13 +12,14 @@ import { NodePalette } from "./components/nodes/NodePalette.js";
 import { NodeGovernancePanel } from "./components/nodes/NodeGovernancePanel.js";
 import { NodeRunDebugger } from "./components/nodes/NodeRunDebugger.js";
 import { useProjectData } from "./context/project-data.js";
-import type { AutomationApprovalRecord, NodeDefinitionManifest, NodeFlowDraftReview, NodeFlowGraph, NodeFlowNode, NodeFlowNodeAttemptRecord, NodeFlowNodeRunRecord, NodeFlowRecord, NodeFlowRunRecord } from "./types.js";
+import type { AgentPreset, AutomationApprovalRecord, NodeDefinitionManifest, NodeFlowDraftReview, NodeFlowGraph, NodeFlowNode, NodeFlowNodeAttemptRecord, NodeFlowNodeRunRecord, NodeFlowRecord, NodeFlowRunRecord, NodeFlowSkillAttachment } from "./types.js";
 import { createDefaultNodeFlowGraph, isNodeFlowDirty, updateNodeInGraph } from "./lib/node-flow-view-models.js";
 import { deserializeNodeCanvasGraphWithMigration, toCanonicalNodeFlowGraph } from "./lib/nodes-canvas-state.js";
+import { fetchAgentPresets } from "./lib/agent-preset-api.js";
 import {
-  cancelNodeFlowRun, compareNodeFlowVersions, createNodeFlowDraft, decideNodeFlowApproval, deleteNodeFlow, dryRunNodeFlowDraft,
+  attachNodeFlowToAgent, cancelNodeFlowRun, compareNodeFlowVersions, createNodeFlowDraft, decideNodeFlowApproval, deleteNodeFlow, detachNodeFlowFromAgent, dryRunNodeFlowDraft,
   fetchNodeDefinition, fetchNodeFlow, fetchNodeFlowApprovals, fetchNodeFlowAttempts, fetchNodeFlowCatalog, fetchNodeFlowNodeRuns,
-  fetchNodeFlowRuns, fetchNodeFlows, patchNodeFlowDraft, publishNodeFlowDraft, requestNodeFlowCredential,
+  fetchNodeFlowAgentSkills, fetchNodeFlowRuns, fetchNodeFlows, patchNodeFlowDraft, publishNodeFlowDraft, requestNodeFlowCredential,
   retryNodeFlowRun, rollbackNodeFlow, runNodeFlow, validateNodeFlowDraft,
   type NodeDefinitionSummary, type NodeFlowDryRunResponse, type NodeFlowVersionDiff,
 } from "./lib/node-flow-api.js";
@@ -31,6 +32,7 @@ export const NodesPage: FunctionComponent = () => {
   const { selectedProject, loading: projectLoading } = useProjectData();
   const projectId = selectedProject?.id ?? null;
   const projectRef = useRef(projectId); projectRef.current = projectId;
+  const flowRef = useRef<string | null>(null);
   const [flows, setFlows] = useState<NodeFlowRecord[]>([]);
   const [catalog, setCatalog] = useState<NodeDefinitionSummary[]>([]);
   const [selectedFlowId, setSelectedFlowId] = useState<string | null>(null);
@@ -48,6 +50,15 @@ export const NodesPage: FunctionComponent = () => {
   const [nodeRuns, setNodeRuns] = useState<NodeFlowNodeRunRecord[]>([]);
   const [attempts, setAttempts] = useState<NodeFlowNodeAttemptRecord[]>([]);
   const [approvals, setApprovals] = useState<AutomationApprovalRecord[]>([]);
+  const [agents, setAgents] = useState<AgentPreset[]>([]);
+  const [attachments, setAttachments] = useState<NodeFlowSkillAttachment[]>([]);
+  const [attachAgentId, setAttachAgentId] = useState("");
+  const [agentsLoading, setAgentsLoading] = useState(false);
+  const [attachmentsLoading, setAttachmentsLoading] = useState(false);
+  const [attachmentBusy, setAttachmentBusy] = useState(false);
+  const [agentsError, setAgentsError] = useState<string | null>(null);
+  const [flowAttachmentError, setFlowAttachmentError] = useState<string | null>(null);
+  const [attachmentMutationError, setAttachmentMutationError] = useState<string | null>(null);
   const [loading, setLoading] = useState(false);
   const [busy, setBusy] = useState(false);
   const [error, setError] = useState<string | null>(null);
@@ -56,6 +67,7 @@ export const NodesPage: FunctionComponent = () => {
   const selectedNode = useMemo(() => graph.nodes.find((node) => node.id === selectedNodeId) ?? null, [graph.nodes, selectedNodeId]);
   const selectedDefinition = selectedNode?.definition ? definitions[`${selectedNode.definition.type}@${selectedNode.definition.version}`] ?? null : null;
   const dirty = isNodeFlowDirty(record, title, description, graph);
+  flowRef.current = record?.id ?? null;
 
   const applyRecord = useCallback((flow: NodeFlowRecord): void => {
     setRecord(flow); setSelectedFlowId(flow.id); setTitle(flow.title); setDescription(flow.description); setGraph(flow.graph);
@@ -88,11 +100,52 @@ export const NodesPage: FunctionComponent = () => {
   }, [applyRecord, selectedFlowId]);
 
   useEffect(() => {
-    setFlows([]); setRecord(null); setSelectedFlowId(null); setRuns([]); setError(null); setNotice(null);
+    setFlows([]); setRecord(null); setSelectedFlowId(null); setRuns([]); setAgents([]); setAttachments([]); setAttachAgentId(""); setAgentsError(null); setFlowAttachmentError(null); setAttachmentMutationError(null); setAttachmentBusy(false); setError(null); setNotice(null);
     if (!projectId) return;
     const controller = new AbortController(); void loadLibrary(projectId, controller.signal); return () => controller.abort();
   }, [projectId]);
 
+  const loadAgents = useCallback(async (nextProjectId: string, signal?: AbortSignal): Promise<void> => {
+    setAgentsLoading(true);
+    setAgentsError(null);
+    try {
+      const nextAgents = await fetchAgentPresets(nextProjectId, signal);
+      if (projectRef.current !== nextProjectId) return;
+      setAgents(nextAgents);
+      setAttachAgentId((current) => nextAgents.some((agent) => agent.id === current) ? current : "");
+    } catch (requestError) {
+      if (!signal?.aborted && projectRef.current === nextProjectId) setAgentsError(`Could not load project agents: ${errorMessage(requestError)}`);
+    } finally {
+      if (!signal?.aborted && projectRef.current === nextProjectId) setAgentsLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    setAgents([]); setAttachAgentId(""); setAgentsLoading(false);
+    if (!projectId) return;
+    const controller = new AbortController(); void loadAgents(projectId, controller.signal); return () => controller.abort();
+  }, [projectId, loadAgents]);
+
+  const loadAttachments = useCallback(async (flowId: string, signal?: AbortSignal): Promise<void> => {
+    setAttachmentsLoading(true);
+    setFlowAttachmentError(null);
+    try {
+      const nextAttachments = await fetchNodeFlowAgentSkills(flowId, signal);
+      if (flowRef.current !== flowId) return;
+      setAttachments(nextAttachments);
+    } catch (requestError) {
+      if (!signal?.aborted && flowRef.current === flowId) setFlowAttachmentError(`Could not load flow attachments: ${errorMessage(requestError)}`);
+    } finally {
+      if (!signal?.aborted && flowRef.current === flowId) setAttachmentsLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    setAttachments([]); setAttachAgentId(""); setAttachmentsLoading(false); setAttachmentBusy(false); setFlowAttachmentError(null); setAttachmentMutationError(null);
+    if (!record) return;
+    const controller = new AbortController(); void loadAttachments(record.id, controller.signal); return () => controller.abort();
+  }, [record?.id, loadAttachments]);
+
   useEffect(() => {
     if (!selectedNode?.definition) return;
     const key = `${selectedNode.definition.type}@${selectedNode.definition.version}`;
@@ -108,6 +161,42 @@ export const NodesPage: FunctionComponent = () => {
   useEffect(() => { if (!selectedRunId) { setNodeRuns([]); setAttempts([]); setApprovals([]); return; } const controller = new AbortController(); void Promise.all([fetchNodeFlowNodeRuns(selectedRunId, controller.signal), fetchNodeFlowAttempts(selectedRunId, controller.signal), fetchNodeFlowApprovals(selectedRunId, controller.signal)]).then(([nodes, history, governed]) => { setNodeRuns(nodes.nodeRuns); setAttempts(history.attempts); setApprovals(governed.approvals); }).catch((requestError) => { if (!controller.signal.aborted) setError(errorMessage(requestError)); }); return () => controller.abort(); }, [selectedRunId]);
 
   const act = async (action: () => Promise<void>): Promise<void> => { setBusy(true); setError(null); setNotice(null); try { await action(); } catch (requestError) { setError(errorMessage(requestError)); } finally { setBusy(false); } };
+  const refreshAttachmentData = (): void => {
+    setAttachmentMutationError(null);
+    if (projectId) void loadAgents(projectId);
+    if (record) void loadAttachments(record.id);
+  };
+  const attachAgent = (): void => {
+    if (!projectId || !record || !attachAgentId || attachmentBusy) return;
+    const mutationProjectId = projectId;
+    const flowId = record.id;
+    const agentPresetId = attachAgentId;
+    setAttachmentBusy(true); setAttachmentMutationError(null);
+    void attachNodeFlowToAgent(flowId, { agentPresetId }).then(async () => {
+      const nextAttachments = await fetchNodeFlowAgentSkills(flowId);
+      if (projectRef.current !== mutationProjectId || flowRef.current !== flowId) return;
+      setAttachments(nextAttachments); setAttachAgentId("");
+    }).catch((requestError) => {
+      if (projectRef.current === mutationProjectId && flowRef.current === flowId) setAttachmentMutationError(`Could not attach agent: ${errorMessage(requestError)}`);
+    }).finally(() => {
+      if (projectRef.current === mutationProjectId && flowRef.current === flowId) setAttachmentBusy(false);
+    });
+  };
+  const detachAgent = (agentPresetId: string): void => {
+    if (!projectId || !record || attachmentBusy) return;
+    const mutationProjectId = projectId;
+    const flowId = record.id;
+    setAttachmentBusy(true); setAttachmentMutationError(null);
+    void detachNodeFlowFromAgent(flowId, agentPresetId).then(async () => {
+      const nextAttachments = await fetchNodeFlowAgentSkills(flowId);
+      if (projectRef.current !== mutationProjectId || flowRef.current !== flowId) return;
+      setAttachments(nextAttachments);
+    }).catch((requestError) => {
+      if (projectRef.current === mutationProjectId && flowRef.current === flowId) setAttachmentMutationError(`Could not detach agent: ${errorMessage(requestError)}`);
+    }).finally(() => {
+      if (projectRef.current === mutationProjectId && flowRef.current === flowId) setAttachmentBusy(false);
+    });
+  };
   const selectFlow = (flowId: string): void => { const flow = flows.find((item) => item.id === flowId); if (!flow || !projectId) return; applyRecord(flow); void validateNodeFlowDraft(projectId, flow.id).then(setReview).catch((requestError) => setError(errorMessage(requestError))); };
   const createFlow = (): void => { if (!projectId) return; void act(async () => { const created = await createNodeFlowDraft(projectId, { title: "Untitled automation", description: "", graph: createDefaultNodeFlowGraph() }); const flow = await fetchNodeFlow(created.flowId); setFlows((current) => [flow, ...current]); applyRecord(flow); setReview(created); setNotice("Draft created in the selected project."); }); };
   const save = (): void => { if (!projectId || !record) return; void act(async () => { const result = await patchNodeFlowDraft(record.id, { projectId, draftRevision: record.version, title, description, graph }); if (result.conflict) { setError(`${result.conflict.message} Current revision is ${result.conflict.actualDraftRevision}.`); return; } const saved = await fetchNodeFlow(record.id); setFlows((current) => current.map((item) => item.id === saved.id ? saved : item)); applyRecord(saved); setReview(result.draft ?? null); setNotice("Draft saved to the canonical flow repository."); }); };
@@ -128,7 +217,7 @@ export const NodesPage: FunctionComponent = () => {
     <div className="flex min-w-0 flex-col gap-4 xl:flex-row"><NodeFlowLibrary flows={flows} selectedFlowId={selectedFlowId} loading={loading} onSelect={selectFlow} onCreate={createFlow} onDelete={(id) => void act(async () => { await deleteNodeFlow(id); await loadLibrary(selectedProject.id); })} />
       <div className="min-w-0 flex-1">{record ? <div className="mb-3 grid gap-3 sm:grid-cols-2"><label className="text-xs font-bold uppercase text-slate-500">Flow name<input className="mt-1 w-full rounded-xl border border-black/[0.08] bg-white/70 px-3 py-2 text-sm normal-case dark:border-white/[0.08] dark:bg-white/[0.04]" value={title} onInput={(event) => setTitle(event.currentTarget.value)} /></label><label className="text-xs font-bold uppercase text-slate-500">Description<input className="mt-1 w-full rounded-xl border border-black/[0.08] bg-white/70 px-3 py-2 text-sm normal-case dark:border-white/[0.08] dark:bg-white/[0.04]" value={description} onInput={(event) => setDescription(event.currentTarget.value)} /></label></div> : null}{record ? <NodeFlowCanvas graph={graph} selectedNodeId={selectedNodeId} onSelectNode={setSelectedNodeId} onMoveNode={(id, position) => setGraph((current) => updateNodeInGraph(current, id, { position }))} /> : <EmptyState icon={<Workflow className="h-7 w-7" />} title="No flows in this project" description="Create a draft to start from the canonical backend workspace." primaryAction={<Button onClick={createFlow}>Create draft</Button>} />}</div>
       <NodePalette definitions={catalog} loading={loading} disabled={!record || busy} onCreateNode={addNode} />
-      {record ? <NodeFlowInspector selectedNode={selectedNode} definition={selectedDefinition} validation={review ? { valid: review.valid, errors: review.validationIssues } : null} requiredCredentials={review?.requiredCredentials.filter((item) => item.nodeId === selectedNode?.id) ?? []} agents={[]} attachments={[]} attachAgentId="" onAttachAgentIdChange={() => undefined} onAttachAgent={() => undefined} onDetachAgent={() => undefined} onNodeChange={(id, update) => setGraph((current) => updateNodeInGraph(current, id, update))} onRequestCredential={(nodeId, slot) => { if (projectId && record) void act(async () => { await requestNodeFlowCredential(projectId, record.id, nodeId, slot); setNotice("Credential binding request recorded; secret material remains outside the graph."); }); }} /> : null}
+      {record ? <NodeFlowInspector selectedNode={selectedNode} definition={selectedDefinition} validation={review ? { valid: review.valid, errors: review.validationIssues } : null} requiredCredentials={review?.requiredCredentials.filter((item) => item.nodeId === selectedNode?.id) ?? []} agents={agents} attachments={attachments} attachAgentId={attachAgentId} attachmentsLoading={agentsLoading || attachmentsLoading} attachmentError={attachmentMutationError ?? flowAttachmentError ?? agentsError} attaching={attachmentBusy} onAttachAgentIdChange={setAttachAgentId} onAttachAgent={attachAgent} onDetachAgent={detachAgent} onRetryAttachments={refreshAttachmentData} onNodeChange={(id, update) => setGraph((current) => updateNodeInGraph(current, id, update))} onRequestCredential={(nodeId, slot) => { if (projectId && record) void act(async () => { await requestNodeFlowCredential(projectId, record.id, nodeId, slot); setNotice("Credential binding request recorded; secret material remains outside the graph."); }); }} /> : null}
     </div>
     {record ? <><NodeGovernancePanel review={review} dryRun={dryRun} diff={diff} busy={busy} onValidate={validate} onDryRun={runDry} onCompare={compare} onPublish={publish} onRollback={rollback} /><NodeRunDebugger runs={runs} selectedRunId={selectedRunId} nodeRuns={nodeRuns} attempts={attempts} approvals={approvals} busy={busy} onSelectRun={setSelectedRunId} onRefresh={() => void act(refreshRuns)} onCancel={() => { const active = runs.find((item) => item.id === selectedRunId); if (projectId && active) void act(async () => { await cancelNodeFlowRun(projectId, active.id); await refreshRuns(); }); }} onRetry={() => { const active = runs.find((item) => item.id === selectedRunId); if (projectId && active) void act(async () => { const result = await retryNodeFlowRun(projectId, active.id); setRuns((current) => [result.run, ...current]); setSelectedRunId(result.run.id); }); }} onApprovalDecision={(approvalId, decision) => void act(async () => { const result = await decideNodeFlowApproval(approvalId, decision); setRuns((current) => current.map((item) => item.id === result.run.id ? result.run : item)); setNodeRuns(result.nodeRuns); setAttempts(result.attempts ?? []); setApprovals((current) => current.map((item) => item.id === approvalId ? { ...item, status: result.status, decidedAt: result.decidedAt, decidedBy: result.decidedBy, decision: result.decision, updatedAt: result.updatedAt } : item)); })} /></> : null}
   </PageContainer>;
diff --git a/dashboard/src/v2/components/nodes/NodeFlowInspector.tsx b/dashboard/src/v2/components/nodes/NodeFlowInspector.tsx
index 2c12419d5c..927ac30772 100644
--- a/dashboard/src/v2/components/nodes/NodeFlowInspector.tsx
+++ b/dashboard/src/v2/components/nodes/NodeFlowInspector.tsx
@@ -23,9 +23,12 @@ interface NodeFlowInspectorProps {
   attachments: NodeFlowSkillAttachment[];
   attachAgentId: string;
   attaching?: boolean;
+  attachmentsLoading?: boolean;
+  attachmentError?: string | null;
   onAttachAgentIdChange: (agentPresetId: string) => void;
   onAttachAgent: () => void;
   onDetachAgent: (agentPresetId: string) => void;
+  onRetryAttachments?: () => void;
   onNodeChange: (nodeId: string, update: Partial<NodeFlowNode>) => void;
   definition?: NodeDefinitionManifest | null;
   requiredCredentials?: NodeFlowRequiredCredential[];
@@ -41,9 +44,12 @@ export const NodeFlowInspector: FunctionComponent<NodeFlowInspectorProps> = ({
   attachments,
   attachAgentId,
   attaching = false,
+  attachmentsLoading = false,
+  attachmentError = null,
   onAttachAgentIdChange,
   onAttachAgent,
   onDetachAgent,
+  onRetryAttachments,
   onNodeChange,
   definition = null,
   requiredCredentials = [],
@@ -133,13 +139,14 @@ export const NodeFlowInspector: FunctionComponent<NodeFlowInspectorProps> = ({
         ))}
       </section>
 
-      <section className="flex flex-col gap-3 border-t border-black/[0.06] pt-4 dark:border-white/[0.06]" aria-labelledby="node-agent-attachments-heading">
+      <section className="flex flex-col gap-3 border-t border-black/[0.06] pt-4 dark:border-white/[0.06]" aria-labelledby="node-agent-attachments-heading" aria-busy={attachmentsLoading || attaching}>
         <h3 id="node-agent-attachments-heading" className="text-xs font-bold uppercase tracking-[0.16em] text-slate-500 dark:text-slate-400">Agent Attachments</h3>
         <div className="flex gap-2">
           <select
             aria-label="Agent preset"
             className={inputClass}
             value={attachAgentId}
+            disabled={attachmentsLoading || attaching}
             onChange={(event) => onAttachAgentIdChange(event.currentTarget.value)}
           >
             <option value="">Select agent</option>
@@ -150,16 +157,23 @@ export const NodeFlowInspector: FunctionComponent<NodeFlowInspectorProps> = ({
           <button
             type="button"
             aria-label="Attach node flow to agent"
-            disabled={!attachAgentId || attaching}
+            disabled={!attachAgentId || attachmentsLoading || attaching}
             onClick={onAttachAgent}
             className="flex h-10 w-10 shrink-0 items-center justify-center rounded-xl bg-signal-500 text-white transition hover:bg-signal-400 focus:outline-none focus-visible:ring-2 focus-visible:ring-signal-500/40 disabled:opacity-50 dark:text-void-900"
           >
             <Link2 className="h-4 w-4" aria-hidden="true" />
           </button>
         </div>
-        {attachments.length === 0 ? (
+        {attachmentsLoading ? <p role="status" className="text-xs leading-relaxed text-slate-500 dark:text-slate-400">Loading agent attachments…</p> : null}
+        {attachmentError ? (
+          <div role="alert" className="rounded-xl border border-status-red/20 bg-status-red/[0.06] p-3 text-xs text-status-red">
+            <p>{attachmentError}</p>
+            {onRetryAttachments ? <button type="button" className="mt-2 font-bold underline focus:outline-none focus-visible:ring-2 focus-visible:ring-signal-500/40" onClick={onRetryAttachments}>Retry attachments</button> : null}
+          </div>
+        ) : null}
+        {!attachmentsLoading && !attachmentError && attachments.length === 0 ? (
           <p className="text-xs leading-relaxed text-slate-500 dark:text-slate-400">No agents attached.</p>
-        ) : (
+        ) : !attachmentsLoading && !attachmentError ? (
           <div className="flex flex-col gap-2">
             {attachments.map((attachment) => {
               const agent = agents.find((entry) => entry.id === attachment.agentPresetId);
@@ -172,6 +186,7 @@ export const NodeFlowInspector: FunctionComponent<NodeFlowInspectorProps> = ({
                   <button
                     type="button"
                     aria-label={`Detach ${agent?.name ?? attachment.agentPresetId}`}
+                    disabled={attaching}
                     className="flex h-8 w-8 items-center justify-center rounded-lg text-slate-400 transition hover:bg-status-red/[0.08] hover:text-status-red focus:outline-none focus-visible:ring-2 focus-visible:ring-signal-500/40"
                     onClick={() => onDetachAgent(attachment.agentPresetId)}
                   >
@@ -181,7 +196,7 @@ export const NodeFlowInspector: FunctionComponent<NodeFlowInspectorProps> = ({
               );
             })}
           </div>
-        )}
+        ) : null}
       </section>
     </aside>
   );
diff --git a/dashboard/src/v2/lib/__tests__/agent-preset-api.test.ts b/dashboard/src/v2/lib/__tests__/agent-preset-api.test.ts
index 7c0ea49890..307d4af85f 100644
--- a/dashboard/src/v2/lib/__tests__/agent-preset-api.test.ts
+++ b/dashboard/src/v2/lib/__tests__/agent-preset-api.test.ts
@@ -2,6 +2,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   applyBaseAgentUpdate,
   createAgentPreset,
+  fetchAgentPresets,
   fetchBaseAgentUpdateNotices,
   pushAgentPresetsToRepository,
   updateAgentPreset,
@@ -62,6 +63,20 @@ describe("createAgentPreset", () => {
   });
 });
 
+describe("fetchAgentPresets", () => {
+  it("forwards the project-transition abort signal", async () => {
+    const controller = new AbortController();
+    vi.mocked(fetchJson).mockResolvedValueOnce([]);
+
+    await expect(fetchAgentPresets("project/one", controller.signal)).resolves.toEqual([]);
+
+    expect(fetchJson).toHaveBeenCalledWith(
+      "/api/projects/project%2Fone/agent-presets",
+      { signal: controller.signal },
+    );
+  });
+});
+
 describe("base-agent updates", () => {
   it("fetches route-aware notices without changing the preset list contract", async () => {
     const notices = [{
diff --git a/dashboard/src/v2/lib/agent-preset-api.ts b/dashboard/src/v2/lib/agent-preset-api.ts
index 5e765760fa..78926338dc 100644
--- a/dashboard/src/v2/lib/agent-preset-api.ts
+++ b/dashboard/src/v2/lib/agent-preset-api.ts
@@ -17,8 +17,8 @@ import type {
 } from "../../../../src/contracts/skill-types.js";
 import { fetchJson } from "../../lib/api/fetch-json.js";
 
-export const fetchAgentPresets = async (projectId: string): Promise<AgentPreset[]> => {
-  return fetchJson<AgentPreset[]>(`/api/projects/${encodeURIComponent(projectId)}/agent-presets`);
+export const fetchAgentPresets = async (projectId: string, signal?: AbortSignal): Promise<AgentPreset[]> => {
+  return fetchJson<AgentPreset[]>(`/api/projects/${encodeURIComponent(projectId)}/agent-presets`, { signal });
 };
 
 export const fetchBaseAgentUpdateNotices = async (projectId: string): Promise<BaseAgentUpdateNotice[]> => {
diff --git a/docs-web/content/docs/user-dashboard-node-flows.mdx b/docs-web/content/docs/user-dashboard-node-flows.mdx
index 2d5946d028..9d41d3fa39 100644
--- a/docs-web/content/docs/user-dashboard-node-flows.mdx
+++ b/docs-web/content/docs/user-dashboard-node-flows.mdx
@@ -36,6 +36,10 @@ Foreach executes the selected downstream branch once per deterministic logical i
 
 ## Agent Attachment
 
+A selected project loads its agent presets, and selecting a flow loads that flow's current bindings. The inspector exposes only agent names and attachment skill metadata; it never renders agent instructions, custom source, credential values, or decrypted material.
+
+Attaching and detaching use the governed node-flow attachment routes, then refresh the selected flow's bindings. Project or flow changes clear the prior selection and visible bindings, abort in-flight reads where possible, and ignore stale responses. Loading, failure, retry, empty, and mutation states remain keyboard accessible. The backend independently enforces project ownership and the attached-flow capability boundary; dashboard state does not grant authorization.
+
 A flow can be attached to a project agent preset as a repeatable skill with a name and description. Detaching removes only that binding; the flow, its graph, schedules, and run history remain in the project.
 
 ## Scheduling
diff --git a/docs-web/content/docs/user-dashboard-nodes-canvas.mdx b/docs-web/content/docs/user-dashboard-nodes-canvas.mdx
index b8325b4b49..d0977cf80f 100644
--- a/docs-web/content/docs/user-dashboard-nodes-canvas.mdx
+++ b/docs-web/content/docs/user-dashboard-nodes-canvas.mdx
@@ -26,6 +26,8 @@ Validated custom definitions can also execute after their immutable artifact and
 
 Credential slots display metadata-only status such as bound, missing, or denied and can submit a binding request. Secret values remain behind the credential broker and are not returned to the graph or browser.
 
+Agent attachments are also metadata-only. The selected project supplies the available preset names, and the selected flow supplies its current skill names and descriptions. Attach and detach refresh that governed backend state; project or flow transitions clear previous bindings and ignore obsolete requests. Agent instructions, custom source, credentials, and decrypted values are never rendered by the attachment controls.
+
 Validation and dry run report graph issues, requested capabilities, credential requirements, side-effect differences, and policy findings. Dry run does not execute nodes. Publication requires the current draft revision, a valid graph and policy review, and all required credentials bound. Published snapshots are immutable; the workspace can compare versions or restore a prior version into a new draft revision.
 
 ## Runs and schedules
diff --git a/docs-web/content/docs/user-dashboard-nodes.mdx b/docs-web/content/docs/user-dashboard-nodes.mdx
index cedf23159d..9b9967ae05 100644
--- a/docs-web/content/docs/user-dashboard-nodes.mdx
+++ b/docs-web/content/docs/user-dashboard-nodes.mdx
@@ -22,6 +22,8 @@ Validation and dry run report structural errors, requested capabilities, credent
 
 The debugger reads persisted flow runs, node runs, attempts, retry decisions, approvals, invocation links, timing, and redacted input and output. Cancellation, safe retry, and approval decisions update the same durable pinned run rather than creating an unrelated execution. Scheduling targets a pinned or latest-published version from the [Scheduler](/docs/user-dashboard-scheduler).
 
+The inspector loads project-owned agent presets and the selected flow's current skill attachments. Attach and detach operations refresh those bindings through the governed backend routes, while project and flow transitions clear stale UI state and cancel or ignore obsolete reads. Only agent and skill metadata is rendered; agent instructions, custom source, credentials, and decrypted values remain outside this surface.
+
 Outside development builds, the workspace requires the Nodes feature flag plus the node-flow backend and automation-security prerequisites. A definition can also require a configured provider, credential broker, allowed egress, approval/outbox services, webhook ingress, or custom-node runtime. Registry presence and feature visibility do not assert that an integration is configured or production-ready.
 
 For the detailed editing contract, see [Nodes Canvas](/docs/user-dashboard-nodes-canvas). For API behavior, publication, execution, and scheduling, see [Node Flows](/docs/user-dashboard-node-flows).
diff --git a/docs-web/user/dashboard/node-flows.md b/docs-web/user/dashboard/node-flows.md
index 8976598cb4..21a2efcbb6 100644
--- a/docs-web/user/dashboard/node-flows.md
+++ b/docs-web/user/dashboard/node-flows.md
@@ -36,6 +36,10 @@ Foreach executes the selected downstream branch once per deterministic logical i
 
 ## Agent Attachment
 
+A selected project loads its agent presets, and selecting a flow loads that flow's current bindings. The inspector exposes only agent names and attachment skill metadata; it never renders agent instructions, custom source, credential values, or decrypted material.
+
+Attaching and detaching use the governed node-flow attachment routes, then refresh the selected flow's bindings. Project or flow changes clear the prior selection and visible bindings, abort in-flight reads where possible, and ignore stale responses. Loading, failure, retry, empty, and mutation states remain keyboard accessible. The backend independently enforces project ownership and the attached-flow capability boundary; dashboard state does not grant authorization.
+
 A flow can be attached to a project agent preset as a repeatable skill with a name and description. Detaching removes only that binding; the flow, its graph, schedules, and run history remain in the project.
 
 ## Scheduling
diff --git a/docs-web/user/dashboard/nodes-canvas.md b/docs-web/user/dashboard/nodes-canvas.md
index d6425dbf6a..243744194a 100644
--- a/docs-web/user/dashboard/nodes-canvas.md
+++ b/docs-web/user/dashboard/nodes-canvas.md
@@ -26,6 +26,8 @@ Validated custom definitions can also execute after their immutable artifact and
 
 Credential slots display metadata-only status such as bound, missing, or denied and can submit a binding request. Secret values remain behind the credential broker and are not returned to the graph or browser.
 
+Agent attachments are also metadata-only. The selected project supplies the available preset names, and the selected flow supplies its current skill names and descriptions. Attach and detach refresh that governed backend state; project or flow transitions clear previous bindings and ignore obsolete requests. Agent instructions, custom source, credentials, and decrypted values are never rendered by the attachment controls.
+
 Validation and dry run report graph issues, requested capabilities, credential requirements, side-effect differences, and policy findings. Dry run does not execute nodes. Publication requires the current draft revision, a valid graph and policy review, and all required credentials bound. Published snapshots are immutable; the workspace can compare versions or restore a prior version into a new draft revision.
 
 ## Runs and schedules
diff --git a/docs-web/user/dashboard/nodes.md b/docs-web/user/dashboard/nodes.md
index 80c4cec3bc..d4022c8f7b 100644
--- a/docs-web/user/dashboard/nodes.md
+++ b/docs-web/user/dashboard/nodes.md
@@ -22,6 +22,8 @@ Validation and dry run report structural errors, requested capabilities, credent
 
 The debugger reads persisted flow runs, node runs, attempts, retry decisions, approvals, invocation links, timing, and redacted input and output. Cancellation, safe retry, and approval decisions update the same durable pinned run rather than creating an unrelated execution. Scheduling targets a pinned or latest-published version from the [Scheduler](./scheduler.md).
 
+The inspector loads project-owned agent presets and the selected flow's current skill attachments. Attach and detach operations refresh those bindings through the governed backend routes, while project and flow transitions clear stale UI state and cancel or ignore obsolete reads. Only agent and skill metadata is rendered; agent instructions, custom source, credentials, and decrypted values remain outside this surface.
+
 Outside development builds, the workspace requires the Nodes feature flag plus the node-flow backend and automation-security prerequisites. A definition can also require a configured provider, credential broker, allowed egress, approval/outbox services, webhook ingress, or custom-node runtime. Registry presence and feature visibility do not assert that an integration is configured or production-ready.
 
 For the detailed editing contract, see [Nodes Canvas](./nodes-canvas.md). For API behavior, publication, execution, and scheduling, see [Node Flows](./node-flows.md).
diff --git a/docs/dashboard/node-flows.md b/docs/dashboard/node-flows.md
index 8ee3bb4e22..1a966a8193 100644
--- a/docs/dashboard/node-flows.md
+++ b/docs/dashboard/node-flows.md
@@ -36,6 +36,10 @@ The run debugger lists durable approvals beside node attempts. A pending item of
 
 ## Agent attachment
 
+A selected project loads its agent presets, and selecting a flow loads that flow's current bindings. The inspector exposes only agent names and attachment skill metadata; it never renders agent instructions, custom source, credential values, or decrypted material.
+
+Attaching and detaching use the governed node-flow attachment routes, then refresh the selected flow's bindings. Project or flow changes clear the prior selection and visible bindings, abort in-flight reads where possible, and ignore stale responses. Loading, failure, retry, empty, and mutation states remain keyboard accessible. The backend independently enforces project ownership and the attached-flow capability boundary; dashboard state does not grant authorization.
+
 A flow can be attached to a project agent preset as a repeatable skill with a name and description. Detaching removes only that binding; the flow, its graph, schedules, and run history remain in the project.
 
 Scheduling is entered through `/scheduler` and targets a pinned or latest-published version. A flow can also be attached to a project agent preset as a reusable skill; removing the attachment does not remove the flow, publications, schedules, or run history.
diff --git a/docs/dashboard/nodes.md b/docs/dashboard/nodes.md
index 675204f44f..491792119b 100644
--- a/docs/dashboard/nodes.md
+++ b/docs/dashboard/nodes.md
@@ -22,6 +22,8 @@ Validation and dry run report structural errors, requested capabilities, credent
 
 The debugger reads persisted flow runs, node runs, attempts, retry decisions, approvals, invocation links, timing, and redacted input and output. Cancellation, safe retry, and approval decisions update the same durable pinned run rather than creating an unrelated execution. Scheduling targets a pinned or latest-published version from the [Scheduler](./scheduler.md).
 
+The inspector loads project-owned agent presets and the selected flow's current skill attachments. Attach and detach operations refresh those bindings through the governed backend routes, while project and flow transitions clear stale UI state and cancel or ignore obsolete reads. Only agent and skill metadata is rendered; agent instructions, custom source, credentials, and decrypted values remain outside this surface.
+
 Outside development builds, the workspace requires the Nodes feature flag plus the node-flow backend and automation-security prerequisites. A definition can also require a configured provider, credential broker, allowed egress, approval/outbox services, webhook ingress, or custom-node runtime. Registry presence and feature visibility do not assert that an integration is configured or production-ready.
 
 For the detailed editing contract, see [Nodes Canvas](./nodes-canvas.md). For API behavior, publication, execution, and scheduling, see [Node Flows Dashboard](./node-flows.md).
diff --git a/tests/dashboard/v2/nodes-page.test.tsx b/tests/dashboard/v2/nodes-page.test.tsx
index e7579cbc71..b193a681ae 100644
--- a/tests/dashboard/v2/nodes-page.test.tsx
+++ b/tests/dashboard/v2/nodes-page.test.tsx
@@ -8,17 +8,21 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { NODES_CANVAS_STORAGE_KEY, NodesPage } from "../../../dashboard/src/v2/NodesPage.js";
 import { ProjectDataContext } from "../../../dashboard/src/v2/context/project-data.js";
 
-const api = vi.hoisted(() => ({ fetchNodeFlows: vi.fn(), fetchNodeFlowCatalog: vi.fn(), createNodeFlowDraft: vi.fn(), fetchNodeFlow: vi.fn(), fetchNodeFlowRuns: vi.fn(), fetchNodeFlowNodeRuns: vi.fn(), fetchNodeFlowAttempts: vi.fn(), fetchNodeFlowApprovals: vi.fn(), decideNodeFlowApproval: vi.fn(), patchNodeFlowDraft: vi.fn(), fetchNodeDefinition: vi.fn(), validateNodeFlowDraft: vi.fn(), deleteNodeFlow: vi.fn() }));
+const api = vi.hoisted(() => ({ fetchNodeFlows: vi.fn(), fetchNodeFlowCatalog: vi.fn(), createNodeFlowDraft: vi.fn(), fetchNodeFlow: vi.fn(), fetchNodeFlowRuns: vi.fn(), fetchNodeFlowNodeRuns: vi.fn(), fetchNodeFlowAttempts: vi.fn(), fetchNodeFlowApprovals: vi.fn(), fetchNodeFlowAgentSkills: vi.fn(), attachNodeFlowToAgent: vi.fn(), detachNodeFlowFromAgent: vi.fn(), decideNodeFlowApproval: vi.fn(), patchNodeFlowDraft: vi.fn(), fetchNodeDefinition: vi.fn(), validateNodeFlowDraft: vi.fn(), deleteNodeFlow: vi.fn() }));
+const agentApi = vi.hoisted(() => ({ fetchAgentPresets: vi.fn() }));
 vi.mock("../../../dashboard/src/v2/lib/node-flow-api.js", async (original) => ({ ...(await original()), ...api }));
+vi.mock("../../../dashboard/src/v2/lib/agent-preset-api.js", async (original) => ({ ...(await original()), ...agentApi }));
 vi.mock("../../../dashboard/src/v2/hooks/use-reduced-motion.js", () => ({ useReducedMotion: () => true, useResolvedMotionDuration: <T,>(value: T): T => value }));
 
 const flow = { id: "flow-1", projectId: "project-1", title: "Release automation", description: "Governed", graph: { schemaVersion: 2 as const, nodes: [{ id: "input-1", type: "input", title: "Input", definition: { type: "input", version: 1 }, position: { x: 40, y: 40 } }], edges: [] }, version: 2, createdAt: "2026-01-01T00:00:00.000Z", updatedAt: "2026-01-01T00:00:00.000Z" };
+const agent = { id: "agent-1", projectId: "project-1", name: "Release Agent", description: "Release helper", instructionMarkdown: "PRIVATE AGENT INSTRUCTIONS", labels: [], sourcePath: null, sourceScope: null, sourceUpdatedAt: null, sourceImportedAt: null, sourceExists: false, syncStatus: "manual", createdAt: "2026-01-01T00:00:00.000Z", updatedAt: "2026-01-01T00:00:00.000Z" };
+const attachment = { flowId: "flow-1", projectId: "project-1", agentPresetId: "agent-1", skillName: "Release skill", description: "Governed", createdAt: "2026-01-01T00:00:00.000Z", updatedAt: "2026-01-01T00:00:00.000Z" };
 const context = { projects: [{ id: "project-1", name: "Test project" }], selectedProjectId: "project-1", selectedProject: { id: "project-1", name: "Test project" }, loading: false, error: null, refreshProjects: async () => undefined, selectProject: async () => undefined, createProject: async () => { throw new Error("unused"); }, updateProject: async () => { throw new Error("unused"); }, deleteProject: async () => undefined };
 
 describe("NodesPage governed workspace", () => {
   const review = { flowId: "flow-1", projectId: "project-1", name: "Release automation", description: "Governed", draftRevision: 2, nodeCount: 1, edgeCount: 0, valid: true, validationIssues: [], policyFindings: [], requiredCredentials: [], requestedCapabilities: [], sideEffectDiffs: [], publishedVersion: 1 };
   beforeEach(() => { api.validateNodeFlowDraft.mockResolvedValue(review); });
-  beforeEach(() => { window.localStorage.clear(); api.fetchNodeFlows.mockResolvedValue({ flows: [flow] }); api.fetchNodeFlowCatalog.mockResolvedValue({ nodes: [{ type: "input", version: 1, executable: true, executionKind: "local", label: "Input", description: "Input", category: "Core", credentials: [], capabilities: [], sideEffect: "none", ports: [] }] }); api.fetchNodeFlowRuns.mockResolvedValue({ runs: [] }); api.fetchNodeFlowNodeRuns.mockResolvedValue({ nodeRuns: [] }); api.fetchNodeFlowAttempts.mockResolvedValue({ attempts: [] }); api.fetchNodeFlowApprovals.mockResolvedValue({ approvals: [] }); api.fetchNodeDefinition.mockResolvedValue({ type: "input", version: 1, executable: true, executionKind: "local", configurationSchema: { type: "object" }, ui: { label: "Input", description: "Input", category: "Core", widgetSchema: { fields: [] } }, ports: [], credentials: [], capabilities: [], sideEffect: "none", defaultPolicy: {}, documentation: "", deprecation: { deprecated: false } }); });
+  beforeEach(() => { window.localStorage.clear(); api.fetchNodeFlows.mockResolvedValue({ flows: [flow] }); api.fetchNodeFlowCatalog.mockResolvedValue({ nodes: [{ type: "input", version: 1, executable: true, executionKind: "local", label: "Input", description: "Input", category: "Core", credentials: [], capabilities: [], sideEffect: "none", ports: [] }] }); api.fetchNodeFlowRuns.mockResolvedValue({ runs: [] }); api.fetchNodeFlowNodeRuns.mockResolvedValue({ nodeRuns: [] }); api.fetchNodeFlowAttempts.mockResolvedValue({ attempts: [] }); api.fetchNodeFlowApprovals.mockResolvedValue({ approvals: [] }); api.fetchNodeFlowAgentSkills.mockResolvedValue([]); api.attachNodeFlowToAgent.mockResolvedValue(attachment); api.detachNodeFlowFromAgent.mockResolvedValue(undefined); agentApi.fetchAgentPresets.mockResolvedValue([agent]); api.fetchNodeDefinition.mockResolvedValue({ type: "input", version: 1, executable: true, executionKind: "local", configurationSchema: { type: "object" }, ui: { label: "Input", description: "Input", category: "Core", widgetSchema: { fields: [] } }, ports: [], credentials: [], capabilities: [], sideEffect: "none", defaultPolicy: {}, documentation: "", deprecation: { deprecated: false } }); });
   afterEach(() => { cleanup(); vi.clearAllMocks(); });
 
   it("loads a project flow library and registry-backed editor", async () => {
@@ -28,6 +32,109 @@ describe("NodesPage governed workspace", () => {
     expect(screen.getByRole("heading", { name: "Node catalog" })).toBeInTheDocument();
     expect(screen.getByText("Run debugger")).toBeInTheDocument();
     expect(api.fetchNodeFlows).toHaveBeenCalledWith("project-1", expect.any(AbortSignal));
+    expect(agentApi.fetchAgentPresets).toHaveBeenCalledWith("project-1", expect.any(AbortSignal));
+    expect(api.fetchNodeFlowAgentSkills).toHaveBeenCalledWith("flow-1", expect.any(AbortSignal));
+  });
+
+  it("loads existing metadata-only flow attachments", async () => {
+    api.fetchNodeFlowAgentSkills.mockResolvedValue([attachment]);
+    render(<ProjectDataContext.Provider value={context as never}><NodesPage /></ProjectDataContext.Provider>);
+
+    expect(await screen.findByText("Release skill")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Detach Release Agent" })).toBeInTheDocument();
+    expect(screen.queryByText("PRIVATE AGENT INSTRUCTIONS")).not.toBeInTheDocument();
+  });
+
+  it("attaches the selected agent from the keyboard and refreshes attachments", async () => {
+    const user = userEvent.setup();
+    let isAttached = false;
+    api.fetchNodeFlowAgentSkills.mockImplementation(async () => isAttached ? [attachment] : []);
+    api.attachNodeFlowToAgent.mockImplementation(async () => { isAttached = true; return attachment; });
+    render(<ProjectDataContext.Provider value={context as never}><NodesPage /></ProjectDataContext.Provider>);
+
+    const select = await screen.findByRole("combobox", { name: "Agent preset" });
+    await waitFor(() => expect(select).toBeEnabled());
+    await user.selectOptions(select, "agent-1");
+    const attachButton = screen.getByRole("button", { name: "Attach node flow to agent" });
+    attachButton.focus();
+    await user.keyboard("{Enter}");
+
+    await waitFor(() => expect(api.attachNodeFlowToAgent).toHaveBeenCalledWith("flow-1", { agentPresetId: "agent-1" }));
+    expect(await screen.findByText("Release skill")).toBeInTheDocument();
+    expect(select).toHaveValue("");
+  });
+
+  it("detaches an existing agent and refreshes the empty state", async () => {
+    const user = userEvent.setup();
+    let isAttached = true;
+    api.fetchNodeFlowAgentSkills.mockImplementation(async () => isAttached ? [attachment] : []);
+    api.detachNodeFlowFromAgent.mockImplementation(async () => { isAttached = false; });
+    render(<ProjectDataContext.Provider value={context as never}><NodesPage /></ProjectDataContext.Provider>);
+
+    const detachButton = await screen.findByRole("button", { name: "Detach Release Agent" });
+    await waitFor(() => expect(detachButton).toBeEnabled());
+    await user.click(detachButton);
+
+    await waitFor(() => expect(api.detachNodeFlowFromAgent).toHaveBeenCalledWith("flow-1", "agent-1"));
+    expect(await screen.findByText("No agents attached.")).toBeInTheDocument();
+  });
+
+  it("clears stale attachment state when the selected project changes", async () => {
+    let firstAgentSignal: AbortSignal | undefined;
+    let firstAttachmentSignal: AbortSignal | undefined;
+    const secondFlow = { ...flow, id: "flow-2", projectId: "project-2", title: "Quality automation" };
+    const secondAgent = { ...agent, id: "agent-2", projectId: "project-2", name: "Quality Agent" };
+    const secondAttachment = { ...attachment, flowId: "flow-2", projectId: "project-2", agentPresetId: "agent-2", skillName: "Quality skill" };
+    api.fetchNodeFlows.mockImplementation(async (projectId: string) => ({ flows: [projectId === "project-1" ? flow : secondFlow] }));
+    agentApi.fetchAgentPresets.mockImplementation(async (projectId: string, signal?: AbortSignal) => {
+      if (projectId === "project-1") firstAgentSignal = signal;
+      return [projectId === "project-1" ? agent : secondAgent];
+    });
+    api.fetchNodeFlowAgentSkills.mockImplementation(async (flowId: string, signal?: AbortSignal) => {
+      if (flowId === "flow-1") firstAttachmentSignal = signal;
+      return [flowId === "flow-1" ? attachment : secondAttachment];
+    });
+    const rendered = render(<ProjectDataContext.Provider value={context as never}><NodesPage /></ProjectDataContext.Provider>);
+    expect(await screen.findByText("Release skill")).toBeInTheDocument();
+
+    const secondContext = { ...context, projects: [{ id: "project-2", name: "Second project" }], selectedProjectId: "project-2", selectedProject: { id: "project-2", name: "Second project" } };
+    rendered.rerender(<ProjectDataContext.Provider value={secondContext as never}><NodesPage /></ProjectDataContext.Provider>);
+
+    expect(await screen.findByText("Quality skill")).toBeInTheDocument();
+    expect(screen.queryByText("Release skill")).not.toBeInTheDocument();
+    expect(screen.getByRole("option", { name: "Quality Agent" })).toBeInTheDocument();
+    expect(firstAgentSignal?.aborted).toBe(true);
+    expect(firstAttachmentSignal?.aborted).toBe(true);
+  });
+
+  it("shows attachment loading and recovers from failed agent API calls", async () => {
+    const user = userEvent.setup();
+    let resolveAttachments: ((value: typeof attachment[]) => void) | undefined;
+    api.fetchNodeFlowAgentSkills.mockReturnValueOnce(new Promise((resolve) => { resolveAttachments = resolve; }));
+    agentApi.fetchAgentPresets.mockRejectedValueOnce(new Error("Agent service unavailable")).mockResolvedValueOnce([agent]);
+    render(<ProjectDataContext.Provider value={context as never}><NodesPage /></ProjectDataContext.Provider>);
+
+    expect(await screen.findByText("Loading agent attachments…")).toBeInTheDocument();
+    resolveAttachments?.([]);
+    expect(await screen.findByRole("alert")).toHaveTextContent("Agent service unavailable");
+    await user.click(screen.getByRole("button", { name: "Retry attachments" }));
+
+    expect(await screen.findByRole("option", { name: "Release Agent" })).toBeInTheDocument();
+    await waitFor(() => expect(screen.queryByText("Agent service unavailable")).not.toBeInTheDocument());
+  });
+
+  it("keeps a failed mutation visible and preserves the selected agent for retry", async () => {
+    const user = userEvent.setup();
+    api.attachNodeFlowToAgent.mockRejectedValueOnce(new Error("Attachment denied"));
+    render(<ProjectDataContext.Provider value={context as never}><NodesPage /></ProjectDataContext.Provider>);
+
+    const select = await screen.findByRole("combobox", { name: "Agent preset" });
+    await waitFor(() => expect(select).toBeEnabled());
+    await user.selectOptions(select, "agent-1");
+    await user.click(screen.getByRole("button", { name: "Attach node flow to agent" }));
+
+    expect(await screen.findByRole("alert")).toHaveTextContent("Attachment denied");
+    expect(select).toHaveValue("agent-1");
   });
 
   it("imports legacy localStorage once and removes it as a source of truth", async () => {