@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/graph-editor-session.js

@@ -0,0 +1,70 @@
+import { execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { startGraphServer } from './graph-server.js';
+import { requireGraphMembership } from './membership.js';
+function openBrowser(url, signal) {
+    const command = process.platform === 'win32' ? 'rundll32.exe' : process.platform === 'darwin' ? 'open' : 'xdg-open';
+    const args = process.platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url];
+    return new Promise((resolve, reject) => {
+        execFile(command, args, { windowsHide: true, timeout: 10_000, signal }, error => {
+            if (error)
+                reject(new Error('Could not open the Graph Builder browser. Try `andorra graph --no-open` to open it manually.'));
+            else
+                resolve();
+        });
+    });
+}
+/** Owns only the editor server started by this interactive CLI session. */
+export function createGraphEditorSession(deps = {}) {
+    const lifetime = new AbortController();
+    let server;
+    let pending = Promise.resolve();
+    let closing;
+    return {
+        open(signal, mode = 'new') {
+            const operation = pending.then(async () => {
+                const active = signal ? AbortSignal.any([signal, lifetime.signal]) : lifetime.signal;
+                active.throwIfAborted();
+                let created = false;
+                try {
+                    if (server)
+                        await (deps.checkMembership ?? requireGraphMembership)(active);
+                    else {
+                        server = await (deps.startServer ?? startGraphServer)();
+                        created = true;
+                    }
+                    active.throwIfAborted();
+                    const url = new URL(server.url);
+                    if (mode === 'new') {
+                        url.searchParams.set('new', '1');
+                        // Give each launch its own URL so browsers do not focus/reload an existing draft tab.
+                        url.searchParams.set('draft', randomUUID());
+                    }
+                    await (deps.openBrowser ?? openBrowser)(url.href, active);
+                    active.throwIfAborted();
+                }
+                catch (error) {
+                    if (created && server) {
+                        const failed = server;
+                        server = undefined;
+                        await failed.close();
+                    }
+                    throw error;
+                }
+            });
+            pending = operation.catch(() => { });
+            return operation;
+        },
+        close() {
+            if (!closing) {
+                lifetime.abort(new Error('Graph Builder session closed.'));
+                closing = pending.then(async () => {
+                    const current = server;
+                    server = undefined;
+                    await current?.close();
+                });
+            }
+            return closing;
+        },
+    };
+}

package/dist/src/graph-health.d.ts

