hivehq 2.0.0

package/dist/src/server/agent-manager.d.ts

@@ -0,0 +1,54 @@
+import { type IWindowsPtyForkOptions } from 'node-pty';
+import { type PtyOutputBus } from './pty-output-bus.js';
+type RunStatus = 'starting' | 'running' | 'exited' | 'error';
+interface StartAgentInput {
+    agentId: string;
+    command: string;
+    args?: string[];
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+    onExit?: (event: {
+        runId: string;
+        exitCode: number | null;
+    }) => void;
+}
+interface AgentRunSnapshot {
+    runId: string;
+    agentId: string;
+    pid: number | null;
+    status: RunStatus;
+    output: string;
+    exitCode: number | null;
+}
+interface AgentRunRecord extends AgentRunSnapshot {
+    process: {
+        isStopped: () => boolean;
+        pause: () => void;
+        pid: number | null;
+        resize: (cols: number, rows: number) => void;
+        resume: () => void;
+        stop: () => void;
+        write: (input: Buffer | string) => void;
+    };
+    onExit?: (event: {
+        runId: string;
+        exitCode: number | null;
+    }) => void;
+}
+interface AgentManager {
+    getOutputBus: () => PtyOutputBus;
+    pauseRun: (runId: string) => void;
+    resizeRun: (runId: string, cols: number, rows: number) => void;
+    resumeRun: (runId: string) => void;
+    startAgent: (input: StartAgentInput) => Promise<AgentRunSnapshot>;
+    writeInput: (runId: string, input: Buffer | string) => void;
+    getRun: (runId: string) => AgentRunSnapshot;
+    removeRun: (runId: string) => void;
+    stopRun: (runId: string) => void;
+}
+export declare const createSpawnEnv: (inputEnv?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, parentEnv?: NodeJS.ProcessEnv) => NodeJS.ProcessEnv;
+export declare const buildAgentPtySpawnOptions: (cwd: string, env: NodeJS.ProcessEnv, platform?: NodeJS.Platform) => IWindowsPtyForkOptions;
+export declare const createAgentManager: ({ ptyOutputBus, }?: {
+    ptyOutputBus?: PtyOutputBus;
+}) => AgentManager;
+export type { AgentManager, AgentRunRecord, AgentRunSnapshot, RunStatus, StartAgentInput };

package/dist/src/server/agent-manager.js

@@ -0,0 +1,104 @@
+import { randomUUID } from 'node:crypto';
+import { spawn } from 'node-pty';
+import { resolveSpawnCommand } from './agent-command-resolver.js';
+import { attachAgentPty, toAgentRunSnapshot } from './agent-manager-support.js';
+import { createPtyOutputBus } from './pty-output-bus.js';
+const createRunId = () => randomUUID();
+const getWindowsEnvKey = (env, key) => {
+    if (Object.hasOwn(env, key))
+        return key;
+    return Object.keys(env)
+        .filter((item) => item.toLowerCase() === key.toLowerCase())
+        .at(-1);
+};
+export const createSpawnEnv = (inputEnv, platform = process.platform, parentEnv = process.env) => {
+    const env = { ...parentEnv };
+    for (const [key, value] of Object.entries(inputEnv ?? {})) {
+        const targetKey = platform === 'win32' ? (getWindowsEnvKey(env, key) ?? key) : key;
+        env[targetKey] = value;
+    }
+    for (const key of Object.keys(env)) {
+        if (env[key] === undefined)
+            delete env[key];
+    }
+    return env;
+};
+export const buildAgentPtySpawnOptions = (cwd, env, platform = process.platform) => ({
+    cols: 80,
+    cwd,
+    env,
+    name: 'xterm-256color',
+    rows: 24,
+    ...(platform === 'win32' ? { useConpty: true } : {}),
+});
+export const createAgentManager = ({ ptyOutputBus = createPtyOutputBus(), } = {}) => {
+    const runs = new Map();
+    const getRunRecord = (runId) => {
+        const run = runs.get(runId);
+        if (!run)
+            throw new Error(`Run not found: ${runId}`);
+        return run;
+    };
+    return {
+        getOutputBus() {
+            return ptyOutputBus;
+        },
+        pauseRun(runId) {
+            getRunRecord(runId).process.pause();
+        },
+        async startAgent(input) {
+            const env = createSpawnEnv(input.env);
+            const spawnCommand = resolveSpawnCommand(input.command, input.cwd, env, input.args ?? []);
+            const runId = createRunId();
+            const run = {
+                runId,
+                agentId: input.agentId,
+                pid: null,
+                status: 'starting',
+                output: '',
+                exitCode: null,
+                process: {
+                    isStopped() {
+                        return false;
+                    },
+                    pause() { },
+                    pid: null,
+                    resize() { },
+                    resume() { },
+                    stop() { },
+                    write() { },
+                },
+            };
+            if (input.onExit)
+                run.onExit = input.onExit;
+            runs.set(runId, run);
+            try {
+                attachAgentPty(run, spawn(spawnCommand.command, spawnCommand.args, buildAgentPtySpawnOptions(input.cwd, env)), ptyOutputBus);
+            }
+            catch (error) {
+                runs.delete(runId);
+                throw error;
+            }
+            return toAgentRunSnapshot(run);
+        },
+        resizeRun(runId, cols, rows) {
+            getRunRecord(runId).process.resize(cols, rows);
+        },
+        resumeRun(runId) {
+            getRunRecord(runId).process.resume();
+        },
+        writeInput(runId, text) {
+            getRunRecord(runId).process.write(text);
+        },
+        getRun(runId) {
+            return toAgentRunSnapshot(getRunRecord(runId));
+        },
+        removeRun(runId) {
+            runs.delete(runId);
+        },
+        stopRun(runId) {
+            const run = getRunRecord(runId);
+            run.process.stop();
+        },
+    };
+};

