@straiffi/archon 1.8.22 → 1.10.0

package/dist/server/lib/agent.js

@@ -1,7 +1,6 @@
 import { spawn } from 'child_process';
 import { randomUUID } from 'crypto';
-import { readFileSync } from 'fs';
-import { extname, isAbsolute, join, relative, resolve, sep } from 'path';
+import { isAbsolute, relative, resolve, sep } from 'path';
 import db from '../db.js';
 import { getChatSession, updateChatSessionUsageSnapshot } from './chats.js';
 import { normalizeClaudeModelId, normalizeModelId } from './models.js';
@@ -23,6 +22,8 @@ import { createHostLauncherEnvironment, createLegacyHostRuntimeEnvironment, crea
 import { OpencodeModelResolutionError, parseOpencodeStderrModelResolutionError, } from './opencodeErrors.js';
 import { extractLeadingOpencodeJsonObjects } from './opencodePromptOutput.js';
 import { assertAgentSpawnPermit, AgentSpawnPermitRevokedError } from './agentSpawnPermits.js';
+import { buildClaudeStdinMessage } from './claudeStdin.js';
+import { createReviewAgentWatchdog, resolveWithin, REVIEW_AGENT_CLOSE_ENRICHMENT_TIMEOUT_MS, REVIEW_AGENT_INACTIVITY_TIMEOUT_MS, REVIEW_AGENT_KILL_GRACE_MS, } from './reviewAgentWatchdog.js';
 const withTranscriptRuns = (value, transcriptRuns) => {
     return transcriptRuns ? { ...value, transcriptRuns } : value;
 };
@@ -57,33 +58,6 @@ const resolveAgentModel = (tool, model) => {
     }
     return normalizeModelId(model) || null;
 };
