@straiffi/archon 1.8.13 → 1.8.15

package/dist/server/lib/agent.js

@@ -2,73 +2,30 @@ import { spawn } from 'child_process';
 import { randomUUID } from 'crypto';
 import { readFileSync } from 'fs';
 import { extname, isAbsolute, join, relative, resolve, sep } from 'path';
-import Database from 'better-sqlite3';
 import db from '../db.js';
 import { getChatSession, updateChatSessionUsageSnapshot } from './chats.js';
 import { normalizeClaudeModelId, normalizeModelId } from './models.js';
 import { createOpencodeTaskSessionReader, parseOpencodeTaskEnvelope } from './opencodeTaskSessions.js';
+import { hostOpencodeSessionOperations } from './opencodeSessionOperations.js';
+import { hostExecutionEnvironment } from './hostExecutionEnvironment.js';
+import { markRetryableOpenCodeDatabaseLock, RetryableOpenCodeDatabaseLockError, retryOpenCodeDatabaseLocks } from './opencodeExecutionReliability.js';
+import { claudeAgentProvider } from './claudeAgentProvider.js';
+import { buildOpencodeSpecReviewInvocation, createOpencodeExitError, createOpencodeRecoveryTracker, interpretOpencodeRecoveryEvent, isSuccessfulOpencodeExit, opencodeAgentProvider, } from './opencodeAgentProvider.js';
 import { appendClaudeHeadlessPlanPrompt, buildClaudeHeadlessPlanArgs } from './planModeQuestions.js';
 import { formatGenericToolCall } from './genericToolCall.js';
 import { getSpecSession, updateSpecSessionResumeId, updateSpecSessionStatus, updateSpecSessionTitle, updateSpecSessionUsageSnapshot } from './specs.js';
 import { updateSpecReviewRunStatus, updateSpecReviewRunStreaming, updateSpecReviewRunUsage } from './specReviews.js';
 import { createAgentRun, emitAgentRunsUpdated, finalizeAgentRun, getNextAgentRunIndex, listAgentRunsForExecutionRun, listAgentRunsForParent, updateAgentRunLabel, updateAgentRunSessionId, updateAgentRunStatus } from './agentRuns.js';
-import { resolveOpencodeDbPath } from './runtimePaths.js';
 import { markTicketDescriptionVisibleInBundle } from './ticketMessages.js';
 import { getTicket } from './tickets.js';
 import { createTranscriptRunSnapshots } from './transcriptRuns.js';
 import { createWorkspaceProcessEnvironment } from './workspaceProcessEnvironment.js';
-import { OpencodeModelResolutionError, parseOpencodeError, parseOpencodeStderrModelResolutionError, } from './opencodeErrors.js';
+import { OpencodeModelResolutionError, parseOpencodeStderrModelResolutionError, } from './opencodeErrors.js';
 import { extractLeadingOpencodeJsonObjects } from './opencodePromptOutput.js';
 import { assertAgentSpawnPermit, AgentSpawnPermitRevokedError } from './agentSpawnPermits.js';
 const withTranscriptRuns = (value, transcriptRuns) => {
     return transcriptRuns ? { ...value, transcriptRuns } : value;
 };
