@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/subagent-run.js

@@ -0,0 +1,930 @@
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import { realpath, stat } from 'node:fs/promises';
+import { appendFile, writeFile } from 'node:fs/promises';
+import { configDirectory, loadConfig, resolveCodeIntelConfig, resolveConfiguredLimits, resolveMemoryConfig } from './config.js';
+import { createRunHandle, drainTelemetry, reportRunFinished, reportRunStarted } from './telemetry/surface.js';
+import { configuredContextWindow, createAdapter, providerModels } from './providers.js';
+import { getMembership, loadAccessibleGraph } from './membership.js';
+import { currentGraphSubject } from './graph-selection.js';
+import { createRunTelemetry, recordModelUse } from './telemetry/capture.js';
+import { checkGraphModelHealth } from './graph-health.js';
+import { validateGraph } from './graphs.js';
+import { runGraph } from './runtime.js';
+import { createTools } from './tools.js';
+import { loadWorkspaceInstructions } from './workspace-instructions.js';
+import { QA_SYSTEM_GUIDANCE } from './qa/index.js';
+import { extensionSnapshot } from './extensions.js';
+import { resolveModelContext } from './model-metadata.js';
+import { MemoryManager } from './memory/MemoryManager.js';
+import { LocalToolMemory } from './memory/LocalToolMemory.js';
+import { ArtifactStore } from './artifacts.js';
+import { CodeIntelligenceManager } from './code-intelligence/CodeIntelligenceManager.js';
+import { DecisionManager } from './decision/DecisionManager.js';
+import { permissionMode } from './permissions.js';
+import { TodoStore } from './todos.js';
+import { claimProcessWorkspace, clearOpenRunClaim, noteCheckpointWriteFailure, noteJournalWriteFailure, releaseProcessWorkspace, removeOpenRunRecord, removeRunCheckpoint, repairSessionMarkers, RUNNING_TURN_SUMMARY, runRecordPath, summaryForStoppedRecord, writeOpenRunRecord, writeRunCheckpoint, writeStudioRunSummary } from './run-records.js';
+import { SessionStore, projectIdentity, sessionName } from './sessions.js';
+/**
+ * External subagent mode: the only graph an external host (Claude CLI, Codex CLI) may run.
+ *
+ * The restriction is structural — the id is a constant here, never a parameter on any surface —
+ * and the id is `default`, which `loadAccessibleGraph` resolves to the bundled single-agent
+ * Software Engineer harness: no Orchestrator intake, no per-node provider pins, no account
+ * membership. That is what makes a one-shot external run headless-safe and lets the caller's
+ * provider/model choice reach every request the run makes.
+ */
+export const SUBAGENT_GRAPH_ID = 'default';
+/**
+ * The longest task a subagent run accepts.
+ *
+ * The bound is the engine's own, and it is enforced here rather than in each entry point: a task
+ * this long is not a task a host meant to ask for, and it is persisted and turned into model
+ * context before anything else looks at it. Every surface that starts a run goes through this
+ * check, so the CLI and the MCP tools refuse the same task the same way.
+ */
+export const MAX_SUBAGENT_TASK_CHARS = 100_000;
+/**
+ * The longest model identifier a subagent run accepts.
+ *
+ * It is the bound the configuration holds a saved model id to, and a per-call model is held to
+ * the same one: the value is written into the open run record and carried through the preflight
+ * and the model resolution, so an unbounded one would fill the installation's storage and the
+ * provider's request with what is only ever a caller's typo.
+ */
+export const MAX_SUBAGENT_MODEL_CHARS = 500;
+/** A task the caller may not ask for: too long for the run to carry. */
+export class SubagentInvalidArgumentError extends Error {
+    constructor(message) { super(message); this.name = 'SubagentInvalidArgumentError'; }
+}
+/**
+ * The permission a caller asked for.
+ *
+ * The two supported modes are the whole vocabulary. A value outside them is the caller's
+ * mistake, and answering it with `full-access` would grant the filesystem and shell mutations the
+ * caller was trying to withhold — so it is refused instead of rounded up. An absent permission
+ * keeps the default, which is what the CLI and the MCP wrappers mean by not naming one.
+ */
+export function resolveSubagentPermissions(requested) {
+    if (requested === undefined)
+        return 'full-access';
+    if (requested === 'read-only' || requested === 'full-access')
+        return requested;
+    throw new SubagentInvalidArgumentError(`The permission must be "read-only" or "full-access"; "${String(requested)}" is not a permission.`);
+}
+/**
+ * The provider snapshot a run's own model is invoked with.
+ *
+ * The saved reasoning effort and context window belong to the provider's *configured* model, so a
+ * run on a different one does not carry them: an adapter that honours them would send a
+ * reasoning setting the model does not take, or compact against the wrong limit. The window the
+ * provider lists for the selected model is applied instead, when it lists one.
+ */
+function providerForModel(provider, model) {
+    const selected = { ...provider, model };
+    if (model !== provider.model) {
+        delete selected.reasoningEffort;
+        delete selected.contextWindow;
+    }
+    const savedWindow = configuredContextWindow(provider, model);
+    if (savedWindow !== undefined)
+        selected.contextWindow = savedWindow;
+    return selected;
+}
+/** Fold one account of spend into another. */
+function foldUsage(target, delta) {
+    target.requests += delta.requests ?? 0;
+    target.inputTokens += delta.inputTokens ?? 0;
+    target.outputTokens += delta.outputTokens ?? 0;
+    // Presence, not magnitude: a counter the provider reported as zero is a measurement, and a
+    // session that is reloaded shows it as one. Only an unreported counter stays absent.
+    if (delta.cacheRead !== undefined)
+        target.cacheRead = (target.cacheRead ?? 0) + delta.cacheRead;
+    if (delta.cacheWrite !== undefined)
+        target.cacheWrite = (target.cacheWrite ?? 0) + delta.cacheWrite;
+}
+/**
+ * The workspaces this process is running a subagent in.
+ *
+ * The reservation is process-wide rather than a runner's own: an embedded host can build several
+ * backends — or a runner of its own — in one process, and each of them held a slot of its own,
+ * so two full-access runs could work the same workspace at once. The unit the slot reserves is
+ * the workspace, because that is what two overlapping runs would both write to.
+ */
+/**
+ * The workspace a run works in, resolved to a real directory.
+ *
+ * Both public wrappers canonicalize the path before they call the runner, and the runner is
+ * exported for embedded use: a relative, empty or file-valued path would create the open record
+ * and the session — and spend the health probe — before the tools failed. A relative alias would
+ * also give one workspace two project identities, and a later resume would resolve the stored
+ * path against whatever working directory it happened to run in.
+ */
+export async function canonicalWorkspace(requested) {
+    let resolved;
+    try {
+        resolved = await realpath(requested);
+    }
+    catch (error) {
+        throw new SubagentInvalidArgumentError(`The workspace must be a directory: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!(await stat(resolved)).isDirectory())
+        throw new SubagentInvalidArgumentError('The workspace must be a directory.');
+    return resolved;
+}
+export class SubagentProviderNotSetError extends Error {
+    providers;
+    constructor(providers) {
+        super('No provider/model is set for Andorra external subagent runs. Ask the user which provider and model to use from the list, then retry with provider and model.');
+        this.providers = providers;
+        this.name = 'SubagentProviderNotSetError';
+    }
+}
+export class SubagentRunInProgressError extends Error {
+    constructor() { super('A subagent run is already active in this process. Poll it with status, result or cancel before starting another.'); this.name = 'SubagentRunInProgressError'; }
+}
+export function listSubagentProviders(config) {
+    return config.providers.map(provider => ({ id: provider.id, type: provider.type, models: providerModels(provider) }));
+}
+/**
+ * Resolve the provider/model a subagent run uses: the caller's explicit pick wins, the saved
+ * `externalSubagent` setting is next, and anything else is the self-describing PROVIDER_NOT_SET
+ * error the calling agent is expected to take back to its user.
+ *
+ * A per-call model is accepted on the same terms as the CLI's `--model` (any nonempty id), while
+ * the saved setting is held to the stricter config validation: a persisted pair names a provider
+ * that must still exist and, when the provider carries an explicit model list, a model on it.
+ */
+/**
+ * The caller named a provider or a model the installation does not have.
+ *
+ * It is a selection failure rather than a backend failure, so a host can tell that its own
+ * choice was wrong and correct the identifier without a second diagnostic path.
+ */
+export class SubagentSelectionError extends Error {
+}
+export function resolveSubagentProvider(config, call = {}) {
+    if (call.model !== undefined && call.provider === undefined)
+        throw new SubagentSelectionError('A model was supplied without a provider. Retry with both provider and model.');
+    if (call.provider !== undefined) {
+        const provider = config.providers.find(item => item.id === call.provider);
+        if (!provider)
+            throw new SubagentSelectionError(`Unknown provider: ${call.provider}`);
+        if (typeof call.model !== 'string' || !call.model.trim()) {
+            throw new SubagentSelectionError('A provider was supplied without a model. Retry with both provider and model.');
+        }
+        // The bound a configured model id is held to. A per-call model is persisted in the open run
+        // record and carried through the preflight and the model resolution, so it is held to the
+        // same length before any of that happens.
+        if (call.model.trim().length > MAX_SUBAGENT_MODEL_CHARS) {
+            throw new SubagentInvalidArgumentError(`The model must be at most ${MAX_SUBAGENT_MODEL_CHARS} characters.`);
+        }
+        return { provider, model: call.model.trim() };
+    }
+    const setting = config.externalSubagent;
+    if (setting) {
+        const provider = config.providers.find(item => item.id === setting.provider);
+        if (provider)
+            return { provider, model: setting.model };
+    }
+    throw new SubagentProviderNotSetError(listSubagentProviders(config));
+}
+const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+/**
+ * The health failure a subagent caller is given.
+ *
+ * A subagent always runs the built-in Software Engineer graph, whose node has no editable model
+ * selection, so the ordinary remedy — edit the graph's model selections — cannot be followed. The
+ * caller has to pick another provider and model, or repair that provider's credentials.
+ */
+function subagentHealthFailure(health) {
+    return ['The provider/model this subagent run would use is not usable:',
+        ...health.failures.map(failure => `- ${failure.provider}/${failure.model}: ${failure.reason}`),
+        'A subagent run always uses the built-in Software Engineer graph, whose model is the one you picked, so there is no graph to edit: retry with another provider and model, or repair that provider credentials.',
+    ].join('\n');
+}
+/**
+ * One subagent run at a time per process, mirroring the engine's own one-run rule: the MCP server
+ * is a single process, so a second start while one run is live is refused rather than queued.
+ *
+ * The reservation is the process's rather than this runner's, because an embedded host can build
+ * several backends in one process: two of them would otherwise each hold a slot of their own and
+ * work the same workspace at once. What the slot reserves is the workspace, because that is what
+ * two overlapping runs would both write to.
+ *
+ * Records follow the installation's own lifecycle — an open run record before any preflight, run
+ * events appended to `runs/<id>.jsonl`, a session record and a terminal run record on finalize —
+ * so a crashed subagent run is classified by the same startup recovery as any other attempt and
+ * stays visible in the Runs view instead of vanishing with its host.
+ */
+/**
+ * The decision service an external subagent run uses: the one this installation configured, never a
+ * hosted default, and only for a signed-in account. The account is asked only when the answer could
+ * matter, so a run with decisions off stays free of an account request.
+ */
+export async function subagentDecisionConfig(config, membership) {
+    const decisions = config.decisions;
+    if (config.jevEnabled === false || !decisions || decisions.provider === 'none' || decisions.mode === 'off')
+        return { mode: 'off', provider: 'none' };
+    return (await membership()).subject ? decisions : { mode: 'off', provider: 'none' };
+}
+export class SubagentRunner {
+    defaults;
+    active;
+    /** Set when the runner was shut down: a start that begins after it must not launch a run. */
+    closed = false;
+    /** A start that is preparing its run holds the slot before it is assigned. */
+    starting = false;
+    /** The workspace this runner holds the process-wide reservation for, when it holds one. */
+    reservedWorkspace;
+    /** A cancellation that arrived while the run was still starting. */
+    pendingCancel = false;
+    /** The start that is preparing a run, so a shutdown can wait for it instead of racing it. */
+    startPromise;
+    /**
+     * This runner's identity in the process-wide workspace reservation.
+     *
+     * The reservation is the process's, so two runners over one workspace cannot both hold it, and
+     * only the holder gives it back.
+     */
+    reservationId = randomUUID();
+    constructor(defaults = {}) {
+        this.defaults = defaults;
+    }
+    async start(options) {
+        if (!options.task.trim())
+            throw new Error('The subagent task must not be empty.');
+        // The bound is checked before anything is written: an oversized task must not leave a record,
+        // a claim or a session behind, whichever surface asked for it.
+        if (options.task.length > MAX_SUBAGENT_TASK_CHARS) {
+            throw new SubagentInvalidArgumentError(`The task must be at most ${MAX_SUBAGENT_TASK_CHARS} characters.`);
+        }
+        // The permission is read before anything is written too: a caller that meant to withhold the
+        // mutations must not be given them by a value this runner could not read.
+        const permissions = resolveSubagentPermissions(options.permissions);
+        // The connection that owned this runner closed while the start was still preparing. A run that
+        // begins now would outlive the connection that asked for it, with nothing left to cancel it.
+        if (this.closed)
+            throw new Error('The connection to Andorra closed before the run started.');
+        // The slot is taken before the first await: two overlapping starts would otherwise both
+        // pass the check, and the later assignment would hide the first run from every reader.
+        if (this.starting || (this.active !== undefined && !this.active.outcome))
+            throw new SubagentRunInProgressError();
+        this.starting = true;
+        // The run takes the reservation over from the start: a start that failed leaves nothing
+        // behind, and a start that reached its run hands the reservation to it.
+        let handedOver = false;
+        const pending = this.begin(options, permissions).then(reply => { handedOver = true; return reply; });
+        // The start is tracked while it prepares, so a shutdown can wait for it: a start that has
+        // not reached its run yet has nothing to abort, and it would otherwise go on to launch a
+        // full-access run after the connection that asked for it has closed.
+        this.startPromise = pending;
+        try {
+            return await pending;
+        }
+        finally {
+            // The reservation is the slot until the run itself holds it, and it is released when the
+            // start failed, so the next caller is not refused for a run that never began. A
+            // cancellation that belonged to that start goes with it: it was never a cancellation of
+            // the next run.
+            this.starting = false;
+            this.pendingCancel = false;
+            if (this.startPromise === pending)
+                this.startPromise = undefined;
+            if (!handedOver)
+                this.releaseWorkspace();
+        }
+    }
+    /** The run itself, once the slot is held. */
+    async begin(options, permissions) {
+        const directory = options.directory ?? this.defaults.directory ?? configDirectory();
+        // The workspace is resolved before anything is written: the records name the directory the
+        // run really works in, and a path that is not one would be recorded before the tools failed.
+        const workspace = await canonicalWorkspace(options.workspace);
+        const config = await (this.defaults.loadConfig ?? loadConfig)(directory);
+        const { provider, model } = resolveSubagentProvider(config, options);
+        // The process-wide reservation: another engine in this process — a second backend of an
+        // embedded host, or the app server over the same project — is already working in this
+        // workspace, and two full-access runs would write to the same files at once. It is taken
+        // here, once the workspace is known, and the check and the claim are one step, so two starts
+        // cannot both pass it.
+        if (!claimProcessWorkspace(workspace, this.reservationId))
+            throw new SubagentRunInProgressError();
+        this.reservedWorkspace = workspace;
+        const telemetryRunId = randomUUID();
+        // Resolved once, before the record is written: the start, the finish and the drains must all
+        // ask the gate for the account that owns this run, or a shared installation answers with
+        // whichever account most recently confirmed a plan.
+        const accountSubject = await currentGraphSubject().catch(() => undefined);
+        const run = {
+            runId: randomUUID(), sessionId: randomUUID(), task: options.task, workspace, directory, telemetryRunId,
+            ...(accountSubject === undefined ? {} : { accountSubject }),
+            jevEnabled: config.jevEnabled !== false, decisionRouting: config.decisions?.mode ?? 'off',
+            providerId: provider.id, model, permissions, controller: new AbortController(), startedAt: new Date().toISOString(),
+            events: [], notices: [], journal: Promise.resolve(), finished: Promise.resolve(),
+            probeUsage: { requests: 0, inputTokens: 0, outputTokens: 0 }, probeModels: new Map(),
+            providerType: provider.type, baseUrl: provider.baseUrl,
+        };
+        // The claim lands before any preflight: a crash between here and finalize leaves exactly the
+        // record recovery knows how to classify.
+        const openRecord = {
+            id: run.runId, status: 'running', sessionId: run.sessionId, startedAt: run.startedAt, pid: process.pid,
+            graphSelection: SUBAGENT_GRAPH_ID, graph: { id: SUBAGENT_GRAPH_ID }, provider: provider.id, model,
+            // The account this attempt was started under travels with the record: recovery on a shared
+            // installation would otherwise gate the finish with whichever cached account is newest.
+            ...(accountSubject === undefined ? {} : { accountSubject }),
+            // A CLI or app-server recovery may find this record in the shared home; the finish it
+            // reports must still be labeled with the subagent surface that produced the start.
+            surface: 'subagent',
+            // `startSent` stays false until the start is queued below; a crash in between owes the
+            // missing start as well as the finish, and recovery reads this flag to decide that.
+            telemetry: { runId: telemetryRunId, nodes: 1, subagents: false, jevEnabled: config.jevEnabled !== false, decisionRouting: config.decisions?.mode ?? 'off', startSent: false },
+            // The marker travels with the open record as well as the terminal one: a crash before
+            // the finalization rewrites this record as interrupted, and it must still say that the
+            // attempt was a subagent run.
+            subagent: true,
+            // The permission the host bound this attempt to. A read-only subagent that is later
+            // resumed must not come back as a full-access run: the workspace's own setting is not
+            // the host's instruction, and the host is the one that prohibited the mutations.
+            permissions: run.permissions,
+        };
+        try {
+            await writeOpenRunRecord(directory, openRecord);
+        }
+        catch (error) {
+            // A partial claim would be classified as an interrupted attempt that never ran.
+            await removeOpenRunRecord(directory, run.runId).catch(() => { });
+            // The filesystem code travels with the message: a storage failure is told to the host as a
+            // storage problem, and a plain error would answer as a general backend one.
+            const code = error && typeof error === 'object' && 'code' in error ? error.code : undefined;
+            throw Object.assign(new Error(`Could not write the subagent run record: ${error instanceof Error ? error.message : String(error)}`), typeof code === 'string' ? { code } : {}, error instanceof Error ? { cause: error } : {});
+        }
+        run.telemetryHandle = createRunHandle(run.telemetryRunId, run.startedAt, {
+            graphId: SUBAGENT_GRAPH_ID, nodes: 1, subagents: false, permissionMode: run.permissions,
+            jevEnabled: run.jevEnabled, decisionRouting: run.decisionRouting,
+        }, workspace);
+        run.telemetryStart = reportRunStarted({ home: directory, config, surface: 'subagent', ...(run.accountSubject === undefined ? {} : { subject: run.accountSubject }) }, run.telemetryHandle).catch(() => { });
+        // Stamp the queue result into the record before the work starts: after this point a crash is
+        // recovered from a start that exists, and recovery must not synthesize a second one.
+        await run.telemetryStart;
+        await writeOpenRunRecord(directory, {
+            ...openRecord,
+            telemetry: { ...openRecord.telemetry, startSent: run.telemetryHandle.started !== false },
+        }).catch(() => { });
+        // The session exists before the work does: a crash between here and the finalization
+        // leaves a session with a running turn, which is what the recovery repairs.
+        try {
+            await this.saveSession(run, { summary: RUNNING_TURN_SUMMARY, tests: [], status: 'running' });
+        }
+        catch (error) {
+            // The claim and the record both name a process that never ran, and nothing else would clear
+            // either: a record left behind is an attempt the Runs view lists, and its live pid tells the
+            // recovery that another process owns it.
+            await removeOpenRunRecord(directory, run.runId).catch(() => { });
+            // The start already left; the run is accepted but ended before executing, so it owes the
+            // finish that joins it rather than leaving an unmatched start on the spool.
+            await run.telemetryStart;
+            // Same account and dimensions as the start: a shared installation must not let a newer
+            // account's cached plan decide whether this run's finish is queued.
+            await reportRunFinished({ home: directory, config, surface: 'subagent', ...(run.accountSubject === undefined ? {} : { subject: run.accountSubject }) }, run.telemetryHandle ?? createRunHandle(run.telemetryRunId, run.startedAt, { graphId: SUBAGENT_GRAPH_ID, nodes: 1, subagents: false, permissionMode: run.permissions,
+                jevEnabled: run.jevEnabled, decisionRouting: run.decisionRouting }), { status: 'infrastructure_error', reason: 'The subagent session record could not be saved.' }).catch(() => { });
+            throw error;
+        }
+        this.active = run;
+        // A cancellation that arrived while the run was starting applies to it now.
+        if (this.pendingCancel) {
+            this.pendingCancel = false;
+            run.controller.abort(new Error('Cancelled by the calling agent'));
+        }
+        run.finished = this.execute(config, run, options).catch(() => { });
+        return { runId: run.runId, sessionId: run.sessionId, provider: provider.id, model, permissions, startedAt: run.startedAt };
+    }
+    status() {
+        const run = this.active;
+        if (!run)
+            return { state: 'idle', events: [] };
+        return {
+            runId: run.runId, sessionId: run.sessionId, state: run.outcome ? run.outcome.status : 'running',
+            provider: run.providerId, model: run.model, permissions: run.permissions,
+            currentNode: run.currentNode, events: run.events.slice(-25),
+            ...(run.notices.length === 0 ? {} : { notices: run.notices.slice(-10) }),
+            ...(run.outcome?.reason !== undefined ? { reason: run.outcome.reason } : {}),
+        };
+    }
+    /** Wait up to `waitMs` for the run; a finished run stays answerable until the next start. */
+    async result(waitMs = 0) {
+        const run = this.active;
+        if (!run)
+            throw new Error('No subagent run has been started in this process.');
+        if (!run.outcome && waitMs > 0)
+            await this.awaitOutcome(run, waitMs);
+        if (!run.outcome)
+            return { state: 'running' };
+        return { state: 'finished', status: run.outcome.status,
+            ...(run.outcome.result !== undefined ? { result: run.outcome.result } : {}),
+            ...(run.outcome.reason !== undefined ? { reason: run.outcome.reason } : {}) };
+    }
+    cancel() {
+        const run = this.active;
+        if (run && !run.outcome && !run.executed) {
+            run.controller.abort(new Error('Cancelled by the calling agent'));
+            return true;
+        }
+        // A cancellation that arrives while a start is preparing belongs to that start: it has no run
+        // to abort yet, and it would otherwise go on to spend tokens. A run that has already finished
+        // is not the one being cancelled either — the replacement that is preparing is, and a
+        // cancellation dropped here would leave it to go on with billable, full-access work after the
+        // caller asked it to stop.
+        if ((!run || run.outcome !== undefined) && this.starting) {
+            this.pendingCancel = true;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * End the run this process owns and wait for it to finish.
+     *
+     * The run finalizes itself: it writes the session and the terminal record, and clears the
+     * open-run claim. A caller that closes while the run works waits for that, so the records it
+     * leaves behind are the ones of a finished attempt rather than of a half-written one.
+     */
+    async shutdown() {
+        // A start that has not reached the runner yet must not begin: the connection that asked for it
+        // is gone, and nothing would ever cancel the run it launches.
+        this.closed = true;
+        // A start that is still preparing has no run to abort yet, and it would otherwise launch a
+        // run after the connection that asked for it is gone. The start is awaited here, marked
+        // cancelled while it waits, and the run it produces is cancelled and awaited in turn, so no
+        // provider request or tool call outlives the controlling connection.
+        if (this.startPromise) {
+            this.pendingCancel = true;
+            await this.startPromise.catch(() => { });
+        }
+        const run = this.active;
+        if (!run)
+            return;
+        this.cancel();
+        // A run that already finished still owns what it spawned: a QA terminal it left behind keeps
+        // the process alive behind that child, and closing the connection does not close it.
+        this.release(run);
+        await run.finished.catch(() => { });
+    }
+    /**
+     * Wait for the run, up to `waitMs`.
+     *
+     * The timer is cleared when the run wins, so a run that finished early does not keep the
+     * process alive for the rest of the wait, and repeated waits do not pile timers up.
+     */
+    async awaitOutcome(run, waitMs) {
+        let timer;
+        const timeout = new Promise(resolve => {
+            timer = setTimeout(resolve, Math.min(waitMs, 60_000));
+            timer.unref?.();
+        });
+        try {
+            await Promise.race([run.finished, timeout]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+    /**
+     * Record one runtime event, and hand back the journal write that carries it.
+     *
+     * The returned promise is what makes the event durable before the run moves on: the runtime
+     * awaits the callback it was given, so a caller that awaits this waits for the append — and for
+     * every append queued before it — to land. Without that the runtime would advance past a
+     * mutating tool call whose event was still queued, and a kill in that window would leave a
+     * journal that omits the completed call: a resume of that attempt would replay to a position
+     * before the call and repeat its effects.
+     */
+    observe(run, event) {
+        const data = event.data;
+        const node = typeof data.nodeId === 'string' ? data.nodeId : typeof data.node === 'string' ? data.node : undefined;
+        run.events.push({ type: event.type, time: event.time, ...(node !== undefined ? { node } : {}) });
+        if (run.events.length > 200)
+            run.events.splice(0, run.events.length - 200);
+        if (event.type === 'graph.node.started' && typeof data.nodeId === 'string')
+            run.currentNode = data.nodeId;
+        // The journal keeps the order the events happened in, and the runtime awaits the callback for
+        // exactly that reason: the writes are chained rather than launched side by side, because the
+        // filesystem does not finish them in the order they were started.
+        run.journal = run.journal
+            .then(() => appendFile(runRecordPath(run.directory, run.runId, 'jsonl'), JSON.stringify(event) + '\n', { mode: 0o600 }))
+            .catch(async (error) => {
+            // The run keeps going — a storage hiccup must not kill the work — but the journal is no
+            // longer a complete account: the events after this failure are written, so nothing in the
+            // file itself reveals the hole. Left unmarked, a crashed attempt would replay to a
+            // position missing whatever this append ate, and a resume would repeat that work.
+            run.journalFailed = true;
+            await noteJournalWriteFailure(run.directory, run.runId, error instanceof Error ? error.message : String(error)).catch(() => { });
+        });
+        return run.journal;
+    }
+    /**
+     * Record what the run could not set up, and publish it.
+     *
+     * The notice is a fact about the attempt, not a log line: the run continues without the
+     * capability, and the caller can only see that from the run's own observable path.
+     */
+    notice(run, message) {
+        run.notices.push(message);
+        if (run.notices.length > 50)
+            run.notices.splice(0, run.notices.length - 50);
+        this.observe(run, { type: 'subagent.notice', time: new Date().toISOString(), data: { message } });
+    }
+    async execute(config, run, options) {
+        const signal = run.controller.signal;
+        let result;
+        let failure;
+        let mcp;
+        let codeIntel;
+        /** The repository's learned command guidance, when the installation keeps it. */
+        let commandMemory;
+        /** The checkpoint writes, chained so the newest conversation is the file's content. */
+        let checkpointWrites = Promise.resolve();
+        try {
+            const graph = validateGraph(await (options.loadGraph ?? loadAccessibleGraph)(SUBAGENT_GRAPH_ID, signal), { providers: config.providers, defaultProvider: config.provider, spawnAvailable: true });
+            // The preflight must probe the model the run will call: the node pins no model, so it
+            // runs on this run provider and model, not on the installation default.
+            const healthConfig = {
+                ...config,
+                provider: run.providerId,
+                providers: config.providers.map(item => {
+                    if (item.id !== run.providerId)
+                        return item;
+                    // The selected model is not the provider's configured one, so the default model's saved
+                    // reasoning and window belong to that model and not to this one: a model that refuses the
+                    // default model's reasoning parameter would fail the probe for a reason the run does not
+                    // have.
+                    return providerForModel(item, run.model);
+                }),
+            };
+            const health = await checkGraphModelHealth(graph, healthConfig, signal, {
+                ...(options.adapterFactory ? { createAdapter: options.adapterFactory } : options.healthDependencies),
+                // The probes are model calls this run pays for, and they happen outside `runGraph`: the
+                // result carries the graph's own calls only, so a run whose totals left the probes out
+                // would report less than it spent — and a probe that reached the provider and failed
+                // would be recorded as having cost nothing at all.
+                onUsage: (delta, reference) => {
+                    foldUsage(run.probeUsage, delta);
+                    options.healthDependencies?.onUsage?.(delta, reference);
+                    const key = `${reference.provider}\0${reference.model}`;
+                    const entry = run.probeModels.get(key) ?? { provider: reference.provider, model: reference.model, usage: {} };
+                    for (const field of ['requests', 'inputTokens', 'outputTokens', 'cacheRead', 'cacheWrite']) {
+                        const value = delta[field];
+                        if (typeof value === 'number')
+                            entry.usage[field] = (entry.usage[field] ?? 0) + value;
+                    }
+                    run.probeModels.set(key, entry);
+                },
+            });
+            if (!health.healthy) {
+                run.healthProviderFailed = health.failures.some(failure => failure.providerError === true);
+                throw new Error(subagentHealthFailure(health));
+            }
+            const runProvider = config.providers.find(item => item.id === run.providerId);
+            // An embedded adapter keeps the run offline; the default path resolves model metadata the
+            // same way the CLI does, so context-window and effort handling match an ordinary session.
+            const resolvedProvider = options.adapterFactory ? { ...runProvider, model: run.model } : await resolveModelContext(runProvider, run.model, signal);
+            const adapterFor = options.adapterFactory ?? createAdapter;
+            const snapshot = await extensionSnapshot(config, signal, run.directory);
+            const instructions = `${await loadWorkspaceInstructions(run.workspace, signal, config.systemPromptOverride)}\n${QA_SYSTEM_GUIDANCE}${snapshot.instructions}`;
+            // The harness needs no hosted membership, and asking for it only adds the delay of a token
+            // refresh and a membership request before a run that is entirely local.
+            const context = {
+                workspace: run.workspace, signal,
+                yolo: run.permissions === 'full-access', permissions: run.permissions, approvalMode: 'headless',
+                approve: async () => false,
+            };
+            if (Object.keys(snapshot.servers).length) {
+                const { connectMcpServers } = await import('./mcp.js');
+                // A server that could not connect, or a catalog that was refused, is told to the
+                // caller: the run continues without those tools, and the host has to know that its
+                // task is running with less than it configured.
+                mcp = await connectMcpServers(snapshot.servers, context, message => this.notice(run, message), signal);
+            }
+            // The run's memory and its decision policy come from the configuration of the home it
+            // runs in: the runner falls back to the process-wide installation otherwise, and the run
+            // would read and write another installation's memory.
+            const memory = await MemoryManager.create({
+                config: resolveMemoryConfig(config), workspace: run.workspace,
+                onEvent: event => this.observe(run, event), getPermissions: () => permissionMode(context),
+            });
+            codeIntel = await this.codeIntelligence(run, config, signal);
+            // The artifacts belong to the home the run works in: the process-wide installation would
+            // hold files the run's own records cannot find.
+            const artifactStore = new ArtifactStore(run.runId, run.directory);
+            // The repository's learned command guidance is the installation's setting, and a subagent
+            // run honours it like any other run.
+            if (config.commandMemory !== false)
+                commandMemory = await LocalToolMemory.open({ workspace: run.workspace, directory: run.directory });
+            // The checkpoints land one at a time, newest last: the runner calls back synchronously from
+            // several nodes, and an unserialized write could leave an older conversation as the file's
+            // final content.
+            const persistCheckpoint = (nodeId, messages, state, meta) => {
+                checkpointWrites = checkpointWrites
+                    .then(() => writeRunCheckpoint(run.directory, run.runId, {
+                    nodeId, messages, state, revision: state.directionRevision, savedAt: new Date().toISOString(),
+                    ...(meta?.generation === undefined ? {} : { generation: meta.generation }),
+                    ...(meta?.provider === undefined ? {} : { provider: meta.provider }),
+                    ...(meta?.model === undefined ? {} : { model: meta.model }),
+                }))
+                    .catch(async (error) => {
+                    // The run keeps going — durability is a convenience, never the run's outcome. But a
+                    // checkpoint that could not be written is the conversation a resume re-enters the
+                    // node with: without it the resume re-enters from the node's opening task and repeats
+                    // the tool calls that already ran. The attempt is therefore marked, and a resume of it
+                    // is refused rather than repeating the work.
+                    run.checkpointFailed = true;
+                    await noteCheckpointWriteFailure(run.directory, run.runId, error instanceof Error ? error.message : String(error)).catch(() => { });
+                });
+                // The write is handed back so the runtime can await it: the checkpoint is the conversation
+                // a resume re-enters the node with, and a run that advanced past a mutating tool call
+                // while its checkpoint was still queued could be killed with that conversation unwritten.
+                return checkpointWrites;
+            };
+            const graphOptions = {
+                task: run.task, runId: run.runId, provider: run.providerId, model: run.model,
+                adapter: adapterFor(resolvedProvider),
+                // The model context window the registry resolved, so the run compacts against the
+                // provider limit rather than the generic one.
+                ...(resolvedProvider.contextWindow === undefined ? {} : { contextWindow: resolvedProvider.contextWindow }),
+                tools: [...createTools(), ...snapshot.tools, ...(mcp?.tools ?? [])],
+                instructions, limits: resolveConfiguredLimits(config), todoStore: new TodoStore(),
+                resolveModel: (id, model, modelSignal) => {
+                    const provider = config.providers.find(item => item.id === id);
+                    if (!provider)
+                        throw new Error(`Unknown provider: ${id}. Use /providers to add or edit providers.`);
+                    // A node that names no model takes the run's own model when it runs on the run's own
+                    // provider: the host chose that pair, and the provider's configured default is a model
+                    // nobody asked for. The preflight and the reported result already use it, so the request
+                    // has to bill the same one.
+                    const wanted = model ?? (id === run.providerId ? run.model : provider.model);
+                    if (options.adapterFactory) {
+                        // The same normalization the preflight and the ordinary path apply: the saved
+                        // reasoning effort and context window belong to the provider's configured model, so an
+                        // embedded adapter is not handed the default model's settings for another one.
+                        return Promise.resolve({ model: wanted, adapter: options.adapterFactory(providerForModel(provider, wanted)), providerType: provider.type, baseUrl: provider.baseUrl });
+                    }
+                    return resolveModelContext(provider, wanted, modelSignal)
+                        .then(resolved => ({ model: resolved.model, adapter: createAdapter(resolved), contextWindow: resolved.contextWindow, providerType: provider.type, baseUrl: provider.baseUrl }));
+                },
+                resolveProvider: id => {
+                    const provider = config.providers.find(item => item.id === id);
+                    if (!provider)
+                        throw new Error(`Unknown provider: ${id}. Use /providers to add or edit providers.`);
+                    // The node pins no model, so it runs on the model this run selected: a provider's
+                    // own default is a model the host never asked for.
+                    const selected = providerForModel(provider, run.model);
+                    return { model: run.model, adapter: adapterFor(selected), contextWindow: selected.contextWindow, providerType: selected.type, baseUrl: selected.baseUrl };
+                },
+                context,
+                artifactStore,
+                ...(commandMemory ? { commandMemory } : {}),
+                memory,
+                decisionManager: new DecisionManager({ config: await subagentDecisionConfig(config, () => (options.membership ?? getMembership)(signal)), onEvent: event => this.observe(run, event) }),
+                decisionNodeOptIn: true,
+                // The code intelligence of the installation this run works in, so the run has the same
+                // repository coverage an ordinary Software Engineer run has.
+                ...(codeIntel ? { codeIntel } : {}),
+                // The checkpoints a resume reads: without them a replay re-enters the node from its
+                // opening task and repeats the writes and shell calls that already ran.
+                onNodeCheckpoint: persistCheckpoint,
+                onEvent: event => this.observe(run, event),
+            };
+            result = await runGraph(graph, graphOptions);
+        }
+        catch (error) {
+            failure = error;
+        }
+        finally {
+            // The work is over: from here the run only writes its records, and a cancellation would be
+            // reported as accepted while the run publishes what it did.
+            run.executed = true;
+            // The checkpoints are drained before the attempt is published: a resume that reads a
+            // half-written checkpoint would replay the node from its opening task.
+            await checkpointWrites.catch(() => { });
+            await mcp?.close().catch(() => { });
+            await codeIntel?.dispose().catch(() => { });
+            await this.finalize(run, result, failure);
+        }
+    }
+    /** The session record for a run: the turn it is running, or the one it finished. */
+    async saveSession(run, completion, usage = { requests: 0, inputTokens: 0, outputTokens: 0 }, updatedAt = new Date().toISOString()) {
+        await new SessionStore(run.directory).save({
+            version: 1, id: run.sessionId, name: sessionName(run.task), workspace: run.workspace, updatedAt,
+            history: [{ task: run.task, completion, runId: run.runId }], usage, projectId: projectIdentity(run.workspace),
+        });
+    }
+    async finalize(run, result, failure) {
+        const status = result?.status ?? (run.controller.signal.aborted ? 'cancelled' : 'infrastructure_error');
+        const reason = result?.reason ?? (failure !== undefined ? (failure instanceof Error ? failure.message : String(failure)) : undefined);
+        // The start's own dimensions and account are repeated: the configuration may have changed
+        // while the run was in flight, and a joined pair that reported different JEV/routing settings
+        // would attribute the run to settings it never used.
+        const telemetrySurface = { home: run.directory, surface: 'subagent', ...(run.accountSubject === undefined ? {} : { subject: run.accountSubject }) };
+        const telemetryHandle = run.telemetryHandle ?? createRunHandle(run.telemetryRunId, run.startedAt, {
+            graphId: SUBAGENT_GRAPH_ID, nodes: 1, subagents: false, permissionMode: run.permissions,
+            jevEnabled: run.jevEnabled, decisionRouting: run.decisionRouting,
+        }, run.workspace);
+        let telemetryFinished = false;
+        // The finish is returned so the caller can wait for it: a drain that starts before the finish
+        // is queued exits with the event still on the spool.
+        const settleTelemetry = (settled, why) => {
+            if (telemetryFinished)
+                return Promise.resolve();
+            telemetryFinished = true;
+            // The finish waits for the start: a short run can otherwise drain before the start is queued.
+            // The health probes precede the graph, so their tuples join the capture the finish reports.
+            const finishedTelemetry = result?.telemetry ?? createRunTelemetry();
+            for (const probe of run.probeModels.values()) {
+                recordModelUse(finishedTelemetry, { providerType: run.providerType, baseUrl: run.baseUrl, model: probe.model, role: 'other', usage: probe.usage });
+            }
+            return (run.telemetryStart ?? Promise.resolve()).then(() => reportRunFinished(telemetrySurface, telemetryHandle, {
+                status: settled, ...(why === undefined ? {} : { reason: why }),
+                ...(result?.providerRequestFailed || run.healthProviderFailed ? { providerRequestFailed: true } : {}),
+                ...(result?.providerOverflow ? { providerOverflow: true } : {}),
+                ...(result?.telemetry !== undefined || run.probeModels.size > 0 ? { telemetry: finishedTelemetry } : {}),
+                ...(result?.toolCalls === undefined ? {} : { toolCalls: result.toolCalls }),
+            })).catch(() => { });
+        };
+        const endedAt = new Date().toISOString();
+        const usage = result?.usage ?? { requests: 0, inputTokens: 0, outputTokens: 0 };
+        // The preflight ran outside `runGraph`, so its spend is folded in here: the result carries
+        // the graph's own calls only, and the record and the session report what the attempt cost.
+        foldUsage(usage, run.probeUsage);
+        // The record holds the run's own result, so the Runs view reports its graph, its
+        // completion, its tool calls and its todos, and the subagent identity is laid over it.
+        const record = {
+            ...(result ?? {}),
+            id: run.runId, status, ...(reason !== undefined ? { reason } : {}), graphSelection: SUBAGENT_GRAPH_ID,
+            subagent: true, usage, sessionId: run.sessionId, startedAt: run.startedAt, endedAt,
+            provider: run.providerId, model: run.model,
+            // The permission the host bound the attempt to, so a later resume of it inherits the
+            // restriction rather than the workspace's own current setting.
+            permissions: run.permissions,
+        };
+        // The journal is drained before the record that says the run finished: a record that reports a
+        // completed run while its last events are still being written is a record whose journal tail
+        // may never land.
+        await run.journal.catch(() => { });
+        // The record carries the flag the resume consults when the marker file could not be written:
+        // an attempt whose journal has a hole is never a resume source.
+        if (run.journalFailed)
+            record.journalIntegrity = 'failed';
+        // The same flag for a checkpoint that could not be written: a resume would re-enter the node
+        // from its opening task and repeat the tool calls it had already made.
+        if (run.checkpointFailed)
+            record.checkpointIntegrity = 'failed';
+        // The terminal record is written before the session is finalized. A crash between the two
+        // leaves a session whose turn is still marked running, which the startup recovery repairs
+        // from the record; the other order would leave a session that reports the completion while
+        // the recovery still rewrites the still-open record as interrupted, and a completed turn is
+        // not one the recovery reconciles.
+        try {
+            await writeFile(runRecordPath(run.directory, run.runId, 'json'), JSON.stringify(record, null, 2) + '\n', { mode: 0o600 });
+        }
+        catch (error) {
+            process.stderr.write(`Could not record the stopped subagent run: ${error instanceof Error ? error.message : String(error)}\n`);
+            // The terminal record did not land, and the attempt is still open: the record says the run
+            // is live and the claim holds the session against it. A long-lived server would keep the
+            // attempt in the Runs view and the session locked until the process exited, so the record is
+            // terminalized here, and the claim released once that record landed: the attempt failed,
+            // and it says so.
+            const detail = error instanceof Error ? error.message : String(error);
+            const terminalized = await writeFile(runRecordPath(run.directory, run.runId, 'json'), JSON.stringify({
+                ...record, status: 'infrastructure_error', reason: `The run record could not be written: ${detail}`, endedAt,
+            }, null, 2) + '\n', { mode: 0o600 }).then(() => true, () => false);
+            // The sidecar carries the same projection the ordinary finalizer writes: it is newer than the
+            // record, and Graph Studio prefers it, so a sidecar without the graph and the tool calls
+            // would report a null for both.
+            // The sidecar is published only when the terminal record landed: it is newer than the
+            // record, and a sidecar that says the attempt is terminal while the record still says the
+            // run is live would make Graph Studio report an attempt that is not.
+            if (terminalized) {
+                await writeStudioRunSummary(run.directory, {
+                    id: run.runId, status: 'infrastructure_error', startedAt: run.startedAt, graphSelection: SUBAGENT_GRAPH_ID,
+                    ...(result?.graph ? { graph: result.graph } : {}),
+                    ...(typeof result?.toolCalls === 'number' ? { toolCalls: result.toolCalls } : {}),
+                }).catch(() => { });
+            }
+            // The session is landed before the claim is given back. The claim is what holds the session
+            // against a mutation, and a rename, archive or delete accepted in that window would be
+            // overwritten by the save below — or, if that save fails, left behind with the session
+            // still marked running. A save that fails is repaired from the record, the way the normal
+            // path repairs it.
+            try {
+                await this.saveSession(run, { summary: `The run finished, but its record could not be written: ${detail}`, tests: [], status: 'infrastructure_error' }, usage, endedAt);
+            }
+            catch {
+                await repairSessionMarkers(run.directory, run.sessionId).catch(() => { });
+            }
+            // The claim is released only when the terminal record landed. A record that still says the
+            // run is live, with no claim to say so, is a history that contradicts itself — and when
+            // even that write fails, the claim stays and the recovery classifies the attempt once
+            // this process is gone, which is the answer that is true rather than one that reads well.
+            if (terminalized)
+                await clearOpenRunClaim(run.directory, run.runId).catch(() => { });
+            // The reservation is given back before the outcome is published: a caller that reads the
+            // outcome must be able to start the next run in the same workspace.
+            this.releaseWorkspace();
+            this.release(run);
+            await settleTelemetry('infrastructure_error', `The run record could not be written: ${detail}`);
+            await drainTelemetry(telemetrySurface).catch(() => { });
+            run.outcome = { status: 'infrastructure_error', reason: `The run record could not be written: ${detail}` };
+            return;
+        }
+        // A finished run has nothing to resume, so its durable conversation goes with it: a checkpoint
+        // file holds the node's whole message history — tool outputs included — and repeated subagent
+        // runs would accumulate all of it under `runs/` for ever. The ordinary CLI and app-server
+        // finalizers delete it for the same reason. A stopped attempt keeps its checkpoint: that one
+        // is what a resume re-enters the node with.
+        if (status === 'succeeded')
+            await removeRunCheckpoint(run.directory, run.runId).catch(() => { });
+        try {
+            // A stopped run's completion says how it stopped: an absent status is read as a success.
+            const completion = result?.completion ?? {
+                summary: summaryForStoppedRecord(record),
+                tests: [],
+                ...(status === 'succeeded' ? {} : { status }),
+            };
+            await this.saveSession(run, completion, usage, endedAt);
+        }
+        catch (error) {
+            // The record says how the attempt ended and the session's turn is still marked running. The
+            // repair belongs to the session now, not to the next start: a long-lived server would leave
+            // the turn unfinished until it was restarted.
+            await repairSessionMarkers(run.directory, run.sessionId).catch(() => { });
+            process.stderr.write(`Could not save the subagent session: ${error instanceof Error ? error.message : String(error)}\n`);
+        }
+        // The studio sidecar carries the same projection the ordinary run finalizers write, so Graph
+        // Studio reports the run's graph and its tool calls rather than a null for both.
+        await writeStudioRunSummary(run.directory, {
+            id: run.runId, status, startedAt: run.startedAt, graphSelection: SUBAGENT_GRAPH_ID,
+            ...(result?.graph ? { graph: result.graph } : {}),
+            ...(typeof result?.toolCalls === 'number' ? { toolCalls: result.toolCalls } : {}),
+        }).catch(() => { });
+        await clearOpenRunClaim(run.directory, run.runId).catch(() => { });
+        // The reservation is given back before the outcome is published: a caller that reads the
+        // outcome must be able to start the next run in the same workspace.
+        this.releaseWorkspace();
+        // The run is over, and what it owns is tied to its signal: a QA terminal it spawned and did
+        // not kill keeps the process alive behind that child, so the CLI would print its result and
+        // never exit. Releasing the signal closes them, and the outcome is already decided.
+        this.release(run);
+        await settleTelemetry(status, reason);
+        await drainTelemetry(telemetrySurface).catch(() => { });
+        run.outcome = { status, ...(result !== undefined ? { result } : {}), ...(reason !== undefined ? { reason } : {}) };
+    }
+    /**
+     * The signal the run's own resources are tied to.
+     *
+     * A run releases it when it ends: a QA terminal it spawned and did not kill stays open behind
+     * its child, and the process would not exit. The signal is what closes it, so this is how a
+     * caller sees that the run has let go of what it owned.
+     */
+    runSignal() {
+        return this.active?.controller.signal;
+    }
+    /**
+     * Release what the run owns.
+     *
+     * The run's signal is what its QA terminals and other run-scoped resources are tied to, and a
+     * finished run never releases it on its own: only a cancellation aborts it. A run that succeeded
+     * with a terminal still open would keep the process alive behind that child.
+     */
+    /**
+     * The code intelligence the run works with.
+     *
+     * The manager takes its own read-only branch and its own disabled branch, so it is always
+     * created; what matters is that both guards reach it rather than indexing by default.
+     */
+    async codeIntelligence(run, config, signal) {
+        if (signal.aborted)
+            return undefined;
+        const configured = resolveCodeIntelConfig(config);
+        const homeWorkspace = run.workspace === await realpath(homedir()).catch(() => homedir());
+        const effective = homeWorkspace ? { ...configured, enabled: false, enabledRepos: [] } : configured;
+        return await CodeIntelligenceManager.create({ workspace: run.workspace, config: effective, permissions: run.permissions === 'full-access' ? 'full-access' : 'read-only', onEvent: event => this.observe(run, event) });
+    }
+    release(run) {
+        if (run.controller.signal.aborted)
+            return;
+        run.controller.abort(new Error('The subagent run has finished.'));
+    }
+    /**
+     * Give the process-wide reservation back.
+     *
+     * Only the holder gives it back: a runner whose start failed releases nothing that another
+     * runner has taken since.
+     */
+    releaseWorkspace() {
+        const workspace = this.reservedWorkspace;
+        if (workspace === undefined)
+            return;
+        releaseProcessWorkspace(workspace, this.reservationId);
+        this.reservedWorkspace = undefined;
+    }
+}