package/dist/src/server/agent-run-bootstrap.d.ts

@@ -0,0 +1,83 @@
+import type { AgentSummary, WorkspaceSummary } from '../shared/types.js';
+import type { AgentLaunchConfigInput } from './agent-run-store.js';
+import type { AgentSessionStorePort } from './agent-runtime-ports.js';
+import type { CommandPresetRecord } from './command-preset-store.js';
+import { type SessionCaptureSnapshot } from './session-capture.js';
+/**
+ * Builds a `{ <PATH-key>: <new-value> }` object for the spawn env override.
+ * Critical on Windows: the OS env block reports PATH under its native casing
+ * (typically `Path`). Writing to a literal `PATH` key would, after spread
+ * with `process.env`, leave two entries — `Path` carrying the original value
+ * and `PATH` carrying our prepend. CreateProcess then sees both and the
+ * effective lookup order is undefined; in practice the child PTY often falls
+ * back to the original `Path` and never sees `HIVE_BIN_DIR`, breaking every
+ * `team` shim resolution.
+ *
+ * We detect the existing key (case-insensitive on Windows) and overwrite IT,
+ * so the merge produces exactly one PATH entry.
+ *
+ * Exported for unit testing — `buildAgentRunBootstrap` is the only in-tree
+ * caller.
+ */
+export declare const buildSpawnPathEnvEntry: (parentEnv: NodeJS.ProcessEnv, hiveBinDir: string, platform: NodeJS.Platform) => NodeJS.ProcessEnv;
+export declare const buildAgentRunBootstrap: (workspace: WorkspaceSummary, agentId: string, config: AgentLaunchConfigInput, sessionStore: AgentSessionStorePort, getCommandPreset: (id: string) => CommandPresetRecord | undefined, agent?: AgentSummary) => {
+    sessionCaptureSnapshot: {
+        discriminator?: {
+            contentIncludes: string | readonly string[];
+        };
+        env: {
+            HIVE_CLAUDE_PROJECTS_DIR: string;
+            CODEX_HOME?: never;
+            HIVE_GEMINI_HOME?: never;
+            HIVE_OPENCODE_DB_PATH?: never;
+        };
+        knownSessionIds: Set<string>;
+        root: string;
+    } | {
+        env: {
+            CODEX_HOME: string;
+            HIVE_CLAUDE_PROJECTS_DIR?: never;
+            HIVE_GEMINI_HOME?: never;
+            HIVE_OPENCODE_DB_PATH?: never;
+        };
+        knownSessionIds: Set<string>;
+        root: string;
+    } | {
+        env: {
+            HIVE_GEMINI_HOME: string;
+            HIVE_CLAUDE_PROJECTS_DIR?: never;
+            CODEX_HOME?: never;
+            HIVE_OPENCODE_DB_PATH?: never;
+        };
+        knownSessionIds: Set<string>;
+        root: string;
+    } | {
+        env: {
+            HIVE_OPENCODE_DB_PATH: string;
+            HIVE_CLAUDE_PROJECTS_DIR?: never;
+            CODEX_HOME?: never;
+            HIVE_GEMINI_HOME?: never;
+        };
+        knownSessionIds: Set<string>;
+        root: string;
+    } | {
+        knownSessionIds: Set<string>;
+        env?: never;
+        root?: never;
+    } | undefined;
+    startConfig: AgentLaunchConfigInput;
+    startEnv: {
+        HIVE_PORT: string;
+        HIVE_PROJECT_ID: string;
+        HIVE_AGENT_ID: string;
+        HIVE_AGENT_TOKEN: string;
+    };
+};
+export declare const startAgentRunCapture: ({ agentId, getRunOutput, sessionCaptureSnapshot, sessionStore, startConfig, workspace, }: {
+    agentId: string;
+    getRunOutput?: () => string | null;
+    sessionCaptureSnapshot: SessionCaptureSnapshot | undefined;
+    sessionStore: AgentSessionStorePort;
+    startConfig: AgentLaunchConfigInput;
+    workspace: WorkspaceSummary;
+}) => void;

