@straiffi/archon 1.7.1 → 1.7.3

package/dist/server/lib/agent.js

@@ -11,7 +11,7 @@ import { appendClaudeHeadlessPlanPrompt, buildClaudeHeadlessPlanArgs } from './p
 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, listAgentRunsForParent, updateAgentRunLabel, updateAgentRunSessionId, updateAgentRunStatus } from './agentRuns.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';
@@ -313,6 +313,7 @@ const hasMatchingUsageSnapshot = (current, next) => {
         && current.usage_snapshot_reasoning_tokens === next.usage_snapshot_reasoning_tokens;
 };
 const activeBuildProcesses = new Map();
+const activeReviewProcesses = new Map();
 const activeChatProcesses = new Map();
 const activeSpecProcesses = new Map();
 const activeSpecReviewProcesses = new Map();
@@ -1319,12 +1320,19 @@ const appendOpencodeTranscriptLine = ({ parsed, logLines, responseLines, recover
     }
     return shouldResetResponse;
 };
-export const createSubagentRunTracker = ({ parentType, parentId, io, mainRun, }) => {
+export const createSubagentRunTracker = ({ parentType, parentId, io, mainRun, executionContext, deferMainFinalization = false, }) => {
     const trackedRuns = [];
-    let nextRunIndex = Math.max(getNextAgentRunIndex(parentType, parentId), mainRun ? mainRun.runIndex + 1 : 1);
+    let nextRunIndex = Math.max(executionContext ? getNextAgentRunIndex(executionContext.runId) : getNextAgentRunIndex(parentType, parentId), mainRun ? mainRun.runIndex + 1 : 1);
     const emitUpdate = () => {
         emitAgentRunsUpdated(io, parentType, parentId);
     };
+    const updateMain = (log, response) => {
+        if (!mainRun) {
+            return;
+        }
+        updateAgentRunStatus(mainRun.id, 'running', log, response);
+        emitUpdate();
+    };
     const findRun = (callId, sessionId) => {
         if (callId) {
             const callRun = trackedRuns.find(run => run.callId === callId);
@@ -1367,11 +1375,12 @@ export const createSubagentRunTracker = ({ parentType, parentId, io, mainRun, })
                     emitUpdate();
                     continue;
                 }
-                const runIndex = Math.max(getNextAgentRunIndex(parentType, parentId), nextRunIndex);
+                const runIndex = Math.max(executionContext ? getNextAgentRunIndex(executionContext.runId) : getNextAgentRunIndex(parentType, parentId), nextRunIndex);
                 const id = createAgentRun({
+                    ...(executionContext ? { executionRunId: executionContext.runId } : {}),
                     parentType,
                     parentId,
-                    runIndex,
+                    ...(!executionContext ? { runIndex } : {}),
                     label: event.label?.trim() || 'Subagent',
                     role: 'subagent',
                 });
@@ -1467,18 +1476,26 @@ export const createSubagentRunTracker = ({ parentType, parentId, io, mainRun, })
             run.status = status;
             finalizeAgentRun(run.id, status, run.response || null);
         }
-        emitUpdate();
+        if (mainRun) {
+            updateMain(parentLog, parentResponse);
+            if (!deferMainFinalization) {
+                finalizeAgentRun(mainRun.id, status, parentResponse);
+            }
+        }
+        if (!mainRun) {
+            emitUpdate();
+        }
         const trackedIds = new Set(trackedRuns.map(run => run.id));
-        const persistedRuns = listAgentRunsForParent(parentType, parentId)
+        const persistedRuns = (executionContext
+            ? listAgentRunsForExecutionRun(executionContext.runId)
+            : listAgentRunsForParent(parentType, parentId))
             .filter(run => trackedIds.has(run.id) || run.id === mainRun?.id);
-        const persistedIds = new Set(persistedRuns.map(run => run.id));
         const timestamp = new Date().toISOString();
         for (const run of trackedRuns) {
-            if (persistedIds.has(run.id)) {
-                continue;
-            }
-            persistedRuns.push({
+            const persistedRun = persistedRuns.find(candidate => candidate.id === run.id);
+            const snapshotRun = {
                 id: run.id,
+                execution_run_id: persistedRun?.execution_run_id ?? executionContext?.runId ?? null,
                 parent_type: parentType,
                 parent_id: parentId,
                 run_index: run.runIndex,
@@ -1488,15 +1505,25 @@ export const createSubagentRunTracker = ({ parentType, parentId, io, mainRun, })
                 agent_log: run.log || null,
                 streaming_response: null,
                 response_text: run.response || null,
+                failure_message: persistedRun?.failure_message ?? null,
                 session_id: run.sessionId,
-                created_at: run.createdAt,
-                updated_at: timestamp,
-            });
+                completed_at: persistedRun?.completed_at ?? timestamp,
+                created_at: persistedRun?.created_at ?? run.createdAt,
+                updated_at: persistedRun?.updated_at ?? timestamp,
+            };
+            const persistedRunIndex = persistedRuns.findIndex(candidate => candidate.id === run.id);
+            if (persistedRunIndex >= 0) {
+                persistedRuns[persistedRunIndex] = snapshotRun;
+            }
+            else {
+                persistedRuns.push(snapshotRun);
+            }
         }
         if (mainRun) {
             const persistedMainRun = persistedRuns.find(run => run.id === mainRun.id);
             const mainSnapshotRun = {
                 id: mainRun.id,
+                execution_run_id: persistedMainRun?.execution_run_id ?? null,
                 parent_type: parentType,
                 parent_id: parentId,
                 run_index: mainRun.runIndex,
@@ -1506,7 +1533,9 @@ export const createSubagentRunTracker = ({ parentType, parentId, io, mainRun, })
                 agent_log: parentLog,
                 streaming_response: null,
                 response_text: parentResponse,
+                failure_message: persistedMainRun?.failure_message ?? null,
                 session_id: persistedMainRun?.session_id ?? null,
+                completed_at: persistedMainRun?.completed_at ?? timestamp,
                 created_at: persistedMainRun?.created_at ?? timestamp,
                 updated_at: persistedMainRun?.updated_at ?? timestamp,
             };
@@ -1521,6 +1550,7 @@ export const createSubagentRunTracker = ({ parentType, parentId, io, mainRun, })
         else {
             persistedRuns.push({
                 id: `${parentType}:${parentId}:main`,
+                execution_run_id: null,
                 parent_type: parentType,
                 parent_id: parentId,
                 run_index: 0,
@@ -1530,14 +1560,22 @@ export const createSubagentRunTracker = ({ parentType, parentId, io, mainRun, })
                 agent_log: parentLog,
                 streaming_response: null,
                 response_text: parentResponse,
+                failure_message: null,
                 session_id: null,
+                completed_at: timestamp,
                 created_at: timestamp,
                 updated_at: timestamp,
             });
         }
         return createTranscriptRunSnapshots(persistedRuns.sort((left, right) => left.run_index - right.run_index));
     };
-    return { applySnapshot, handle, finalize };
+    const setMainSessionId = (sessionId) => {
+        const normalized = sessionId?.trim();
+        if (mainRun && normalized) {
+            updateAgentRunSessionId(mainRun.id, normalized);
+        }
+    };
+    return { applySnapshot, handle, finalize, setMainSessionId, updateMain };
 };
 export const reconstructOpencodeSubagentTranscript = (parts, cwd) => {
     let log = '';
@@ -1728,6 +1766,22 @@ const untrackChatProcess = (chatSessionId, state) => {
     state.metadataRefresher?.stop();
     state.metadataRefresher = null;
 };
+export const registerChatProcessPlaceholder = (chatSessionId) => {
+    const state = {
+        child: null,
+        researchChildren: new Set(),
+        stopRequested: false,
+        metadataRefresher: null,
+    };
+    activeChatProcesses.set(chatSessionId, state);
+    return state;
+};
+export const untrackChatProcessById = (chatSessionId) => {
+    const state = activeChatProcesses.get(chatSessionId);
+    if (state) {
+        untrackChatProcess(chatSessionId, state);
+    }
+};
 const untrackSpecProcess = (specSessionId, state) => {
     if (activeSpecProcesses.get(specSessionId) === state) {
         activeSpecProcesses.delete(specSessionId);
@@ -1743,6 +1797,7 @@ const untrackSpecProcess = (specSessionId, state) => {
 export const registerSpecProcessPlaceholder = (specSessionId) => {
     const state = {
         child: null,
+        researchChildren: new Set(),
         stopRequested: false,
         metadataRefresher: null,
     };
@@ -1763,6 +1818,24 @@ const untrackSpecReviewProcess = (specReviewRunId, state) => {
     state.metadataRefresher = null;
 };
 export const isBuildAgentRunning = (ticketId) => activeBuildProcesses.has(ticketId);
+export const registerReviewProcess = (ticketId) => {
+    const state = { children: new Set(), stopRequested: false };
+    activeReviewProcesses.set(ticketId, state);
+    return state;
+};
+export const untrackReviewProcess = (ticketId, state) => {
+    if (activeReviewProcesses.get(ticketId) === state) {
+        activeReviewProcesses.delete(ticketId);
+    }
+};
+export const isReviewAgentRunning = (ticketId) => activeReviewProcesses.has(ticketId);
+export const isReviewStopRequested = (ticketId) => {
+    return activeReviewProcesses.get(ticketId)?.stopRequested === true;
+};
+export const stopAllReviewAgents = async () => {
+    const ticketIds = [...activeReviewProcesses.keys()];
+    await Promise.all(ticketIds.map(stopReviewAgent));
+};
 export const stopAllBuildAgents = async () => {
     const ticketIds = [...activeBuildProcesses.keys()];
     await Promise.all(ticketIds.map(stopBuildAgent));
@@ -1781,13 +1854,34 @@ export const stopBuildAgent = async (ticketId) => {
     }
     return true;
 };
+export const stopReviewAgent = async (ticketId) => {
+    const state = activeReviewProcesses.get(ticketId);
+    if (!state) {
+        return false;
+    }
+    state.stopRequested = true;
+    const children = [...state.children];
+    for (const child of children) {
+        killProcess(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 => waitForProcessExit(child, 1000)));
+    return true;
+};
 export const stopChatAgent = async (chatSessionId) => {
     const state = activeChatProcesses.get(chatSessionId);
-    if (!state?.child) {
+    if (!state) {
         return false;
     }
     state.stopRequested = true;
     state.metadataRefresher?.stop();
+    if (!state.child) {
+        return true;
+    }
     killProcess(state.child, 'SIGTERM');
     await waitForProcessExit(state.child, 5000);
     if (isProcessAlive(state.child)) {
@@ -1803,20 +1897,22 @@ export const stopSpecAgent = async (specSessionId) => {
     }
     state.stopRequested = true;
     state.metadataRefresher?.stop();
-    // No child yet means we are in the pre-response window (the worker is still
-    // running prepareLinkedPlanningResearch). There is nothing to kill, but the
-    // stop request still succeeds: the worker honors stopRequested and finalizes
-    // the session to 'stopped' once its pre-step resolves. This mirrors how Chat
-    // treats an interrupt as accepted even before the agent child is live.
-    if (!state.child) {
+    const children = [...state.researchChildren];
+    if (state.child) {
+        children.push(state.child);
+    }
+    if (children.length === 0) {
         return true;
     }
-    killProcess(state.child, 'SIGTERM');
-    await waitForProcessExit(state.child, 5000);
-    if (isProcessAlive(state.child)) {
-        killProcess(state.child, 'SIGKILL');
-        await waitForProcessExit(state.child, 1000);
+    for (const child of children) {
+        killProcess(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 => waitForProcessExit(child, 1000)));
     return true;
 };
 export const stopSpecReviewAgent = async (specReviewRunId) => {
@@ -1834,7 +1930,7 @@ export const stopSpecReviewAgent = async (specReviewRunId) => {
     }
     return true;
 };
-export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = null, resumeSessionId = null, sessionField = 'session_id', trackBuildProcess = false, emitSuccessUpdate = true, opencodeAgentMode, runStream, }) => {
+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, }) => {
     const resolvedModel = resolveAgentModel(tool, model);
     const subagentTracker = createSubagentRunTracker({
         parentType: 'ticket',
@@ -1850,6 +1946,7 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
                 },
             }
             : {}),
+        executionContext,
     });
     const writeRunStatus = (status, log, streamingResponse = null, options = {}) => {
         if (runStream) {
@@ -1863,6 +1960,9 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
         if (runStream) {
             updateAgentRunSessionId(runStream.runId, sessionId);
             emitAgentRunsUpdated(io, 'ticket', ticketId);
+            if (persistSessionIdToTicket) {
+                updateSessionId(ticketId, sessionId, sessionField, io);
+            }
             return;
         }
         updateSessionId(ticketId, sessionId, sessionField, io);
@@ -1885,6 +1985,7 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
         let settled = false;
         let startTime = null;
         let firstFinalAnswerTime = null;
+        let reviewChild = null;
         const buildState = trackBuildProcess
             ? { child: null, stopRequested: false, sessionLookupTimer: null }
             : null;
@@ -1901,6 +2002,9 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
             if (trackBuildProcess && buildState) {
                 untrackBuildProcess(ticketId, buildState);
             }
+            if (reviewChild) {
+                reviewProcessState?.children.delete(reviewChild);
+            }
             handler(value);
         };
         const resolveOnce = settle(resolve);
@@ -1937,12 +2041,22 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
         if (tool === 'opencode') {
             spawnTimestamp = Date.now();
         }
-        const child = spawn(cmd, args, {
-            cwd,
-            stdio: tool === 'claude' ? ['pipe', 'pipe', 'pipe'] : ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, PWD: cwd },
-            detached: process.platform !== 'win32',
-        });
+        let child;
+        try {
+            child = spawn(cmd, args, {
+                cwd,
+                stdio: tool === 'claude' ? ['pipe', 'pipe', 'pipe'] : ['ignore', 'pipe', 'pipe'],
+                env: { ...process.env, PWD: cwd },
+                detached: process.platform !== 'win32',
+            });
+        }
+        catch (error) {
+            const resolvedError = error instanceof Error ? error : new Error(String(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)
@@ -1953,6 +2067,12 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
             buildState.child = child;
             activeBuildProcesses.set(ticketId, buildState);
         }
+        if (reviewProcessState) {
+            reviewProcessState.children.add(child);
+            if (reviewProcessState.stopRequested) {
+                killProcess(child, 'SIGTERM');
+            }
+        }
         startTime = Date.now();
         if (tool === 'opencode' && spawnTimestamp !== null) {
             opencodeSubagentMonitor = createOpencodeSubagentMonitor({
@@ -2018,7 +2138,7 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
                 const finalResponse = responseLines.join('\n\n') || errOutput;
                 const modelError = isModelResolutionError(finalLog);
                 const timing = startTime ? { totalMs: Date.now() - startTime } : null;
-                if (buildState?.stopRequested) {
+                if (buildState?.stopRequested || reviewProcessState?.stopRequested) {
                     const transcriptRuns = finalizeRun('stopped', finalLog, finalResponse);
                     resolveOnce(withTranscriptRuns({ response: finalResponse, responseTiming: timing, usageSnapshot }, transcriptRuns));
                     return;
@@ -2033,7 +2153,7 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
             });
             child.on('error', err => {
                 progressUpdater.cancel();
-                if (buildState?.stopRequested) {
+                if (buildState?.stopRequested || reviewProcessState?.stopRequested) {
                     const transcriptRuns = finalizeRun('stopped', null, null);
                     resolveOnce(withTranscriptRuns({ response: null, responseTiming: null, usageSnapshot }, transcriptRuns));
                     return;
@@ -2117,8 +2237,8 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
                 ? recoveredResponse
                 : responseLines.join('\n\n') || stderrOutput;
             const modelError = isModelResolutionError(log);
-            const timing = buildResponseTiming({ startTime, firstFinalAnswerTime, isStopped: Boolean(buildState?.stopRequested) });
-            if (buildState?.stopRequested) {
+            const timing = buildResponseTiming({ startTime, firstFinalAnswerTime, isStopped: Boolean(buildState?.stopRequested || reviewProcessState?.stopRequested) });
+            if (buildState?.stopRequested || reviewProcessState?.stopRequested) {
                 const transcriptRuns = finalizeRun('stopped', log, finalResponse);
                 resolveOnce(withTranscriptRuns({ response: finalResponse, responseTiming: timing }, transcriptRuns));
                 return;
@@ -2137,7 +2257,7 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
                 clearTimeout(sessionLookupTimer);
                 sessionLookupTimer = null;
             }
-            if (buildState?.stopRequested) {
+            if (buildState?.stopRequested || reviewProcessState?.stopRequested) {
                 const transcriptRuns = finalizeRun('stopped', null, null);
                 resolveOnce(withTranscriptRuns({ response: null, responseTiming: null }, transcriptRuns));
                 return;
@@ -2147,12 +2267,15 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
         });
     });
 };
-export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io, model, variant = null, resumeSessionId = null, opencodeAgentMode = 'build', }) => {
+export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io, model, variant = null, resumeSessionId = null, opencodeAgentMode = 'build', executionContext, mainRun, }) => {
     const resolvedModel = resolveAgentModel(tool, model);
     const subagentTracker = createSubagentRunTracker({
         parentType: 'chat',
         parentId: chatSessionId,
         io,
+        executionContext,
+        mainRun,
+        deferMainFinalization: true,
     });
     return new Promise((resolve, reject) => {
         let sessionId = null;
@@ -2163,11 +2286,7 @@ export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io,
         let startTime = null;
         let firstFinalAnswerTime = null;
         let usageSnapshot = EMPTY_CHAT_USAGE_SNAPSHOT;
-        const chatState = {
-            child: null,
-            stopRequested: false,
-            metadataRefresher: null,
-        };
+        const chatState = activeChatProcesses.get(chatSessionId) ?? registerChatProcessPlaceholder(chatSessionId);
         const settle = (handler) => (value) => {
             if (settled) {
                 return;
@@ -2180,6 +2299,16 @@ export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io,
         };
         const resolveOnce = settle(resolve);
         const rejectOnce = settle(reject);
+        if (chatState.stopRequested) {
+            const transcriptRuns = subagentTracker.finalize('stopped', null, null);
+            resolveOnce(withTranscriptRuns({
+                completionStatus: 'stopped',
+                finalResponse: null,
+                usageSnapshot,
+                responseTiming: null,
+            }, transcriptRuns));
+            return;
+        }
         const [cmd, args] = tool === 'claude'
             ? (() => {
                 sessionId = resumeSessionId || randomUUID();
@@ -2190,8 +2319,10 @@ export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io,
             })()
             : ['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]];
         updateChatSessionStatus(chatSessionId, 'running', null, io);
+        subagentTracker.updateMain(null, null);
         if (tool === 'claude' && sessionId) {
             updateChatSessionId(chatSessionId, tool, sessionId, io);
+            subagentTracker.setMainSessionId(sessionId);
         }
         if (tool === 'opencode') {
             spawnTimestamp = Date.now();
@@ -2209,12 +2340,21 @@ export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io,
                 }
             }
         }
-        const child = spawn(cmd, args, {
-            cwd,
-            stdio: tool === 'claude' ? ['pipe', 'pipe', 'pipe'] : ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, PWD: cwd },
-            detached: process.platform !== 'win32',
-        });
+        let child;
+        try {
+            child = spawn(cmd, args, {
+                cwd,
+                stdio: tool === 'claude' ? ['pipe', 'pipe', 'pipe'] : ['ignore', 'pipe', 'pipe'],
+                env: { ...process.env, PWD: cwd },
+                detached: process.platform !== 'win32',
+            });
+        }
+        catch (error) {
+            const resolvedError = error instanceof Error ? error : new Error(String(error));
+            const transcriptRuns = subagentTracker.finalize('error', resolvedError.message, null);
+            rejectOnce(attachTranscriptRunsToError(resolvedError, transcriptRuns));
+            return;
+        }
         chatState.child = child;
         activeChatProcesses.set(chatSessionId, chatState);
         if (tool === 'claude') {
@@ -2233,6 +2373,7 @@ export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io,
                 discoverParentSession: false,
                 onParentSessionId: discoveredSessionId => {
                     updateChatSessionId(chatSessionId, 'opencode', discoveredSessionId, io);
+                    subagentTracker.setMainSessionId(discoveredSessionId);
                 },
             });
             opencodeSubagentMonitor.start();
@@ -2243,7 +2384,10 @@ export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io,
             let remainder = '';
             const stderrChunks = [];
             const progressUpdater = createThrottledProgressUpdater(() => {
-                updateChatSessionStatus(chatSessionId, 'running', logLines.join('\n\n'), io, responseLines.join('\n\n'));
+                const log = logLines.join('\n\n');
+                const response = responseLines.join('\n\n');
+                updateChatSessionStatus(chatSessionId, 'running', log, io, response);
+                subagentTracker.updateMain(log, response);
             });
             child.stdout?.on('data', (chunk) => {
                 const text = remainder + chunk.toString();
@@ -2350,7 +2494,10 @@ export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io,
         let remainder = '';
         const stderrChunks = [];
         const progressUpdater = createThrottledProgressUpdater(() => {
-            updateChatSessionStatus(chatSessionId, 'running', logLines.join('\n\n'), io, responseLines.join('\n\n'));
+            const log = logLines.join('\n\n');
+            const response = responseLines.join('\n\n');
+            updateChatSessionStatus(chatSessionId, 'running', log, io, response);
+            subagentTracker.updateMain(log, response);
         });
         child.stdout?.on('data', (chunk) => {
             const text = remainder + chunk.toString();
@@ -2492,12 +2639,15 @@ export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io,
         });
     });
 };
-export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io, model, variant = null, resumeSessionId = null, }) => {
+export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io, model, variant = null, resumeSessionId = null, executionContext, mainRun, }) => {
     const resolvedModel = resolveAgentModel(tool, model);
     const subagentTracker = createSubagentRunTracker({
         parentType: 'spec',
         parentId: specSessionId,
         io,
+        executionContext,
+        mainRun,
+        deferMainFinalization: true,
     });
     return new Promise((resolve, reject) => {
         let sessionId = null;
@@ -2508,11 +2658,7 @@ export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io,
         let startTime = null;
         let firstFinalAnswerTime = null;
         let usageSnapshot = EMPTY_CHAT_USAGE_SNAPSHOT;
-        const specState = {
-            child: null,
-            stopRequested: false,
-            metadataRefresher: null,
-        };
+        const specState = activeSpecProcesses.get(specSessionId) ?? registerSpecProcessPlaceholder(specSessionId);
         const settle = (handler) => (value) => {
             if (settled) {
                 return;
@@ -2525,6 +2671,16 @@ export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io,
         };
         const resolveOnce = settle(resolve);
         const rejectOnce = settle(reject);
+        if (specState.stopRequested) {
+            const transcriptRuns = subagentTracker.finalize('stopped', null, null);
+            resolveOnce(withTranscriptRuns({
+                completionStatus: 'stopped',
+                finalResponse: null,
+                usageSnapshot,
+                responseTiming: null,
+            }, transcriptRuns));
+            return;
+        }
         const [cmd, args] = tool === 'claude'
             ? (() => {
                 sessionId = resumeSessionId || randomUUID();
@@ -2535,8 +2691,10 @@ export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io,
             })()
             : ['opencode', ['run', '--agent', 'plan', '--format', 'json', '--thinking', ...(resumeSessionId ? ['--session', resumeSessionId] : []), ...(resolvedModel ? ['--model', resolvedModel] : []), ...(variant ? ['--variant', variant] : []), ...files.flatMap(filePath => ['--file', filePath]), ...(files.length > 0 ? ['--'] : []), prompt]];
         updateSpecSessionStatusLocal(specSessionId, 'running', null, io);
+        subagentTracker.updateMain(null, null);
         if (tool === 'claude' && sessionId) {
             updateSpecSessionIdLocal(specSessionId, tool, sessionId, io);
+            subagentTracker.setMainSessionId(sessionId);
         }
         if (tool === 'opencode') {
             spawnTimestamp = Date.now();
@@ -2554,12 +2712,21 @@ export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io,
                 }
             }
         }
-        const child = spawn(cmd, args, {
-            cwd,
-            stdio: tool === 'claude' ? ['pipe', 'pipe', 'pipe'] : ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, PWD: cwd },
-            detached: process.platform !== 'win32',
-        });
+        let child;
+        try {
+            child = spawn(cmd, args, {
+                cwd,
+                stdio: tool === 'claude' ? ['pipe', 'pipe', 'pipe'] : ['ignore', 'pipe', 'pipe'],
+                env: { ...process.env, PWD: cwd },
+                detached: process.platform !== 'win32',
+            });
+        }
+        catch (error) {
+            const resolvedError = error instanceof Error ? error : new Error(String(error));
+            const transcriptRuns = subagentTracker.finalize('error', resolvedError.message, null);
+            rejectOnce(attachTranscriptRunsToError(resolvedError, transcriptRuns));
+            return;
+        }
         specState.child = child;
         activeSpecProcesses.set(specSessionId, specState);
         if (tool === 'claude') {
@@ -2575,6 +2742,7 @@ export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io,
                 discoverParentSession: false,
                 onParentSessionId: discoveredSessionId => {
                     updateSpecSessionIdLocal(specSessionId, 'opencode', discoveredSessionId, io);
+                    subagentTracker.setMainSessionId(discoveredSessionId);
                 },
             });
             opencodeSubagentMonitor.start();
@@ -2585,7 +2753,10 @@ export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io,
             let remainder = '';
             const stderrChunks = [];
             const progressUpdater = createThrottledProgressUpdater(() => {
-                updateSpecSessionStatusLocal(specSessionId, 'running', logLines.join('\n\n'), io, responseLines.join('\n\n'));
+                const log = logLines.join('\n\n');
+                const response = responseLines.join('\n\n');
+                updateSpecSessionStatusLocal(specSessionId, 'running', log, io, response);
+                subagentTracker.updateMain(log, response);
             });
             child.stdout?.on('data', (chunk) => {
                 const text = remainder + chunk.toString();
@@ -2692,7 +2863,10 @@ export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io,
         let remainder = '';
         const stderrChunks = [];
         const progressUpdater = createThrottledProgressUpdater(() => {
-            updateSpecSessionStatusLocal(specSessionId, 'running', logLines.join('\n\n'), io, responseLines.join('\n\n'));
+            const log = logLines.join('\n\n');
+            const response = responseLines.join('\n\n');
+            updateSpecSessionStatusLocal(specSessionId, 'running', log, io, response);
+            subagentTracker.updateMain(log, response);
         });
         child.stdout?.on('data', (chunk) => {
             const text = remainder + chunk.toString();
@@ -2845,15 +3019,24 @@ 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, tool, prompt, files = [], cwd, io, model, variant = null, }) => {
+export const runSpecReviewAgent = ({ specReviewRunId, specSessionId, tool, prompt, files = [], cwd, io, model, variant = null, executionContext, }) => {
     const resolvedModel = resolveAgentModel(tool, model);
+    const subagentTracker = createSubagentRunTracker({
+        parentType: 'spec',
+        parentId: specSessionId,
+        io,
+        executionContext,
+    });
     return new Promise((resolve, reject) => {
+        let spawnTimestamp = null;
+        let opencodeSubagentMonitor = null;
         let settled = false;
         let startTime = null;
         let firstFinalAnswerTime = null;
         let usageSnapshot = EMPTY_CHAT_USAGE_SNAPSHOT;
         const reviewState = {
             child: null,
+            researchChildren: new Set(),
             stopRequested: false,
             metadataRefresher: null,
         };
@@ -2862,14 +3045,12 @@ export const runSpecReviewAgent = ({ specReviewRunId, tool, prompt, files = [],
                 return;
             }
             settled = true;
+            opencodeSubagentMonitor?.stop();
             untrackSpecReviewProcess(specReviewRunId, reviewState);
             handler(value);
         };
         const resolveOnce = settle(resolve);
         const rejectOnce = settle(reject);
-        const emitReviewUpdated = () => {
-            io.emit('spec-review:updated', { spec_review_run_id: specReviewRunId });
-        };
         const [cmd, args] = tool === 'claude'
             ? [
                 'claude',
@@ -2877,7 +3058,6 @@ export const runSpecReviewAgent = ({ specReviewRunId, tool, prompt, files = [],
             ]
             : ['opencode', ['run', '--agent', 'plan', '--format', 'json', '--thinking', ...(resolvedModel ? ['--model', resolvedModel] : []), ...(variant ? ['--variant', variant] : []), ...files.flatMap(filePath => ['--file', filePath]), ...(files.length > 0 ? ['--'] : []), prompt]];
         updateSpecReviewRunStreaming(specReviewRunId, null);
-        emitReviewUpdated();
         const child = spawn(cmd, args, {
             cwd,
             stdio: tool === 'claude' ? ['pipe', 'pipe', 'pipe'] : ['ignore', 'pipe', 'pipe'],
@@ -2890,6 +3070,16 @@ export const runSpecReviewAgent = ({ specReviewRunId, tool, prompt, files = [],
             writeClaudeStdin(child, buildClaudeStdinMessage(appendClaudeHeadlessPlanPrompt(prompt), files, cwd));
         }
         startTime = Date.now();
+        if (tool === 'opencode') {
+            spawnTimestamp = startTime;
+            opencodeSubagentMonitor = createOpencodeSubagentMonitor({
+                initialParentSessionId: null,
+                spawnTimestamp,
+                cwd,
+                tracker: subagentTracker,
+            });
+            opencodeSubagentMonitor.start();
+        }
         if (tool === 'claude') {
             const logLines = [];
             const responseLines = [];
@@ -2904,7 +3094,8 @@ export const runSpecReviewAgent = ({ specReviewRunId, tool, prompt, files = [],
                 remainder = lines.pop() ?? '';
                 for (const line of lines) {
                     usageSnapshot = mergeUsageFromJsonLine(usageSnapshot, line);
-                    const { logFragment, responseFragment } = parseClaudeStreamJsonLine(line);
+                    const { logFragment, responseFragment, subagentEvents } = parseClaudeStreamJsonLine(line);
+                    subagentTracker.handle(subagentEvents);
                     if (logFragment !== null) {
                         logLines.push(logFragment);
                     }
@@ -2921,7 +3112,8 @@ export const runSpecReviewAgent = ({ specReviewRunId, tool, prompt, files = [],
                 progressUpdater.cancel();
                 if (remainder.trim()) {
                     usageSnapshot = mergeUsageFromJsonLine(usageSnapshot, remainder);
-                    const { logFragment, responseFragment } = parseClaudeStreamJsonLine(remainder);
+                    const { logFragment, responseFragment, subagentEvents } = parseClaudeStreamJsonLine(remainder);
+                    subagentTracker.handle(subagentEvents);
                     if (logFragment !== null) {
                         logLines.push(logFragment);
                     }
@@ -2934,6 +3126,7 @@ export const runSpecReviewAgent = ({ specReviewRunId, tool, prompt, files = [],
                 const finalResponse = responseLines.join('\n\n') || errOutput;
                 if (reviewState.stopRequested) {
                     updateSpecReviewRunStreaming(specReviewRunId, finalResponse || null);
+                    subagentTracker.finalize('stopped', finalLog || null, finalResponse || null);
                     resolveOnce({
                         completionStatus: 'stopped',
                         finalResponse,
@@ -2945,6 +3138,7 @@ export const runSpecReviewAgent = ({ specReviewRunId, tool, prompt, files = [],
                 const modelError = isModelResolutionError(finalLog);
                 if (code === 0 && !modelError) {
                     updateSpecReviewRunStreaming(specReviewRunId, finalResponse || null);
+                    subagentTracker.finalize('done', finalLog || null, finalResponse || null);
                     resolveOnce({
                         completionStatus: 'done',
                         finalResponse,
@@ -2953,10 +3147,12 @@ export const runSpecReviewAgent = ({ specReviewRunId, tool, prompt, files = [],
                     });
                     return;
                 }
+                subagentTracker.finalize('error', finalLog || null, finalResponse || null);
                 rejectOnce(new Error(`Agent exited with code ${code ?? 'null'}\n${finalLog}${errOutput !== finalLog && errOutput ? '\n\n' + errOutput : ''}`));
             });
             child.on('error', err => {
                 progressUpdater.cancel();
+                subagentTracker.finalize(reviewState.stopRequested ? 'stopped' : 'error', getErrorMessage(err), null);
                 rejectOnce(err instanceof Error ? err : new Error(getErrorMessage(err)));
             });
             return;
@@ -2991,7 +3187,9 @@ export const runSpecReviewAgent = ({ specReviewRunId, tool, prompt, files = [],
                     }
                 }
                 const parsed = parseOpencodeJsonLine(line, cwd);
-                const { logFragment, responseFragment } = parsed;
+                const { logFragment, responseFragment, subagentEvents, providerSessionId } = parsed;
+                opencodeSubagentMonitor?.setParentSessionId(providerSessionId);
+                subagentTracker.handle(subagentEvents);
                 if (appendOpencodeTranscriptLine({ parsed, logLines, responseLines, recoveryTracker })) {
                     firstFinalAnswerTime = null;
                 }
@@ -3003,9 +3201,12 @@ export const runSpecReviewAgent = ({ specReviewRunId, tool, prompt, files = [],
         child.stderr?.on('data', (chunk) => stderrChunks.push(chunk));
         child.on('close', code => {
             progressUpdater.cancel();
+            opencodeSubagentMonitor?.refresh();
             if (remainder.trim()) {
                 usageSnapshot = mergeUsageFromJsonLine(usageSnapshot, remainder);
                 const parsed = parseOpencodeJsonLine(remainder, cwd);
+                opencodeSubagentMonitor?.setParentSessionId(parsed.providerSessionId);
+                subagentTracker.handle(parsed.subagentEvents);
                 if (appendOpencodeTranscriptLine({ parsed, logLines, responseLines, recoveryTracker })) {
                     firstFinalAnswerTime = null;
                 }
@@ -3018,6 +3219,7 @@ export const runSpecReviewAgent = ({ specReviewRunId, tool, prompt, files = [],
                 : responseLines.join('\n\n') || stderrOutput;
             if (reviewState.stopRequested) {
                 updateSpecReviewRunStreaming(specReviewRunId, finalResponse || null);
+                subagentTracker.finalize('stopped', log || null, finalResponse || null);
                 resolveOnce({
                     completionStatus: 'stopped',
                     finalResponse,
@@ -3029,6 +3231,7 @@ export const runSpecReviewAgent = ({ specReviewRunId, tool, prompt, files = [],
             const modelError = isModelResolutionError(log);
             if (isSuccessfulOpencodeExit(code, modelError, recoveryTracker)) {
                 updateSpecReviewRunStreaming(specReviewRunId, finalResponse || null);
+                subagentTracker.finalize('done', log || null, finalResponse || null);
                 resolveOnce({
                     completionStatus: 'done',
                     finalResponse,
@@ -3037,10 +3240,12 @@ export const runSpecReviewAgent = ({ specReviewRunId, tool, prompt, files = [],
                 });
                 return;
             }
+            subagentTracker.finalize('error', log || null, finalResponse || null);
             rejectOnce(new Error(`Agent exited with code ${code ?? 'null'}\n${log}${stderrOutput !== log && stderrOutput ? '\n\n' + stderrOutput : ''}`));
         });
         child.on('error', err => {
             progressUpdater.cancel();
+            subagentTracker.finalize(reviewState.stopRequested ? 'stopped' : 'error', getErrorMessage(err), null);
             rejectOnce(err instanceof Error ? err : new Error(getErrorMessage(err)));
         });
     });