voratiq 0.1.0-beta.2 → 0.1.0-beta.21

package/dist/commands/root-launcher/command.js

@@ -0,0 +1,233 @@
+import process from "node:process";
+import { CliError } from "../../cli/errors.js";
+import { writeCommandOutput, } from "../../cli/output.js";
+import { loadAgentCatalogDiagnostics } from "../../configs/agents/loader.js";
+import { prepareNativeInteractiveSession, spawnPreparedInteractiveSession, } from "../../interactive/index.js";
+import { resolveCliContext } from "../../preflight/index.js";
+import { renderRootLauncherInvalidSelection, renderRootLauncherLaunchStart, renderRootLauncherMcpInstallStart, renderRootLauncherMcpInstallSuccess, renderRootLauncherSelectionScreen, renderRootLauncherSingleAgentScreen, } from "../../render/transcripts/root-launcher.js";
+import { renderWorkspaceAutoInitializedNotice } from "../../render/transcripts/shared.js";
+import { createEntrypointVoratiqCliTarget } from "../../utils/voratiq-cli-target.js";
+export async function runRootLauncherCommand(options) {
+    const { resolveContext = resolveCliContext, loadDiagnostics = loadAgentCatalogDiagnostics, createWorkflow, prepareSession = prepareNativeInteractiveSession, spawnSession = spawnPreparedInteractiveSession, selfCliTarget = createEntrypointVoratiqCliTarget({
+        cliEntrypoint: process.argv[1],
+    }), writeOutput = writeCommandOutput, } = options;
+    const createRootLauncherWorkflow = createWorkflow ??
+        (() => {
+            throw new Error("Missing root launcher workflow factory.");
+        });
+    const setup = await setupRootLauncher({
+        resolveContext,
+        loadDiagnostics,
+        writeOutput,
+    });
+    const workflow = createRootLauncherWorkflow({
+        onUnavailable: () => {
+            throw new CliError("An interactive terminal is required to launch a native agent session.", [], [
+                "Run `voratiq` from an interactive terminal, or use an explicit subcommand instead.",
+            ]);
+        },
+    });
+    let workflowClosed = false;
+    const closeWorkflow = () => {
+        if (!workflowClosed) {
+            workflow.close();
+            workflowClosed = true;
+        }
+    };
+    try {
+        const promptResult = await promptForLaunchPlan({
+            availability: setup.availability,
+            prompt: (promptOptions) => workflow.prompt(promptOptions),
+            writeOutput,
+        });
+        const qaInitialPrompt = resolveQaInitialPrompt();
+        let acceptedMcpInstallPrompt = false;
+        const prepared = await prepareFirstPartyInteractiveSession({
+            root: setup.root,
+            selected: promptResult.selected,
+            prepareSession,
+            selfCliTarget,
+            prompt: qaInitialPrompt,
+            promptForMcpInstall: async (promptOptions) => {
+                const accepted = await workflow.confirm({
+                    message: promptOptions.message,
+                    defaultValue: promptOptions.defaultValue,
+                    prefaceLines: ["", ...(promptOptions.prefaceLines ?? [])],
+                });
+                if (accepted) {
+                    acceptedMcpInstallPrompt = true;
+                    writeLauncherNotice(writeOutput, renderRootLauncherMcpInstallStart());
+                }
+                return accepted;
+            },
+        });
+        if (!prepared.ok) {
+            throw new CliError(`Failed to launch ${formatAgentLabel(promptResult.selected.entry)}.`, [prepared.failure.message]);
+        }
+        if (acceptedMcpInstallPrompt) {
+            writeLauncherNotice(writeOutput, renderRootLauncherMcpInstallSuccess());
+        }
+        closeWorkflow();
+        const started = await launchFirstPartyInteractiveSession({
+            selected: promptResult.selected,
+            prepared: prepared.prepared,
+            spawnSession,
+            writeOutput,
+        });
+        await finalizeLaunchResult(started.selected, started.launchResult);
+    }
+    finally {
+        closeWorkflow();
+    }
+}
+async function setupRootLauncher(options) {
+    const { resolveContext, loadDiagnostics, writeOutput } = options;
+    const context = await resolveContext({
+        requireWorkspace: true,
+        workspaceAutoInitMode: "when-missing",
+    });
+    if (context.workspaceAutoInitialized) {
+        writeLauncherNotice(writeOutput, renderWorkspaceAutoInitializedNotice());
+    }
+    const diagnostics = loadDiagnostics({ root: context.root });
+    assertEnabledAgents(diagnostics);
+    const availability = buildLauncherAvailability(diagnostics);
+    if (availability.launchable.length === 0) {
+        throw buildNoLaunchableAgentsError(availability.unavailable);
+    }
+    return {
+        root: context.root,
+        availability,
+    };
+}
+function assertEnabledAgents(diagnostics) {
+    if (diagnostics.enabledAgents.length > 0) {
+        return;
+    }
+    throw new CliError("No enabled agents found.", [], [
+        "Add agents to `.voratiq/agents.yaml` or run `voratiq init` to set up your workspace.",
+    ]);
+}
+function buildLauncherAvailability(diagnostics) {
+    const issuesByAgentId = new Map();
+    for (const issue of diagnostics.issues) {
+        const current = issuesByAgentId.get(issue.agentId) ?? [];
+        current.push(issue.message);
+        issuesByAgentId.set(issue.agentId, current);
+    }
+    const resolvableAgentIds = new Set(diagnostics.catalog.map((agent) => agent.id));
+    const launchable = [];
+    const unavailable = [];
+    for (const entry of diagnostics.enabledAgents) {
+        const reasons = issuesByAgentId.get(entry.id) ?? [];
+        if (reasons.length === 0 && resolvableAgentIds.has(entry.id)) {
+            launchable.push({ entry });
+            continue;
+        }
+        unavailable.push({
+            entry,
+            reasons: reasons.length > 0
+                ? reasons
+                : ["agent definition could not be resolved"],
+        });
+    }
+    return { launchable, unavailable };
+}
+async function promptForLaunchPlan(options) {
+    const { availability, prompt, writeOutput } = options;
+    const selected = availability.launchable.length === 1
+        ? availability.launchable[0]
+        : await promptForAgentSelection({
+            launchable: availability.launchable,
+            unavailable: availability.unavailable,
+            prompt: (promptOptions) => prompt(promptOptions),
+            writeOutput,
+        });
+    if (availability.launchable.length === 1) {
+        writeLauncherNotice(writeOutput, renderRootLauncherSingleAgentScreen({
+            selected: formatAgentLabel(selected.entry),
+            unavailable: availability.unavailable.map((agent) => ({
+                label: formatAgentLabel(agent.entry),
+                reasons: agent.reasons,
+            })),
+        }));
+    }
+    return { selected };
+}
+async function promptForAgentSelection(options) {
+    const { launchable, unavailable, prompt, writeOutput } = options;
+    writeLauncherNotice(writeOutput, renderRootLauncherSelectionScreen({
+        launchable: launchable.map((agent) => ({
+            label: formatAgentLabel(agent.entry),
+        })),
+        unavailable: unavailable.map((agent) => ({
+            label: formatAgentLabel(agent.entry),
+            reasons: agent.reasons,
+        })),
+    }));
+    for (;;) {
+        const response = await prompt({ message: `[1-${launchable.length}]` });
+        const parsed = Number.parseInt(response.trim(), 10);
+        if (Number.isInteger(parsed) &&
+            parsed >= 1 &&
+            parsed <= launchable.length) {
+            return launchable[parsed - 1];
+        }
+        writeLauncherNotice(writeOutput, renderRootLauncherInvalidSelection(launchable.length));
+    }
+}
+async function prepareFirstPartyInteractiveSession(options) {
+    const { root, selected, prepareSession, selfCliTarget, prompt, promptForMcpInstall, } = options;
+    return await prepareSession({
+        root,
+        cwd: root,
+        agentId: selected.entry.id,
+        launchMode: "first-party",
+        prompt,
+        ...(selfCliTarget ? { voratiqCliTarget: selfCliTarget } : {}),
+        promptForMcpInstall: async (promptOptions) => await promptForMcpInstall({
+            message: promptOptions.message,
+            defaultValue: promptOptions.defaultValue,
+            prefaceLines: promptOptions.prefaceLines,
+        }),
+    });
+}
+async function launchFirstPartyInteractiveSession(options) {
+    const { selected, prepared, spawnSession, writeOutput } = options;
+    writeLauncherNotice(writeOutput, renderRootLauncherLaunchStart(formatAgentLabel(selected.entry)), {
+        leadingNewline: true,
+    });
+    const launchResult = await spawnSession(prepared, { stdio: "inherit" });
+    return { selected, launchResult };
+}
+function writeLauncherNotice(writeOutput, message, options = {}) {
+    writeOutput({
+        alerts: [{ severity: "info", message: message.trimEnd() }],
+        leadingNewline: options.leadingNewline ?? false,
+    });
+}
+async function finalizeLaunchResult(selected, launchResult) {
+    if (!launchResult.ok) {
+        throw new CliError(`Failed to launch ${formatAgentLabel(selected.entry)}.`, [launchResult.failure.message]);
+    }
+    const completedRecord = await launchResult.completion;
+    if (completedRecord.status === "failed") {
+        process.exitCode = 1;
+    }
+}
+function buildNoLaunchableAgentsError(unavailable) {
+    const detailLines = [
+        "Enabled agents with blocking issues:",
+        ...unavailable.map((agent) => `  - ${formatAgentLabel(agent.entry)}: ${agent.reasons.join("; ")}`),
+    ];
+    return new CliError("No enabled agents can be launched.", detailLines, [
+        "Fix the blocking agent configuration in `.voratiq/agents.yaml`, then retry.",
+    ]);
+}
+function formatAgentLabel(agent) {
+    return `${agent.id} (${agent.provider} / ${agent.model})`;
+}
+function resolveQaInitialPrompt() {
+    const prompt = process.env.VORATIQ_QA_INITIAL_PROMPT?.trim();
+    return prompt && prompt.length > 0 ? prompt : undefined;
+}