package/dist/src/server/agent-run-bootstrap.js

@@ -0,0 +1,101 @@
+import { dirname, posix, resolve, sep, win32 } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildAgentLegacyIdentityMarker, buildAgentSessionBindingMarker, } from './agent-startup-instructions.js';
+import { withPresetResumeArgs } from './preset-launch-support.js';
+import { captureSessionIdForCapture, getSessionCaptureEnvironment, snapshotSessionIdsForCapture, } from './session-capture.js';
+const resolveHiveBinDir = () => {
+    const moduleDir = dirname(fileURLToPath(import.meta.url));
+    const packageRoot = resolve(moduleDir, '../..');
+    return moduleDir.includes(`${sep}dist${sep}src${sep}`)
+        ? resolve(packageRoot, 'bin')
+        : resolve(packageRoot, 'dist/bin');
+};
+const HIVE_BIN_DIR = resolveHiveBinDir();
+const SESSION_CAPTURE_TIMEOUT_MS = 30_000;
+const getWindowsEnvKey = (env, key) => {
+    if (Object.hasOwn(env, key))
+        return key;
+    return Object.keys(env)
+        .filter((item) => item.toLowerCase() === key.toLowerCase())
+        .at(-1);
+};
+/**
+ * Builds a `{ <PATH-key>: <new-value> }` object for the spawn env override.
+ * Critical on Windows: the OS env block reports PATH under its native casing
+ * (typically `Path`). Writing to a literal `PATH` key would, after spread
+ * with `process.env`, leave two entries — `Path` carrying the original value
+ * and `PATH` carrying our prepend. CreateProcess then sees both and the
+ * effective lookup order is undefined; in practice the child PTY often falls
+ * back to the original `Path` and never sees `HIVE_BIN_DIR`, breaking every
+ * `team` shim resolution.
+ *
+ * We detect the existing key (case-insensitive on Windows) and overwrite IT,
+ * so the merge produces exactly one PATH entry.
+ *
+ * Exported for unit testing — `buildAgentRunBootstrap` is the only in-tree
+ * caller.
+ */
+export const buildSpawnPathEnvEntry = (parentEnv, hiveBinDir, platform) => {
+    const existingKey = platform === 'win32' ? getWindowsEnvKey(parentEnv, 'PATH') : undefined;
+    const key = existingKey ?? 'PATH';
+    const existingValue = existingKey ? parentEnv[existingKey] : parentEnv.PATH;
+    // Target platform's delimiter — Windows uses `;`, POSIX `:` — independent
+    // of where this function is running (tests on macOS verify the win32 path).
+    const platformDelimiter = platform === 'win32' ? win32.delimiter : posix.delimiter;
+    const value = existingValue ? `${hiveBinDir}${platformDelimiter}${existingValue}` : hiveBinDir;
+    return { [key]: value };
+};
+const resolveLaunchPreset = (config, getCommandPreset) => {
+    if (config.presetAugmentationDisabled)
+        return undefined;
+    if (config.commandPresetId)
+        return getCommandPreset(config.commandPresetId);
+    const implicitPreset = getCommandPreset(config.command);
+    if (!implicitPreset || implicitPreset.command !== config.command)
+        return undefined;
+    return {
+        resumeArgsTemplate: null,
+        sessionIdCapture: null,
+        yoloArgsTemplate: implicitPreset.yoloArgsTemplate,
+    };
+};
+const createSessionCaptureDiscriminator = (workspace, agent) => {
+    if (!agent)
+        return undefined;
+    return {
+        contentIncludes: [
+            buildAgentSessionBindingMarker({ agent, workspace }),
+            buildAgentLegacyIdentityMarker({ agent, workspace }),
+        ],
+    };
+};
+export const buildAgentRunBootstrap = (workspace, agentId, config, sessionStore, getCommandPreset, agent) => {
+    const preset = resolveLaunchPreset(config, getCommandPreset);
+    const discriminator = createSessionCaptureDiscriminator(workspace, agent);
+    const startConfig = withPresetResumeArgs(config, preset, sessionStore.getLastSessionId(workspace.id, agentId), workspace.path, discriminator, () => sessionStore.clearLastSessionId(workspace.id, agentId));
+    const sessionCaptureSnapshot = startConfig.resumedSessionId
+        ? undefined
+        : snapshotSessionIdsForCapture(workspace.path, startConfig.sessionIdCapture, discriminator);
+    return {
+        sessionCaptureSnapshot,
+        startConfig,
+        startEnv: {
+            ...getSessionCaptureEnvironment(sessionCaptureSnapshot),
+            HIVE_PORT: '',
+            HIVE_PROJECT_ID: workspace.id,
+            HIVE_AGENT_ID: agentId,
+            HIVE_AGENT_TOKEN: '',
+            ...buildSpawnPathEnvEntry(process.env, HIVE_BIN_DIR, process.platform),
+        },
+    };
+};
+export const startAgentRunCapture = ({ agentId, getRunOutput, sessionCaptureSnapshot, sessionStore, startConfig, workspace, }) => {
+    if (!sessionCaptureSnapshot || !startConfig.sessionIdCapture)
+        return;
+    const captureSnapshot = startConfig.sessionIdCapture.source === 'stdout_regex' && getRunOutput
+        ? { ...sessionCaptureSnapshot, getOutput: getRunOutput }
+        : sessionCaptureSnapshot;
+    void captureSessionIdForCapture(workspace.path, startConfig.sessionIdCapture, captureSnapshot, (sessionId) => {
+        sessionStore.setLastSessionId(workspace.id, agentId, sessionId);
+    }, SESSION_CAPTURE_TIMEOUT_MS);
+};