@@ -0,0 +1,88 @@
+import type { Config } from './config.js';
+import type { Graph } from './graphs.js';
+import { type ProviderConfig } from './providers.js';
+import type { ModelAdapter, Usage } from './types.js';
+export interface GraphModelHealthFailure {
+    provider: string;
+    model: string;
+    nodes: string[];
+    reason: string;
+    /** The provider answered with a failure (or timed out): the run failed in the provider, not in its configuration. */
+    providerError?: boolean;
+    /**
+     * The probe passed its bound rather than failing on an answer.
+     *
+     * A timeout is the one failure that says nothing about the model: a local deployment still
+     * loading its weights, or a provider queueing the request, looks exactly like an unavailable
+     * model inside the probe's short window. A caller that must not block work the user already
+     * asked for — a resume, where the attempt and its conversation exist and only the model call is
+     * missing — can tell this apart from a rejection and let the run report the real error.
+     */
+    timedOut?: boolean;
+}
+export interface GraphModelHealthResult {
+    healthy: boolean;
+    failures: GraphModelHealthFailure[];
+}
+/** The run's own pair for nodes that inherit it, when it differs from the saved configuration. */
+export interface GraphModelSession {
+    provider?: string;
+    model?: string;
+}
+export interface GraphModelHealthDependencies {
+    createAdapter?: (provider: ProviderConfig) => ModelAdapter;
+    timeoutMs?: number;
+    /** A run-level provider/model override that nodes without their own provider resolve to. */
+    session?: GraphModelSession;
+    /**
+     * Each dispatched probe's spend, so a caller can bill it to the run that requested the check.
+     * The reference names the model that spent it, which is what lets the run report per-model
+     * tuples instead of an unattributable total.
+     */
+    onUsage?: (usage: Partial<Usage>, reference: {
+        provider: string;
+        model: string;
+    }) => void;
+    /** The agent nodes to check; every agent node of the graph when absent, none when empty. */
+    nodes?: string[];
+    /** A bound for the whole check rather than one probe: probes still running when it passes are reported as unverified. */
+    overallTimeoutMs?: number;
+}
+/** The stopped attempt's own state, as far as the models a continuation can still call depend on it. */
+export interface GraphResumeScope {
+    /** The nodes the stopped attempt completed. */
+    nodeResults?: Record<string, unknown>;
+    /** Visit counts, so a node the journal proves ran is known even without a completion. */
+    visits?: Record<string, number>;
+    /** The frontier the journal proved was queued or started but never completed. */
+    pending?: {
+        nodeId: string;
+    }[];
+    /** The conversations a checkpoint can re-enter. */
+    checkpoints?: {
+        nodeId: string;
+    }[];
+}
+/**
+ * The agent nodes a resumed attempt can still call, or every agent node when the attempt is a
+ * fresh start. A continuation only re-enters the frontier the journal proves, so the models it
+ * will call are the ones that frontier's subgraph names: a stopped attempt that completed its
+ * agents and left only End makes no model call at all, and checking its models would fail a
+ * continuation that has nothing to run.
+ */
+export declare function resumeModelNodes(graph: Graph, resume?: GraphResumeScope): string[] | undefined;
+/** Probe inference itself, rather than trusting a provider's possibly stale model listing. */
+export declare function checkGraphModelHealth(graph: Graph, config: Config, signal: AbortSignal, dependencies?: GraphModelHealthDependencies): Promise<GraphModelHealthResult>;
+export declare function formatGraphHealthFailure(result: GraphModelHealthResult, remediation?: string): string;
+/**
+ * The health failures that must stop work before it starts.
+ *
+ * A fresh start has nothing invested yet, so every failure refuses it: that is the check's whole
+ * purpose, and a run that begins on a rejected model wastes its first nodes' tokens before the
+ * error surfaces. A continuation is different — the attempt, its journal and the conversation it
+ * re-enters already exist, and only the model call is missing. A probe that ran out of its short
+ * bound says nothing about whether that call can be served, so it is not allowed to refuse the
+ * continuation; the run reports the provider's own error if the model really cannot answer. A
+ * definite rejection still blocks both, because it will fail the continuation just as surely.
+ */
+export declare function blockingHealthFailures(result: GraphModelHealthResult, continuation: boolean): GraphModelHealthFailure[];

package/dist/src/graph-health.js

