@andorra-labs/code 0.0.0-stage → 0.1.4

package/dist/src/graphs.js

@@ -0,0 +1,1102 @@
+import { mkdir, readFile, readdir, rename, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { configDirectory } from './config.js';
+import { acquireSaveLock, archiveUnpublishedSnapshot, SaveLockBusyError } from './save-lock.js';
+import { validateMappingConstants, validateMappings, validateSchema, validateValue, schemaAt, nodeOutputSchema } from './handoffs.js';
+import { CANONICAL_CODING_TOOLS, canonicalToolName, canonicalizeToolList, toolNameMatches } from './tool-names.js';
+export const GRAPH_TOOLS = [...CANONICAL_CODING_TOOLS, 'NativeExec', 'AsyncProcess', 'PowerShellFast', 'ShellMetrics', 'read_file', 'list_files', 'search_files', 'write_file', 'edit_file', 'read', 'write', 'edit', 'find', 'grep', 'ls', 'powershell', 'bash', 'shell', 'git_read', 'read_artifact', 'write_artifact', 'repo_explore', 'memory_search', 'set_timer', 'pull_request', 'qa.inspect_project', 'qa.status', 'qa.fast', 'qa.deep', 'qa.test', 'qa.terminal', 'qa.security', 'qa.browser', 'qa.browser_session', 'read_skill_resource', 'browser.panel'];
+/** QA tool names are an explicit allowlist; gating keys off membership, never a name prefix. */
+export const QA_TOOL_NAMES = ['qa.inspect_project', 'qa.status', 'qa.fast', 'qa.deep', 'qa.test', 'qa.terminal', 'qa.security', 'qa.browser'];
+export const isQaToolName = (name) => QA_TOOL_NAMES.includes(name);
+export const LEGACY_DEFAULT_HARNESS = {
+    schemaVersion: 1, id: 'default', name: 'Software Engineer', revision: 1, entry: 'engineer',
+    nodes: {
+        engineer: {
+            id: 'engineer', name: 'Software Engineer', type: 'agent', position: { x: 120, y: 120 },
+            prompt: "You are the Software Engineer agent.\nInspect the workspace, implement the user's task, and verify changes with appropriate tools.",
+        },
+        done: { id: 'done', name: 'Done', type: 'end', position: { x: 440, y: 120 } },
+    }, edges: [{ source: 'engineer', target: 'done' }],
+};
+/** The intake role is configuration for the shared executor, not a separate runtime. */
+export function createOrchestratorNode(id = 'orchestrator') {
+    const list = { type: 'array', items: { type: 'string' } };
+    return {
+        id, name: 'Orchestrator', type: 'agent', agentRole: 'orchestrator', executor: 'react-basic',
+        instruction: 'Understand the requested work before delegating implementation. Inspect relevant repository files, components, interfaces, architecture and testing patterns with the available read tools. Ground codebase findings in inspected paths and distinguish evidence from unknowns. Ask the user to clarify requirements, acceptance criteria, design preferences and important tradeoffs before handing work onward; do not infer approval from silence. Summarize the confirmed requirements, design considerations and codebase findings, then produce a concrete task instruction for the next Agent. Research subagents are optional and bounded; use only those that help resolve specific questions. Do not implement or modify the workspace during intake.',
+        capabilities: { filesystem: 'read', shell: 'disabled', git: 'read', github: 'none', browser: 'playwright', deployment: 'none' },
+        tools: ['read_file', 'list_files', 'search_files', 'git_read', 'read_artifact', 'write_artifact', 'repo_explore', 'read_skill_resource', 'qa.browser_session', 'browser.panel'],
+        completion: { mode: 'single', outcome: 'completed' },
+        contextPolicy: { history: true },
+        inputs: { originalTask: '$run.input.task' },
+        inputSchema: { type: 'object', properties: { originalTask: { type: 'string' } }, required: ['originalTask'], additionalProperties: false },
+        outputSchema: { type: 'object', properties: { originalTask: { type: 'string' }, requirements: list, acceptanceCriteria: list, designConsiderations: list, codebaseFindings: list, taskInstruction: { type: 'string' } }, required: ['originalTask', 'requirements', 'acceptanceCriteria', 'designConsiderations', 'codebaseFindings', 'taskInstruction'], additionalProperties: false },
+        subagents: { enabled: true, maxConcurrent: 3, maxTotal: 8, maxDepth: 1, workspace: 'shared-read-only', modelPolicy: 'inherit', toolInheritance: 'restricted', context: 'selected', roles: [
+                { id: 'repository-researcher', name: 'Repository Researcher', instruction: 'Inspect the assigned repository question. Report evidence with file paths, relevant interfaces and test patterns. Do not change files.', outputSchema: { type: 'object', properties: { findings: list, unknowns: list }, required: ['findings'], additionalProperties: false } },
+            ] },
+    };
+}
+export const ORCHESTRATOR_HANDOFF = {
+    originalTask: '$run.input.task', taskInstruction: '$source.output.taskInstruction', requirements: '$source.output.requirements',
+    acceptanceCriteria: '$source.output.acceptanceCriteria', designConsiderations: '$source.output.designConsiderations', codebaseFindings: '$source.output.codebaseFindings',
+};
+/**
+ * Revision 2 of the bundled harness, frozen exactly as it was published.
+ *
+ * A published revision is a promise about behavior, so each one is stored as its own snapshot
+ * rather than rebuilt from the current builders. Were revision 2 derived from
+ * {@link createOrchestratorNode} or from the current harness body, editing either would silently
+ * rewrite history and `loadGraph('default', 2)` would stop describing the graph revision 2 always
+ * described; the revision-1 graph above is frozen the same way. Do not tidy this into a builder,
+ * and publish a new revision rather than editing it.
+ */
+export const DEFAULT_HARNESS_REVISION_2 = {
+    schemaVersion: 3, id: "default", name: "Software Engineer", revision: 2, entry: "orchestrator",
+    nodes: {
+        orchestrator: { "id": "orchestrator", "name": "Orchestrator", "type": "agent", "agentRole": "orchestrator", "executor": "react-basic", "instruction": "Understand the requested work before delegating implementation. Inspect relevant repository files, components, interfaces, architecture and testing patterns with the available read tools. Ground codebase findings in inspected paths and distinguish evidence from unknowns. Ask the user to clarify requirements, acceptance criteria, design preferences and important tradeoffs before handing work onward; do not infer approval from silence. Summarize the confirmed requirements, design considerations and codebase findings, then produce a concrete task instruction for the next Agent. Research subagents are optional and bounded; use only those that help resolve specific questions. Do not implement or modify the workspace during intake.", "capabilities": { "filesystem": "read", "shell": "disabled", "git": "read", "github": "none", "browser": "disabled", "deployment": "none" }, "tools": ["read_file", "list_files", "search_files", "git_read", "read_artifact", "write_artifact", "repo_explore"], "completion": { "mode": "single", "outcome": "completed" }, "contextPolicy": { "history": true }, "inputs": { "originalTask": "$run.input.task" }, "inputSchema": { "type": "object", "properties": { "originalTask": { "type": "string" } }, "required": ["originalTask"], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "originalTask": { "type": "string" }, "requirements": { "type": "array", "items": { "type": "string" } }, "acceptanceCriteria": { "type": "array", "items": { "type": "string" } }, "designConsiderations": { "type": "array", "items": { "type": "string" } }, "codebaseFindings": { "type": "array", "items": { "type": "string" } }, "taskInstruction": { "type": "string" } }, "required": ["originalTask", "requirements", "acceptanceCriteria", "designConsiderations", "codebaseFindings", "taskInstruction"], "additionalProperties": false }, "subagents": { "enabled": true, "maxConcurrent": 3, "maxTotal": 8, "maxDepth": 1, "workspace": "shared-read-only", "modelPolicy": "inherit", "toolInheritance": "restricted", "context": "selected", "roles": [{ "id": "repository-researcher", "name": "Repository Researcher", "instruction": "Inspect the assigned repository question. Report evidence with file paths, relevant interfaces and test patterns. Do not change files.", "tools": ["read_file", "list_files", "search_files", "git_read"], "outputSchema": { "type": "object", "properties": { "findings": { "type": "array", "items": { "type": "string" } }, "unknowns": { "type": "array", "items": { "type": "string" } } }, "required": ["findings"], "additionalProperties": false } }] }, "position": { "x": 100, "y": 120 } },
+        engineer: { "id": "engineer", "name": "Software Engineer", "type": "agent", "executor": "react-basic", "instruction": "Implement the confirmed task instruction completely. Use the supplied requirements, acceptance criteria, design considerations and repository findings to guide the work. Verify the result and report remaining issues.", "position": { "x": 440, "y": 120 } },
+        done: { "id": "done", "name": "Done", "type": "end", "position": { "x": 780, "y": 120 } },
+    },
+    edges: [{ "id": "orchestrator-engineer", "source": "orchestrator", "target": "engineer", "outcome": "completed", "inputMapping": { "originalTask": "$run.input.task", "taskInstruction": "$source.output.taskInstruction", "requirements": "$source.output.requirements", "acceptanceCriteria": "$source.output.acceptanceCriteria", "designConsiderations": "$source.output.designConsiderations", "codebaseFindings": "$source.output.codebaseFindings" } }, { "id": "engineer-done", "source": "engineer", "target": "done", "outcome": "completed" }],
+};
+/**
+ * Frozen revision 3 adds one retry for the Orchestrator to the revision-2 snapshot.
+ *
+ * Intake is read-only and runs many turns, so one transient provider failure must not discard it,
+ * and the retry keeps the user's confirmed clarifications. The Engineer writes to the workspace,
+ * where re-running a finished attempt could repeat side effects, so it stays single-shot; a graph
+ * that wants retries there opts in per node.
+ */
+export const DEFAULT_HARNESS_REVISION_3 = { ...structuredClone(DEFAULT_HARNESS_REVISION_2), revision: 3 };
+DEFAULT_HARNESS_REVISION_3.nodes.orchestrator.retry = { maxAttempts: 2 };
+/** Frozen revision 4 adds skill resources to the published revision-3 snapshot. */
+export const DEFAULT_HARNESS_REVISION_4 = { ...structuredClone(DEFAULT_HARNESS_REVISION_3), revision: 4 };
+DEFAULT_HARNESS_REVISION_4.nodes.orchestrator.tools.push('read_skill_resource');
+/** Revision 5 enables the integrated browser for all default agents. */
+export const DEFAULT_HARNESS = {
+    schemaVersion: 3, id: 'default', name: 'Software Engineer', revision: 5, entry: 'orchestrator',
+    nodes: {
+        orchestrator: { ...createOrchestratorNode(), retry: { maxAttempts: 2 }, position: { x: 100, y: 120 } },
+        engineer: { id: 'engineer', name: 'Software Engineer', type: 'agent', executor: 'react-basic', instruction: 'Implement the confirmed task instruction completely. Use the supplied requirements, acceptance criteria, design considerations and repository findings to guide the work. Verify the result and report remaining issues.', position: { x: 440, y: 120 } },
+        done: { id: 'done', name: 'Done', type: 'end', position: { x: 780, y: 120 } },
+    }, edges: [{ id: 'orchestrator-engineer', source: 'orchestrator', target: 'engineer', outcome: 'completed', inputMapping: structuredClone(ORCHESTRATOR_HANDOFF) }, { id: 'engineer-done', source: 'engineer', target: 'done', outcome: 'completed' }],
+};
+/** Upgrade only in-memory copies. Stored snapshots remain unchanged. */
+/**
+ * `addOrchestrator: false` upgrades a legacy graph without an Orchestrator to the current schema as it
+ * stands, rather than placing an Orchestrator in front of its entry: a free account's graph may not
+ * carry one, and inserting it would leave an eligible graph unsavable.
+ */
+export function migrateGraphForEditor(input, options = {}) {
+    const graph = validateGraphInternal(input);
+    for (const node of Object.values(graph.nodes)) {
+        // Assign only when a list exists: writing back undefined would add a `tools: undefined`
+        // own property, and the editor's round-trip checks compare the copy against loaded
+        // snapshots that never carried the key.
+        if (node.tools)
+            node.tools = canonicalizeToolList(node.tools);
+        if (node.subagents?.roles)
+            for (const role of node.subagents.roles)
+                if (role.tools)
+                    role.tools = canonicalizeToolList(role.tools);
+    }
+    if (graph.schemaVersion === 3)
+        return graph;
+    const existing = Object.values(graph.nodes).filter(node => node.agentRole === 'orchestrator');
+    if (existing.length === 1 && existing[0].id === graph.entry && !graph.edges.some(edge => edge.target === graph.entry)
+        && ['read', 'find', 'grep', 'ls', 'read_file', 'list_files', 'search_files'].some(tool => permitsBuiltInTool(existing[0], tool))) {
+        const intake = existing[0];
+        if (intake.maxIterations !== undefined)
+            intake.maxIterations = Math.max(intake.maxIterations, 3);
+        if (intake.limits?.maxIterations !== undefined)
+            intake.limits.maxIterations = Math.max(intake.limits.maxIterations, 3);
+        if (intake.limits?.maxToolCalls !== undefined)
+            intake.limits.maxToolCalls = Math.max(intake.limits.maxToolCalls, 2);
+        graph.schemaVersion = 3;
+        raiseGraphToolCallsToMinimum(graph);
+        return validateGraph(graph);
+    }
+    if (options.addOrchestrator === false && !existing.length) {
+        graph.schemaVersion = 3;
+        raiseGraphToolCallsToMinimum(graph);
+        return validateGraph(graph);
+    }
+    for (const node of existing) {
+        if (node.maxSubagents !== undefined && node.subagents) {
+            if (node.maxSubagents === 0)
+                node.subagents.enabled = false;
+            else {
+                node.subagents.maxTotal = Math.min(node.subagents.maxTotal ?? 8, node.maxSubagents);
+                node.subagents.maxConcurrent = Math.min(node.subagents.maxConcurrent ?? 3, node.subagents.maxTotal);
+                node.subagents.maxDepth = Math.min(node.subagents.maxDepth ?? 1, node.subagents.maxConcurrent);
+            }
+        }
+        delete node.agentRole;
+        delete node.maxSubagents;
+    }
+    const previousEntry = graph.nodes[graph.entry];
+    let id = 'orchestrator';
+    for (let i = 2; Object.hasOwn(graph.nodes, id); i++)
+        id = `orchestrator-${i}`;
+    const orchestrator = createOrchestratorNode(id);
+    // The promoted intake is built after the canonicalization loop above, and the builder
+    // must keep the frozen legacy spellings for the published revisions. Rewrite this copy
+    // so the editor graph is canonical end to end, and re-migrating it is a no-op.
+    if (orchestrator.tools)
+        orchestrator.tools = canonicalizeToolList(orchestrator.tools);
+    if (orchestrator.subagents?.roles)
+        for (const role of orchestrator.subagents.roles)
+            if (role.tools)
+                role.tools = canonicalizeToolList(role.tools);
+    orchestrator.position = { x: Math.max(-100000, (previousEntry.position?.x ?? 440) - 340), y: previousEntry.position?.y ?? 120 };
+    const inputMapping = Object.fromEntries(Object.entries(ORCHESTRATOR_HANDOFF).filter(([key]) => {
+        if (Object.hasOwn(previousEntry.inputs ?? {}, key))
+            return false;
+        const target = previousEntry.inputSchema?.properties?.[key];
+        if (!target)
+            return previousEntry.inputSchema?.additionalProperties !== false;
+        const source = orchestrator.outputSchema.properties[key];
+        return target.type === source.type && (source.type !== 'array' || !target.items || target.items.type === 'string');
+    }));
+    let edgeId = `${id}-entry`;
+    for (let i = 2; graph.edges.some(edge => edge.id === edgeId); i++)
+        edgeId = `${id}-entry-${i}`;
+    graph.nodes[id] = orchestrator;
+    const bootstrap = previousEntry.type === 'join' && graph.edges.some(edge => edge.target === graph.entry);
+    graph.edges.unshift({ id: edgeId, source: id, target: graph.entry, outcome: 'completed', inputMapping, ...(bootstrap ? { bootstrap: true } : {}) });
+    graph.entry = id;
+    graph.schemaVersion = 3;
+    raiseGraphToolCallsToMinimum(graph);
+    return validateGraph(graph);
+}
+const validId = (value) => typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,79}$/.test(value) && !['constructor', 'prototype', '__proto__'].includes(value);
+/**
+ * Outcome names are author-facing phrases rather than identifiers ("FAILED TESTING"), yet
+ * they still travel through loop exits, edge routing and criteria keys, so single inner
+ * spaces are the only addition over the identifier rules and both ends stay alphanumeric.
+ */
+const validOutcomeName = (value) => typeof value === 'string'
+    && /^[a-zA-Z0-9][a-zA-Z0-9_ -]{0,79}$/.test(value) && !value.endsWith(' ') && !value.includes('  ')
+    && !['constructor', 'prototype', '__proto__'].includes(value);
+const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const fail = (message) => { throw new Error(`Invalid graph: ${message}`); };
+const policies = { filesystem: ['none', 'read', 'read-write'], shell: ['disabled', 'read-only', 'allowed'], git: ['none', 'read', 'write'], github: ['none', 'read', 'pull-request', 'review'], browser: ['disabled', 'playwright'], deployment: ['none', 'allowed'] };
+export function effectiveCapabilities(node) {
+    return node.capabilities ?? { filesystem: 'read-write', shell: 'allowed', git: 'write', github: 'none', browser: 'playwright', deployment: 'none' };
+}
+export function intakeCapabilities(node) {
+    const policy = effectiveCapabilities(node);
+    return { filesystem: policy.filesystem === 'none' ? 'none' : 'read', shell: 'disabled',
+        git: policy.git === 'none' ? 'none' : 'read', github: 'none', browser: policy.browser, deployment: 'none' };
+}
+const canRunCommands = (policy, child) => !child && policy.shell === 'allowed' && policy.filesystem === 'read-write' && policy.git === 'write';
+export function permitsBuiltInTool(node, name, child = false) {
+    if (node.tools !== undefined && !node.tools.some(configured => toolNameMatches(configured, name)))
+        return false;
+    const policy = effectiveCapabilities(node);
+    const canonical = canonicalToolName(name);
+    if (name === 'qa.browser_session')
+        return policy.browser === 'playwright';
+    if (['Read', 'Glob', 'Grep', 'repo_explore', 'read_skill_resource'].includes(canonical))
+        return policy.filesystem !== 'none';
+    if (['Write', 'Edit'].includes(canonical))
+        return policy.filesystem === 'read-write';
+    if (['PowerShell', 'Bash', 'NativeExec', 'AsyncProcess', 'PowerShellFast'].includes(canonical))
+        return canRunCommands(policy, child);
+    if (name === 'ShellMetrics')
+        return policy.filesystem !== 'none';
+    // Every QA tool is part of the command-execution surface: even the read-only
+    // pair only makes sense for nodes that can run the QA pipeline itself.
+    if (isQaToolName(name))
+        return canRunCommands(policy, child);
+    if (name === 'git_read')
+        return policy.git !== 'none';
+    return name === 'read_artifact' || name === 'write_artifact';
+}
+export function capabilitySubset(child, parent) {
+    return Object.keys(policies).every(key => {
+        if (key === 'github' && ['pull-request', 'review'].includes(child[key]))
+            return child[key] === parent[key];
+        const levels = policies[key];
+        return levels.indexOf(child[key]) <= levels.indexOf(parent[key]);
+    });
+}
+export function nodeOutcomes(node) {
+    if (node.type === 'end')
+        return [];
+    if (node.type === 'condition' || node.modifiers?.condition)
+        return ['true', 'false'];
+    if (node.type === 'loop')
+        return ['body', 'done'];
+    if (node.modifiers?.loop?.until.outcome !== undefined)
+        return [node.modifiers.loop.until.outcome];
+    if (node.type === 'approval')
+        return ['approved', 'rejected'];
+    return node.completion?.mode === 'outcomes' ? node.completion.outcomes : [node.completion?.outcome ?? 'completed'];
+}
+function guaranteedGraphInvocations(graph) {
+    const nodes = Object.values(graph.nodes);
+    const routes = (id, outcome) => graph.edges.filter(edge => edge.source === id && (edge.outcome ?? 'completed') === outcome);
+    const loopBodies = new Map();
+    const guarantees = (boundary) => {
+        const guaranteed = new Map(nodes.map(node => [node.id, new Set([node.id])]));
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (const node of nodes) {
+                if (node.id === boundary)
+                    continue;
+                const alternatives = nodeOutcomes(node).map(outcome => {
+                    const reached = new Set();
+                    for (const edge of routes(node.id, outcome))
+                        for (const id of guaranteed.get(edge.target))
+                            reached.add(id);
+                    return reached;
+                });
+                const body = boundary === undefined ? loopBodies.get(node.id) : undefined;
+                const nestedDone = boundary !== undefined && node.type === 'loop' && alternatives[0].has(node.id);
+                const requiredAfter = nestedDone ? alternatives[1] : body ? new Set([
+                    ...body,
+                    ...(body.has(node.id) ? alternatives[1] : []),
+                ]) : new Set([...(alternatives[0] ?? [])].filter(id => alternatives.every(branch => branch.has(id))));
+                const required = guaranteed.get(node.id);
+                for (const id of requiredAfter)
+                    if (!required.has(id)) {
+                        required.add(id);
+                        changed = true;
+                    }
+            }
+        }
+        return guaranteed;
+    };
+    for (const node of nodes.filter(node => node.type === 'loop')) {
+        const local = guarantees(node.id);
+        loopBodies.set(node.id, new Set(routes(node.id, 'body').flatMap(edge => [...local.get(edge.target)])));
+    }
+    const required = guarantees().get(graph.entry);
+    return { required, loopBodies };
+}
+function minimumGraphToolCalls(graph) {
+    const { required, loopBodies } = guaranteedGraphInvocations(graph);
+    const calls = new Map([...required].map(id => [id, graph.nodes[id].agentRole === 'orchestrator' ? 2 : graph.nodes[id].type === 'action' ? 1 : 0]));
+    for (const [loopId, body] of loopBodies) {
+        if (!required.has(loopId) || !body.has(loopId))
+            continue;
+        for (const id of body)
+            if (graph.nodes[id].type === 'action')
+                calls.set(id, Math.max(calls.get(id) ?? 0, graph.nodes[loopId].loop.maxIterations));
+    }
+    return [...calls.values()].reduce((total, count) => total + count, 0);
+}
+/**
+ * Whether a configured tool-call ceiling is at least what the graph needs.
+ *
+ * An absent ceiling means unlimited, so it always satisfies the minimum. Comparing
+ * against the old numeric default instead would read an unset limit as "no budget"
+ * and reject a graph that is in fact unbounded.
+ * @param configured - the graph's explicit ceiling, or undefined when unlimited.
+ * @param minimum - the fewest tool calls the graph provably needs.
+ * @returns whether the graph can afford its guaranteed tool calls.
+ */
+function meetsMinimumToolCalls(configured, minimum) {
+    return configured === undefined || configured >= minimum;
+}
+/**
+ * Raise a graph's explicit tool-call ceiling to the minimum its guaranteed
+ * invocations need. An unlimited graph needs no ceiling, so this is a no-op then.
+ * @param graph - graph being migrated in place.
+ */
+function raiseGraphToolCallsToMinimum(graph) {
+    const configured = graph.limits?.maxToolCalls;
+    if (configured === undefined)
+        return;
+    const minimum = minimumGraphToolCalls(graph);
+    if (configured < minimum)
+        graph.limits = { ...graph.limits, maxToolCalls: minimum };
+}
+function bounds(value, label, max = 1_000_000_000, min = 1) {
+    if (value !== undefined && (!Number.isSafeInteger(value) || value < min || value > max))
+        fail(`${label} must be an integer between ${min} and ${max}`);
+}
+/**
+ * Erase the explicit `0` spelling of an unlimited deadline-shaped bound.
+ *
+ * Internally an absent key is the only spelling of unlimited, so the alias is resolved at the
+ * one boundary where graph JSON enters rather than making every consumer handle two
+ * encodings. A zero tool-call ceiling is untouched: there it genuinely means "no calls".
+ * @param holder - the object owning the limit.
+ * @param key - the limit key to normalize.
+ */
+function normalizeUnlimited(holder, key) {
+    const limits = holder;
+    if (limits[key] === 0)
+        delete limits[key];
+}
+/**
+ * The visit ceiling a graph enforces on each node, or `Infinity` when it enforces none.
+ *
+ * Node visits are unlimited unless a graph says otherwise: the setting's default is `0`, and a
+ * `0` is normalized away, so an absent limit is the single internal spelling of "no ceiling".
+ * @param graph - the graph whose limits apply.
+ * @returns the maximum visits per node, or Infinity when visits are unbounded.
+ */
+export function maxNodeVisitsOf(graph) {
+    const limit = graph.limits?.maxNodeVisits;
+    return limit === undefined || limit === 0 ? Infinity : limit;
+}
+/**
+ * Whether a graph's run is bounded well enough for a return connection to terminate.
+ *
+ * A cycle repeats the same agents until something stops it. Visits are unlimited by default, so
+ * a cycle needs a ceiling of its own: a finite visit count, or the run's wall clock, which
+ * advances whatever the agents do.
+ * @param graph - the validated graph.
+ * @returns whether the graph bounds how long its cycles may run.
+ */
+function hasRunCeiling(graph) {
+    return graph.limits?.maxNodeVisits !== undefined || graph.limits?.wallTimeMs !== undefined;
+}
+function capabilities(value, label) {
+    if (!record(value) || Object.keys(value).length !== Object.keys(policies).length || Object.entries(policies).some(([key, choices]) => !choices.includes(value[key])))
+        fail(`${label}: select a valid permission for each capability`);
+}
+function modelRef(value, label, options) {
+    if (value.provider !== undefined && (typeof value.provider !== 'string' || !/^[\w-]+$/.test(value.provider)))
+        fail(`${label}: provider must be a configured provider id`);
+    if (value.model !== undefined && (typeof value.model !== 'string' || !value.model.trim() || value.model.length > 500))
+        fail(`${label}: model must be a nonempty model reference`);
+    if (options.providers && !options.allowMissingProviders && value.provider && !options.providers.some(p => p.id === value.provider))
+        fail(`${label}: unknown model profile; configure provider ${value.provider} with andorra and open /providers first`);
+}
+function subagentModelRef(value, label, options) {
+    modelRef(value, label, options);
+    if (options.providers && !options.allowMissingProviders && value.model !== undefined && !value.provider)
+        fail(`${label}: select a configured provider profile for this subagent model`);
+    const profile = options.providers?.find(p => p.id === value.provider);
+    if (!options.allowMissingProviders && profile && value.model !== undefined && ![profile.model, ...(profile.models ?? [])].includes(value.model))
+        fail(`${label}: unknown subagent model profile; configure an additional provider profile for model ${value.model} with andorra and open /providers`);
+}
+function objectSchema(schema, label) {
+    validateSchema(schema, label);
+    if (schema.type !== 'object')
+        fail(`${label}: top-level handoff schema must be an object; put arrays or primitive values inside named properties`);
+}
+function validateOrchestratorContracts(node, label) {
+    const check = (schema, fields, side) => {
+        if (!schema)
+            return;
+        for (const [key, type] of Object.entries(fields)) {
+            const field = schema.properties?.[key];
+            if (!field) {
+                if (schema.additionalProperties === false)
+                    fail(`${label}: closed Orchestrator ${side} schema must allow ${key}; declare the field or permit additional properties`);
+                continue;
+            }
+            if (field.type !== type || type === 'array' && field.items !== undefined && field.items.type !== 'string')
+                fail(`${label}: Orchestrator ${side} ${key} must be ${type === 'array' ? 'an array of strings' : 'a string'} to match the intake runtime contract`);
+        }
+    };
+    check(node.inputSchema, { originalTask: 'string' }, 'input');
+    check(node.outputSchema, { originalTask: 'string', taskInstruction: 'string', requirements: 'array', acceptanceCriteria: 'array', designConsiderations: 'array', codebaseFindings: 'array' }, 'output');
+}
+function toolsValid(value, label) {
+    if (value !== undefined && (!Array.isArray(value) || value.some(t => !GRAPH_TOOLS.includes(t)) || new Set(value).size !== value.length))
+        fail(`${label}: tools must be unique supported tool names`);
+}
+export function validateGraph(value, options = {}) { return validateGraphInternal(value, options); }
+/**
+ * Whether a run of this graph can execute the session's own provider/model pair.
+ *
+ * An agent node that omits its provider resolves against the live session pair, so the run's own
+ * adapter is reachable and its metadata has to be resolved. When every agent node names its own
+ * provider, every model call resolves against that node's provider instead — this is the same
+ * predicate the desktop's model-pinning read applies when it hides the session model controls —
+ * and a run of the graph cannot consult the session pair at all. A graph with no agent node leaves
+ * it unused as well.
+ */
+export function graphLeavesNodesToSession(graph) {
+    const agents = Object.values(graph?.nodes ?? {}).filter(node => node.type === 'agent');
+    return agents.length === 0 || agents.some(node => node.provider === undefined);
+}
+function validateGraphInternal(value, options = {}) {
+    if (!record(value))
+        fail('expected an object');
+    validateMappingConstants(value);
+    const graph = structuredClone(value);
+    if (Object.keys(graph).some(k => !['schemaVersion', 'id', 'name', 'revision', 'entry', 'nodes', 'edges', 'metadata', 'limits', 'widgets', 'inputSchema', 'stateSchema'].includes(k)))
+        fail('unsupported graph settings');
+    if (![1, 2, 3].includes(graph.schemaVersion) || !validId(graph.id))
+        fail('schemaVersion must be 1, 2 or 3 and id must be a safe identifier');
+    if (typeof graph.name !== 'string' || !graph.name.trim() || graph.name.length > 200)
+        fail('name must contain 1-200 characters');
+    bounds(graph.revision, 'revision', 1_000_000_000, 0);
+    if (graph.revision === undefined)
+        fail('revision is required');
+    if (!record(graph.nodes) || !Array.isArray(graph.edges))
+        fail('nodes must be a map and edges must be an array');
+    const entries = Object.entries(graph.nodes);
+    const hasOrchestrator = graph.schemaVersion === 3 && entries.some(([, node]) => record(node) && node.type === 'agent' && node.agentRole === 'orchestrator');
+    if (entries.length < 2 || entries.length > (hasOrchestrator ? 101 : 100))
+        fail('include between 2 and 100 nodes (plus the version 3 Orchestrator)');
+    if (!validId(graph.entry) || !Object.hasOwn(graph.nodes, graph.entry))
+        fail('entry must reference an existing node');
+    if (graph.metadata !== undefined) {
+        if (!record(graph.metadata))
+            fail('graph metadata must be an object');
+        // Studio layout data has a dedicated versioned key; metadata.groups was
+        // previously unrestricted extension data and must not be reinterpreted.
+        const groups = graph.metadata.studioLayoutGroupsV1;
+        if (groups !== undefined) {
+            if (!Array.isArray(groups) || groups.length > 50)
+                fail('studioLayoutGroupsV1 must contain at most 50 groups');
+            const groupIds = new Set(), membership = new Set();
+            for (const group of groups) {
+                if (!record(group) || Object.keys(group).some(key => !['id', 'name', 'nodeIds'].includes(key))
+                    || !validId(group.id) || groupIds.has(group.id) || typeof group.name !== 'string'
+                    || !group.name.trim() || group.name.length > 80 || !Array.isArray(group.nodeIds)
+                    || group.nodeIds.length < 1 || group.nodeIds.length > 100)
+                    fail('invalid graph layout group');
+                groupIds.add(group.id);
+                for (const nodeId of group.nodeIds) {
+                    if (typeof nodeId !== 'string' || !Object.hasOwn(graph.nodes, nodeId) || membership.has(nodeId))
+                        fail('layout group refers to an unknown or already grouped node');
+                    membership.add(nodeId);
+                }
+            }
+        }
+    }
+    // A zero tool-call ceiling is valid: it permits a node to complete without tools while
+    // refusing any call. The runtime accepts it, so the validator must too, or a graph the
+    // editor offers to save cannot be saved. A zero wall time, iteration or node-visit ceiling
+    // is a different thing — the explicit spelling of unlimited — and is normalized away below.
+    if (graph.limits !== undefined) {
+        if (!record(graph.limits))
+            fail('limits must be an object');
+        for (const [k, v] of Object.entries(graph.limits)) {
+            if (k === 'maxTokens')
+                continue;
+            if (!['maxNodeVisits', 'maxConcurrency', 'maxToolCalls', 'wallTimeMs'].includes(k))
+                fail(`unsupported graph limit ${k}`);
+            bounds(v, `graph ${k}`, k === 'maxConcurrency' ? 32 : 1_000_000_000, k === 'maxToolCalls' || k === 'wallTimeMs' || k === 'maxNodeVisits' ? 0 : 1);
+        }
+        normalizeUnlimited(graph.limits, 'wallTimeMs');
+        normalizeUnlimited(graph.limits, 'maxNodeVisits');
+    }
+    if (graph.widgets !== undefined) {
+        if (!Array.isArray(graph.widgets) || graph.widgets.length > 5)
+            fail('widgets must be an array of at most 5 widgets');
+        const widgetIds = new Set();
+        for (const [index, widget] of graph.widgets.entries()) {
+            const label = `widget ${index + 1}`;
+            if (!record(widget) || Object.keys(widget).some(k => !['id', 'name', 'description'].includes(k)))
+                fail(`${label}: unsupported widget setting`);
+            if (!validId(widget.id))
+                fail(`${label}: id must be a safe identifier`);
+            if (widgetIds.has(widget.id))
+                fail(`${label}: duplicate widget id ${widget.id}`);
+            widgetIds.add(widget.id);
+            if (typeof widget.name !== 'string' || !widget.name.trim() || widget.name.length > 80)
+                fail(`${label}: provide a name of up to 80 characters`);
+            if (typeof widget.description !== 'string' || !widget.description.trim() || widget.description.length > 1000)
+                fail(`${label}: provide a description of up to 1000 characters`);
+        }
+    }
+    for (const [id, node] of entries) {
+        const label = `node ${id}`;
+        if (!validId(id) || !record(node) || node.id !== id)
+            fail(`${label} must have a matching safe id`);
+        if (Object.keys(node).some(k => !['id', 'name', 'type', 'position', 'agentRole', 'maxSubagents', 'executor', 'instruction', 'systemPrompt', 'prompt', 'provider', 'model', 'tools', 'maxIterations', 'completion', 'capabilities', 'contextPolicy', 'inputs', 'inputSchema', 'outputSchema', 'limits', 'retry', 'subagents', 'join', 'condition', 'loop', 'action', 'modifiers', 'jevEnabled'].includes(k)))
+            fail(`${label}: unsupported node setting`);
+        if (node.jevEnabled !== undefined && (node.type !== 'agent' || typeof node.jevEnabled !== 'boolean'))
+            fail(`${label}: jevEnabled must be a boolean on an Agent node`);
+        if (!['agent', 'end', 'join', 'parallel', 'condition', 'loop', 'action', 'approval'].includes(node.type))
+            fail(`${label}: unsupported node type`);
+        if (typeof node.name !== 'string' || !node.name.trim() || node.name.length > 200)
+            fail(`${label}: provide a name of up to 200 characters`);
+        if (node.position !== undefined && (!record(node.position) || !Number.isFinite(node.position.x) || !Number.isFinite(node.position.y) || Math.abs(node.position.x) > 100000 || Math.abs(node.position.y) > 100000))
+            fail(`${label}: position must contain finite canvas coordinates`);
+        for (const k of ['prompt', 'instruction', 'systemPrompt'])
+            if (node[k] !== undefined && (typeof node[k] !== 'string' || node[k].length > 100000))
+                fail(`${label}: invalid ${k}`);
+        modelRef(node, label, options);
+        toolsValid(node.tools, label);
+        bounds(node.maxIterations, `${label} maxIterations`, 1000, 0);
+        if (node.maxIterations === 0)
+            delete node.maxIterations;
+        if (node.type === 'end' && Object.keys(node).some(k => !['id', 'name', 'type', 'position'].includes(k)))
+            fail(`${label}: End cannot have Agent settings`);
+        if (node.agentRole !== undefined && (node.type !== 'agent' || node.agentRole !== 'orchestrator'))
+            fail(`${label}: only Agent nodes can have the orchestrator role`);
+        if (node.maxSubagents !== undefined) {
+            if (node.agentRole !== 'orchestrator')
+                fail(`${label}: maxSubagents belongs to the Orchestrator role`);
+            bounds(node.maxSubagents, `${label} maxSubagents`, 100, 0);
+        }
+        if (node.subagents !== undefined && node.type !== 'agent')
+            fail(`${label}: subagent policies are only supported on Agent nodes`);
+        if (node.executor !== undefined && node.executor !== 'react-basic')
+            fail(`${label}: select the shared react-basic executor`);
+        if (node.type === 'agent') {
+            node.executor ??= 'react-basic';
+            node.completion ??= { mode: 'single', outcome: 'completed' };
+            node.subagents ??= { enabled: false };
+        }
+        if (node.completion !== undefined) {
+            if (node.type !== 'agent')
+                fail(`${label}: completion policies are only supported on Agent nodes`);
+            const c = node.completion;
+            if (!record(c) || !['single', 'outcomes'].includes(c.mode) || (c.mode === 'single' ? !validOutcomeName(c.outcome) : !Array.isArray(c.outcomes) || !c.outcomes.length || c.outcomes.length > 20 || c.outcomes.some(o => !validOutcomeName(o)) || new Set(c.outcomes).size !== c.outcomes.length))
+                fail(`${label}: outcome names must be unique phrases of 1-80 characters using letters, numbers, single spaces, underscores or hyphens and starting with a letter or number`);
+            if (c.mode === 'outcomes' && c.requireRoutes !== undefined && typeof c.requireRoutes !== 'boolean')
+                fail(`${label}: requireRoutes must be boolean`);
+            if ('criteria' in c && c.criteria !== undefined) {
+                if (c.mode === 'outcomes') {
+                    if (!record(c.criteria))
+                        fail(`${label}: completion criteria must be a mapping for named outcomes`);
+                    else
+                        for (const [outcome, criterion] of Object.entries(c.criteria)) {
+                            if (!c.outcomes.includes(outcome))
+                                fail(`${label}: completion criteria must reference a declared outcome`);
+                            if (typeof criterion !== 'string' || !criterion.trim() || criterion.length > 8000)
+                                fail(`${label}: each completion criterion must contain 1-8000 characters and cannot be blank`);
+                        }
+                }
+                else if (typeof c.criteria !== 'string' || !c.criteria.trim() || c.criteria.length > 8000)
+                    fail(`${label}: completion criteria must contain 1-8000 characters and cannot be blank`);
+            }
+        }
+        if (node.capabilities !== undefined)
+            capabilities(node.capabilities, label);
+        if (node.contextPolicy !== undefined) {
+            const c = node.contextPolicy;
+            if (!record(c) || (c.history !== undefined && typeof c.history !== 'boolean') || (c.predecessors !== undefined && !['none', 'direct', 'all'].includes(c.predecessors)) || (c.conversation !== undefined && !['reuse', 'isolate'].includes(c.conversation)) || (c.skillInheritance !== undefined && !['inherit', 'none'].includes(c.skillInheritance)))
+                fail(`${label}: invalid context policy`);
+            bounds(c.maxChars, `${label} context maxChars`);
+        }
+        if (node.type === 'agent' && graph.schemaVersion === 1)
+            node.contextPolicy = { history: true, ...node.contextPolicy };
+        if (node.inputs !== undefined && !record(node.inputs))
+            fail(`${label}: inputs must be a mapping object`);
+        if (node.inputSchema)
+            objectSchema(node.inputSchema, `${label} inputSchema`);
+        if (node.outputSchema) {
+            objectSchema(node.outputSchema, `${label} outputSchema`);
+            if (['condition', 'approval', 'loop', 'action'].includes(node.type)) {
+                const output = node.type === 'loop' ? { iteration: 1 } : node.type === 'action' ? { result: '' } : {};
+                validateValue(node.outputSchema, output, `${label} outputSchema incompatible with ${node.type} output`);
+            }
+        }
+        if (node.type !== 'agent' && (node.limits !== undefined || node.maxIterations !== undefined))
+            fail(`${label}: node limits are supported only on Agent nodes; remove them and use graph limits (or loop.maxIterations for a Loop)`);
+        if (node.agentRole === 'orchestrator')
+            validateOrchestratorContracts(node, label);
+        // `maxTokens` is accepted but ignored: graphs saved before the cumulative token
+        // ceiling was removed still carry it, and rejecting an unknown key would make those
+        // graphs fail to load instead of simply dropping a setting that no longer applies.
+        if (node.limits !== undefined) {
+            if (!record(node.limits))
+                fail(`${label}: limits must be an object`);
+            for (const [k, v] of Object.entries(node.limits)) {
+                if (k === 'maxTokens')
+                    continue;
+                if (!['maxIterations', 'maxToolCalls', 'wallTimeMs', 'maxContextChars', 'maxCompletionRepairs'].includes(k))
+                    fail(`${label}: unsupported limit ${k}`);
+                const deadlineShaped = k === 'maxIterations' || k === 'wallTimeMs';
+                bounds(v, `${label} ${k}`, k === 'maxIterations' ? 1000 : 1_000_000_000, k === 'maxCompletionRepairs' || k === 'maxToolCalls' || deadlineShaped ? 0 : 1);
+                if (deadlineShaped)
+                    normalizeUnlimited(node.limits, k);
+            }
+        }
+        if (node.retry !== undefined) {
+            if (node.type !== 'agent')
+                fail(`${label}: retry policies are only supported on Agent nodes`);
+            if (!record(node.retry))
+                fail(`${label}: retry must be an object`);
+            bounds(node.retry.maxAttempts, `${label} retry maxAttempts`, 10);
+            if (node.retry.maxAttempts === undefined)
+                fail(`${label}: retry requires maxAttempts`);
+            if (node.retry.fallback !== undefined) {
+                if (!record(node.retry.fallback))
+                    fail(`${label}: invalid fallback`);
+                if ((typeof node.retry.fallback.provider !== 'string' || !/^[\w-]+$/.test(node.retry.fallback.provider)))
+                    fail(`${label}: fallback requires a configured provider id; select a fallback provider`);
+                modelRef(node.retry.fallback, `${label} fallback`, options);
+            }
+        }
+        if (node.modifiers !== undefined) {
+            const rawModifiers = node.modifiers;
+            if (node.type !== 'agent' || node.agentRole === 'orchestrator')
+                fail(`${label}: modifiers require an ordinary Agent`);
+            if (!record(rawModifiers) || Object.keys(rawModifiers).some(key => !['condition', 'loop', 'parallel'].includes(key)))
+                fail(`${label}: unsupported Agent modifier`);
+            const m = node.modifiers;
+            const predicate = (p, name) => {
+                if (!record(p) || typeof p.path !== 'string' || !p.path.trim() || p.path.split('.').some(part => !/^[a-zA-Z0-9_-]+$/.test(part) || ['__proto__', 'constructor', 'prototype'].includes(part)) || !['string', 'number', 'boolean'].includes(typeof p.equals) || typeof p.equals === 'number' && !Number.isFinite(p.equals))
+                    fail(`${label}: ${name} needs an output path and finite scalar comparison`);
+            };
+            if (m.condition !== undefined) {
+                predicate(m.condition, 'Condition');
+                if (Object.keys(m.condition).some(key => !['path', 'equals'].includes(key)))
+                    fail(`${label}: unsupported Condition setting`);
+            }
+            if (m.loop !== undefined) {
+                const l = m.loop;
+                if (!record(l) || Object.keys(l).some(key => !['maxIterations', 'until'].includes(key)) || l.maxIterations === undefined || !record(l.until))
+                    fail(`${label}: Loop needs bounded maxIterations and an exit condition`);
+                bounds(l.maxIterations, `${label} loop maxIterations`, 1000);
+                if (Object.keys(l.until).some(key => !['outcome', 'path', 'equals'].includes(key)))
+                    fail(`${label}: unsupported Loop exit condition`);
+                if (l.until.outcome !== undefined) {
+                    const outcomes = node.completion?.mode === 'outcomes' ? node.completion.outcomes : [node.completion?.outcome ?? 'completed'];
+                    if (l.until.path !== undefined || l.until.equals !== undefined || !outcomes.includes(l.until.outcome))
+                        fail(`${label}: Loop exit must select one declared completion outcome`);
+                }
+                else
+                    predicate(l.until, 'Loop exit');
+            }
+            if (m.parallel !== undefined) {
+                const parallel = m.parallel;
+                if (!record(parallel) || Object.keys(parallel).some(key => !['mode', 'maxConcurrent', 'copies'].includes(key)) || !['branches', 'copies'].includes(parallel.mode) || parallel.maxConcurrent === undefined)
+                    fail(`${label}: Parallel needs a mode and concurrency limit`);
+                bounds(parallel.maxConcurrent, `${label} parallel concurrency`, 32);
+                if (parallel.mode === 'copies') {
+                    if (parallel.copies === undefined)
+                        fail(`${label}: Parallel copies needs a copy count`);
+                    bounds(parallel.copies, `${label} parallel copies`, 100);
+                    const c = effectiveCapabilities(node);
+                    if (c.filesystem === 'read-write' || c.git === 'write' || c.shell === 'allowed' || c.github === 'pull-request' || c.github === 'review' || c.deployment === 'allowed')
+                        fail(`${label}: parallel copies require read-only capabilities in the shared workspace`);
+                }
+                else if (parallel.copies !== undefined)
+                    fail(`${label}: copy count is only supported for parallel copies`);
+            }
+            for (const predicate of [m.condition, m.loop?.until.outcome === undefined ? m.loop?.until : undefined]) {
+                if (!predicate?.path)
+                    continue;
+                const selected = schemaAt(nodeOutputSchema(node), predicate.path.split('.'), `${label} modifier output path`);
+                if (selected)
+                    validateValue(selected, predicate.equals, `${label} modifier comparison`);
+            }
+        }
+        if (node.type === 'join' && (!record(node.join) || !['all', 'any'].includes(node.join.mode)))
+            fail(`${label}: choose Join all or any`);
+        if (node.type === 'condition' && (!record(node.condition) || !Object.hasOwn(graph.nodes, node.condition.source) || typeof node.condition.path !== 'string' || !['string', 'number', 'boolean'].includes(typeof node.condition.equals)))
+            fail(`${label}: Condition needs an existing source, path and comparison value`);
+        if (node.type === 'condition' && typeof node.condition.equals === 'number' && !Number.isFinite(node.condition.equals))
+            fail(`${label}: Condition comparison must be finite; replace NaN or infinity with a finite number`);
+        if (node.type === 'condition') {
+            const c = node.condition;
+            const selected = schemaAt(nodeOutputSchema(graph.nodes[c.source]), c.path.split('.').filter(Boolean), `${label} Condition path`);
+            if (selected)
+                validateValue(selected, c.equals, `${label} Condition comparison`);
+        }
+        if (node.type === 'loop') {
+            if (!record(node.loop) || node.loop.maxIterations === undefined)
+                fail(`${label}: Loop requires bounded maxIterations`);
+            bounds(node.loop.maxIterations, `${label} loop maxIterations`, 1000);
+        }
+        if (node.type === 'action' && (!record(node.action) || !['command', 'tests', 'git'].includes(node.action.kind) || typeof node.action.command !== 'string' || !node.action.command.trim()))
+            fail(`${label}: Action requires a kind and command`);
+        if (node.subagents !== undefined) {
+            const s = node.subagents;
+            if (!record(s) || typeof s.enabled !== 'boolean')
+                fail(`${label}: subagents.enabled must be boolean`);
+            // The two subagent token budgets are accepted but ignored for the same reason as
+            // node maxTokens: previously saved graphs must keep loading.
+            for (const key of Object.keys(s)) {
+                if (key === 'maxTokensPerSubagent' || key === 'maxCombinedTokens')
+                    continue;
+                if (!['enabled', 'maxConcurrent', 'maxTotal', 'maxDepth', 'modelPolicy', 'provider', 'model', 'workspace', 'toolInheritance', 'context', 'maxWallTimeMs', 'roles'].includes(key))
+                    fail(`${label}: unsupported subagent setting ${key}; use a supported SubagentPolicy field`);
+            }
+            bounds(s.maxConcurrent, `${label} subagent concurrency`, 16);
+            bounds(s.maxTotal, `${label} subagent maxTotal`, 1000);
+            bounds(s.maxDepth, `${label} subagent maxDepth`, 3);
+            bounds(s.maxWallTimeMs, `${label} maxWallTimeMs`);
+            for (const [k, values] of Object.entries({ modelPolicy: ['inherit', 'specific', 'per-role'], workspace: ['shared-read-only', 'shared-write', 'worktree'], toolInheritance: ['restricted', 'inherit'], context: ['selected', 'task-only'] }))
+                if (s[k] !== undefined && !values.includes(s[k]))
+                    fail(`${label}: invalid subagent ${k}`);
+            subagentModelRef({ ...s, provider: s.provider ?? node.provider ?? options.defaultProvider }, `${label} subagent`, options);
+            const spawningEnabled = s.enabled && node.maxSubagents !== 0;
+            if (spawningEnabled && options.spawnAvailable === false)
+                fail(`${label}: runtime lacks spawn capability; enable spawn_subagent or disable subagents`);
+            if (spawningEnabled && s.modelPolicy === 'specific' && !s.provider)
+                fail(`${label}: select a specific subagent model profile`);
+            if (spawningEnabled && (s.maxDepth ?? 1) > (s.maxConcurrent ?? 3))
+                fail(`${label}: subagent maxDepth cannot exceed maxConcurrent; increase concurrent slots or reduce nesting depth`);
+            if ((s.maxConcurrent ?? 3) > (s.maxTotal ?? 8))
+                fail(`${label}: subagent concurrency cannot exceed maxTotal`);
+            if (s.roles !== undefined && !Array.isArray(s.roles))
+                fail(`${label}: subagent roles must be an array`);
+            const ids = new Set();
+            for (const r of s.roles ?? []) {
+                if (!record(r) || !validId(r.id) || ids.has(r.id) || typeof r.name !== 'string' || !r.name.trim() || typeof r.instruction !== 'string' || !r.instruction.trim())
+                    fail(`${label}: each subagent role needs a unique safe id, name and instruction`);
+                for (const key of Object.keys(r))
+                    if (!['id', 'name', 'instruction', 'provider', 'model', 'capabilities', 'tools', 'inputSchema', 'outputSchema'].includes(key))
+                        fail(`${label}: unsupported subagent role setting ${key}; use a supported SubagentRole field (for permissions use capabilities)`);
+                ids.add(r.id);
+                if (r.inputSchema)
+                    objectSchema(r.inputSchema, `${label} role inputSchema`);
+                if (r.outputSchema)
+                    objectSchema(r.outputSchema, `${label} role outputSchema`);
+                subagentModelRef({ ...r, provider: r.provider ?? node.provider ?? options.defaultProvider }, `${label} role ${r.id}`, options);
+                toolsValid(r.tools, `${label} role ${r.id}`);
+                if (s.context === 'task-only' && r.inputSchema?.required?.length)
+                    fail(`${label}: task-only context cannot supply required inputs for role ${r.id}; select selected context or make the role inputs optional`);
+                if (r.capabilities)
+                    capabilities(r.capabilities, `${label} role ${r.id}`);
+                const parent = node.agentRole === 'orchestrator' && spawningEnabled ? intakeCapabilities(node) : effectiveCapabilities(node);
+                const child = r.capabilities ?? { ...parent, ...((s.workspace ?? 'shared-read-only') === 'shared-read-only' ? { filesystem: parent.filesystem === 'none' ? 'none' : 'read', git: parent.git === 'none' ? 'none' : 'read', shell: 'disabled' } : {}) };
+                if (!capabilitySubset(child, parent))
+                    fail(`${label}: role ${r.id} capability exceeds parent${node.agentRole === 'orchestrator' ? ' intake read-only ceiling; reduce child permissions' : '; reduce child permissions or explicitly grant them to the parent'}`);
+                if (r.tools?.some(t => !permitsBuiltInTool({ ...node, capabilities: parent }, t)))
+                    fail(`${label}: role ${r.id} tools exceed effective parent capabilities; reduce its tools or explicitly grant parent permissions`);
+                if (r.tools?.some(t => !permitsBuiltInTool({ capabilities: child }, t, true)))
+                    fail(`${label}: role ${r.id} tools exceed its child capabilities; remove unavailable tools (subagents cannot use the host shell)`);
+                const writes = child.filesystem === 'read-write' || child.git === 'write';
+                if (spawningEnabled && s.workspace === 'worktree' && writes && parent.git !== 'write')
+                    fail(`${label}: writing worktree role ${r.id} requires parent Git write access; grant Git write or select a read-only role`);
+                if (spawningEnabled && (s.workspace ?? 'shared-read-only') === 'shared-read-only' && writes)
+                    fail(`${label}: shared read-only subagents cannot write files or Git; reduce role permissions or select a writable workspace`);
+                if (spawningEnabled && (s.workspace ?? 'shared-read-only') === 'shared-write' && (s.maxConcurrent ?? 3) > 1 && writes)
+                    fail(`${label}: concurrent writing subagents require separate worktrees; select worktree or maxConcurrent 1`);
+            }
+            if (spawningEnabled && (s.workspace ?? 'shared-read-only') === 'shared-write' && (s.maxConcurrent ?? 3) > 1 && !s.roles?.length)
+                fail(`${label}: concurrent writing subagents require separate worktrees or maxConcurrent 1`);
+        }
+    }
+    if (graph.metadata !== undefined && (!record(graph.metadata) || (graph.metadata.description !== undefined && (typeof graph.metadata.description !== 'string' || graph.metadata.description.length > 2000)) || (graph.metadata.updatedAt !== undefined && typeof graph.metadata.updatedAt !== 'string')))
+        fail('invalid metadata');
+    const ids = new Set(), pairs = new Set();
+    const outgoing = new Map(), incoming = new Map();
+    for (const [i, edge] of graph.edges.entries()) {
+        if (!record(edge) || !validId(edge.source) || !validId(edge.target) || !Object.hasOwn(graph.nodes, edge.source) || !Object.hasOwn(graph.nodes, edge.target))
+            fail('every edge must connect existing nodes');
+        if (Object.keys(edge).some(k => !['id', 'source', 'target', 'outcome', 'toInput', 'inputMapping', 'bootstrap'].includes(k)))
+            fail('unsupported edge setting; use outcome for named completion routing');
+        edge.id ??= `edge-${i + 1}`;
+        edge.outcome ??= 'completed';
+        if (!validId(edge.id) || ids.has(edge.id))
+            fail('duplicate/invalid edge id; assign a unique safe identifier');
+        ids.add(edge.id);
+        if (!nodeOutcomes(graph.nodes[edge.source]).includes(edge.outcome))
+            fail(`edge ${edge.id}: nonexistent outcome ${edge.outcome}; select a declared output port`);
+        if (edge.toInput !== undefined && !validId(edge.toInput))
+            fail(`edge ${edge.id}: invalid target input name`);
+        if (edge.bootstrap !== undefined && (edge.bootstrap !== true || graph.schemaVersion !== 3 || edge.source !== graph.entry || graph.nodes[edge.source].agentRole !== 'orchestrator' || graph.nodes[edge.target].type !== 'join' || graph.edges.filter(candidate => candidate.bootstrap === true).length !== 1 || !graph.edges.some(candidate => candidate !== edge && candidate.target === edge.target && candidate.bootstrap !== true)))
+            fail(`edge ${edge.id}: bootstrap must be the single version 3 Orchestrator-entry route to a Join with existing cyclic incoming branches`);
+        const pair = JSON.stringify([edge.source, edge.outcome, edge.target]);
+        if (pairs.has(pair))
+            fail(`duplicate edge ${edge.id}; remove the repeated connection (toInput does not create a separate runtime route)`);
+        pairs.add(pair);
+        outgoing.set(edge.source, [...(outgoing.get(edge.source) ?? []), edge]);
+        incoming.set(edge.target, [...(incoming.get(edge.target) ?? []), edge]);
+    }
+    const visited = new Set(), active = new Set();
+    function walk(id) { if (active.has(id)) {
+        if (!hasRunCeiling(graph))
+            fail('unlimited graph cycle; set graph limits.maxNodeVisits to a finite number of visits, or graph limits.wallTimeMs to a finite duration');
+        return;
+    } if (visited.has(id))
+        return; visited.add(id); active.add(id); for (const e of outgoing.get(id) ?? [])
+        walk(e.target); active.delete(id); }
+    walk(graph.entry);
+    for (const edge of graph.edges.filter(edge => edge.bootstrap)) {
+        const reachable = new Set();
+        const visit = (id) => {
+            if (reachable.has(id))
+                return;
+            reachable.add(id);
+            for (const next of outgoing.get(id) ?? [])
+                if (!next.bootstrap)
+                    visit(next.target);
+        };
+        visit(edge.target);
+        if (graph.edges.some(branch => branch.target === edge.target && !branch.bootstrap && !reachable.has(branch.source)))
+            fail(`edge ${edge.id}: bootstrap requires every ordinary incoming branch to cycle back from this Join; remove bootstrap for acyclic dependencies`);
+        if (graph.nodes[edge.target].join?.mode === 'all' && (incoming.get(edge.target) ?? []).filter(branch => !branch.bootstrap).length > 1)
+            fail(`Join ${edge.target}: bootstrap Join all supports only one ordinary cyclic incoming branch; use Join any or a single return branch`);
+    }
+    if (visited.size !== entries.length)
+        fail('all nodes must be reachable from the entry; connect or remove disconnected nodes');
+    if (!entries.some(([, n]) => n.type === 'end'))
+        fail('include an End node');
+    const canReach = (start, target, blocked, seen = new Set()) => {
+        if (start === blocked || seen.has(start))
+            return false;
+        if (start === target)
+            return true;
+        seen.add(start);
+        return (outgoing.get(start) ?? []).some(edge => canReach(edge.target, target, blocked, seen));
+    };
+    const { required: guaranteedNodes, loopBodies } = guaranteedGraphInvocations(graph);
+    for (const [id, node] of entries) {
+        if (node.modifiers?.parallel?.mode === 'branches') {
+            for (const edge of outgoing.get(id) ?? []) {
+                const target = graph.nodes[edge.target];
+                if (target.type !== 'agent' || target.agentRole === 'orchestrator')
+                    fail(`Agent ${id}: Parallel branches must connect directly to ordinary Agents; connect an End after those Agents`);
+                if (node.modifiers.parallel.maxConcurrent > 1) {
+                    const c = effectiveCapabilities(target);
+                    if (c.filesystem === 'read-write' || c.git === 'write' || c.shell === 'allowed' || c.github === 'pull-request' || c.github === 'review' || c.deployment === 'allowed')
+                        fail(`Agent ${id}: parallel branch target ${edge.target} requires read-only capabilities in the shared workspace; reduce target permissions or set maxConcurrent to 1`);
+                }
+            }
+        }
+        if (node.type === 'loop' && (outgoing.get(id) ?? []).some(edge => edge.outcome === 'body' && canReach(edge.target, id))) {
+            let entriesRequired = 1;
+            for (const [outerId, body] of loopBodies) {
+                if (outerId !== id && guaranteedNodes.has(outerId) && body.has(outerId) && body.has(id))
+                    entriesRequired = Math.max(entriesRequired, graph.nodes[outerId].loop.maxIterations);
+            }
+            const minimumVisits = node.loop.maxIterations + entriesRequired;
+            // An unlimited visit budget can always reach the done outcome, so the check is about a
+            // finite cap that is too small to get there.
+            if (maxNodeVisitsOf(graph) < minimumVisits)
+                fail(`Loop ${id}: set graph limits.maxNodeVisits to at least ${minimumVisits} so the body cycle and enclosing reentries can return for the done outcome`);
+        }
+        if (node.type === 'condition' && (node.condition.source === id || canReach(graph.entry, id, node.condition.source)))
+            fail(`Condition ${id}: source ${node.condition.source} must execute on every path before this condition; route through the source first`);
+        for (const outcome of nodeOutcomes(node))
+            if (!(node.completion?.mode === 'outcomes' && node.completion.requireRoutes === false) && !(outgoing.get(id) ?? []).some(e => e.outcome === outcome))
+                fail(`node ${id}: required outcome ${outcome} has no route; connect its output port`);
+        if (node.type === 'join' && node.join?.mode === 'all') {
+            const edges = (incoming.get(id) ?? []).filter(edge => !edge.bootstrap);
+            if (!edges.length)
+                fail(`Join ${id} needs an incoming branch`);
+            // Like bootstrap entry, direct entry skips the first barrier. Each cyclic
+            // return then advances its own generation, so multiple returns cannot join.
+            if (graph.schemaVersion === 3 && graph.entry === id && edges.length > 1)
+                fail(`Join ${id}: direct-start Join all supports only one ordinary cyclic incoming branch; use Join any or a single return branch`);
+            if (graph.schemaVersion === 3 && edges.some(edge => canReach(graph.entry, edge.source, id)) && edges.some(edge => canReach(id, edge.source)))
+                fail(`Join ${id}: cyclic entry dependencies require a bootstrap edge from the Orchestrator; use bootstrap only when every other incoming branch cycles back from this Join`);
+            for (const edge of edges)
+                if (edges.some(other => other.source === edge.source && other.outcome !== edge.outcome))
+                    fail(`Join ${id} waits on impossible exclusive outcomes; use Join any or join independent branches`);
+            for (const [loopId, loopNode] of entries) {
+                if (loopNode.type !== 'loop')
+                    continue;
+                const routes = outgoing.get(loopId) ?? [];
+                const returnsBeforeJoin = routes.some(edge => edge.outcome === 'body' && canReach(edge.target, loopId, id));
+                const suppliesDone = edges.some(branch => branch.source === loopId ? branch.outcome === 'done' : routes.some(edge => edge.outcome === 'done' && canReach(edge.target, branch.source, id)));
+                if (returnsBeforeJoin && suppliesDone && edges.some(branch => !canReach(loopId, branch.source, id)))
+                    fail(`Join ${id}: returning Loop ${loopId} advances generations independently of a sibling branch; use Join any or move the Loop before the shared fan-out`);
+            }
+            for (const [ancestorId, ancestor] of entries) {
+                if (nodeOutcomes(ancestor).length < 2)
+                    continue;
+                const reaches = (start, target, seen = new Set()) => { if (start === target)
+                    return true; if (start === id || start === ancestorId || seen.has(start))
+                    return false; seen.add(start); return (outgoing.get(start) ?? []).some(e => reaches(e.target, target, seen)); };
+                const possibilities = edges.map(branch => new Set((outgoing.get(ancestorId) ?? []).filter(e => ancestorId === branch.source ? e.outcome === branch.outcome : reaches(e.target, branch.source)).map(e => e.outcome)));
+                for (let a = 0; a < possibilities.length; a++)
+                    for (let b = a + 1; b < possibilities.length; b++)
+                        if (possibilities[a].size && possibilities[b].size && ![...possibilities[a]].some(o => possibilities[b].has(o)))
+                            fail(`Join ${id} waits on impossible branches from exclusive outcomes of ${ancestorId}; choose Join any or independent fan-out branches`);
+            }
+        }
+    }
+    if (graph.inputSchema !== undefined) {
+        objectSchema(graph.inputSchema, 'graph inputSchema');
+        const taskSchema = graph.inputSchema.properties?.task;
+        if (graph.inputSchema.additionalProperties === false && !taskSchema)
+            fail('graph inputSchema: closed schemas must declare the reserved task property as a string');
+        if (taskSchema && taskSchema.type !== 'string')
+            fail('graph inputSchema: the reserved canonical task property must have type string');
+    }
+    if (graph.stateSchema !== undefined)
+        objectSchema(graph.stateSchema, 'graph stateSchema');
+    validateMappings(graph);
+    const orchestrators = entries.filter(([, node]) => node.agentRole === 'orchestrator');
+    if (graph.schemaVersion === 3 && orchestrators.length) {
+        if (orchestrators.length > 1 || orchestrators[0][0] !== graph.entry)
+            fail('version 3 allows at most one Orchestrator Agent, which must be the graph entry');
+        if (!['read', 'find', 'grep', 'ls', 'read_file', 'list_files', 'search_files', 'repo_explore'].some(tool => permitsBuiltInTool(orchestrators[0][1], tool)))
+            fail('Orchestrator requires a usable research path; enable a filesystem read tool and filesystem read access');
+        const intake = orchestrators[0][1];
+        // An unlimited iteration ceiling has no upper bound at all, so it satisfies the minimum
+        // trivially. Only an explicit ceiling that is too small can fail this check; treating an
+        // absent bound as `3` would have made the check pass for the wrong reason.
+        const intakeIterations = [intake.maxIterations, intake.limits?.maxIterations].filter((value) => typeof value === 'number' && value > 0);
+        if (intakeIterations.length && Math.min(...intakeIterations) < 3)
+            fail('Orchestrator requires at least three model iterations; raise maxIterations or limits.maxIterations for research, clarification and completion, or leave them unset for no ceiling; todo-only turns have a separate budget');
+        // An absent ceiling is unlimited, which satisfies the Orchestrator minimum; only
+        // an explicit ceiling that is too small fails.
+        if (!meetsMinimumToolCalls(intake.limits?.maxToolCalls, 2))
+            fail('Orchestrator requires at least two tool calls; increase node limits.maxToolCalls for research and ask_user');
+        if (!meetsMinimumToolCalls(graph.limits?.maxToolCalls, 2))
+            fail('Orchestrator requires at least two tool calls; increase graph limits.maxToolCalls for research and ask_user');
+        if (graph.edges.some(edge => edge.target === graph.entry))
+            fail('Orchestrator intake cannot have incoming edges; route remediation to the downstream worker instead');
+    }
+    if (graph.schemaVersion === 3) {
+        const minimumToolCalls = minimumGraphToolCalls(graph);
+        const requiredWork = orchestrators.length ? 'Orchestrator research, ask_user and unavoidable Action nodes' : 'unavoidable Action nodes';
+        if (!meetsMinimumToolCalls(graph.limits?.maxToolCalls, minimumToolCalls))
+            fail(`graph maxToolCalls must be at least ${minimumToolCalls} for ${requiredWork}`);
+    }
+    if (graph.schemaVersion !== 3)
+        graph.schemaVersion = 2;
+    return graph;
+}
+export class GraphConflictError extends Error {
+    constructor(message = 'This graph changed in another editor. Reload it before saving.') { super(message); this.name = 'GraphConflictError'; }
+}
+/** Publish an immutable cloud revision only when the local revision is absent or identical. */
+export async function restoreGraphRevision(input, directory) {
+    const graph = validateGraphInternal(input);
+    if (graph.id === 'default' || graph.revision < 1)
+        throw new Error('Invalid cloud revision');
+    const folder = join(directory, 'graphs', graph.id);
+    await mkdir(folder, { recursive: true });
+    const release = await acquireSaveLock(folder);
+    const temp = join(folder, `latest-${randomUUID()}.tmp`);
+    try {
+        const snapshot = join(folder, `${graph.revision}.json`);
+        let exists = false;
+        try {
+            const previousRaw = await readFile(snapshot, 'utf8');
+            let previous;
+            try {
+                previous = validateGraphInternal(JSON.parse(previousRaw));
+            }
+            catch {
+                throw new GraphConflictError('The local revision is damaged; preserve it as a conflict.');
+            }
+            if (JSON.stringify(previous) !== JSON.stringify(graph))
+                throw new GraphConflictError();
+            exists = true;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (!exists)
+            await writeFile(snapshot, JSON.stringify(graph, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+        let current = 0;
+        try {
+            const raw = await readFile(join(folder, 'latest.json'), 'utf8');
+            try {
+                current = JSON.parse(raw);
+            }
+            catch {
+                throw new GraphConflictError('The local latest pointer is damaged; preserve it as a conflict.');
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (!Number.isSafeInteger(current) || current < 0)
+            throw new GraphConflictError('Invalid latest revision');
+        if (graph.revision > current) {
+            await writeFile(temp, JSON.stringify(graph.revision), { flag: 'wx', mode: 0o600 });
+            await rename(temp, join(folder, 'latest.json'));
+        }
+        return graph;
+    }
+    finally {
+        await unlink(temp).catch(() => { });
+        await release();
+    }
+}
+export async function loadGraph(id, revision, directory = configDirectory()) {
+    if (!validId(id))
+        throw new Error('Invalid graph id');
+    if (revision !== undefined && (!Number.isSafeInteger(revision) || revision < 1))
+        throw new Error('Invalid graph revision');
+    if (id === 'default') {
+        if (revision !== undefined && ![1, 2, 3, 4, 5].includes(revision))
+            throw new Error('Default graph revision does not exist');
+        return structuredClone(revision === 1 ? LEGACY_DEFAULT_HARNESS : revision === 2 ? DEFAULT_HARNESS_REVISION_2 : revision === 3 ? DEFAULT_HARNESS_REVISION_3 : revision === 4 ? DEFAULT_HARNESS_REVISION_4 : DEFAULT_HARNESS);
+    }
+    const folder = join(directory, 'graphs', id);
+    const selected = revision ?? JSON.parse(await readFile(join(folder, 'latest.json'), 'utf8'));
+    if (!Number.isSafeInteger(selected) || selected < 1)
+        throw new Error('Invalid stored graph revision');
+    const graph = validateGraphInternal(JSON.parse(await readFile(join(folder, `${selected}.json`), 'utf8')));
+    if (graph.id !== id || graph.revision !== selected)
+        throw new Error('Stored graph identity does not match its revision');
+    return graph;
+}
+export async function listGraphs(directory = configDirectory(), onLoadError) {
+    let entries;
+    try {
+        entries = await readdir(join(directory, 'graphs'), { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [structuredClone(DEFAULT_HARNESS)];
+        throw error;
+    }
+    const graphs = [structuredClone(DEFAULT_HARNESS)];
+    for (const entry of entries.filter(item => item.isDirectory() && validId(item.name) && item.name !== 'default').sort((a, b) => a.name.localeCompare(b.name))) {
+        try {
+            graphs.push(await loadGraph(entry.name, undefined, directory));
+        }
+        catch (error) {
+            onLoadError?.(entry.name, error);
+        }
+    }
+    return graphs;
+}
+export async function saveGraph(input, expectedRevision, directory = configDirectory()) {
+    const graph = validateGraph(input);
+    if (graph.id === 'default')
+        throw new Error('Duplicate the bundled default graph before customizing it');
+    if (expectedRevision !== null && (!Number.isSafeInteger(expectedRevision) || expectedRevision < 1))
+        throw new Error('Invalid expected revision');
+    if (graph.revision !== (expectedRevision ?? 0))
+        throw new GraphConflictError('The graph revision does not match the expected revision');
+    const folder = join(directory, 'graphs', graph.id);
+    await mkdir(folder, { recursive: true });
+    let releaseLock;
+    try {
+        releaseLock = await acquireSaveLock(folder);
+    }
+    catch (error) {
+        if (error instanceof SaveLockBusyError)
+            throw new GraphConflictError(error.message);
+        throw error;
+    }
+    const temporary = join(folder, `latest-${randomUUID()}.tmp`);
+    let createdSnapshot;
+    try {
+        let current;
+        try {
+            current = await loadGraph(graph.id, undefined, directory);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if ((current?.revision ?? null) !== expectedRevision)
+            throw new GraphConflictError();
+        graph.revision = (expectedRevision ?? 0) + 1;
+        // The creation time comes from storage, not the submitted graph: it decides which graph a free
+        // account keeps, so a save cannot move it.
+        const now = new Date().toISOString();
+        const createdAt = current ? current.metadata?.createdAt : now;
+        graph.metadata = { ...graph.metadata, updatedAt: now };
+        if (typeof createdAt === 'string')
+            graph.metadata.createdAt = createdAt;
+        else
+            delete graph.metadata.createdAt;
+        await archiveUnpublishedSnapshot(folder, graph.revision);
+        const snapshot = join(folder, `${graph.revision}.json`);
+        await writeFile(snapshot, JSON.stringify(graph, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+        createdSnapshot = snapshot;
+        await writeFile(temporary, JSON.stringify(graph.revision) + '\n', { flag: 'wx', mode: 0o600 });
+        await rename(temporary, join(folder, 'latest.json'));
+        createdSnapshot = undefined;
+        return graph;
+    }
+    finally {
+        await unlink(temporary).catch(() => { });
+        if (createdSnapshot)
+            await unlink(createdSnapshot).catch(() => { });
+        await releaseLock();
+    }
+}