package/dist/src/server/agent-run-exit-handler.d.ts

@@ -0,0 +1,8 @@
+import type { AgentRunExitContext } from './agent-run-start-context.js';
+interface HandleRunExitInput {
+    exitCode: number | null;
+    endedAt: number;
+    runId: string;
+}
+export declare const handleAgentRunExit: (context: AgentRunExitContext, { exitCode, endedAt, runId }: HandleRunExitInput) => boolean;
+export {};

package/dist/src/server/agent-run-exit-handler.js

@@ -0,0 +1,32 @@
+import { shouldClearResumedSessionOnExit } from './agent-exit-classification.js';
+import { completeLiveRun } from './agent-run-sync.js';
+const clearResumedSessionOnFailure = (context, exitCode) => {
+    if (shouldClearResumedSessionOnExit(exitCode) && context.startConfig.resumedSessionId) {
+        context.sessionStore.clearLastSessionId(context.workspace.id, context.agentId);
+    }
+};
+export const handleAgentRunExit = (context, { exitCode, endedAt, runId }) => {
+    context.registry.setPendingExitCode(runId, exitCode);
+    const liveRun = context.registry.get(runId);
+    if (!liveRun) {
+        context.tokenRegistry.revokeIfMatches(context.agentId, context.token);
+        return false;
+    }
+    if (context.handledRunExits.has(runId)) {
+        context.registry.clearPendingExitCode(runId);
+        return false;
+    }
+    context.handledRunExits.add(runId);
+    try {
+        completeLiveRun(liveRun, exitCode, endedAt, context.store);
+        if (!liveRun.userStopped)
+            clearResumedSessionOnFailure(context, exitCode);
+        context.onAgentExit(context.workspace.id, context.agentId);
+        return true;
+    }
+    finally {
+        context.tokenRegistry.revokeIfMatches(context.agentId, context.token);
+        context.registry.resolveExit(runId);
+        context.registry.clearPendingExitCode(runId);
+    }
+};