@@ -0,0 +1,243 @@
+import { configuredContextWindow, createAdapter } from './providers.js';
+/**
+ * The agent nodes a resumed attempt can still call, or every agent node when the attempt is a
+ * fresh start. A continuation only re-enters the frontier the journal proves, so the models it
+ * will call are the ones that frontier's subgraph names: a stopped attempt that completed its
+ * agents and left only End makes no model call at all, and checking its models would fail a
+ * continuation that has nothing to run.
+ */
+export function resumeModelNodes(graph, resume) {
+    if (resume === undefined)
+        return undefined;
+    const seeds = new Set();
+    for (const activation of resume.pending ?? [])
+        if (graph.nodes[activation.nodeId] !== undefined)
+            seeds.add(activation.nodeId);
+    for (const checkpoint of resume.checkpoints ?? [])
+        if (graph.nodes[checkpoint.nodeId] !== undefined)
+            seeds.add(checkpoint.nodeId);
+    const provenWork = Object.keys(resume.nodeResults ?? {}).length > 0 || Object.values(resume.visits ?? {}).some(count => count > 0);
+    if (seeds.size === 0) {
+        // Nothing is queued. The continuation either finalizes the stopped attempt through End or the
+        // runner refuses it, and neither calls a model. A journal that proves no work at all is a
+        // fresh start from the entry, which can call every model the graph names.
+        return provenWork ? [] : undefined;
+    }
+    const reachable = new Set();
+    const queue = [...seeds];
+    while (queue.length > 0) {
+        const nodeId = queue.pop();
+        if (reachable.has(nodeId))
+            continue;
+        reachable.add(nodeId);
+        for (const edge of graph.edges ?? [])
+            if (edge.source === nodeId)
+                queue.push(edge.target);
+    }
+    return [...reachable].filter(nodeId => graph.nodes[nodeId]?.type === 'agent');
+}
+/** Enumerate the effective models, including retries and delegated roles, before running any graph work. */
+function graphModels(graph, config, session = {}, only) {
+    const references = new Map();
+    const sessionProvider = session.provider ?? config.provider;
+    const resolve = (provider, model) => ({ provider, model: model ?? config.providers.find(p => p.id === provider)?.model ?? '(default model)' });
+    // A node without its own provider runs the session pair: the run's own model override, when it
+    // has one, replaces the provider's configured model exactly where the runtime would resolve it.
+    const inherited = (node) => node.provider === undefined
+        ? resolve(sessionProvider, node.model ?? session.model)
+        : resolve(node.provider, node.model);
+    const key = (ref) => JSON.stringify([ref.provider, ref.model]);
+    const add = (ref, node) => {
+        const entry = references.get(key(ref));
+        if (entry) {
+            if (!entry.nodes.includes(node))
+                entry.nodes.push(node);
+        }
+        else
+            references.set(key(ref), { ...ref, nodes: [node] });
+    };
+    for (const node of Object.values(graph.nodes)) {
+        if (node.type !== 'agent')
+            continue;
+        if (only && !only.includes(node.id))
+            continue;
+        const label = `${node.name} (${node.id})`;
+        const primary = inherited(node);
+        add(primary, label);
+        let parents = [primary];
+        if (node.retry?.fallback && node.retry.maxAttempts > 1) {
+            const fallback = resolve(node.retry.fallback.provider, node.retry.fallback.model);
+            add(fallback, `${label} fallback`);
+            // Spawned roles inherit the active attempt's model, including a fallback attempt.
+            parents.push(fallback);
+        }
+        const policy = node.subagents;
+        if (!policy?.enabled || Math.min(policy.maxTotal ?? 8, node.maxSubagents ?? Infinity) <= 0)
+            continue;
+        // Every ancestor occupies a concurrent slot; runtime refuses nesting when all slots are occupied.
+        const maxDepth = Math.min(policy.maxDepth ?? 1, policy.maxConcurrent ?? 3, policy.maxTotal ?? 8, node.maxSubagents ?? Infinity);
+        const seen = new Set();
+        for (let depth = 0; depth < maxDepth && parents.length; depth++) {
+            const children = [];
+            for (const parent of parents) {
+                if (seen.has(key(parent)))
+                    continue;
+                seen.add(key(parent));
+                for (const role of policy.roles ?? []) {
+                    const provider = policy.modelPolicy === 'specific' ? policy.provider ?? parent.provider
+                        : policy.modelPolicy === 'per-role' ? role.provider ?? parent.provider : parent.provider;
+                    const model = policy.modelPolicy === 'specific' ? policy.model
+                        : policy.modelPolicy === 'per-role' ? role.model ?? (provider === parent.provider ? parent.model : undefined) : parent.model;
+                    const child = resolve(provider, model);
+                    add(child, `${label} subagent ${role.name} (${role.id})`);
+                    children.push(child);
+                }
+            }
+            parents = children;
+        }
+    }
+    return [...references.values()];
+}
+/** Probe inference itself, rather than trusting a provider's possibly stale model listing. */
+export async function checkGraphModelHealth(graph, config, signal, dependencies = {}) {
+    signal.throwIfAborted();
+    const timeoutMs = dependencies.timeoutMs ?? 30_000;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30_000)
+        throw new Error('Graph model health timeout must be between 1 and 30000 milliseconds');
+    const overallTimeoutMs = dependencies.overallTimeoutMs;
+    if (overallTimeoutMs !== undefined && (!Number.isSafeInteger(overallTimeoutMs) || overallTimeoutMs < 1 || overallTimeoutMs > 300_000)) {
+        throw new Error('Graph model health overall timeout must be between 1 and 300000 milliseconds');
+    }
+    const references = graphModels(graph, config, dependencies.session, dependencies.nodes);
+    const failures = new Array(references.length);
+    // The pairs that answered: a pair that was asked and answered is known good, and the overall
+    // bound must not report it as a pair it never verified.
+    const answered = new Array(references.length);
+    // The whole check has its own bound: a graph with more model pairs than the workers can carry
+    // would otherwise take one timeout per wave, and a caller that waits for the answer (a graph
+    // selection) would wait for minutes.
+    const overall = overallTimeoutMs === undefined ? undefined : new AbortController();
+    const overallTimer = overall === undefined ? undefined : setTimeout(() => overall.abort(new Error('Health check timed out')), overallTimeoutMs);
+    overallTimer?.unref?.();
+    let next = 0;
+    const worker = async () => {
+        while (next < references.length) {
+            signal.throwIfAborted();
+            if (overall?.signal.aborted)
+                return;
+            const index = next++, reference = references[index];
+            const provider = config.providers.find(p => p.id === reference.provider);
+            if (!provider) {
+                failures[index] = { ...reference, reason: 'Provider is not configured.' };
+                continue;
+            }
+            const controller = new AbortController();
+            const abort = () => controller.abort(signal.reason);
+            signal.addEventListener('abort', abort, { once: true });
+            let timedOut = false;
+            const timer = setTimeout(() => { timedOut = true; controller.abort(new Error('Health check timed out')); }, timeoutMs);
+            // The whole check's bound cuts this probe short too: a probe still waiting when the bound
+            // passes is one the check will not verify.
+            const abortOverall = () => { timedOut = true; controller.abort(overall?.signal.reason); };
+            overall?.signal.addEventListener('abort', abortOverall, { once: true });
+            let abortProbe;
+            const aborted = new Promise((_, reject) => {
+                abortProbe = () => reject(controller.signal.reason);
+                controller.signal.addEventListener('abort', abortProbe, { once: true });
+            });
+            try {
+                let requests = 0;
+                const response = await Promise.race([Promise.resolve().then(() => {
+                        controller.signal.throwIfAborted();
+                        const snapshot = { ...provider, model: reference.model };
+                        // Match runtime model overrides: saved reasoning and context settings belong to the profile's model.
+                        if (reference.model !== provider.model) {
+                            delete snapshot.contextWindow;
+                            delete snapshot.reasoningEffort;
+                        }
+                        const savedWindow = configuredContextWindow(provider, reference.model);
+                        if (savedWindow !== undefined)
+                            snapshot.contextWindow = savedWindow;
+                        return (dependencies.createAdapter ?? createAdapter)(snapshot).generate({
+                            model: reference.model, messages: [{ role: 'user', content: 'Reply OK.' }], tools: [], maxTokens: 16, signal: controller.signal,
+                            onRequest: () => {
+                                requests += 1;
+                                // No token keys: the provider has not said yet, and a zero here would be published as
+                                // a measured zero rather than as absent.
+                                dependencies.onUsage?.({ requests: 1 }, reference);
+                            },
+                        });
+                    }), aborted]);
+                signal.throwIfAborted();
+                answered[index] = true;
+                if (response.usage) {
+                    const reported = response.usage;
+                    dependencies.onUsage?.({
+                        // The transport callback already counted this attempt; a provider that reports the
+                        // total itself adds only the attempts it measured beyond the callbacks.
+                        requests: Math.max(0, (reported.requests ?? 1) - requests),
+                        // Omitted rather than defaulted: a provider that sends usage without a token field did
+                        // not measure it, and a zero would be published as a measured zero.
+                        ...(reported.inputTokens === undefined ? {} : { inputTokens: reported.inputTokens }),
+                        ...(reported.outputTokens === undefined ? {} : { outputTokens: reported.outputTokens }),
+                        ...(reported.cacheRead === undefined ? {} : { cacheRead: reported.cacheRead }),
+                        ...(reported.cacheWrite === undefined ? {} : { cacheWrite: reported.cacheWrite }),
+                    }, reference);
+                }
+            }
+            catch {
+                signal.throwIfAborted();
+                // Provider bodies and thrown messages can contain credentials. Keep diagnostics local and generic.
+                failures[index] = { ...reference, providerError: true, ...(timedOut ? { timedOut: true } : {}), reason: timedOut ? 'Model health check timed out.' : 'Model request failed. Check model availability and provider credentials.' };
+            }
+            finally {
+                clearTimeout(timer);
+                signal.removeEventListener('abort', abort);
+                overall?.signal.removeEventListener('abort', abortOverall);
+                controller.signal.removeEventListener('abort', abortProbe);
+            }
+        }
+    };
+    try {
+        await Promise.all(Array.from({ length: Math.min(4, references.length) }, worker));
+    }
+    finally {
+        if (overallTimer !== undefined)
+            clearTimeout(overallTimer);
+    }
+    signal.throwIfAborted();
+    if (overall?.signal.aborted) {
+        // The bound passed before these pairs were reached: the check could not verify them, which is
+        // reported rather than passed over — a model that was never asked is not a model that answered.
+        for (let index = 0; index < references.length; index += 1) {
+            // Only the pairs that were never verified: a pair that answered before the bound passed is
+            // known good, and reporting it as unavailable would defeat the point of naming the pairs.
+            if (failures[index] === undefined && answered[index] !== true)
+                failures[index] = { ...references[index], timedOut: true, reason: 'Model health check timed out.' };
+        }
+    }
+    const unavailable = failures.filter((failure) => failure !== undefined);
+    return { healthy: unavailable.length === 0, failures: unavailable };
+}
+export function formatGraphHealthFailure(result, remediation = 'Open /graph > Edit Graphs, fix the model selections, then reload the graph to check again.') {
+    if (result.healthy)
+        return '';
+    return ['Graph model health check failed. These models are unavailable:',
+        ...result.failures.map(failure => `- ${failure.provider}/${failure.model}: ${failure.reason} Nodes: ${failure.nodes.join(', ')}`),
+        `Tasks are blocked because these unavailable models will cause errors downstream. ${remediation}`,
+    ].join('\n');
+}
+/**
+ * The health failures that must stop work before it starts.
+ *
+ * A fresh start has nothing invested yet, so every failure refuses it: that is the check's whole
+ * purpose, and a run that begins on a rejected model wastes its first nodes' tokens before the
+ * error surfaces. A continuation is different — the attempt, its journal and the conversation it
+ * re-enters already exist, and only the model call is missing. A probe that ran out of its short
+ * bound says nothing about whether that call can be served, so it is not allowed to refuse the
+ * continuation; the run reports the provider's own error if the model really cannot answer. A
+ * definite rejection still blocks both, because it will fail the continuation just as surely.
+ */
+export function blockingHealthFailures(result, continuation) {
+    return continuation ? result.failures.filter(failure => failure.timedOut !== true) : result.failures;
+}