-const createOpencodeRecoveryTracker = () => {
-    let sawError = false;
-    let latestEvent = null;
-    let recoveredFinalAnswerFragments = [];
-    let latestError = null;
-    let modelResolutionError = null;
-    return {
-        consume: events => {
-            let shouldResetResponse = false;
-            for (const event of events ?? []) {
-                latestEvent = event.type;
-                if (event.type === 'error') {
-                    sawError = true;
-                    latestError = event.error;
-                    if (event.error?.isModelResolutionError) {
-                        modelResolutionError = event.error;
-                    }
-                    recoveredFinalAnswerFragments = [];
-                    shouldResetResponse = true;
-                    continue;
-                }
-                if (sawError) {
-                    recoveredFinalAnswerFragments.push(event.text);
-                }
-            }
-            return shouldResetResponse;
-        },
-        hasRecoveredFinalAnswer: () => (sawError
-            && latestEvent === 'final_answer'
-            && recoveredFinalAnswerFragments.length > 0),
-        hasUnrecoveredError: () => latestEvent === 'error',
-        getModelResolutionError: () => modelResolutionError,
-        getUnrecoveredError: () => latestEvent === 'error' ? latestError : null,
-        getRecoveredResponse: () => recoveredFinalAnswerFragments.join('\n\n'),
-    };
-};
-const isSuccessfulOpencodeExit = (code, stderrModelError, recoveryTracker) => (!stderrModelError
-    && !recoveryTracker.getModelResolutionError()
-    && !recoveryTracker.hasUnrecoveredError()
-    && (code === 0 || recoveryTracker.hasRecoveredFinalAnswer()));
-const createOpencodeExitError = (message, stderrModelError, recoveryTracker) => {
-    const structuredError = recoveryTracker.getModelResolutionError() ?? recoveryTracker.getUnrecoveredError();
-    return structuredError?.isModelResolutionError || stderrModelError
-        ? new OpencodeModelResolutionError(message)
-        : new Error(message);
-};
 export class AgentContinuationRejectedError extends Error {
     constructor(message) {
         super(message);
@@ -91,9 +48,9 @@ export const getAgentErrorTranscriptRuns = (error) => {
     const transcriptRuns = error.transcriptRuns;
     return Array.isArray(transcriptRuns) && transcriptRuns.length > 0 ? transcriptRuns : null;
 };
-const OPENCODE_PLACEHOLDER_TITLE_PATTERN = /^New session\b/i;
 const OPENCODE_SESSION_METADATA_LOOKUP_DELAY_MS = 1500;
 const AGENT_PROGRESS_UPDATE_INTERVAL_MS = 100;
+const OPENCODE_SUBAGENT_POLL_INTERVAL_MS = 750;
 const resolveAgentModel = (tool, model) => {
     if (tool === 'claude') {
         return normalizeClaudeModelId(model) || null;
@@ -157,13 +114,6 @@ const buildClaudeArgs = (mode, model, resumeSessionId, sessionId) => {
         sessionId,
     ];
 };
-const OPENCODE_SESSION_BY_ID_QUERY = 'SELECT id, title FROM session WHERE id = ? LIMIT 1';
-const OPENCODE_SESSION_BY_CREATED_AT_QUERY = 'SELECT id, title FROM session WHERE time_created > ? ORDER BY time_created DESC LIMIT 1';
-const OPENCODE_COMPLETED_ASSISTANT_MESSAGE_USAGE_QUERY = "SELECT data FROM message WHERE session_id = ? AND json_extract(data, '$.role') = 'assistant' AND json_extract(data, '$.time.completed') IS NOT NULL ORDER BY time_created DESC LIMIT 1";
-const OPENCODE_COMPLETED_ASSISTANT_MESSAGE_USAGE_SINCE_QUERY = "SELECT data FROM message WHERE session_id = ? AND time_created >= ? AND json_extract(data, '$.role') = 'assistant' AND json_extract(data, '$.time.completed') IS NOT NULL ORDER BY time_created DESC LIMIT 1";
-const OPENCODE_STEP_FINISH_USAGE_QUERY = "SELECT data FROM part WHERE session_id = ? AND json_extract(data, '$.type') = 'step-finish' ORDER BY time_created DESC LIMIT 1";
-const OPENCODE_STEP_FINISH_USAGE_SINCE_QUERY = "SELECT data FROM part WHERE session_id = ? AND time_created >= ? AND json_extract(data, '$.type') = 'step-finish' ORDER BY time_created DESC LIMIT 1";
-const OPENCODE_SESSION_COST_QUERY = 'SELECT cost FROM session WHERE id = ?';
 const GET_PERSISTED_CHAT_STATE_QUERY = 'SELECT agent_log, streaming_response, opencode_session_id FROM chat_sessions WHERE id = ?';
 const GET_PERSISTED_SPEC_STATE_QUERY = 'SELECT agent_log, streaming_response, opencode_session_id FROM spec_sessions WHERE id = ?';
 export const EMPTY_CHAT_USAGE_SNAPSHOT = {
@@ -327,9 +277,6 @@ export const mergeUsageFromJsonLine = (current, line) => {
     }
     return next;
 };
-const hasUsageSnapshot = (value) => {
-    return Object.values(value).some(candidate => candidate !== null && candidate !== undefined);
-};
 const hasMatchingUsageSnapshot = (current, next) => {
     return current.usage_snapshot_context_window === next.usage_snapshot_context_window
         && current.usage_snapshot_max_output_tokens === next.usage_snapshot_max_output_tokens
@@ -500,67 +447,12 @@ const createThrottledProgressUpdater = (flushUpdate) => {
         },
     };
 };
-const openOpencodeDatabase = () => new Database(resolveOpencodeDbPath(), { readonly: true });
-const readOpencodeSession = (statement, value) => {
-    const opencodeDb = openOpencodeDatabase();
-    try {
-        const row = opencodeDb.prepare(statement).get(value);
-        if (!row?.id) {
-            return null;
-        }
-        const normalizedTitle = typeof row.title === 'string'
-            ? row.title.trim() || null
-            : null;
-        const title = normalizedTitle && !OPENCODE_PLACEHOLDER_TITLE_PATTERN.test(normalizedTitle)
-            ? normalizedTitle
-            : null;
-        return {
-            id: row.id,
-            title,
-        };
-    }
-    finally {
-        opencodeDb.close();
-    }
-};
 export const readOpencodeUsageSnapshot = ({ sessionId, spawnTimestamp = null, }) => {
-    const opencodeDb = openOpencodeDatabase();
-    try {
-        const costRow = opencodeDb.prepare(OPENCODE_SESSION_COST_QUERY).get(sessionId);
-        const sessionCost = typeof costRow?.cost === 'number' ? { usage_snapshot_cost: costRow.cost } : {};
-        const completedAssistantMessage = (spawnTimestamp === null
-            ? opencodeDb.prepare(OPENCODE_COMPLETED_ASSISTANT_MESSAGE_USAGE_QUERY).get(sessionId)
-            : opencodeDb.prepare(OPENCODE_COMPLETED_ASSISTANT_MESSAGE_USAGE_SINCE_QUERY).get(sessionId, spawnTimestamp));
-        if (typeof completedAssistantMessage?.data === 'string') {
-            try {
-                const parsedUsage = extractChatUsageSnapshot(JSON.parse(completedAssistantMessage.data));
-                if (hasUsageSnapshot(parsedUsage)) {
-                    return mergeChatUsageSnapshot(mergeChatUsageSnapshot(EMPTY_CHAT_USAGE_SNAPSHOT, parsedUsage), sessionCost);
-                }
-            }
-            catch {
-                // Fall through to the step-finish lookup below.
-            }
-        }
-        const latestStepFinish = (spawnTimestamp === null
-            ? opencodeDb.prepare(OPENCODE_STEP_FINISH_USAGE_QUERY).get(sessionId)
-            : opencodeDb.prepare(OPENCODE_STEP_FINISH_USAGE_SINCE_QUERY).get(sessionId, spawnTimestamp));
-        if (typeof latestStepFinish?.data === 'string') {
-            try {
-                const parsedUsage = extractChatUsageSnapshot(JSON.parse(latestStepFinish.data));
-                if (hasUsageSnapshot(parsedUsage)) {
-                    return mergeChatUsageSnapshot(mergeChatUsageSnapshot(EMPTY_CHAT_USAGE_SNAPSHOT, parsedUsage), sessionCost);
-                }
-            }
-            catch {
-                return mergeChatUsageSnapshot(EMPTY_CHAT_USAGE_SNAPSHOT, sessionCost);
-            }
-        }
-        return mergeChatUsageSnapshot(EMPTY_CHAT_USAGE_SNAPSHOT, sessionCost);
-    }
-    finally {
-        opencodeDb.close();
+    const snapshot = hostOpencodeSessionOperations.readUsageSnapshot(sessionId, spawnTimestamp);
+    if (!snapshot) {
+        throw new Error('OpenCode usage snapshot read failed');
     }
+    return snapshot;
 };
 const resolveOpencodeUsageSnapshot = ({ current, sessionId, spawnTimestamp = null, }) => {
     try {
@@ -655,12 +547,12 @@ const createOpencodeMetadataRefresher = ({ chatSessionId, io, spawnTimestamp, in
     };
     const readCurrentSession = () => {
         if (knownSessionId) {
-            return readOpencodeSession(OPENCODE_SESSION_BY_ID_QUERY, knownSessionId);
+            return hostOpencodeSessionOperations.findSessionById(knownSessionId);
         }
         if (spawnTimestamp === null) {
             return null;
         }
-        return readOpencodeSession(OPENCODE_SESSION_BY_CREATED_AT_QUERY, spawnTimestamp);
+        return hostOpencodeSessionOperations.findLatestSessionAfter(spawnTimestamp);
     };
     const refresh = () => {
         if (stopped) {
@@ -723,12 +615,12 @@ const createSpecOpencodeMetadataRefresher = ({ specSessionId, io, spawnTimestamp
     };
     const readCurrentSession = () => {
         if (knownSessionId) {
-            return readOpencodeSession(OPENCODE_SESSION_BY_ID_QUERY, knownSessionId);
+            return hostOpencodeSessionOperations.findSessionById(knownSessionId);
         }
         if (spawnTimestamp === null) {
             return null;
         }
-        return readOpencodeSession(OPENCODE_SESSION_BY_CREATED_AT_QUERY, spawnTimestamp);
+        return hostOpencodeSessionOperations.findLatestSessionAfter(spawnTimestamp);
     };
     const refresh = () => {
         if (stopped) {
@@ -1094,15 +986,14 @@ const parseOpencodeJsonEvent = (event, cwd) => {
     if (event.type === 'text' && event.part?.type === 'text' && event.part.text) {
         const text = event.part.text.trim();
         const phase = event.part.metadata?.openai?.phase;
+        const recoveryEvent = interpretOpencodeRecoveryEvent(event.type, event.error, text, phase);
         return {
             logFragment: text || null,
             responseFragment: text && (!phase || phase === 'final_answer') ? text : null,
             subagentEvents: [],
             providerSessionId,
             modelResolutionError: false,
-            recoveryEvents: text && phase === 'final_answer'
-                ? [{ type: 'final_answer', text }]
-                : [],
+            recoveryEvents: recoveryEvent ? [recoveryEvent] : [],
         };
     }
     if (event.type === 'reasoning' && event.part?.type === 'reasoning') {
@@ -1186,14 +1077,15 @@ const parseOpencodeJsonEvent = (event, cwd) => {
         };
     }
     if (event.type === 'error') {
-        const parsedError = parseOpencodeError(event.error, event.part?.text);
+        const recoveryEvent = interpretOpencodeRecoveryEvent(event.type, event.error, event.part?.text, undefined);
+        const parsedError = recoveryEvent?.type === 'error' ? recoveryEvent.error : null;
         const text = parsedError?.message ?? '';
         return {
             logFragment: text ? `**Error:** ${text}` : null,
             responseFragment: null,
             subagentEvents: [],
             providerSessionId,
-            recoveryEvents: [{ type: 'error', error: parsedError }],
+            recoveryEvents: recoveryEvent ? [recoveryEvent] : [],
         };
     }
     return emptyParsedStreamLine();
@@ -1596,7 +1488,7 @@ export const readOpencodeSessionTranscript = ({ sessionId, since, cwd, }) => {
         reader.close();
     }
 };
-export const createOpencodeSubagentMonitor = ({ initialParentSessionId, spawnTimestamp, cwd, tracker, onParentSessionId, taskSessionReader, discoverParentSession = true, }) => {
+export const createOpencodeSubagentMonitor = ({ initialParentSessionId, spawnTimestamp, cwd, tracker, onParentSessionId, taskSessionReader, discoverParentSession = true, parentDiscoveryDelayMs = 0, }) => {
     const reader = taskSessionReader === undefined ? createOpencodeTaskSessionReader() : taskSessionReader;
     let parentSessionId = initialParentSessionId;
     let timer = null;
@@ -1639,7 +1531,7 @@ export const createOpencodeSubagentMonitor = ({ initialParentSessionId, spawnTim
             return;
         }
         try {
-            if (!parentSessionId && discoverParentSession) {
+            if (!parentSessionId && discoverParentSession && Date.now() >= spawnTimestamp + parentDiscoveryDelayMs) {
                 setParentSessionId(reader.findParentSessionSince(spawnTimestamp));
             }
             if (!parentSessionId) {
@@ -1672,7 +1564,7 @@ export const createOpencodeSubagentMonitor = ({ initialParentSessionId, spawnTim
             return;
         }
         refresh();
-        timer = setInterval(refresh, 150);
+        timer = setInterval(refresh, OPENCODE_SUBAGENT_POLL_INTERVAL_MS);
         timer.unref?.();
     };
     const stop = () => {
@@ -1724,6 +1616,16 @@ const killProcess = (proc, signal) => {
     catch {
     }
 };
+const interruptProcess = (state, signal) => {
+    if (!isProcessAlive(state.child)) {
+        return;
+    }
+    if (state.interrupt) {
+        state.interrupt(signal);
+        return;
+    }
+    killProcess(state.child, signal);
+};
 const waitForProcessExit = async (proc, timeoutMs) => {
     const deadline = Date.now() + timeoutMs;
     await new Promise(resolve => {
@@ -1757,6 +1659,7 @@ const untrackChatProcess = (chatSessionId, state) => {
 export const registerChatProcessPlaceholder = (chatSessionId) => {
     const state = {
         child: null,
+        interrupt: null,
         researchChildren: new Set(),
         stopRequested: false,
         metadataRefresher: null,
@@ -1765,7 +1668,7 @@ export const registerChatProcessPlaceholder = (chatSessionId) => {
     return state;
 };
 export const registerBuildProcessPlaceholder = (ticketId) => {
-    const state = { child: null, stopRequested: false, sessionLookupTimer: null };
+    const state = { child: null, interrupt: null, stopRequested: false, sessionLookupTimer: null };
     activeBuildProcesses.set(ticketId, state);
     return state;
 };
@@ -1796,6 +1699,7 @@ const untrackSpecProcess = (specSessionId, state) => {
 export const registerSpecProcessPlaceholder = (specSessionId) => {
     const state = {
         child: null,
+        interrupt: null,
         researchChildren: new Set(),
         stopRequested: false,
         metadataRefresher: null,
@@ -1819,6 +1723,7 @@ const untrackSpecReviewProcess = (specReviewRunId, state) => {
 export const registerSpecReviewProcessPlaceholder = (specReviewRunId) => {
     const state = {
         child: null,
+        interrupt: null,
         researchChildren: new Set(),
         stopRequested: false,
         metadataRefresher: null,
@@ -1864,10 +1769,20 @@ export const stopBuildAgent = async (ticketId) => {
     if (!state.child) {
         return true;
     }
-    killProcess(state.child, 'SIGTERM');
+    if (state.interrupt) {
+        state.interrupt('SIGTERM');
+    }
+    else {
+        killProcess(state.child, 'SIGTERM');
+    }
     await waitForProcessExit(state.child, 5000);
     if (isProcessAlive(state.child)) {
-        killProcess(state.child, 'SIGKILL');
+        if (state.interrupt) {
+            state.interrupt('SIGKILL');
+        }
+        else {
+            killProcess(state.child, 'SIGKILL');
+        }
         await waitForProcessExit(state.child, 1000);
     }
     return true;
@@ -1943,15 +1858,15 @@ export const stopSpecReviewAgent = async (specReviewRunId) => {
     if (!state.child) {
         return true;
     }
-    killProcess(state.child, 'SIGTERM');
+    interruptProcess(state, 'SIGTERM');
     await waitForProcessExit(state.child, 5000);
     if (isProcessAlive(state.child)) {
-        killProcess(state.child, 'SIGKILL');
+        interruptProcess(state, 'SIGKILL');
         await waitForProcessExit(state.child, 1000);
     }
     return true;
 };
-export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = null, resumeSessionId = null, sessionField = 'session_id', trackBuildProcess = false, reviewProcessState, emitSuccessUpdate = true, opencodeAgentMode, runStream, executionContext, persistSessionIdToTicket = false, spawnPermitId, }) => {
+const runAgentOnce = ({ ticketId, tool, prompt, cwd, io, model, variant = null, resumeSessionId = null, sessionField = 'session_id', trackBuildProcess = false, reviewProcessState, emitSuccessUpdate = true, opencodeAgentMode, runStream, executionContext, persistSessionIdToTicket = false, spawnPermitId, executionProvider = hostExecutionEnvironment, }) => {
     const resolvedModel = resolveAgentModel(tool, model);
     const subagentTracker = createSubagentRunTracker({
         parentType: 'ticket',
@@ -2049,7 +1964,7 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
                 return hasResolvedOpencodeSessionId;
             }
             try {
-                const session = readOpencodeSession(OPENCODE_SESSION_BY_CREATED_AT_QUERY, spawnTimestamp);
+                const session = hostOpencodeSessionOperations.findLatestSessionAfter(spawnTimestamp);
                 if (session?.id) {
                     bindResolvedOpencodeSession(session.id);
                 }
@@ -2059,15 +1974,19 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
             }
             return hasResolvedOpencodeSessionId;
         };
-        const [cmd, args] = tool === 'claude'
-            ? (() => {
-                sessionId = resumeSessionId || randomUUID();
-                return [
-                    'claude',
-                    buildClaudeArgs(opencodeAgentMode, resolvedModel, resumeSessionId, sessionId),
-                ];
-            })()
-            : ['opencode', ['run', ...(opencodeAgentMode === 'plan' ? ['--agent', 'plan'] : []), '--format', 'json', '--thinking', ...(resumeSessionId ? ['--session', resumeSessionId] : []), ...(resolvedModel ? ['--model', resolvedModel] : []), ...(variant ? ['--variant', variant] : []), prompt]];
+        const agentProvider = tool === 'claude'
+            ? claudeAgentProvider
+            : opencodeAgentProvider;
+        const invocation = agentProvider.buildStreamingInvocation({
+            cwd,
+            prompt,
+            model: resolvedModel,
+            variant,
+            mode: opencodeAgentMode,
+            resumeSessionId,
+            sessionId: randomUUID(),
+        });
+        sessionId = invocation.sessionId;
         writeRunStatus('running', null);
         if (tool === 'claude' && sessionId) {
             writeRunSessionId(sessionId);
@@ -2076,6 +1995,8 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
             spawnTimestamp = Date.now();
         }
         let child;
+        let interrupt;
+        let placementFailure;
         try {
             if (buildState?.stopRequested) {
                 throw new AgentSpawnPermitRevokedError();
@@ -2083,28 +2004,37 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
             if (spawnPermitId && executionContext) {
                 assertAgentSpawnPermit(spawnPermitId, executionContext.runId);
             }
-            child = spawn(cmd, args, {
+            const handle = executionProvider.execute({
+                target: {
+                    kind: 'worktree',
+                    id: ticketId,
+                    workspacePath: cwd,
+                    revision: 'working-tree',
+                },
+                command: invocation.command,
+                args: invocation.args,
                 cwd,
-                stdio: tool === 'claude' ? ['pipe', 'pipe', 'pipe'] : ['ignore', 'pipe', 'pipe'],
+                stdio: invocation.stdio,
                 env: createWorkspaceProcessEnvironment(cwd, { PWD: cwd }),
                 detached: process.platform !== 'win32',
             });
+            child = handle.child;
+            interrupt = handle.interrupt;
+            placementFailure = handle.placementFailure;
         }
         catch (error) {
-            const resolvedError = error instanceof Error ? error : new Error(String(error));
+            const resolvedError = agentProvider.classifyExecutionFailure(error);
             const transcriptRuns = subagentTracker.finalize('error', resolvedError.message, null);
             rejectOnce(attachTranscriptRunsToError(resolvedError, transcriptRuns));
             return;
         }
         reviewChild = child;
-        if (tool === 'claude') {
-            const claudePrompt = opencodeAgentMode === 'plan'
-                ? appendClaudeHeadlessPlanPrompt(prompt)
-                : prompt;
-            writeClaudeStdin(child, buildClaudeStdinMessage(claudePrompt, [], cwd));
+        if (invocation.stdin !== null) {
+            writeClaudeStdin(child, invocation.stdin);
         }
         if (trackBuildProcess && buildState) {
             buildState.child = child;
+            buildState.interrupt = interrupt;
             activeBuildProcesses.set(ticketId, buildState);
         }
         if (reviewProcessState) {
@@ -2113,6 +2043,14 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
                 killProcess(child, 'SIGTERM');
             }
         }
+        void placementFailure.then(failure => {
+            if (!failure || settled) {
+                return;
+            }
+            const resolvedError = agentProvider.classifyExecutionFailure(failure);
+            const transcriptRuns = finalizeRun('error', getErrorMessage(resolvedError), null);
+            rejectOnce(attachTranscriptRunsToError(resolvedError, transcriptRuns));
+        });
         startTime = Date.now();
         if (tool === 'opencode' && spawnTimestamp !== null) {
             opencodeSubagentMonitor = createOpencodeSubagentMonitor({
@@ -2207,8 +2145,9 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
                     resolveOnce(withTranscriptRuns({ response: null, responseTiming: null, usageSnapshot }, transcriptRuns));
                     return;
                 }
-                const transcriptRuns = finalizeRun('error', getErrorMessage(err), null);
-                rejectOnce(attachTranscriptRunsToError(err, transcriptRuns));
+                const resolvedError = agentProvider.classifyExecutionFailure(err);
+                const transcriptRuns = finalizeRun('error', getErrorMessage(resolvedError), null);
+                rejectOnce(attachTranscriptRunsToError(resolvedError, transcriptRuns));
             });
             return;
         }
@@ -2307,6 +2246,13 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
             const error = resumeSessionId && !executionCapableEventObserved && isTypedPreExecutionContinuationRejection(failureMessage)
                 ? new AgentContinuationRejectedError(failureMessage)
                 : createOpencodeExitError(failureMessage, stderrModelError, recoveryTracker);
+            const retryableError = !executionCapableEventObserved && !sessionId
+                ? markRetryableOpenCodeDatabaseLock(error)
+                : error;
+            if (retryableError instanceof RetryableOpenCodeDatabaseLockError) {
+                rejectOnce(retryableError);
+                return;
+            }
             const transcriptRuns = finalizeRun('error', log, finalResponse);
             rejectOnce(attachTranscriptRunsToError(error, transcriptRuns));
         });
@@ -2321,12 +2267,17 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
                 resolveOnce(withTranscriptRuns({ response: null, responseTiming: null }, transcriptRuns));
                 return;
             }
-            const transcriptRuns = finalizeRun('error', getErrorMessage(err), null);
-            rejectOnce(attachTranscriptRunsToError(err, transcriptRuns));
+            const resolvedError = agentProvider.classifyExecutionFailure(err);
+            const transcriptRuns = finalizeRun('error', getErrorMessage(resolvedError), null);
+            rejectOnce(attachTranscriptRunsToError(resolvedError, transcriptRuns));
         });
     });
 };
-export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io, model, variant = null, resumeSessionId = null, opencodeAgentMode = 'build', executionContext, mainRun, spawnPermitId, }) => {
+export const runAgent = (options) => {
+    const run = () => runAgentOnce(options);
+    return options.tool === 'opencode' ? retryOpenCodeDatabaseLocks(run) : run();
+};
+const runChatAgentOnce = ({ chatSessionId, tool, prompt, files = [], cwd, io, model, variant = null, resumeSessionId = null, opencodeAgentMode = 'build', executionContext, mainRun, spawnPermitId, }) => {
     const resolvedModel = resolveAgentModel(tool, model);
     const subagentTracker = createSubagentRunTracker({
         parentType: 'chat',
@@ -2693,11 +2644,18 @@ export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io,
                 }, transcriptRuns));
                 return;
             }
-            updateChatSessionStatus(chatSessionId, 'error', log, io, finalResponse);
             const failureMessage = `Agent exited with code ${code ?? 'null'}\n${log}${stderrOutput !== log && stderrOutput ? '\n\n' + stderrOutput : ''}`;
             const error = resumeSessionId && !executionCapableEventObserved && isTypedPreExecutionContinuationRejection(failureMessage)
                 ? new AgentContinuationRejectedError(failureMessage)
                 : createOpencodeExitError(failureMessage, stderrModelError, recoveryTracker);
+            const retryableError = !executionCapableEventObserved
+                ? markRetryableOpenCodeDatabaseLock(error)
+                : error;
+            if (retryableError instanceof RetryableOpenCodeDatabaseLockError) {
+                rejectOnce(retryableError);
+                return;
+            }
+            updateChatSessionStatus(chatSessionId, 'error', log, io, finalResponse);
             const transcriptRuns = subagentTracker.finalize('error', log, finalResponse);
             rejectOnce(attachTranscriptRunsToError(error, transcriptRuns));
         });
@@ -2727,7 +2685,11 @@ export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io,
         });
     });
 };
-export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io, model, variant = null, resumeSessionId = null, executionContext, mainRun, }) => {
+export const runChatAgent = (options) => {
+    const run = () => runChatAgentOnce(options);
+    return options.tool === 'opencode' ? retryOpenCodeDatabaseLocks(run) : run();
+};
+const runSpecAgentOnce = ({ specSessionId, tool, prompt, files = [], cwd, io, model, variant = null, resumeSessionId = null, executionContext, mainRun, }) => {
     const resolvedModel = resolveAgentModel(tool, model);
     const subagentTracker = createSubagentRunTracker({
         parentType: 'spec',
@@ -3067,10 +3029,18 @@ export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io,
                 }, transcriptRuns));
                 return;
             }
+            const failureMessage = `Agent exited with code ${code ?? 'null'}\n${log}${stderrOutput !== log && stderrOutput ? '\n\n' + stderrOutput : ''}`;
+            const error = createOpencodeExitError(failureMessage, stderrModelError, recoveryTracker);
+            const retryableError = logLines.length === 0 && responseLines.length === 0
+                ? markRetryableOpenCodeDatabaseLock(error)
+                : error;
+            if (retryableError instanceof RetryableOpenCodeDatabaseLockError) {
+                rejectOnce(retryableError);
+                return;
+            }
             updateSpecSessionStatusLocal(specSessionId, 'error', log, io, finalResponse);
             const transcriptRuns = subagentTracker.finalize('error', log, finalResponse);
-            const failureMessage = `Agent exited with code ${code ?? 'null'}\n${log}${stderrOutput !== log && stderrOutput ? '\n\n' + stderrOutput : ''}`;
-            rejectOnce(attachTranscriptRunsToError(createOpencodeExitError(failureMessage, stderrModelError, recoveryTracker), transcriptRuns));
+            rejectOnce(attachTranscriptRunsToError(error, transcriptRuns));
         });
         child.on('error', err => {
             progressUpdater.cancel();
@@ -3098,6 +3068,10 @@ export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io,
         });
     });
 };
+export const runSpecAgent = (options) => {
+    const run = () => runSpecAgentOnce(options);
+    return options.tool === 'opencode' ? retryOpenCodeDatabaseLocks(run) : run();
+};
 /**
  * Focused, decoupled runner for a one-shot Spec Review.
  *
@@ -3108,7 +3082,7 @@ export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io,
  * updateSpecReviewRunStatus / updateSpecReviewRunStreaming / updateSpecReviewRunUsage —
  * the spec_sessions row is never touched by this path.
  */
-export const runSpecReviewAgent = ({ specReviewRunId, specSessionId, tool, prompt, files = [], cwd, io, model, variant = null, executionContext, }) => {
+const runSpecReviewAgentOnce = ({ specReviewRunId, specSessionId, tool, prompt, files = [], cwd, io, model, variant = null, executionContext, }) => {
     const registeredState = activeSpecReviewProcesses.get(specReviewRunId);
     if (registeredState?.stopRequested) {
         return Promise.resolve({
@@ -3127,6 +3101,7 @@ export const runSpecReviewAgent = ({ specReviewRunId, specSessionId, tool, promp
     });
     return new Promise((resolve, reject) => {
         let spawnTimestamp = null;
+        let opencodeSessionId = null;
         let opencodeSubagentMonitor = null;
         let settled = false;
         let startTime = null;
@@ -3134,6 +3109,7 @@ export const runSpecReviewAgent = ({ specReviewRunId, specSessionId, tool, promp
         let usageSnapshot = EMPTY_CHAT_USAGE_SNAPSHOT;
         const reviewState = registeredState ?? {
             child: null,
+            interrupt: null,
             researchChildren: new Set(),
             stopRequested: false,
             metadataRefresher: null,
@@ -3149,21 +3125,56 @@ export const runSpecReviewAgent = ({ specReviewRunId, specSessionId, tool, promp
         };
         const resolveOnce = settle(resolve);
         const rejectOnce = settle(reject);
-        const [cmd, args] = tool === 'claude'
-            ? [
-                'claude',
-                buildClaudeArgs('plan', resolvedModel, null, randomUUID()),
-            ]
-            : ['opencode', ['run', '--agent', 'plan', '--format', 'json', '--thinking', ...(resolvedModel ? ['--model', resolvedModel] : []), ...(variant ? ['--variant', variant] : []), ...files.flatMap(filePath => ['--file', filePath]), ...(files.length > 0 ? ['--'] : []), prompt]];
+        const [cmd, args] = [
+            'claude',
+            buildClaudeArgs('plan', resolvedModel, null, randomUUID()),
+        ];
         updateSpecReviewRunStreaming(specReviewRunId, null);
-        const child = spawn(cmd, args, {
-            cwd,
-            stdio: tool === 'claude' ? ['pipe', 'pipe', 'pipe'] : ['ignore', 'pipe', 'pipe'],
-            env: createWorkspaceProcessEnvironment(cwd, { PWD: cwd }),
-            detached: process.platform !== 'win32',
-        });
+        const env = createWorkspaceProcessEnvironment(cwd, { PWD: cwd });
+        let child;
+        if (tool === 'opencode') {
+            const invocation = buildOpencodeSpecReviewInvocation({ prompt, files, model: resolvedModel, variant });
+            try {
+                const handle = hostExecutionEnvironment.execute({
+                    target: {
+                        kind: 'repository',
+                        id: cwd,
+                        workspacePath: cwd,
+                        revision: 'working-tree',
+                    },
+                    command: invocation.command,
+                    args: invocation.args,
+                    cwd,
+                    stdio: invocation.stdio,
+                    env,
+                    detached: process.platform !== 'win32',
+                });
+                child = handle.child;
+                reviewState.interrupt = handle.interrupt;
+                void handle.placementFailure.then(failure => {
+                    if (failure) {
+                        rejectOnce(opencodeAgentProvider.classifyExecutionFailure(failure));
+                    }
+                });
+            }
+            catch (error) {
+                rejectOnce(opencodeAgentProvider.classifyExecutionFailure(error));
+                return;
+            }
+        }
+        else {
+            child = spawn(cmd, args, {
+                cwd,
+                stdio: ['pipe', 'pipe', 'pipe'],
+                env,
+                detached: process.platform !== 'win32',
+            });
+        }
         reviewState.child = child;
         activeSpecReviewProcesses.set(specReviewRunId, reviewState);
+        if (reviewState.stopRequested) {
+            interruptProcess(reviewState, 'SIGTERM');
+        }
         if (tool === 'claude') {
             writeClaudeStdin(child, buildClaudeStdinMessage(appendClaudeHeadlessPlanPrompt(prompt), files, cwd));
         }
@@ -3175,6 +3186,7 @@ export const runSpecReviewAgent = ({ specReviewRunId, specSessionId, tool, promp
                 spawnTimestamp,
                 cwd,
                 tracker: subagentTracker,
+                parentDiscoveryDelayMs: OPENCODE_SESSION_METADATA_LOOKUP_DELAY_MS,
             });
             opencodeSubagentMonitor.start();
         }
@@ -3287,6 +3299,7 @@ export const runSpecReviewAgent = ({ specReviewRunId, specSessionId, tool, promp
                 const parsed = parseOpencodeJsonLine(line, cwd);
                 const { logFragment, responseFragment, subagentEvents, providerSessionId } = parsed;
                 opencodeSubagentMonitor?.setParentSessionId(providerSessionId);
+                opencodeSessionId = providerSessionId ?? opencodeSessionId;
                 subagentTracker.handle(subagentEvents);
                 if (appendOpencodeTranscriptLine({ parsed, logLines, responseLines, recoveryTracker })) {
                     firstFinalAnswerTime = null;
@@ -3304,6 +3317,7 @@ export const runSpecReviewAgent = ({ specReviewRunId, specSessionId, tool, promp
                 usageSnapshot = mergeUsageFromJsonLine(usageSnapshot, remainder);
                 const parsed = parseOpencodeJsonLine(remainder, cwd);
                 opencodeSubagentMonitor?.setParentSessionId(parsed.providerSessionId);
+                opencodeSessionId = parsed.providerSessionId ?? opencodeSessionId;
                 subagentTracker.handle(parsed.subagentEvents);
                 if (appendOpencodeTranscriptLine({ parsed, logLines, responseLines, recoveryTracker })) {
                     firstFinalAnswerTime = null;
@@ -3315,6 +3329,13 @@ export const runSpecReviewAgent = ({ specReviewRunId, specSessionId, tool, promp
             const finalResponse = recoveryTracker.hasRecoveredFinalAnswer()
                 ? recoveredResponse
                 : responseLines.join('\n\n') || stderrOutput;
+            if (opencodeSessionId && spawnTimestamp !== null) {
+                usageSnapshot = resolveOpencodeUsageSnapshot({
+                    current: usageSnapshot,
+                    sessionId: opencodeSessionId,
+                    spawnTimestamp,
+                });
+            }
             if (reviewState.stopRequested) {
                 updateSpecReviewRunStreaming(specReviewRunId, finalResponse || null);
                 subagentTracker.finalize('stopped', log || null, finalResponse || null);
@@ -3338,15 +3359,44 @@ export const runSpecReviewAgent = ({ specReviewRunId, specSessionId, tool, promp
                 });
                 return;
             }
-            subagentTracker.finalize('error', log || null, finalResponse || null);
             const failureMessage = `Agent exited with code ${code ?? 'null'}\n${log}${stderrOutput !== log && stderrOutput ? '\n\n' + stderrOutput : ''}`;
-            rejectOnce(createOpencodeExitError(failureMessage, stderrModelError, recoveryTracker));
+            const error = createOpencodeExitError(failureMessage, stderrModelError, recoveryTracker);
+            const retryableError = logLines.length === 0 && responseLines.length === 0 && !opencodeSessionId
+                ? markRetryableOpenCodeDatabaseLock(error)
+                : error;
+            if (retryableError instanceof RetryableOpenCodeDatabaseLockError) {
+                rejectOnce(retryableError);
+                return;
+            }
+            subagentTracker.finalize('error', log || null, finalResponse || null);
+            rejectOnce(error);
         });
         child.on('error', err => {
             progressUpdater.cancel();
-            subagentTracker.finalize(reviewState.stopRequested ? 'stopped' : 'error', getErrorMessage(err), null);
-            rejectOnce(err instanceof Error ? err : new Error(getErrorMessage(err)));
+            if (reviewState.stopRequested) {
+                const processError = getErrorMessage(err);
+                const finalLog = logLines.join('\n\n') || processError;
+                const finalResponse = recoveryTracker.hasRecoveredFinalAnswer()
+                    ? recoveryTracker.getRecoveredResponse()
+                    : responseLines.join('\n\n') || null;
+                updateSpecReviewRunStreaming(specReviewRunId, finalResponse);
+                subagentTracker.finalize('stopped', finalLog || null, finalResponse);
+                resolveOnce({
+                    completionStatus: 'stopped',
+                    finalResponse,
+                    usageSnapshot,
+                    responseTiming: buildResponseTiming({ startTime, firstFinalAnswerTime, isStopped: true }),
+                });
+                return;
+            }
+            const failure = opencodeAgentProvider.classifyExecutionFailure(err);
+            subagentTracker.finalize('error', failure.message, null);
+            rejectOnce(failure);
         });
     });
 };
+export const runSpecReviewAgent = (options) => {
+    const run = () => runSpecReviewAgentOnce(options);
+    return options.tool === 'opencode' ? retryOpenCodeDatabaseLocks(run) : run();
+};
 //# sourceMappingURL=agent.js.map