package/dist/src/server/agent-run-start-context.d.ts

@@ -0,0 +1,24 @@
+import type { WorkspaceSummary } from '../shared/types.js';
+import type { PersistedAgentRun } from './agent-run-store.js';
+import type { AgentSessionStorePort } from './agent-runtime-ports.js';
+import type { AgentTokenRegistry } from './agent-tokens.js';
+import type { LiveRunRegistry } from './live-run-registry.js';
+export type PersistedRunStatus = PersistedAgentRun['status'];
+export interface AgentRunStarterStorePort {
+    insertAgentRun: (runId: string, agentId: string, startedAt: number, pid: number | null, status?: PersistedRunStatus, exitCode?: number | null, endedAt?: number | null) => void;
+    updatePersistedRun: (runId: string, status: PersistedRunStatus, exitCode: number | null, endedAt: number | null) => void;
+}
+export interface AgentRunExitContext {
+    agentId: string;
+    handledRunExits: Set<string>;
+    onAgentExit: (workspaceId: string, agentId: string) => void;
+    registry: LiveRunRegistry;
+    sessionStore: AgentSessionStorePort;
+    startConfig: {
+        resumedSessionId?: string | null;
+    };
+    store: AgentRunStarterStorePort;
+    token: string;
+    tokenRegistry: AgentTokenRegistry;
+    workspace: WorkspaceSummary;
+}

package/dist/src/server/agent-run-start-context.js

@@ -0,0 +1 @@
+export {};

package/dist/src/server/agent-run-starter.d.ts

@@ -0,0 +1,30 @@
+import type { AgentSummary, WorkspaceSummary } from '../shared/types.js';
+import type { AgentManager } from './agent-manager.js';
+import type { AgentRunStarterStorePort } from './agent-run-start-context.js';
+import type { AgentLaunchConfigInput } from './agent-run-store.js';
+import type { AgentSessionStorePort } from './agent-runtime-ports.js';
+import type { LiveAgentRun } from './agent-runtime-types.js';
+import type { AgentTokenRegistry } from './agent-tokens.js';
+import type { CommandPresetRecord } from './command-preset-store.js';
+import { type FeatureFlags } from './feature-flags.js';
+import type { LiveRunRegistry } from './live-run-registry.js';
+import type { RestartPolicy } from './restart-policy.js';
+import { type TeamMemoryInjectionService } from './team-memory-injection.js';
+interface AgentRunStarterInput {
+    agentManager: AgentManager | undefined;
+    registry: LiveRunRegistry;
+    onAgentExit: (workspaceId: string, agentId: string) => void;
+    store: AgentRunStarterStorePort;
+    sessionStore: AgentSessionStorePort;
+    tokenRegistry: AgentTokenRegistry;
+    getCommandPreset: (id: string) => CommandPresetRecord | undefined;
+    getAgent: ((workspaceId: string, agentId: string) => AgentSummary | undefined) | undefined;
+    restartPolicy: RestartPolicy;
+    /** Resolves the live experimental flags for the orchestrator's startup
+     *  prompt (`workflowsEnabled` gates the `team workflow` line + authoring
+     *  rule; `autostaffEnabled` gates the team-sizing rule). */
+    getFlags?: () => FeatureFlags;
+    memoryInjection?: TeamMemoryInjectionService;
+}
+export declare const createAgentRunStarter: ({ agentManager, registry, onAgentExit, store, sessionStore, tokenRegistry, getCommandPreset, getAgent, restartPolicy, getFlags, memoryInjection, }: AgentRunStarterInput) => (workspace: WorkspaceSummary, agentId: string, config: AgentLaunchConfigInput, hivePort: string) => Promise<LiveAgentRun>;
+export {};

package/dist/src/server/agent-run-starter.js