package/dist/src/graph-provider-portability.d.ts

@@ -0,0 +1,30 @@
+import type { Config } from './config.js';
+import type { Graph } from './graphs.js';
+import { type ProviderConfig } from './providers.js';
+/**
+ * A graph cannot be bound to this machine's providers: one it names is absent, or more than one
+ * local Codex OAuth profile could serve it, so execution has no single profile to bind.
+ *
+ * Selection keeps the graph (it must stay selectable to be edited, and a run that overrides every
+ * node sets the references aside); what refuses is the run, before any node starts. The two are
+ * told apart by this class rather than by message text.
+ */
+export declare class GraphProviderUnavailableError extends Error {
+    constructor(message: string);
+}
+/** Add portable identity metadata when a machine publishes a graph revision. Existing identities win. */
+export declare function stampGraphProviderProfiles(graph: Graph, config: {
+    providers: readonly Pick<ProviderConfig, 'id' | 'type' | 'model'>[];
+}, 
+/** A CLI model override chooses its model before updating config.json. */
+selectedModels?: Readonly<Record<string, string>>): Graph;
+/**
+ * Use local profiles for execution without changing the saved graph. A provider configured
+ * locally under the same ID is authoritative: references that do not name a model follow that
+ * provider's current configured model, so a provider-settings change reaches future runs without
+ * republishing the graph. A recorded Codex OAuth identity may instead bind to a differently named
+ * local Codex profile offering every model its references require — including models from
+ * providerless `per-role` or `specific` subagent entries, which execution resolves through the
+ * parent node. The Codex adapter/health check verifies the actual sign-in before any run is allowed.
+ */
+export declare function bindPortableGraphProviders(graph: Graph, config: Pick<Config, 'providers'>): Graph;