package/dist/commands/run/command.d.ts

@@ -1,11 +1,16 @@
-import type { RunReport } from "../../records/types.js";
+import type { ResolvedExtraContextFile } from "../../competition/shared/extra-context.js";
+import type { RunReport } from "../../domain/run/model/types.js";
 import type { RunProgressRenderer } from "../../render/transcripts/run.js";
 export interface RunCommandInput {
     root: string;
     runsFilePath: string;
     specAbsolutePath: string;
     specDisplayPath: string;
+    agentIds?: readonly string[];
+    agentOverrideFlag?: string;
+    profileName?: string;
     maxParallel?: number;
+    extraContextFiles?: readonly ResolvedExtraContextFile[];
     renderer?: RunProgressRenderer;
 }
 /**

package/dist/commands/run/command.js

@@ -1,33 +1,48 @@
-import { createAgentRecordMutators } from "../../records/mutators.js";
-import { flushRunRecordBuffer, rewriteRunRecord, } from "../../records/persistence.js";
-import { toError } from "../../utils/errors.js";
+import { teardownSessionAuth } from "../../agents/runtime/registry.js";
+import { createTeardownController } from "../../competition/shared/teardown.js";
+import { executeAgents } from "../../domain/run/competition/agent-execution.js";
+import { RunCommandError, RunProcessStreamError, } from "../../domain/run/competition/errors.js";
+import { toRunReport } from "../../domain/run/competition/reports.js";
+import { generateRunId } from "../../domain/run/model/id.js";
+import { createAgentRecordMutators, mergeAgentRecords, } from "../../domain/run/model/mutators.js";
+import { flushRunRecordBuffer, rewriteRunRecord, } from "../../domain/run/persistence/adapter.js";
+import { buildRecordLifecycleCompleteFields } from "../../domain/shared/lifecycle.js";
+import { buildPersistedExtraContextFields } from "../../extra-context/contract.js";
+import { deriveRunStatusFromAgents } from "../../status/index.js";
+import { toErrorMessage } from "../../utils/errors.js";
 import { normalizePathForDisplay, relativeToRoot } from "../../utils/path.js";
 import { buildAgentWorkspacePaths, formatRunWorkspaceRelative, } from "../../workspace/layout.js";
 import { prepareRunWorkspace } from "../../workspace/run.js";
-import { executeAgents } from "./agent-execution.js";
-import { generateRunId } from "./id.js";
-import { clearActiveRun, registerActiveRun } from "./lifecycle.js";
+import { resolveStageCompetitors } from "../shared/resolve-stage-competitors.js";
+import { finalizeActiveRun, registerActiveRun } from "./lifecycle.js";
 import { initializeRunRecord } from "./record-init.js";
-import { toRunReport } from "./reports.js";
-import { teardownRunSandboxes } from "./sandbox-registry.js";
 import { validateAndPrepare } from "./validation.js";
 /**
  * Execute a complete run: validate inputs, prepare workspace, execute agents, and finalize report.
  */
 export async function executeRunCommand(input) {
-    const { root, runsFilePath, specAbsolutePath, specDisplayPath, maxParallel: requestedMaxParallel, renderer, } = input;
+    const { root, runsFilePath, specAbsolutePath, specDisplayPath, agentIds, agentOverrideFlag, profileName, maxParallel: requestedMaxParallel, extraContextFiles = [], renderer, } = input;
+    const resolution = resolveStageCompetitors({
+        root,
+        stageId: "run",
+        cliAgentIds: agentIds,
+        cliOverrideFlag: agentOverrideFlag,
+        profileName,
+        includeDefinitions: false,
+    });
     const validation = await validateAndPrepare({
         root,
         specAbsolutePath,
+        resolvedAgentIds: resolution.agentIds,
         maxParallel: requestedMaxParallel,
     });
     const runId = generateRunId();
-    const createdAt = new Date().toISOString();
+    const startedAt = new Date().toISOString();
+    const createdAt = startedAt;
     const repoDisplayPath = normalizePathForDisplay(relativeToRoot(root, root));
     const { runWorkspace } = await prepareRunWorkspace({
         root,
         runId,
-        prompt: validation.prompt,
     });
     const runRoot = runWorkspace.absolute;
     const { recordPersisted } = await initializeRunRecord({
@@ -38,7 +53,17 @@ export async function executeRunCommand(input) {
         baseRevisionSha: validation.baseRevisionSha,
         repoDisplayPath,
         createdAt,
+        startedAt,
         runRoot,
+        ...buildPersistedExtraContextFields(extraContextFiles),
+    });
+    const teardown = createTeardownController(`run \`${runId}\``);
+    teardown.addAction({
+        key: `run-auth:${runId}`,
+        label: "session auth",
+        cleanup: async () => {
+            await teardownSessionAuth(runId);
+        },
     });
     const agentAbortContexts = validation.agents.map((agent) => {
         const workspacePaths = buildAgentWorkspacePaths({
@@ -46,6 +71,7 @@ export async function executeRunCommand(input) {
             runId,
             agentId: agent.id,
         });
+        registerRunWorkspaceTeardown(teardown, workspacePaths, agent.id);
         return {
             agentId: agent.id,
             providerId: agent.provider,
@@ -56,16 +82,16 @@ export async function executeRunCommand(input) {
         root,
         runsFilePath,
         runId,
+        teardown,
         agents: agentAbortContexts,
     });
     if (renderer) {
         renderer.begin({
             runId,
             status: "running",
-            specPath: specDisplayPath,
             workspacePath: formatRunWorkspaceRelative(runId),
             createdAt,
-            baseRevisionSha: validation.baseRevisionSha,
+            startedAt,
         });
     }
     const mutators = createAgentRecordMutators({
@@ -76,7 +102,6 @@ export async function executeRunCommand(input) {
     });
     let agentRecords = [];
     let executionError;
-    let cleanupError;
     let runReport;
     try {
         const executionResult = await executeAgents({
@@ -84,17 +109,14 @@ export async function executeRunCommand(input) {
             baseRevisionSha: validation.baseRevisionSha,
             runId,
             root,
-            evalPlan: validation.evalPlan,
+            specContent: validation.specContent,
+            extraContextFiles,
             effectiveMaxParallel: validation.effectiveMaxParallel,
             environment: validation.environment,
             mutators,
         });
         agentRecords = executionResult.agentRecords;
-        const derivedRunStatus = executionResult.hadAgentFailure || executionResult.hadEvalFailure
-            ? "failed"
-            : executionResult.agentReports.some((report) => report.status === "errored")
-                ? "errored"
-                : "succeeded";
+        const derivedRunStatus = deriveRunStatusFromAgents(executionResult.agentReports.map((report) => report.status));
         const updatedRunRecord = await rewriteRunRecord({
             root,
             runsFilePath,
@@ -105,13 +127,14 @@ export async function executeRunCommand(input) {
                 }
                 return {
                     ...existing,
-                    agents: agentRecords,
+                    agents: mergeFinalAgentRecords(existing.agents, agentRecords),
                     status: derivedRunStatus,
+                    ...buildRecordLifecycleCompleteFields({ existing }),
                     deletedAt: null,
                 };
             },
         });
-        runReport = toRunReport(updatedRunRecord, executionResult.agentReports, executionResult.hadAgentFailure, executionResult.hadEvalFailure);
+        runReport = toRunReport(updatedRunRecord, executionResult.agentReports, executionResult.hadAgentFailure);
     }
     catch (error) {
         executionError = error;
@@ -127,8 +150,11 @@ export async function executeRunCommand(input) {
                         }
                         return {
                             ...existing,
-                            agents: agentRecords.length > 0 ? agentRecords : existing.agents,
+                            agents: agentRecords.length > 0
+                                ? mergeFinalAgentRecords(existing.agents, agentRecords)
+                                : existing.agents,
                             status: "errored",
+                            ...buildRecordLifecycleCompleteFields({ existing }),
                             deletedAt: null,
                         };
                     },
@@ -140,27 +166,16 @@ export async function executeRunCommand(input) {
         }
     }
     finally {
-        try {
-            await teardownRunSandboxes(runId);
-        }
-        catch (error) {
-            cleanupError = error;
-        }
-        finally {
-            clearActiveRun(runId);
-        }
-    }
-    if (cleanupError) {
-        if (executionError) {
-            throw new AggregateError([executionError, cleanupError], `Sandbox teardown failed after run ${runId} error`);
-        }
-        throw toError(cleanupError);
+        await finalizeActiveRun(runId);
     }
     if (executionError) {
-        throw toError(executionError);
+        if (executionError instanceof RunCommandError) {
+            throw executionError;
+        }
+        throw new RunProcessStreamError(toErrorMessage(executionError));
     }
     if (!runReport) {
-        throw new Error(`Run ${runId} did not produce a report`);
+        throw new RunProcessStreamError(`Run \`${runId}\` did not produce a report.`);
     }
     await flushRunRecordBuffer({
         runsFilePath,
@@ -168,3 +183,18 @@ export async function executeRunCommand(input) {
     });
     return runReport;
 }
+function registerRunWorkspaceTeardown(teardown, workspacePaths, agentId) {
+    teardown.addPath(workspacePaths.contextPath, `${agentId} context`);
+    teardown.addPath(workspacePaths.runtimePath, `${agentId} runtime`);
+    teardown.addPath(workspacePaths.sandboxPath, `${agentId} sandbox`);
+}
+function mergeFinalAgentRecords(existing, incoming) {
+    const merged = new Map();
+    for (const agent of existing) {
+        merged.set(agent.agentId, agent);
+    }
+    for (const agent of incoming) {
+        merged.set(agent.agentId, mergeAgentRecords(merged.get(agent.agentId), agent));
+    }
+    return [...merged.values()];
+}

package/dist/commands/run/lifecycle.d.ts

@@ -1,9 +1,12 @@
+import type { TeardownController } from "../../competition/shared/teardown.js";
+import { getActiveTerminationStatus, RUN_ABORT_WARNING } from "../../domain/run/competition/termination-state.js";
 import type { RunStatus } from "../../status/index.js";
-export declare const RUN_ABORT_WARNING = "Run aborted before agent completed.";
+import { TERMINABLE_RUN_STATUSES } from "../../status/index.js";
 interface ActiveRunContext {
     root: string;
     runsFilePath: string;
     runId: string;
+    teardown?: TeardownController;
     agents?: readonly ActiveRunAgentContext[];
 }
 interface ActiveRunAgentContext {
@@ -11,9 +14,8 @@ interface ActiveRunAgentContext {
     providerId?: string;
     agentRoot: string;
 }
-declare const TERMINABLE_STATUSES: readonly ["failed", "aborted"];
 export declare function registerActiveRun(context: ActiveRunContext): void;
 export declare function clearActiveRun(runId: string): void;
-export declare function getActiveTerminationStatus(runId: string): RunStatus | undefined;
-export declare function terminateActiveRun(status: Extract<RunStatus, (typeof TERMINABLE_STATUSES)[number]>): Promise<void>;
-export {};
+export { getActiveTerminationStatus, RUN_ABORT_WARNING };
+export declare function terminateActiveRun(status: Extract<RunStatus, (typeof TERMINABLE_RUN_STATUSES)[number]>): Promise<void>;
+export declare function finalizeActiveRun(runId: string): Promise<void>;

package/dist/commands/run/lifecycle.js

@@ -1,12 +1,12 @@
-import { disposeRunRecordBuffer, getRunRecordSnapshot, rewriteRunRecord, } from "../../records/persistence.js";
+import { runTeardown } from "../../competition/shared/teardown.js";
+import { getActiveTerminationStatus, RUN_ABORT_WARNING, setActiveTerminationStatus, } from "../../domain/run/competition/termination-state.js";
+import { disposeRunRecordBuffer, getRunRecordSnapshot, rewriteRunRecord, } from "../../domain/run/persistence/adapter.js";
+import { buildOperationLifecycleCompleteFields, buildRecordLifecycleCompleteFields, } from "../../domain/shared/lifecycle.js";
+import { TERMINABLE_RUN_STATUSES } from "../../status/index.js";
 import { toErrorMessage } from "../../utils/errors.js";
 import { preserveProviderChatTranscripts } from "../../workspace/chat/artifacts.js";
-import { teardownRunSandboxes } from "./sandbox-registry.js";
-export const RUN_ABORT_WARNING = "Run aborted before agent completed.";
 let activeRun;
 let terminationInFlight = false;
-let activeTerminationStatus;
-const TERMINABLE_STATUSES = ["failed", "aborted"];
 export function registerActiveRun(context) {
     activeRun = context;
 }
@@ -18,25 +18,17 @@ export function clearActiveRun(runId) {
         activeRun = undefined;
     }
 }
-export function getActiveTerminationStatus(runId) {
-    if (!terminationInFlight) {
-        return undefined;
-    }
-    if (!activeRun || activeRun.runId !== runId) {
-        return undefined;
-    }
-    return activeTerminationStatus;
-}
+export { getActiveTerminationStatus, RUN_ABORT_WARNING };
 export async function terminateActiveRun(status) {
-    if (!TERMINABLE_STATUSES.includes(status)) {
+    if (!TERMINABLE_RUN_STATUSES.includes(status)) {
         return;
     }
     if (!activeRun || terminationInFlight) {
         return;
     }
     terminationInFlight = true;
-    activeTerminationStatus = status;
     const context = activeRun;
+    setActiveTerminationStatus(context.runId, status);
     let finalized = false;
     const chatArtifactsByAgent = new Map();
     let persistenceError;
@@ -47,12 +39,12 @@ export async function terminateActiveRun(status) {
         await rewriteRunRecord({
             ...context,
             mutate: (existing) => {
+                const completedAt = new Date().toISOString();
                 const runInProgress = existing.status === "running" || existing.status === "queued";
                 const runStatusNeedsUpdate = runInProgress && existing.status !== status;
                 let agentsChanged = false;
                 let agents = existing.agents;
                 if (status === "aborted") {
-                    const abortedAt = new Date().toISOString();
                     const abortWarning = RUN_ABORT_WARNING;
                     agents = existing.agents.map((agent) => {
                         if (agent.status !== "running" && agent.status !== "queued") {
@@ -74,8 +66,11 @@ export async function terminateActiveRun(status) {
                         return {
                             ...agent,
                             status: "aborted",
-                            startedAt: agent.startedAt ?? abortedAt,
-                            completedAt: abortedAt,
+                            ...buildOperationLifecycleCompleteFields({
+                                existing: agent,
+                                startedAt: agent.startedAt ?? completedAt,
+                                completedAt,
+                            }),
                             warnings: nextWarnings,
                             artifacts: nextArtifacts,
                         };
@@ -84,10 +79,21 @@ export async function terminateActiveRun(status) {
                 if (!runStatusNeedsUpdate && !agentsChanged) {
                     return existing;
                 }
+                if (runStatusNeedsUpdate) {
+                    return {
+                        ...existing,
+                        status,
+                        ...buildRecordLifecycleCompleteFields({
+                            existing,
+                            startedAt: existing.startedAt ?? completedAt,
+                            completedAt,
+                        }),
+                        deletedAt: null,
+                        agents,
+                    };
+                }
                 return {
                     ...existing,
-                    status: runStatusNeedsUpdate ? status : existing.status,
-                    deletedAt: runStatusNeedsUpdate ? null : existing.deletedAt,
                     agents,
                 };
             },
@@ -115,17 +121,30 @@ export async function terminateActiveRun(status) {
         }
     }
     try {
-        await teardownRunSandboxes(context.runId);
+        await finalizeRegisteredRunTeardown(context);
     }
     finally {
         terminationInFlight = false;
-        activeTerminationStatus = undefined;
+        setActiveTerminationStatus(context.runId, undefined);
         activeRun = undefined;
     }
     if (persistenceError) {
         throw persistenceError;
     }
 }
+export async function finalizeActiveRun(runId) {
+    if (!activeRun || activeRun.runId !== runId) {
+        clearActiveRun(runId);
+        return;
+    }
+    const context = activeRun;
+    try {
+        await finalizeRegisteredRunTeardown(context);
+    }
+    finally {
+        clearActiveRun(runId);
+    }
+}
 async function captureChatArtifactsBeforeAbort(context, output) {
     const agentContexts = context.agents ?? [];
     if (agentContexts.length === 0) {
@@ -184,3 +203,6 @@ async function captureChatArtifactsBeforeAbort(context, output) {
         }
     }
 }
+async function finalizeRegisteredRunTeardown(context) {
+    await runTeardown(context.teardown);
+}

package/dist/commands/run/record-init.d.ts

@@ -1,4 +1,4 @@
-import type { RunRecordInitResult } from "./phases.js";
+import type { RunRecordInitResult } from "../../domain/run/competition/phases.js";
 export interface RecordInitInput {
     readonly root: string;
     readonly runsFilePath: string;
@@ -7,7 +7,10 @@ export interface RecordInitInput {
     readonly baseRevisionSha: string;
     readonly repoDisplayPath: string;
     readonly createdAt: string;
+    readonly startedAt: string;
     readonly runRoot: string;
+    readonly extraContext?: string[];
+    readonly extraContextMetadata?: import("../../extra-context/contract.js").PersistedExtraContextMetadataEntry[];
 }
 /**
  * Initialize and persist the initial run record.

package/dist/commands/run/record-init.js

@@ -1,17 +1,20 @@
-import { appendRunRecord } from "../../records/persistence.js";
+import { appendRunRecord } from "../../domain/run/persistence/adapter.js";
 import { normalizePathForDisplay } from "../../utils/path.js";
 import { cleanupRunWorkspace } from "../../workspace/cleanup.js";
 /**
  * Initialize and persist the initial run record.
  */
 export async function initializeRunRecord(input) {
-    const { root, runsFilePath, runId, specDisplayPath, baseRevisionSha, repoDisplayPath, createdAt, runRoot, } = input;
+    const { root, runsFilePath, runId, specDisplayPath, baseRevisionSha, repoDisplayPath, createdAt, startedAt, runRoot, extraContext, extraContextMetadata, } = input;
     const initialRecord = {
         runId,
         spec: {
             path: normalizePathForDisplay(specDisplayPath),
         },
+        extraContext,
+        extraContextMetadata,
         createdAt,
+        startedAt,
         baseRevisionSha,
         rootPath: repoDisplayPath,
         agents: [],

package/dist/commands/run/shim/run-agent-shim.d.ts

@@ -1 +1,2 @@
-export declare function main(argv?: string[]): Promise<number>;
+import { main } from "../../../agents/runtime/shim/run-agent-shim.js";
+export { main };