@@ -0,0 +1,155 @@
+import { classifyCompletedRunStatus, shouldClearResumedSessionOnExit, } from './agent-exit-classification.js';
+import { buildAgentRunBootstrap, startAgentRunCapture } from './agent-run-bootstrap.js';
+import { handleAgentRunExit } from './agent-run-exit-handler.js';
+import { buildAgentStartupInstructions } from './agent-startup-instructions.js';
+import { FEATURE_FLAGS_ALL_OFF } from './feature-flags.js';
+import { createPostStartInputWriter, isInteractiveAgentCommand } from './post-start-input-writer.js';
+import { buildMemoryDigestSafely, logMemoryDigestInjection, rollbackMemoryDigestInjection, } from './team-memory-injection.js';
+export const createAgentRunStarter = ({ agentManager, registry, onAgentExit, store, sessionStore, tokenRegistry, getCommandPreset, getAgent, restartPolicy, getFlags, memoryInjection, }) => async (workspace, agentId, config, hivePort) => {
+    if (!agentManager)
+        throw new Error('Agent manager is required to start agents');
+    const agent = getAgent?.(workspace.id, agentId);
+    const { sessionCaptureSnapshot, startConfig, startEnv } = buildAgentRunBootstrap(workspace, agentId, config, sessionStore, getCommandPreset, agent);
+    const handledRunExits = new Set();
+    const abortedRunIds = new Set();
+    const startedAt = Date.now();
+    const token = tokenRegistry.issue(agentId);
+    const exitContext = {
+        agentId,
+        handledRunExits,
+        onAgentExit,
+        registry,
+        sessionStore,
+        startConfig,
+        store,
+        token,
+        tokenRegistry,
+        workspace,
+    };
+    const startInput = {
+        agentId,
+        command: startConfig.command,
+        cwd: workspace.path,
+        env: {
+            ...startEnv,
+            COLORTERM: 'truecolor',
+            FORCE_COLOR: '1',
+            NO_COLOR: undefined,
+            TERM: 'xterm-256color',
+            TERM_PROGRAM: 'hive',
+            HIVE_PORT: hivePort,
+            HIVE_AGENT_TOKEN: token,
+        },
+        onExit: ({ runId, exitCode }) => {
+            const endedAt = Date.now();
+            if (!handleAgentRunExit(exitContext, { exitCode, endedAt, runId }) &&
+                abortedRunIds.has(runId)) {
+                registry.clearPendingExitCode(runId);
+                return;
+            }
+        },
+    };
+    let run;
+    try {
+        run = await agentManager.startAgent(startConfig.args ? { ...startInput, args: startConfig.args } : startInput);
+    }
+    catch (error) {
+        tokenRegistry.revokeIfMatches(agentId, token);
+        throw error;
+    }
+    const liveRun = {
+        ...run,
+        exitCode: run.status === 'error' ? run.exitCode : null,
+        startedAt,
+        status: run.status === 'error' ? 'error' : 'starting',
+    };
+    try {
+        store.insertAgentRun(run.runId, agentId, startedAt, run.pid, liveRun.status, liveRun.exitCode);
+    }
+    catch (error) {
+        abortedRunIds.add(run.runId);
+        registry.clearPendingExitCode(run.runId);
+        tokenRegistry.revokeIfMatches(agentId, token);
+        agentManager.stopRun(run.runId);
+        throw error;
+    }
+    registry.createExitEntry(run.runId);
+    registry.add(liveRun);
+    if (run.status === 'error') {
+        liveRun.status = classifyCompletedRunStatus(run.exitCode);
+        store.updatePersistedRun(run.runId, liveRun.status, run.exitCode, Date.now());
+        if (startConfig.resumedSessionId && shouldClearResumedSessionOnExit(run.exitCode)) {
+            sessionStore.clearLastSessionId(workspace.id, agentId);
+        }
+        tokenRegistry.revokeIfMatches(agentId, token);
+        // Ensure §12 three-state: failed spawn must flip AgentSummary to stopped.
+        onAgentExit(workspace.id, agentId);
+        registry.resolveExit(run.runId);
+        registry.clearPendingExitCode(run.runId);
+        return liveRun;
+    }
+    startAgentRunCapture({
+        agentId,
+        getRunOutput: () => {
+            try {
+                return agentManager.getRun(run.runId).output;
+            }
+            catch {
+                return null;
+            }
+        },
+        sessionCaptureSnapshot,
+        sessionStore,
+        startConfig,
+        workspace,
+    });
+    const postStartWriter = createPostStartInputWriter(agentManager, startConfig.interactiveCommand ?? startConfig.command);
+    queueMicrotask(() => {
+        try {
+            const injectedRestartMessage = restartPolicy.injectPostStartMessage({
+                agentId,
+                runId: run.runId,
+                startConfig,
+                workspace,
+                writeToRun: postStartWriter,
+            });
+            if (!startConfig.resumedSessionId &&
+                !injectedRestartMessage &&
+                agent &&
+                isInteractiveAgentCommand(startConfig.interactiveCommand ?? startConfig.command)) {
+                const memoryDigest = buildMemoryDigestSafely({
+                    contextType: 'startup',
+                    memoryInjection,
+                    workspaceId: workspace.id,
+                });
+                const injectionIds = logMemoryDigestInjection({
+                    agentId,
+                    contextType: 'startup',
+                    memoryDigest,
+                    memoryInjection,
+                    workspaceId: workspace.id,
+                });
+                const auditedMemoryDigest = injectionIds ? memoryDigest : null;
+                void postStartWriter(run.runId, buildAgentStartupInstructions({
+                    agent,
+                    memoryDigest: auditedMemoryDigest?.text,
+                    workspace,
+                    flags: getFlags?.() ?? FEATURE_FLAGS_ALL_OFF,
+                })).catch(() => {
+                    rollbackMemoryDigestInjection({ injectionIds, memoryInjection });
+                    // The agent may have exited before post-start guidance could be written.
+                });
+            }
+        }
+        catch {
+            // The agent may have exited before post-start guidance could be written.
+        }
+    });
+    if (registry.hasPendingExitCode(run.runId)) {
+        const exitCode = registry.getPendingExitCode(run.runId) ?? null;
+        queueMicrotask(() => {
+            handleAgentRunExit(exitContext, { exitCode, endedAt: Date.now(), runId: run.runId });
+        });
+    }
+    return liveRun;
+};