-const CLAUDE_IMAGE_EXTENSIONS = {
-    '.png': 'image/png',
-    '.jpg': 'image/jpeg',
-    '.jpeg': 'image/jpeg',
-    '.webp': 'image/webp',
-    '.gif': 'image/gif',
-};
-const buildClaudeStdinMessage = (prompt, files, cwd) => {
-    if (files.length === 0) {
-        return JSON.stringify({ type: 'user', message: { role: 'user', content: prompt } });
-    }
-    const content = [{ type: 'text', text: prompt }];
-    for (const filePath of files) {
-        const absolutePath = isAbsolute(filePath) ? filePath : join(cwd, filePath);
-        const ext = extname(absolutePath).toLowerCase();
-        const mediaType = CLAUDE_IMAGE_EXTENSIONS[ext];
-        if (!mediaType) {
-            continue;
-        }
-        const data = readFileSync(absolutePath).toString('base64');
-        content.push({
-            type: 'image',
-            source: { type: 'base64', media_type: mediaType, data },
-        });
-    }
-    return JSON.stringify({ type: 'user', message: { role: 'user', content } });
-};
 const writeClaudeStdin = (child, message) => {
     const stdin = child.stdin;
     if (!stdin) {
@@ -454,9 +428,9 @@ export const readOpencodeUsageSnapshot = async ({ sessionId, spawnTimestamp = nu
     }
     return snapshot;
 };
-const resolveOpencodeUsageSnapshot = async ({ current, sessionId, spawnTimestamp = null, }) => {
+const resolveOpencodeUsageSnapshot = async ({ current, sessionId, spawnTimestamp = null, sessionOperations = hostOpencodeSessionOperations, }) => {
     try {
-        return mergeChatUsageSnapshot(current, await readOpencodeUsageSnapshot({ sessionId, spawnTimestamp }));
+        return mergeChatUsageSnapshot(current, await readOpencodeUsageSnapshot({ sessionId, spawnTimestamp, sessionOperations }));
     }
     catch {
         return current;
@@ -532,7 +506,7 @@ const updateChatSessionOpencodeMetadata = (chatSessionId, sessionId, title, io)
         io.emit('chat-session:updated', chatSession);
     }
 };
-const createOpencodeMetadataRefresher = ({ chatSessionId, io, spawnTimestamp, initialSessionId = null, }) => {
+const createOpencodeMetadataRefresher = ({ chatSessionId, io, spawnTimestamp, initialSessionId = null, sessionOperations = hostOpencodeSessionOperations, }) => {
     let lookupTimer = null;
     let stopped = false;
     let knownSessionId = initialSessionId;
@@ -547,12 +521,12 @@ const createOpencodeMetadataRefresher = ({ chatSessionId, io, spawnTimestamp, in
     };
     const readCurrentSession = async () => {
         if (knownSessionId) {
-            return hostOpencodeSessionOperations.findSessionById(knownSessionId);
+            return sessionOperations.findSessionById(knownSessionId);
         }
         if (spawnTimestamp === null) {
             return null;
         }
-        return hostOpencodeSessionOperations.findLatestSessionAfter(spawnTimestamp);
+        return sessionOperations.findLatestSessionAfter(spawnTimestamp);
     };
     const refresh = async () => {
         if (stopped) {
@@ -1316,12 +1290,14 @@ export const createSubagentRunTracker = ({ parentType, parentId, io, mainRun, ex
     };
     const applySnapshot = ({ callId, label, status, log, response, sessionId, }) => {
         let run = findRun(callId);
+        let created = false;
         if (!run) {
             handle([{ kind: 'start', callId, label, sessionId }]);
             run = findRun(callId);
+            created = Boolean(run);
         }
         if (!run) {
-            return;
+            return false;
         }
         bindSessionId(run, sessionId);
         updateLabel(run, label);
@@ -1330,7 +1306,7 @@ export const createSubagentRunTracker = ({ parentType, parentId, io, mainRun, ex
         const nextStatus = run.status !== 'running' && status === 'running' ? run.status : status;
         const hasChanged = run.log !== nextLog || run.response !== nextResponse || run.status !== nextStatus;
         if (!hasChanged) {
-            return;
+            return created;
         }
         run.log = nextLog;
         run.response = nextResponse;
@@ -1343,7 +1319,9 @@ export const createSubagentRunTracker = ({ parentType, parentId, io, mainRun, ex
             finalizeAgentRun(run.id, nextStatus, run.response || null);
         }
         emitUpdate();
+        return true;
     };
+    const hasRunningSubagents = () => trackedRuns.some(run => run.status === 'running');
     const finalize = (status, parentLog, parentResponse) => {
         if (trackedRuns.length === 0 && !mainRun) {
             return null;
@@ -1454,11 +1432,13 @@ export const createSubagentRunTracker = ({ parentType, parentId, io, mainRun, ex
             updateAgentRunSessionId(mainRun.id, normalized);
         }
     };
-    return { applySnapshot, handle, finalize, setMainSessionId, updateMain };
+    return { applySnapshot, handle, finalize, hasRunningSubagents, setMainSessionId, updateMain };
 };
 export const reconstructOpencodeSubagentTranscript = (parts, cwd) => {
     let log = '';
     let response = '';
+    let finalResponse = '';
+    let finalResponseMessageId = null;
     for (const persistedPart of parts) {
         if (persistedPart.role && persistedPart.role !== 'assistant') {
             continue;
@@ -1479,11 +1459,22 @@ export const reconstructOpencodeSubagentTranscript = (parts, cwd) => {
         if (parsed.responseFragment) {
             response = appendTranscriptText(response, parsed.responseFragment);
         }
+        const finalAnswerFragments = (parsed.recoveryEvents ?? []).flatMap(event => (event.type === 'final_answer' ? [event.text] : []));
+        if (finalAnswerFragments.length > 0) {
+            const messageId = persistedPart.messageId ?? persistedPart.id;
+            if (finalResponseMessageId !== messageId) {
+                finalResponse = '';
+                finalResponseMessageId = messageId;
+            }
+            for (const fragment of finalAnswerFragments) {
+                finalResponse = appendTranscriptText(finalResponse, fragment);
+            }
+        }
     }
-    return { log: log || null, response: response || null };
+    return { finalResponse: finalResponse || null, log: log || null, response: response || null };
 };
-export const readOpencodeSessionTranscript = async ({ sessionId, since, cwd, }) => {
-    const reader = createOpencodeTaskSessionReader();
+export const readOpencodeSessionTranscript = async ({ sessionId, since, cwd, sessionOperations = hostOpencodeSessionOperations, }) => {
+    const reader = createOpencodeTaskSessionReader(sessionOperations);
     if (!reader) {
         return null;
     }
@@ -1497,7 +1488,7 @@ export const readOpencodeSessionTranscript = async ({ sessionId, since, cwd, })
         reader.close();
     }
 };
-export const createOpencodeSubagentMonitor = ({ initialParentSessionId, spawnTimestamp, cwd, tracker, onParentSessionId, taskSessionReader, discoverParentSession = true, parentDiscoveryDelayMs = 0, }) => {
+export const createOpencodeSubagentMonitor = ({ initialParentSessionId, spawnTimestamp, cwd, tracker, onParentSessionId, onActivity, taskSessionReader, discoverParentSession = true, parentDiscoveryDelayMs = 0, }) => {
     const reader = taskSessionReader === undefined ? createOpencodeTaskSessionReader() : taskSessionReader;
     let parentSessionId = initialParentSessionId;
     let timer = null;
@@ -1557,7 +1548,7 @@ export const createOpencodeSubagentMonitor = ({ initialParentSessionId, spawnTim
                 const transcript = childSessionId
                     ? reconstructOpencodeSubagentTranscript(await reader.listSessionParts(childSessionId), cwd)
                     : { log: null, response: null };
-                tracker.applySnapshot({
+                const changed = tracker.applySnapshot({
                     callId: invocation.callId,
                     label: invocation.label,
                     status: invocation.status,
@@ -1565,6 +1556,9 @@ export const createOpencodeSubagentMonitor = ({ initialParentSessionId, spawnTim
                     response: transcript.response ?? invocation.output,
                     sessionId: childSessionId ?? null,
                 });
+                if (changed) {
+                    onActivity?.();
+                }
             }
         }
         catch {
@@ -1648,6 +1642,19 @@ const interruptProcess = (state, signal) => {
     }
     killProcess(state.child, signal);
 };
+const interruptReviewProcess = async (state, child, signal) => {
+    if (!isProcessAlive(child)) {
+        return;
+    }
+    const interrupt = state.interrupts.get(child);
+    if (interrupt) {
+        await Promise.resolve(interrupt(signal)).catch(() => {
+            // The execution provider owns interruption failure reporting.
+        });
+        return;
+    }
+    killProcess(child, signal);
+};
 const waitForProcessExit = async (proc, timeoutMs) => {
     const deadline = Date.now() + timeoutMs;
     await new Promise(resolve => {
@@ -1682,6 +1689,7 @@ export const registerChatProcessPlaceholder = (chatSessionId) => {
     const state = {
         child: null,
         interrupt: null,
+        abortController: new AbortController(),
         researchChildren: new Set(),
         stopRequested: false,
         metadataRefresher: null,
@@ -1722,12 +1730,13 @@ const untrackSpecProcess = (specSessionId, state) => {
 // Registers a cancellation token for a spec session before its child process
 // exists. This closes the race window between the worker flipping the DB
 // status to 'running' and runSpecAgent() registering the abortable child: an
-// interrupt during that window sets stopRequested on this placeholder, which
-// the worker honors once its pre-step (prepareLinkedPlanningResearch) resolves.
+// interrupt during that window aborts preparation and sets stopRequested on
+// this placeholder, which the worker honors before starting the agent.
 export const registerSpecProcessPlaceholder = (specSessionId) => {
     const state = {
         child: null,
         interrupt: null,
+        abortController: new AbortController(),
         researchChildren: new Set(),
         stopRequested: false,
         metadataRefresher: null,
@@ -1752,6 +1761,7 @@ export const registerSpecReviewProcessPlaceholder = (specReviewRunId) => {
     const state = {
         child: null,
         interrupt: null,
+        abortController: new AbortController(),
         researchChildren: new Set(),
         stopRequested: false,
         metadataRefresher: null,
@@ -1767,7 +1777,7 @@ export const untrackSpecReviewProcessById = (specReviewRunId) => {
 };
 export const isBuildAgentRunning = (ticketId) => activeBuildProcesses.has(ticketId);
 export const registerReviewProcess = (ticketId) => {
-    const state = { children: new Set(), stopRequested: false };
+    const state = { children: new Set(), interrupts: new Map(), stopRequested: false };
     activeReviewProcesses.set(ticketId, state);
     return state;
 };
@@ -1823,14 +1833,10 @@ export const stopReviewAgent = async (ticketId) => {
     }
     state.stopRequested = true;
     const children = [...state.children];
-    for (const child of children) {
-        killProcess(child, 'SIGTERM');
-    }
+    await Promise.all(children.map(child => interruptReviewProcess(state, child, 'SIGTERM')));
     await Promise.all(children.map(child => waitForProcessExit(child, 5000)));
     const aliveChildren = children.filter(isProcessAlive);
-    for (const child of aliveChildren) {
-        killProcess(child, 'SIGKILL');
-    }
+    await Promise.all(aliveChildren.map(child => interruptReviewProcess(state, child, 'SIGKILL')));
     await Promise.all(aliveChildren.map(child => waitForProcessExit(child, 1000)));
     return true;
 };
@@ -1840,14 +1846,25 @@ export const stopChatAgent = async (chatSessionId) => {
         return false;
     }
     state.stopRequested = true;
+    state.abortController.abort(new Error('Chat stop requested'));
     state.metadataRefresher?.stop();
     if (!state.child) {
         return true;
     }
-    killProcess(state.child, 'SIGTERM');
+    if (state.interrupt) {
+        await state.interrupt('SIGTERM');
+    }
+    else {
+        killProcess(state.child, 'SIGTERM');
+    }
     await waitForProcessExit(state.child, 5000);
     if (isProcessAlive(state.child)) {
-        killProcess(state.child, 'SIGKILL');
+        if (state.interrupt) {
+            await state.interrupt('SIGKILL');
+        }
+        else {
+            killProcess(state.child, 'SIGKILL');
+        }
         await waitForProcessExit(state.child, 1000);
     }
     return true;
@@ -1858,23 +1875,43 @@ export const stopSpecAgent = async (specSessionId) => {
         return false;
     }
     state.stopRequested = true;
+    state.abortController.abort(new Error('Spec stop requested'));
     state.metadataRefresher?.stop();
-    const children = [...state.researchChildren];
-    if (state.child) {
-        children.push(state.child);
-    }
-    if (children.length === 0) {
+    const researchChildren = [...state.researchChildren];
+    if (researchChildren.length === 0 && !state.child) {
         return true;
     }
-    for (const child of children) {
+    for (const child of researchChildren) {
         killProcess(child, 'SIGTERM');
     }
-    await Promise.all(children.map(child => waitForProcessExit(child, 5000)));
-    const aliveChildren = children.filter(isProcessAlive);
-    for (const child of aliveChildren) {
+    if (state.child) {
+        if (state.interrupt) {
+            await state.interrupt('SIGTERM');
+        }
+        else {
+            killProcess(state.child, 'SIGTERM');
+        }
+    }
+    await Promise.all([
+        ...researchChildren.map(child => waitForProcessExit(child, 5000)),
+        ...(state.child ? [waitForProcessExit(state.child, 5000)] : []),
+    ]);
+    const aliveResearchChildren = researchChildren.filter(isProcessAlive);
+    for (const child of aliveResearchChildren) {
         killProcess(child, 'SIGKILL');
     }
-    await Promise.all(aliveChildren.map(child => waitForProcessExit(child, 1000)));
+    if (isProcessAlive(state.child)) {
+        if (state.interrupt) {
+            await state.interrupt('SIGKILL');
+        }
+        else {
+            killProcess(state.child, 'SIGKILL');
+        }
+    }
+    await Promise.all([
+        ...aliveResearchChildren.map(child => waitForProcessExit(child, 1000)),
+        ...(isProcessAlive(state.child) ? [waitForProcessExit(state.child, 1000)] : []),
+    ]);
     return true;
 };
 export const stopSpecReviewAgent = async (specReviewRunId) => {
@@ -1883,6 +1920,7 @@ export const stopSpecReviewAgent = async (specReviewRunId) => {
         return false;
     }
     state.stopRequested = true;
+    state.abortController.abort(new Error('Spec review stop requested'));
     state.metadataRefresher?.stop();
     if (!state.child) {
         return true;
@@ -1942,24 +1980,32 @@ const runAgentOnce = ({ ticketId, tool, prompt, cwd, io, model, variant = null,
         updateSessionId(ticketId, sessionId, sessionField, io);
     };
     const finalizeRun = (status, log, responseText, options = {}) => {
+        const { transcriptResponseText = responseText, ...statusOptions } = options;
         if (runStream) {
-            finalizeAgentRun(runStream.runId, status, responseText);
+            finalizeAgentRun(runStream.runId, status, transcriptResponseText);
             emitRunUpdate();
-            return subagentTracker.finalize(status, log, responseText);
+            return subagentTracker.finalize(status, log, transcriptResponseText);
         }
-        updateStatus(ticketId, status, log, io, responseText, options);
-        return subagentTracker.finalize(status, log, responseText);
+        updateStatus(ticketId, status, log, io, responseText, statusOptions);
+        return subagentTracker.finalize(status, log, transcriptResponseText);
     };
     return new Promise((resolve, reject) => {
         let sessionId = null;
         let spawnTimestamp = null;
         let sessionLookupTimer = null;
         let hasResolvedOpencodeSessionId = Boolean(resumeSessionId);
+        let hasTrustedOpencodeSessionId = Boolean(resumeSessionId);
         let opencodeSubagentMonitor = null;
         let settled = false;
         let startTime = null;
         let firstFinalAnswerTime = null;
+        let reviewFinalAnswerObserved = false;
         let reviewChild = null;
+        let reviewWatchdog = null;
+        let reviewKillTimer = null;
+        let reviewCompletionForced = false;
+        let reviewInactivityTimeoutForced = false;
+        let lastOutputAt = Date.now();
         let executionCapableEventObserved = false;
         const buildState = trackBuildProcess
             ? activeBuildProcesses.get(ticketId) ?? registerBuildProcessPlaceholder(ticketId)
@@ -1970,6 +2016,11 @@ const runAgentOnce = ({ ticketId, tool, prompt, cwd, io, model, variant = null,
             }
             settled = true;
             opencodeSubagentMonitor?.stop();
+            reviewWatchdog?.stop();
+            if (reviewKillTimer) {
+                clearTimeout(reviewKillTimer);
+                reviewKillTimer = null;
+            }
             if (sessionLookupTimer) {
                 clearTimeout(sessionLookupTimer);
                 sessionLookupTimer = null;
@@ -1979,12 +2030,13 @@ const runAgentOnce = ({ ticketId, tool, prompt, cwd, io, model, variant = null,
             }
             if (reviewChild) {
                 reviewProcessState?.children.delete(reviewChild);
+                reviewProcessState?.interrupts.delete(reviewChild);
             }
             handler(value);
         };
         const resolveOnce = settle(resolve);
         const rejectOnce = settle(reject);
-        const bindResolvedOpencodeSession = (resolvedId) => {
+        const bindResolvedOpencodeSession = (resolvedId, trusted = false) => {
             const normalized = resolvedId?.trim();
             if (!normalized) {
                 return;
@@ -1992,6 +2044,7 @@ const runAgentOnce = ({ ticketId, tool, prompt, cwd, io, model, variant = null,
             const shouldPersist = sessionId !== normalized;
             sessionId = normalized;
             hasResolvedOpencodeSessionId = true;
+            hasTrustedOpencodeSessionId = hasTrustedOpencodeSessionId || trusted;
             opencodeSubagentMonitor?.setParentSessionId(normalized);
             if (shouldPersist) {
                 writeRunSessionId(normalized);
@@ -2078,9 +2131,7 @@ const runAgentOnce = ({ ticketId, tool, prompt, cwd, io, model, variant = null,
         }
         if (reviewProcessState) {
             reviewProcessState.children.add(child);
-            if (reviewProcessState.stopRequested) {
-                killProcess(child, 'SIGTERM');
-            }
+            reviewProcessState.interrupts.set(child, interrupt);
         }
         void placementFailure.then(failure => {
             if (!failure || settled) {
@@ -2105,9 +2156,12 @@ const runAgentOnce = ({ ticketId, tool, prompt, cwd, io, model, variant = null,
                 onParentSessionId: discoveredSessionId => {
                     bindResolvedOpencodeSession(discoveredSessionId);
                 },
+                onActivity: () => {
+                    lastOutputAt = Date.now();
+                },
             });
             opencodeSubagentMonitor.start();
-            bindResolvedOpencodeSession(resumeSessionId);
+            bindResolvedOpencodeSession(resumeSessionId, true);
         }
         if (tool === 'claude') {
             const logLines = [];
@@ -2196,6 +2250,9 @@ const runAgentOnce = ({ ticketId, tool, prompt, cwd, io, model, variant = null,
                 const transcriptRuns = finalizeRun('error', getErrorMessage(resolvedError), null);
                 rejectOnce(attachTranscriptRunsToError(resolvedError, transcriptRuns));
             });
+            if (reviewProcessState?.stopRequested) {
+                void interruptReviewProcess(reviewProcessState, child, 'SIGTERM');
+            }
             return;
         }
         const logLines = [];
@@ -2207,7 +2264,27 @@ const runAgentOnce = ({ ticketId, tool, prompt, cwd, io, model, variant = null,
         const progressUpdater = createThrottledProgressUpdater(() => {
             writeRunStatus('running', logLines.join('\n\n'), responseLines.join('\n\n'));
         });
+        if (reviewProcessState && startTime !== null) {
+            reviewWatchdog = createReviewAgentWatchdog({
+                getLastOutputAt: () => lastOutputAt,
+                checkForCompletion: async () => reviewFinalAnswerObserved && !subagentTracker.hasRunningSubagents(),
+                onTrigger: async (trigger) => {
+                    if (trigger === 'completed') {
+                        reviewCompletionForced = true;
+                    }
+                    else {
+                        reviewInactivityTimeoutForced = true;
+                    }
+                    await interruptReviewProcess(reviewProcessState, child, 'SIGTERM');
+                    reviewKillTimer = setTimeout(() => {
+                        void interruptReviewProcess(reviewProcessState, child, 'SIGKILL');
+                    }, REVIEW_AGENT_KILL_GRACE_MS);
+                    reviewKillTimer.unref?.();
+                },
+            });
+        }
         child.stdout?.on('data', (chunk) => {
+            lastOutputAt = Date.now();
             const text = remainder + chunk.toString();
             const lines = text.split('\n');
             remainder = lines.pop() ?? '';
@@ -2230,13 +2307,19 @@ const runAgentOnce = ({ ticketId, tool, prompt, cwd, io, model, variant = null,
                 }
                 const parsed = parseOpencodeJsonLine(line);
                 const { logFragment, responseFragment, subagentEvents, providerSessionId } = parsed;
+                const hasExplicitFinalAnswer = parsed.recoveryEvents?.some(event => event.type === 'final_answer') === true;
                 if (isExecutionCapableParsedStreamLine(parsed)) {
                     executionCapableEventObserved = true;
+                    reviewFinalAnswerObserved = hasExplicitFinalAnswer;
+                }
+                else if (hasExplicitFinalAnswer) {
+                    reviewFinalAnswerObserved = true;
                 }
-                bindResolvedOpencodeSession(providerSessionId);
+                bindResolvedOpencodeSession(providerSessionId, true);
                 subagentTracker.handle(subagentEvents);
                 if (appendOpencodeTranscriptLine({ parsed, logLines, responseLines, recoveryTracker })) {
                     firstFinalAnswerTime = null;
+                    reviewFinalAnswerObserved = false;
                 }
                 if (logFragment !== null || responseFragment !== null) {
                     progressUpdater.schedule();
@@ -2256,6 +2339,11 @@ const runAgentOnce = ({ ticketId, tool, prompt, cwd, io, model, variant = null,
         }
         child.on('close', async (code) => {
             progressUpdater.cancel();
+            reviewWatchdog?.stop();
+            if (reviewKillTimer) {
+                clearTimeout(reviewKillTimer);
+                reviewKillTimer = null;
+            }
             const finalPlacementFailure = await placementCompletion;
             if (finalPlacementFailure || settled) {
                 return;
@@ -2266,34 +2354,82 @@ const runAgentOnce = ({ ticketId, tool, prompt, cwd, io, model, variant = null,
                 const { subagentEvents, providerSessionId } = parsed;
                 if (isExecutionCapableParsedStreamLine(parsed)) {
                     executionCapableEventObserved = true;
+                    reviewFinalAnswerObserved = false;
                 }
-                bindResolvedOpencodeSession(providerSessionId);
+                bindResolvedOpencodeSession(providerSessionId, true);
                 subagentTracker.handle(subagentEvents);
                 if (appendOpencodeTranscriptLine({ parsed, logLines, responseLines, recoveryTracker })) {
                     firstFinalAnswerTime = null;
                 }
             }
-            const resolvedSessionOnClose = await attemptOpencodeSessionLookup();
+            const collectCloseEnrichment = async () => {
+                const resolvedSessionOnClose = await attemptOpencodeSessionLookup();
+                await opencodeSubagentMonitor?.refresh();
+                const hasPersistedCompletion = Boolean(opencodeSessionOperations
+                    && hasTrustedOpencodeSessionId
+                    && sessionId
+                    && spawnTimestamp !== null
+                    && await opencodeSessionOperations.hasCompletedAssistantSince(sessionId, spawnTimestamp));
+                const persistedTranscript = hasPersistedCompletion && opencodeSessionOperations && sessionId
+                    ? await readOpencodeSessionTranscript({
+                        sessionId,
+                        since: spawnTimestamp ?? undefined,
+                        cwd,
+                        sessionOperations: opencodeSessionOperations,
+                    })
+                    : null;
+                return { resolvedSessionOnClose, hasPersistedCompletion, persistedTranscript };
+            };
+            const closeEnrichmentFallback = {
+                resolvedSessionOnClose: hasResolvedOpencodeSessionId,
+                hasPersistedCompletion: false,
+                persistedTranscript: null,
+            };
+            const closeEnrichment = reviewProcessState
+                ? await resolveWithin(collectCloseEnrichment(), REVIEW_AGENT_CLOSE_ENRICHMENT_TIMEOUT_MS, closeEnrichmentFallback)
+                : await collectCloseEnrichment();
+            const { resolvedSessionOnClose, hasPersistedCompletion, persistedTranscript } = closeEnrichment;
             if (sessionLookupTimer && (resolvedSessionOnClose || hasResolvedOpencodeSessionId)) {
                 clearTimeout(sessionLookupTimer);
                 sessionLookupTimer = null;
             }
             const stderrOutput = Buffer.concat(stderrChunks).toString();
-            await opencodeSubagentMonitor?.refresh();
-            const log = logLines.join('\n\n') || stderrOutput;
+            const log = logLines.join('\n\n') || persistedTranscript?.log || stderrOutput;
             const recoveredResponse = recoveryTracker.getRecoveredResponse();
-            const finalResponse = recoveryTracker.hasRecoveredFinalAnswer()
+            const streamedResponse = recoveryTracker.hasRecoveredFinalAnswer()
                 ? recoveredResponse
-                : responseLines.join('\n\n') || stderrOutput;
+                : responseLines.join('\n\n');
+            const persistedResponse = persistedTranscript?.response?.trim() ?? '';
+            const persistedFinalResponse = persistedTranscript?.finalResponse?.trim() ?? '';
+            const selectedPersistedResponse = reviewProcessState
+                ? persistedFinalResponse || (!streamedResponse ? persistedResponse : '')
+                : persistedResponse;
+            const finalResponse = selectedPersistedResponse && (reviewCompletionForced || hasPersistedCompletion || !streamedResponse)
+                ? selectedPersistedResponse
+                : streamedResponse || stderrOutput;
+            const transcriptResponseText = reviewProcessState && persistedResponse
+                ? persistedResponse
+                : finalResponse;
             const stderrModelError = parseOpencodeStderrModelResolutionError(stderrOutput);
             const timing = buildResponseTiming({ startTime, firstFinalAnswerTime, isStopped: Boolean(buildState?.stopRequested || reviewProcessState?.stopRequested) });
             if (buildState?.stopRequested || reviewProcessState?.stopRequested) {
-                const transcriptRuns = finalizeRun('stopped', log, finalResponse);
+                const transcriptRuns = finalizeRun('stopped', log, finalResponse, { transcriptResponseText });
                 resolveOnce(withTranscriptRuns({ response: finalResponse, responseTiming: timing, usageSnapshot }, transcriptRuns));
                 return;
             }
-            if (isSuccessfulOpencodeExit(code, stderrModelError, recoveryTracker)) {
-                const transcriptRuns = finalizeRun('done', log, finalResponse, { emit: emitSuccessUpdate });
+            const hasUsableReviewResponse = Boolean((persistedResponse || streamedResponse).trim());
+            if (reviewInactivityTimeoutForced) {
+                const message = `Review agent produced no output for ${REVIEW_AGENT_INACTIVITY_TIMEOUT_MS} ms.`;
+                const transcriptRuns = finalizeRun('error', log || message, finalResponse || null, { transcriptResponseText });
+                rejectOnce(attachTranscriptRunsToError(new Error(message), transcriptRuns));
+                return;
+            }
+            const forcedReviewCompletion = Boolean(reviewProcessState
+                && hasUsableReviewResponse
+                && !recoveryTracker.hasUnrecoveredError()
+                && reviewCompletionForced);
+            if (isSuccessfulOpencodeExit(code, stderrModelError, recoveryTracker) || forcedReviewCompletion) {
+                const transcriptRuns = finalizeRun('done', log, finalResponse, { emit: emitSuccessUpdate, transcriptResponseText });
                 resolveOnce(withTranscriptRuns({ response: finalResponse, responseTiming: timing, usageSnapshot }, transcriptRuns));
                 return;
             }
@@ -2313,27 +2449,51 @@ const runAgentOnce = ({ ticketId, tool, prompt, cwd, io, model, variant = null,
         });
         child.on('error', err => {
             progressUpdater.cancel();
+            reviewWatchdog?.stop();
+            if (reviewKillTimer) {
+                clearTimeout(reviewKillTimer);
+                reviewKillTimer = null;
+            }
+            if (remainder.trim()) {
+                usageSnapshot = mergeUsageFromJsonLine(usageSnapshot, remainder);
+                const parsed = parseOpencodeJsonLine(remainder);
+                bindResolvedOpencodeSession(parsed.providerSessionId, true);
+                subagentTracker.handle(parsed.subagentEvents);
+                appendOpencodeTranscriptLine({ parsed, logLines, responseLines, recoveryTracker });
+            }
+            const stderrOutput = Buffer.concat(stderrChunks).toString();
+            const log = logLines.join('\n\n') || stderrOutput;
+            const response = recoveryTracker.hasRecoveredFinalAnswer()
+                ? recoveryTracker.getRecoveredResponse()
+                : responseLines.join('\n\n') || stderrOutput;
             if (sessionLookupTimer && hasResolvedOpencodeSessionId) {
                 clearTimeout(sessionLookupTimer);
                 sessionLookupTimer = null;
             }
             if (buildState?.stopRequested || reviewProcessState?.stopRequested) {
-                const transcriptRuns = finalizeRun('stopped', null, null);
-                resolveOnce(withTranscriptRuns({ response: null, responseTiming: null }, transcriptRuns));
+                const transcriptRuns = finalizeRun('stopped', log, response);
+                resolveOnce(withTranscriptRuns({ response, responseTiming: null, usageSnapshot }, transcriptRuns));
                 return;
             }
             const resolvedError = agentProvider.classifyExecutionFailure(err);
-            const transcriptRuns = finalizeRun('error', getErrorMessage(resolvedError), null);
+            const transcriptRuns = finalizeRun('error', log || getErrorMessage(resolvedError), response);
             rejectOnce(attachTranscriptRunsToError(resolvedError, transcriptRuns));
         });
+        if (reviewProcessState?.stopRequested) {
+            void interruptReviewProcess(reviewProcessState, child, 'SIGTERM');
+        }
+        else {
+            reviewWatchdog?.start();
+        }
     });
 };
 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 runChatAgentOnce = ({ chatSessionId, tool, prompt, files = [], cwd, io, model, variant = null, resumeSessionId = null, opencodeAgentMode = 'build', executionContext, mainRun, spawnPermitId, executionProvider = hostExecutionEnvironment, executionTarget, executionLauncherEnvironment = createHostLauncherEnvironment(), executionRuntimeEnvironment = createLegacyHostRuntimeEnvironment(cwd, { PWD: cwd }), }) => {
     const resolvedModel = resolveAgentModel(tool, model);
+    const opencodeSessionOperations = executionProvider.sessionOperations?.opencode ?? null;
     const subagentTracker = createSubagentRunTracker({
         parentType: 'chat',
         parentId: chatSessionId,
@@ -2375,15 +2535,20 @@ const runChatAgentOnce = ({ chatSessionId, tool, prompt, files = [], cwd, io, mo
             }, transcriptRuns));
             return;
         }
-        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] : []), ...files.flatMap(filePath => ['--file', filePath]), ...(files.length > 0 ? ['--'] : []), prompt]];
+        const agentProvider = tool === 'claude'
+            ? claudeAgentProvider
+            : opencodeAgentProvider;
+        const invocation = agentProvider.buildStreamingInvocation({
+            cwd,
+            files,
+            prompt,
+            model: resolvedModel,
+            variant,
+            mode: opencodeAgentMode,
+            resumeSessionId,
+            sessionId: randomUUID(),
+        });
+        sessionId = invocation.sessionId;
         updateChatSessionStatus(chatSessionId, 'running', null, io);
         subagentTracker.updateMain(null, null);
         if (tool === 'claude' && sessionId) {
@@ -2397,6 +2562,7 @@ const runChatAgentOnce = ({ chatSessionId, tool, prompt, files = [], cwd, io, mo
                 io,
                 spawnTimestamp,
                 initialSessionId: resumeSessionId,
+                ...(opencodeSessionOperations ? { sessionOperations: opencodeSessionOperations } : {}),
             });
             chatState.metadataRefresher = opencodeMetadataRefresher;
             if (resumeSessionId) {
@@ -2409,6 +2575,7 @@ const runChatAgentOnce = ({ chatSessionId, tool, prompt, files = [], cwd, io, mo
             }
         }
         let child;
+        let placementCompletion;
         try {
             if (chatState.stopRequested) {
                 throw new AgentSpawnPermitRevokedError();
@@ -2416,27 +2583,40 @@ const runChatAgentOnce = ({ chatSessionId, tool, prompt, files = [], cwd, io, mo
             if (spawnPermitId) {
                 assertAgentSpawnPermit(spawnPermitId, executionContext.runId);
             }
-            child = spawn(cmd, args, {
+            const handle = executionProvider.execute({
+                phase: 'agent',
+                target: executionTarget ?? null,
+                command: invocation.command,
+                args: invocation.args,
                 cwd,
-                stdio: tool === 'claude' ? ['pipe', 'pipe', 'pipe'] : ['ignore', 'pipe', 'pipe'],
-                env: createWorkspaceProcessEnvironment(cwd, { PWD: cwd }),
+                stdio: invocation.stdio,
+                launcherEnvironment: executionLauncherEnvironment,
+                runtimeEnvironment: executionRuntimeEnvironment,
                 detached: process.platform !== 'win32',
             });
+            child = handle.child;
+            chatState.interrupt = handle.interrupt;
+            placementCompletion = 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;
         }
         chatState.child = child;
         activeChatProcesses.set(chatSessionId, chatState);
-        if (tool === 'claude') {
-            const claudePrompt = opencodeAgentMode === 'plan'
-                ? appendClaudeHeadlessPlanPrompt(prompt)
-                : prompt;
-            writeClaudeStdin(child, buildClaudeStdinMessage(claudePrompt, files, cwd));
+        if (invocation.stdin !== null) {
+            writeClaudeStdin(child, invocation.stdin);
         }
+        void placementCompletion.then(failure => {
+            if (!failure || settled) {
+                return;
+            }
+            const resolvedError = agentProvider.classifyExecutionFailure(failure);
+            const transcriptRuns = subagentTracker.finalize('error', resolvedError.message, null);
+            rejectOnce(attachTranscriptRunsToError(resolvedError, transcriptRuns));
+        });
         startTime = Date.now();
         if (tool === 'opencode' && spawnTimestamp !== null) {
             opencodeSubagentMonitor = createOpencodeSubagentMonitor({
@@ -2444,6 +2624,9 @@ const runChatAgentOnce = ({ chatSessionId, tool, prompt, files = [], cwd, io, mo
                 spawnTimestamp,
                 cwd,
                 tracker: subagentTracker,
+                taskSessionReader: opencodeSessionOperations
+                    ? createOpencodeTaskSessionReader(opencodeSessionOperations)
+                    : null,
                 discoverParentSession: false,
                 onParentSessionId: discoveredSessionId => {
                     updateChatSessionId(chatSessionId, 'opencode', discoveredSessionId, io);
@@ -2487,8 +2670,12 @@ const runChatAgentOnce = ({ chatSessionId, tool, prompt, files = [], cwd, io, mo
                 }
             });
             child.stderr?.on('data', (chunk) => stderrChunks.push(chunk));
-            child.on('close', code => {
+            child.on('close', async (code) => {
                 progressUpdater.cancel();
+                const placementFailure = await placementCompletion;
+                if (placementFailure || settled) {
+                    return;
+                }
                 if (remainder.trim()) {
                     usageSnapshot = mergeUsageFromJsonLine(usageSnapshot, remainder);
                     const parsed = parseClaudeStreamJsonLine(remainder);
@@ -2627,6 +2814,10 @@ const runChatAgentOnce = ({ chatSessionId, tool, prompt, files = [], cwd, io, mo
         }
         child.on('close', async (code) => {
             progressUpdater.cancel();
+            const placementFailure = await placementCompletion;
+            if (placementFailure || settled) {
+                return;
+            }
             if (remainder.trim()) {
                 usageSnapshot = mergeUsageFromJsonLine(usageSnapshot, remainder);
                 const parsed = parseOpencodeJsonLine(remainder, cwd);
@@ -2665,6 +2856,7 @@ const runChatAgentOnce = ({ chatSessionId, tool, prompt, files = [], cwd, io, mo
                         current: usageSnapshot,
                         sessionId: resolvedOpencodeSessionId,
                         spawnTimestamp,
+                        ...(opencodeSessionOperations ? { sessionOperations: opencodeSessionOperations } : {}),
                     });
                 }
                 updateChatSessionStatus(chatSessionId, 'running', preservedOutput?.log ?? null, io, preservedOutput?.response ?? null);
@@ -2689,6 +2881,7 @@ const runChatAgentOnce = ({ chatSessionId, tool, prompt, files = [], cwd, io, mo
                         current: usageSnapshot,
                         sessionId: resolvedOpencodeSessionId,
                         spawnTimestamp,
+                        ...(opencodeSessionOperations ? { sessionOperations: opencodeSessionOperations } : {}),
                     });
                 }
                 updateChatSessionStatus(chatSessionId, 'running', finalOutput.log, io, finalOutput.response);
@@ -2746,7 +2939,7 @@ 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 runSpecAgentOnce = ({ specSessionId, tool, prompt, files = [], cwd, io, model, variant = null, resumeSessionId = null, executionContext, mainRun, executionProvider = hostExecutionEnvironment, executionTarget, executionLauncherEnvironment = createHostLauncherEnvironment(), executionRuntimeEnvironment = createLegacyHostRuntimeEnvironment(cwd, { PWD: cwd }), }) => {
     const resolvedModel = resolveAgentModel(tool, model);
     const subagentTracker = createSubagentRunTracker({
         parentType: 'spec',
@@ -2822,13 +3015,27 @@ const runSpecAgentOnce = ({ specSessionId, tool, prompt, files = [], cwd, io, mo
             }
         }
         let child;
+        let placementFailure = Promise.resolve(null);
         try {
-            child = spawn(cmd, args, {
+            const handle = executionProvider.execute({
+                phase: 'agent',
+                target: executionTarget ?? null,
+                command: cmd,
+                args,
                 cwd,
                 stdio: tool === 'claude' ? ['pipe', 'pipe', 'pipe'] : ['ignore', 'pipe', 'pipe'],
-                env: createWorkspaceProcessEnvironment(cwd, { PWD: cwd }),
+                launcherEnvironment: executionLauncherEnvironment,
+                runtimeEnvironment: executionRuntimeEnvironment,
                 detached: process.platform !== 'win32',
             });
+            child = handle.child;
+            specState.interrupt = handle.interrupt;
+            placementFailure = handle.placementFailure;
+            void placementFailure.then(failure => {
+                if (failure) {
+                    rejectOnce(failure);
+                }
+            });
         }
         catch (error) {
             const resolvedError = error instanceof Error ? error : new Error(String(error));
@@ -2887,8 +3094,13 @@ const runSpecAgentOnce = ({ specSessionId, tool, prompt, files = [], cwd, io, mo
                 }
             });
             child.stderr?.on('data', (chunk) => stderrChunks.push(chunk));
-            child.on('close', code => {
+            child.on('close', async (code) => {
                 progressUpdater.cancel();
+                const placementError = await placementFailure;
+                if (placementError) {
+                    rejectOnce(placementError);
+                    return;
+                }
                 if (remainder.trim()) {
                     usageSnapshot = mergeUsageFromJsonLine(usageSnapshot, remainder);
                     const { logFragment, responseFragment, subagentEvents } = parseClaudeStreamJsonLine(remainder);
@@ -3016,6 +3228,11 @@ const runSpecAgentOnce = ({ specSessionId, tool, prompt, files = [], cwd, io, mo
         }
         child.on('close', async (code) => {
             progressUpdater.cancel();
+            const placementError = await placementFailure;
+            if (placementError) {
+                rejectOnce(placementError);
+                return;
+            }
             await opencodeSubagentMonitor?.refresh();
             if (remainder.trim()) {
                 usageSnapshot = mergeUsageFromJsonLine(usageSnapshot, remainder);
@@ -3141,7 +3358,7 @@ export const runSpecAgent = (options) => {
  * updateSpecReviewRunStatus / updateSpecReviewRunStreaming / updateSpecReviewRunUsage —
  * the spec_sessions row is never touched by this path.
  */
-const runSpecReviewAgentOnce = ({ specReviewRunId, specSessionId, tool, prompt, files = [], cwd, io, model, variant = null, executionContext, }) => {
+const runSpecReviewAgentOnce = ({ specReviewRunId, specSessionId, tool, prompt, files = [], cwd, io, model, variant = null, executionContext, executionProvider = hostExecutionEnvironment, executionTarget, executionLauncherEnvironment = createHostLauncherEnvironment(), executionRuntimeEnvironment = createLegacyHostRuntimeEnvironment(cwd, { PWD: cwd }), }) => {
     const registeredState = activeSpecReviewProcesses.get(specReviewRunId);
     if (registeredState?.stopRequested) {
         return Promise.resolve({
@@ -3169,6 +3386,7 @@ const runSpecReviewAgentOnce = ({ specReviewRunId, specSessionId, tool, prompt,
         const reviewState = registeredState ?? {
             child: null,
             interrupt: null,
+            abortController: new AbortController(),
             researchChildren: new Set(),
             stopRequested: false,
             metadataRefresher: null,
@@ -3189,42 +3407,39 @@ const runSpecReviewAgentOnce = ({ specReviewRunId, specSessionId, tool, prompt,
             buildClaudeArgs('plan', resolvedModel, null, randomUUID()),
         ];
         updateSpecReviewRunStreaming(specReviewRunId, null);
-        const env = createWorkspaceProcessEnvironment(cwd, { PWD: cwd });
         let child;
-        if (tool === 'opencode') {
-            const invocation = buildOpencodeSpecReviewInvocation({ prompt, files, model: resolvedModel, variant });
-            try {
-                const handle = hostExecutionEnvironment.execute({
-                    phase: 'agent',
-                    target: null,
-                    command: invocation.command,
-                    args: invocation.args,
-                    cwd,
-                    stdio: invocation.stdio,
-                    launcherEnvironment: createHostLauncherEnvironment(),
-                    runtimeEnvironment: createLegacyHostRuntimeEnvironment(cwd, { PWD: cwd }),
-                    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,
+        let placementFailure = Promise.resolve(null);
+        const invocation = tool === 'opencode'
+            ? buildOpencodeSpecReviewInvocation({ prompt, files, model: resolvedModel, variant })
+            : {
+                command: cmd,
+                args,
                 stdio: ['pipe', 'pipe', 'pipe'],
-                env,
+            };
+        try {
+            const handle = executionProvider.execute({
+                phase: 'agent',
+                target: executionTarget ?? null,
+                command: invocation.command,
+                args: invocation.args,
+                cwd,
+                stdio: invocation.stdio,
+                launcherEnvironment: executionLauncherEnvironment,
+                runtimeEnvironment: executionRuntimeEnvironment,
                 detached: process.platform !== 'win32',
             });
+            child = handle.child;
+            reviewState.interrupt = handle.interrupt;
+            placementFailure = handle.placementFailure;
+            void placementFailure.then(failure => {
+                if (failure) {
+                    rejectOnce(tool === 'opencode' ? opencodeAgentProvider.classifyExecutionFailure(failure) : failure);
+                }
+            });
+        }
+        catch (error) {
+            rejectOnce(tool === 'opencode' ? opencodeAgentProvider.classifyExecutionFailure(error) : error);
+            return;
         }
         reviewState.child = child;
         activeSpecReviewProcesses.set(specReviewRunId, reviewState);
@@ -3274,8 +3489,13 @@ const runSpecReviewAgentOnce = ({ specReviewRunId, specSessionId, tool, prompt,
                 }
             });
             child.stderr?.on('data', (chunk) => stderrChunks.push(chunk));
-            child.on('close', code => {
+            child.on('close', async (code) => {
                 progressUpdater.cancel();
+                const placementError = await placementFailure;
+                if (placementError) {
+                    rejectOnce(placementError);
+                    return;
+                }
                 if (remainder.trim()) {
                     usageSnapshot = mergeUsageFromJsonLine(usageSnapshot, remainder);
                     const { logFragment, responseFragment, subagentEvents } = parseClaudeStreamJsonLine(remainder);
@@ -3368,6 +3588,11 @@ const runSpecReviewAgentOnce = ({ specReviewRunId, specSessionId, tool, prompt,
         child.stderr?.on('data', (chunk) => stderrChunks.push(chunk));
         child.on('close', async (code) => {
             progressUpdater.cancel();
+            const placementError = await placementFailure;
+            if (placementError) {
+                rejectOnce(tool === 'opencode' ? opencodeAgentProvider.classifyExecutionFailure(placementError) : placementError);
+                return;
+            }
             await opencodeSubagentMonitor?.refresh();
             if (remainder.trim()) {
                 usageSnapshot = mergeUsageFromJsonLine(usageSnapshot, remainder);