package/dist/src/graph-provider-portability.js

@@ -0,0 +1,197 @@
+import { providerModels } from './providers.js';
+const profileKey = 'graphProviderProfilesV1';
+/**
+ * A graph cannot be bound to this machine's providers: one it names is absent, or more than one
+ * local Codex OAuth profile could serve it, so execution has no single profile to bind.
+ *
+ * Selection keeps the graph (it must stay selectable to be edited, and a run that overrides every
+ * node sets the references aside); what refuses is the run, before any node starts. The two are
+ * told apart by this class rather than by message text.
+ */
+export class GraphProviderUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GraphProviderUnavailableError';
+    }
+}
+function references(graph) {
+    const result = [];
+    for (const node of Object.values(graph.nodes)) {
+        if (node.type !== 'agent')
+            continue;
+        result.push(node);
+        // Ignore provider fields that execution cannot reach.
+        if (node.retry?.fallback && node.retry.maxAttempts > 1)
+            result.push(node.retry.fallback);
+        const policy = node.subagents;
+        if (!policy?.enabled || node.maxSubagents === 0 || policy.maxTotal === 0)
+            continue;
+        if (policy.modelPolicy === 'specific')
+            result.push(policy);
+        else if (policy.modelPolicy === 'per-role') {
+            for (const role of policy.roles ?? [])
+                result.push(role);
+        }
+    }
+    return result;
+}
+function profiles(graph) {
+    const raw = graph.metadata?.[profileKey];
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const parsed = {};
+    for (const [id, entry] of Object.entries(raw)) {
+        // Same id grammar as validateConfig: unbounded `^[\w-]+$`, so a long but valid id is never
+        // silently dropped here, which would strand it on a device that uses a different local id.
+        if (!/^[\w-]+$/.test(id) || !entry || typeof entry !== 'object' || Array.isArray(entry))
+            continue;
+        const value = entry;
+        if (!['codex', 'anthropic', 'openai-compatible', 'claude', 'opencode-go'].includes(value.type)
+            || typeof value.model !== 'string' || !value.model.trim())
+            continue;
+        // An own property is mandatory for IDs such as "__proto__", "constructor" and "toString".
+        Object.defineProperty(parsed, id, {
+            value: { type: value.type, model: value.model },
+            enumerable: true, writable: true, configurable: true,
+        });
+    }
+    return parsed;
+}
+/** Add portable identity metadata when a machine publishes a graph revision. Existing identities win. */
+export function stampGraphProviderProfiles(graph, config, 
+/** A CLI model override chooses its model before updating config.json. */
+selectedModels = {}) {
+    const copy = structuredClone(graph);
+    const saved = profiles(copy);
+    for (const reference of references(copy)) {
+        if (!reference.provider)
+            continue;
+        const provider = config.providers.find(item => item.id === reference.provider);
+        if (!provider)
+            continue; // Preserve provenance when the local provider is absent.
+        const selectedModel = Object.hasOwn(selectedModels, reference.provider)
+            ? selectedModels[reference.provider] : undefined;
+        if (!selectedModel && Object.hasOwn(saved, reference.provider))
+            continue;
+        Object.defineProperty(saved, reference.provider, {
+            value: { type: provider.type, model: selectedModel ?? provider.model },
+            enumerable: true, writable: true, configurable: true,
+        });
+    }
+    if (Object.keys(saved).length)
+        copy.metadata = { ...copy.metadata, [profileKey]: saved };
+    return copy;
+}
+/**
+ * Use local profiles for execution without changing the saved graph. A provider configured
+ * locally under the same ID is authoritative: references that do not name a model follow that
+ * provider's current configured model, so a provider-settings change reaches future runs without
+ * republishing the graph. A recorded Codex OAuth identity may instead bind to a differently named
+ * local Codex profile offering every model its references require — including models from
+ * providerless `per-role` or `specific` subagent entries, which execution resolves through the
+ * parent node. The Codex adapter/health check verifies the actual sign-in before any run is allowed.
+ */
+export function bindPortableGraphProviders(graph, config) {
+    const copy = structuredClone(graph);
+    const saved = profiles(copy);
+    const requirements = new Map();
+    const add = (reference, inheritedModels = [], inheritsParentModel = false) => {
+        if (!reference.provider)
+            return; // Intentionally inherits this machine's default.
+        const originalId = reference.provider;
+        let required = requirements.get(originalId);
+        if (!required) {
+            required = { references: [], models: new Set(), inheritsRecordedModel: false };
+            requirements.set(originalId, required);
+        }
+        required.references.push({ reference, inheritsParentModel });
+        if (inheritsParentModel && !reference.model)
+            return; // The parent's requirement already covers it.
+        if (reference.model)
+            required.models.add(reference.model);
+        else
+            required.inheritsRecordedModel = true;
+        for (const inherited of inheritedModels)
+            required.models.add(inherited);
+    };
+    // Collect all active requirements before choosing an OAuth alias. Two nodes using the
+    // same original provider must never bind to different local profiles.
+    for (const node of Object.values(copy.nodes)) {
+        if (node.type !== 'agent')
+            continue;
+        const policy = node.subagents;
+        const activeSubagents = policy?.enabled && node.maxSubagents !== 0 && policy.maxTotal !== 0;
+        const inherited = [];
+        if (activeSubagents) {
+            const children = policy.modelPolicy === 'per-role' ? policy.roles ?? []
+                : policy.modelPolicy === 'specific' ? [policy] : [];
+            for (const child of children) {
+                if (!child.provider && child.model)
+                    inherited.push(child.model);
+            }
+        }
+        add(node, inherited);
+        if (node.retry?.fallback && node.retry.maxAttempts > 1) {
+            // Enabled retry attempts may spawn providerless children on the fallback provider.
+            add(node.retry.fallback, inherited);
+        }
+        if (!activeSubagents)
+            continue;
+        if (policy.modelPolicy === 'specific')
+            add(policy);
+        else if (policy.modelPolicy === 'per-role') {
+            for (const role of policy.roles ?? []) {
+                add(role, [], Boolean(role.provider) && role.provider === node.provider && !role.model);
+            }
+        }
+    }
+    for (const [originalId, required] of requirements) {
+        const original = Object.hasOwn(saved, originalId) ? saved[originalId] : undefined;
+        const explicitModels = [...required.models];
+        // Only an alias needs the recorded model: it is the model this graph was published with, and
+        // the alias must offer it before execution can pin references that did not name one.
+        const requiredModels = original && required.inheritsRecordedModel ? [...explicitModels, original.model] : explicitModels;
+        const offers = (provider, models) => models.every(model => providerModels(provider).includes(model));
+        const sameType = (provider) => !original || provider.type === original.type;
+        // A same-ID provider that exists locally wins outright once it offers the models the graph
+        // actually names. Its current model is what the graph follows, so changing the provider's
+        // model (or removing the old one from its pool) applies to the next run without a new revision.
+        const exact = config.providers.find(provider => provider.id === originalId);
+        let resolved = exact && sameType(exact) && offers(exact, explicitModels) ? exact : undefined;
+        const exactResolved = resolved !== undefined;
+        // A local provider that owns the original ID is authoritative even when it cannot serve the
+        // graph: silently aliasing to another OAuth profile would switch accounts and bypass the
+        // explicit override's validation. Only an absent original ID may bind to a named alias.
+        if (!resolved && exact === undefined && original?.type === 'codex') {
+            const candidates = config.providers.filter(provider => provider.type === 'codex' && offers(provider, requiredModels));
+            if (candidates.length > 1) {
+                throw new GraphProviderUnavailableError('Graph provider ' + originalId + ' has ambiguous Codex OAuth matches: '
+                    + candidates.map(p => p.id).join(', ') + '. '
+                    + 'Configure the original provider ID or leave exactly one compatible Codex OAuth profile on this machine, '
+                    + 'or start the task with a model override so every node runs on one provider.');
+            }
+            if (candidates.length === 1)
+                resolved = candidates[0];
+        }
+        if (!resolved) {
+            throw new GraphProviderUnavailableError('Graph provider ' + originalId + (requiredModels.length ? ' / ' + requiredModels.join(', ') : '')
+                + ' is unavailable on this machine. '
+                + 'Connect the corresponding OAuth provider or configure the same provider ID and models in /providers, '
+                + 'or start the task with a model override so every node runs on one provider.');
+        }
+        // Rewrite only the execution copy after the original provider is fully validated.
+        for (const tracked of required.references) {
+            tracked.reference.provider = resolved.id;
+            if (tracked.inheritsParentModel && !tracked.reference.model)
+                continue; // Stay unset; execution inherits the parent's model.
+            if (tracked.reference.model)
+                continue; // An explicit model selection is the graph's own.
+            // An exact local provider stays unpinned so execution reads its current configured model.
+            // An alias has no local configuration of its own, so the recorded model is the only identity
+            // this graph can continue with.
+            if (!exactResolved && original?.model)
+                tracked.reference.model = original.model;
+        }
+    }
+    return copy;
+}