package/dist/src/server/agent-run-store.d.ts

@@ -0,0 +1,51 @@
+import type { Database } from 'better-sqlite3';
+import type { SessionIdCaptureConfig } from './session-capture.js';
+export interface AgentLaunchConfigInput {
+    command: string;
+    args?: string[];
+    commandPresetId?: string | null;
+    interactiveCommand?: string | null;
+    presetAugmentationDisabled?: boolean;
+    resumedSessionId?: string | null;
+    resumeArgsTemplate?: string | null;
+    sessionIdCapture?: SessionIdCaptureConfig | null;
+}
+export interface PersistedAgentRun {
+    runId: string;
+    agentId: string;
+    status: 'starting' | 'running' | 'exited' | 'error';
+    exitCode: number | null;
+    pid: number | null;
+    startedAt: number;
+    endedAt: number | null;
+}
+export declare const createAgentRunStore: (db: Database) => {
+    close: () => void;
+    insertAgentRun: (runId: string, agentId: string, startedAt: number, pid: number | null, status?: PersistedAgentRun["status"], exitCode?: number | null, endedAt?: number | null) => void;
+    deleteLaunchConfig: (workspaceId: string, agentId: string) => void;
+    listAgentRuns: (agentId: string) => {
+        runId: string;
+        agentId: string;
+        pid: number | null;
+        status: "starting" | "running" | "exited" | "error";
+        exitCode: number | null;
+        startedAt: number;
+        endedAt: number | null;
+    }[];
+    listLaunchConfigs: () => {
+        agentId: string;
+        config: {
+            command: string;
+            args: string[];
+            commandPresetId: string | null;
+            interactiveCommand: string | null;
+            presetAugmentationDisabled: boolean;
+            resumeArgsTemplate: string | null;
+            sessionIdCapture: SessionIdCaptureConfig | null;
+        };
+        workspaceId: string;
+    }[];
+    markUnfinishedRunsStale: (endedAt?: number) => void;
+    saveLaunchConfig: (workspaceId: string, agentId: string, input: AgentLaunchConfigInput) => void;
+    updatePersistedRun: (runId: string, status: PersistedAgentRun["status"], exitCode: number | null, endedAt: number | null) => void;
+};