@straiffi/archon 1.7.1 → 1.7.3

package/dist/server/workers/plan.js

@@ -24,30 +24,50 @@ import { beginTicketThinkingRun, bindTicketThinkingMessage } from '../lib/thinki
 import { createTicketMessage, upsertTicketDescriptionMessage } from '../lib/ticketMessages.js';
 import { getTicket, resolveTicketBranch, resolveTicketTool, resolveTicketWorkerKey } from '../lib/tickets.js';
 import { createOpencodeSubagentMonitor, createSubagentRunTracker, formatAgentErrorForTranscript, getAgentErrorTranscriptRuns, storeTicketUsageSnapshot, storeTicketUsageSnapshotDirect, mergeUsageFromJsonLine, EMPTY_CHAT_USAGE_SNAPSHOT } from '../lib/agent.js';
-import { clearAndEmitAgentRunsForParent, createAgentRun, finalizeAgentRun, getNextAgentRunIndex } from '../lib/agentRuns.js';
+import { createAgentRun, emitAgentRunsUpdated, finalizeAgentRun, getNextAgentRunIndex, terminalizeAgentRunsForExecutionRun } from '../lib/agentRuns.js';
+import { addExecutionRunLink, createExecutionRun, transitionExecutionRun } from '../lib/executionRuns.js';
+const resolvePlannerAgentRunParent = (options) => {
+    if (options.agentRunParent) {
+        return options.agentRunParent;
+    }
+    if (options.ticketId && options.io) {
+        return { parentType: 'ticket', parentId: options.ticketId, io: options.io };
+    }
+    return undefined;
+};
 const createPlanningInvocation = (options, label, role) => {
-    const parentType = options.ticketId ? 'ticket' : options.projectId ? 'planning' : null;
-    const parentId = options.ticketId ?? options.projectId ?? null;
+    const parentType = options.agentRunParent?.parentType ?? (options.ticketId ? 'ticket' : options.projectId ? 'planning' : null);
+    const parentId = options.agentRunParent?.parentId ?? options.ticketId ?? options.projectId ?? null;
     if (!parentType || !parentId) {
         return null;
     }
+    const runIndex = options.executionContext
+        ? getNextAgentRunIndex(options.executionContext.runId)
+        : getNextAgentRunIndex(parentType, parentId);
+    const persistedRole = role === 'research-selection' || role === 'research' ? role : 'main';
     return {
         parentType,
         parentId,
-        runId: createAgentRun({
+        id: createAgentRun({
+            ...(options.executionContext ? { executionRunId: options.executionContext.runId } : {}),
             parentType,
             parentId,
-            runIndex: getNextAgentRunIndex(parentType, parentId),
+            ...(!options.executionContext ? { runIndex } : {}),
             label,
-            role,
+            role: persistedRole,
         }),
+        runIndex,
+        label,
+        role: persistedRole,
     };
 };
-const finalizePlanningInvocation = (invocation, status, response) => {
+const finalizePlanningInvocation = (invocation, status, evidence) => {
     if (invocation) {
-        finalizeAgentRun(invocation.runId, status, response);
+        finalizeAgentRun(invocation.id, status, status === 'done' ? evidence : null, status === 'error' ? evidence : null);
     }
 };
+const activePlanProcesses = new Map();
+const activePlannerProcesses = new Set();
 const createPlannerRecoveryTracker = () => {
     let sawError = false;
     let latestEvent = null;
@@ -116,6 +136,19 @@ const extractLeadingJsonObject = (line) => {
     }
     return null;
 };
+const extractLeadingJsonObjects = (line) => {
+    const jsonObjects = [];
+    let remainder = line.trim();
+    while (remainder.startsWith('{')) {
+        const jsonObject = extractLeadingJsonObject(remainder);
+        if (!jsonObject) {
+            break;
+        }
+        jsonObjects.push(jsonObject);
+        remainder = remainder.slice(jsonObject.length).trim();
+    }
+    return { jsonObjects, remainder };
+};
 const normalizeToolName = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, '');
 const isPlannerSubagentTool = (name) => {
     const normalized = normalizeToolName(name);
@@ -332,35 +365,7 @@ const formatPlannerStepTitle = (event) => {
     const title = event.part?.title?.trim();
     return title || null;
 };
-const parseOpencodePlannerJsonLine = (line) => {
-    const trimmedLine = line.trim();
-    if (!trimmedLine) {
-        return emptyParsedPlannerStreamLine();
-    }
-    const jsonLine = extractLeadingJsonObject(trimmedLine);
-    if (!jsonLine) {
-        const envelope = parseOpencodeTaskEnvelope(trimmedLine);
-        if (envelope) {
-            return {
-                ...emptyParsedPlannerStreamLine(),
-                subagentEvents: [{
-                        kind: 'complete',
-                        callId: null,
-                        sessionId: envelope.childSessionId,
-                        status: envelope.state?.toLowerCase() === 'error' || envelope.state?.toLowerCase() === 'failed' ? 'error' : 'done',
-                        ...(envelope.result ? { text: envelope.result } : {}),
-                    }],
-            };
-        }
-        return { ...emptyParsedPlannerStreamLine(), logFragment: trimmedLine, responseFragment: trimmedLine };
-    }
-    let event;
-    try {
-        event = JSON.parse(jsonLine);
-    }
-    catch {
-        return { ...emptyParsedPlannerStreamLine(), logFragment: trimmedLine, responseFragment: trimmedLine };
-    }
+const parseOpencodePlannerJsonEvent = (event) => {
     const providerSessionId = event.sessionID?.trim()
         || event.sessionId?.trim()
         || event.part?.sessionID?.trim()
@@ -374,6 +379,7 @@ const parseOpencodePlannerJsonLine = (line) => {
             responseFragment: text && (!phase || phase === 'final_answer') ? text : null,
             subagentEvents: [],
             providerSessionId,
+            hasFinalAnswer: Boolean(text && (!phase || phase === 'final_answer')),
             recoveryEvents: text && phase === 'final_answer'
                 ? [{ type: 'final_answer', text }]
                 : [],
@@ -460,6 +466,86 @@ const parseOpencodePlannerJsonLine = (line) => {
     }
     return { ...emptyParsedPlannerStreamLine(), providerSessionId };
 };
+const parseOpencodePlannerJsonLine = (line) => {
+    const trimmedLine = line.trim();
+    if (!trimmedLine) {
+        return emptyParsedPlannerStreamLine();
+    }
+    const { jsonObjects, remainder } = extractLeadingJsonObjects(trimmedLine);
+    if (jsonObjects.length === 0) {
+        if (trimmedLine.startsWith('{')) {
+            return emptyParsedPlannerStreamLine();
+        }
+        const envelope = parseOpencodeTaskEnvelope(trimmedLine);
+        if (envelope) {
+            return {
+                ...emptyParsedPlannerStreamLine(),
+                subagentEvents: [{
+                        kind: 'complete',
+                        callId: null,
+                        sessionId: envelope.childSessionId,
+                        status: envelope.state?.toLowerCase() === 'error' || envelope.state?.toLowerCase() === 'failed' ? 'error' : 'done',
+                        ...(envelope.result ? { text: envelope.result } : {}),
+                    }],
+            };
+        }
+        return { ...emptyParsedPlannerStreamLine(), logFragment: trimmedLine, responseFragment: trimmedLine };
+    }
+    const logFragments = [];
+    const responseFragments = [];
+    const subagentEvents = [];
+    const recoveryEvents = [];
+    let providerSessionId = null;
+    let hasFinalAnswer = false;
+    for (const jsonObject of jsonObjects) {
+        let event;
+        try {
+            event = JSON.parse(jsonObject);
+        }
+        catch {
+            continue;
+        }
+        const parsedEvent = parseOpencodePlannerJsonEvent(event);
+        const eventRecoveryEvents = parsedEvent.recoveryEvents ?? [];
+        if (eventRecoveryEvents.some(recoveryEvent => recoveryEvent.type === 'error')) {
+            responseFragments.length = 0;
+        }
+        if (parsedEvent.logFragment !== null) {
+            logFragments.push(parsedEvent.logFragment);
+        }
+        if (parsedEvent.responseFragment !== null) {
+            responseFragments.push(parsedEvent.responseFragment);
+        }
+        subagentEvents.push(...parsedEvent.subagentEvents);
+        recoveryEvents.push(...eventRecoveryEvents);
+        providerSessionId = providerSessionId ?? parsedEvent.providerSessionId;
+        hasFinalAnswer ||= parsedEvent.hasFinalAnswer === true;
+    }
+    if (remainder) {
+        const envelope = parseOpencodeTaskEnvelope(remainder);
+        if (envelope) {
+            subagentEvents.push({
+                kind: 'complete',
+                callId: null,
+                sessionId: envelope.childSessionId,
+                status: envelope.state?.toLowerCase() === 'error' || envelope.state?.toLowerCase() === 'failed' ? 'error' : 'done',
+                ...(envelope.result ? { text: envelope.result } : {}),
+            });
+        }
+        else if (logFragments.length === 0 && responseFragments.length === 0 && subagentEvents.length === 0 && recoveryEvents.length === 0) {
+            logFragments.push(remainder);
+            responseFragments.push(remainder);
+        }
+    }
+    return {
+        logFragment: logFragments.length > 0 ? logFragments.join('\n\n') : null,
+        responseFragment: responseFragments.length > 0 ? responseFragments.join('\n\n') : null,
+        subagentEvents,
+        providerSessionId,
+        recoveryEvents,
+        hasFinalAnswer,
+    };
+};
 const attachPlannerTranscriptRuns = (error, transcriptRuns) => {
     const resolvedError = (error instanceof Error ? error : new Error(String(error)));
     if (transcriptRuns) {
@@ -883,7 +969,7 @@ const killPlannerProcess = (proc, signal) => {
         }
         catch (error) {
             if (error.code === 'ESRCH') {
-                return;
+                // The child may not have a process group; fall back to signaling it directly.
             }
         }
     }
@@ -894,6 +980,18 @@ const killPlannerProcess = (proc, signal) => {
         // best-effort
     }
 };
+export const stopPlannerProcesses = async (children) => {
+    for (const child of children) {
+        killPlannerProcess(child, 'SIGTERM');
+    }
+    const deadline = Date.now() + PLANNER_KILL_GRACE_MS;
+    while (children.some(isPlannerProcessAlive) && Date.now() < deadline) {
+        await new Promise(resolve => setTimeout(resolve, 100));
+    }
+    for (const child of children.filter(isPlannerProcessAlive)) {
+        killPlannerProcess(child, 'SIGKILL');
+    }
+};
 const opencodeSessionHasCompletedAssistantSince = (sessionId, sinceMs) => {
     try {
         const opencodeDb = new Database(resolveOpencodeDbPath(), { readonly: true });
@@ -964,6 +1062,9 @@ export const runPlannerPrompt = (tool, model, variant, prompt, cwd, options = {}
             ? createSubagentRunTracker({
                 ...options.agentRunParent,
                 io: options.agentRunParent.io,
+                executionContext: options.executionContext,
+                mainRun: options.mainRun,
+                deferMainFinalization: Boolean(options.mainRun),
             })
             : null;
         let opencodeSubagentMonitor = null;
@@ -1011,11 +1112,28 @@ export const runPlannerPrompt = (tool, model, variant, prompt, cwd, options = {}
         if (tool === 'opencode' && (sessionTracking || subagentTracker)) {
             spawnTimestamp = Date.now();
         }
-        const child = spawn(cmd, args, {
-            stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, ...(cwd ? { PWD: cwd } : {}) },
-            ...(cwd ? { cwd } : {}),
-        });
+        let child;
+        try {
+            child = spawn(cmd, args, {
+                stdio: ['ignore', 'pipe', 'pipe'],
+                env: { ...process.env, ...(cwd ? { PWD: cwd } : {}) },
+                detached: process.platform !== 'win32',
+                ...(cwd ? { cwd } : {}),
+            });
+        }
+        catch (error) {
+            const resolvedError = error instanceof Error ? error : new Error(String(error));
+            const transcriptRuns = subagentTracker?.finalize('error', resolvedError.message, null) ?? null;
+            rejectOnce(attachPlannerTranscriptRuns(resolvedError, transcriptRuns));
+            return;
+        }
+        activePlannerProcesses.add(child);
+        if (options.cancellationState) {
+            options.cancellationState.researchChildren.add(child);
+            if (options.cancellationState.stopRequested) {
+                killPlannerProcess(child, 'SIGTERM');
+            }
+        }
         if (sessionTracking && tool === 'claude' && sessionId) {
             hasResolvedSessionId = true;
             updatePlanningSessionId(sessionTracking.ticketId, sessionId, sessionTracking.io);
@@ -1070,21 +1188,6 @@ export const runPlannerPrompt = (tool, model, variant, prompt, cwd, options = {}
                 if (tool === 'claude') {
                     usageSnapshot = mergeUsageFromJsonLine(usageSnapshot, line);
                 }
-                if (tool === 'opencode' && firstFinalAnswerTime === null) {
-                    const trimmedLine = line.trim();
-                    if (trimmedLine.startsWith('{')) {
-                        try {
-                            const event = JSON.parse(trimmedLine);
-                            if (event.type === 'text' && event.part?.type === 'text' && event.part.text) {
-                                const phase = event.part.metadata?.openai?.phase;
-                                if (!phase || phase === 'final_answer') {
-                                    firstFinalAnswerTime = Date.now();
-                                }
-                            }
-                        }
-                        catch { /* best-effort timing */ }
-                    }
-                }
                 const parsedLine = tool === 'claude'
                     ? parseClaudePlannerStreamJsonLine(line)
                     : parseOpencodePlannerJsonLine(line);
@@ -1093,6 +1196,9 @@ export const runPlannerPrompt = (tool, model, variant, prompt, cwd, options = {}
                     responseLines.length = 0;
                     firstFinalAnswerTime = null;
                 }
+                if (tool === 'opencode' && firstFinalAnswerTime === null && parsedLine.hasFinalAnswer) {
+                    firstFinalAnswerTime = Date.now();
+                }
                 subagentTracker?.handle(subagentEvents);
                 if (providerSessionId) {
                     opencodeSubagentMonitor?.setParentSessionId(providerSessionId);
@@ -1117,6 +1223,8 @@ export const runPlannerPrompt = (tool, model, variant, prompt, cwd, options = {}
         });
         child.stderr?.on('data', (chunk) => stderrChunks.push(chunk));
         child.on('close', code => {
+            activePlannerProcesses.delete(child);
+            options.cancellationState?.researchChildren.delete(child);
             clearWatchdogTimer();
             opencodeSubagentMonitor?.refresh();
             const resolvedSessionOnClose = attemptOpencodeSessionLookup();
@@ -1136,6 +1244,9 @@ export const runPlannerPrompt = (tool, model, variant, prompt, cwd, options = {}
                     responseLines.length = 0;
                     firstFinalAnswerTime = null;
                 }
+                if (tool === 'opencode' && firstFinalAnswerTime === null && parsedLine.hasFinalAnswer) {
+                    firstFinalAnswerTime = Date.now();
+                }
                 subagentTracker?.handle(subagentEvents);
                 if (providerSessionId) {
                     opencodeSubagentMonitor?.setParentSessionId(providerSessionId);
@@ -1150,11 +1261,14 @@ export const runPlannerPrompt = (tool, model, variant, prompt, cwd, options = {}
             }
             const rawOutput = Buffer.concat(stdoutChunks).toString().trim();
             const recoveredResponse = recoveryTracker.getRecoveredResponse();
+            const parsedResponse = responseLines.join('\n\n').trim();
             const output = tool === 'opencode' && recoveryTracker.hasRecoveredFinalAnswer()
                 ? recoveredResponse
-                : tool === 'claude' && !rawOutput.startsWith('{')
-                    ? rawOutput
-                    : responseLines.join('\n\n').trim() || rawOutput;
+                : tool === 'opencode'
+                    ? parsedResponse || (rawOutput.startsWith('{') ? '' : rawOutput)
+                    : !rawOutput.startsWith('{')
+                        ? rawOutput
+                        : parsedResponse || rawOutput;
             const errorOutput = Buffer.concat(stderrChunks).toString().trim();
             const timing = (() => {
                 const totalMs = Date.now() - startTime;
@@ -1165,6 +1279,11 @@ export const runPlannerPrompt = (tool, model, variant, prompt, cwd, options = {}
                 }
                 return { totalMs };
             })();
+            if (options.cancellationState?.stopRequested) {
+                const transcriptRuns = subagentTracker?.finalize('stopped', logLines.join('\n\n') || errorOutput || null, output || null) ?? null;
+                rejectOnce(attachPlannerTranscriptRuns(new Error(output || errorOutput || 'Planning was stopped.'), transcriptRuns));
+                return;
+            }
             if (hardTimeoutForced) {
                 const transcriptRuns = subagentTracker?.finalize('error', logLines.join('\n\n') || errorOutput || null, output || null) ?? null;
                 rejectOnce(attachPlannerTranscriptRuns(new Error(output || errorOutput || `Planner exceeded the ${PLANNER_HARD_TIMEOUT_MS} ms hard timeout.`), transcriptRuns));
@@ -1180,16 +1299,20 @@ export const runPlannerPrompt = (tool, model, variant, prompt, cwd, options = {}
             const fallbackError = code === 0
                 ? 'Planner did not return a usable plan.'
                 : `Process exited with code ${code}`;
-            const transcriptRuns = subagentTracker?.finalize('error', logLines.join('\n\n') || errorOutput || null, output || null) ?? null;
+            const finalStatus = options.cancellationState?.stopRequested ? 'stopped' : 'error';
+            const transcriptRuns = subagentTracker?.finalize(finalStatus, logLines.join('\n\n') || errorOutput || null, output || null) ?? null;
             rejectOnce(attachPlannerTranscriptRuns(new Error(output || errorOutput || fallbackError), transcriptRuns));
         });
         child.on('error', err => {
+            activePlannerProcesses.delete(child);
+            options.cancellationState?.researchChildren.delete(child);
             clearWatchdogTimer();
             if (sessionLookupTimer && hasResolvedSessionId) {
                 clearTimeout(sessionLookupTimer);
                 sessionLookupTimer = null;
             }
-            const transcriptRuns = subagentTracker?.finalize('error', err.message, null) ?? null;
+            const finalStatus = options.cancellationState?.stopRequested ? 'stopped' : 'error';
+            const transcriptRuns = subagentTracker?.finalize(finalStatus, err.message, null) ?? null;
             rejectOnce(attachPlannerTranscriptRuns(err, transcriptRuns));
         });
         if (tool === 'opencode') {
@@ -1475,11 +1598,22 @@ export const prepareLinkedPlanningResearch = async (taskDescription, options = {
     }
     const tool = options.tool ?? config.tool ?? 'opencode';
     let decision;
+    const selectionInvocation = createPlanningInvocation(options, 'Linked Research Selection', 'research-selection');
     try {
-        const { output } = await runPlannerPrompt(tool, options.model ?? null, options.variant ?? null, buildLinkedProjectSelectionPrompt(taskDescription, project, linkedProjects), cwd);
+        const { output } = await runPlannerPrompt(tool, options.model ?? null, options.variant ?? null, buildLinkedProjectSelectionPrompt(taskDescription, project, linkedProjects), cwd, {
+            agentRunParent: resolvePlannerAgentRunParent(options),
+            executionContext: options.executionContext,
+            cancellationState: options.cancellationState,
+            ...(selectionInvocation ? { mainRun: selectionInvocation } : {}),
+        });
         decision = extractFirstJsonObject(output);
+        finalizePlanningInvocation(selectionInvocation, 'done', output);
     }
-    catch {
+    catch (error) {
+        finalizePlanningInvocation(selectionInvocation, options.cancellationState?.stopRequested ? 'stopped' : 'error', error instanceof Error ? error.message : String(error));
+        if (options.executionContext?.kind === 'planning_agent') {
+            throw error;
+        }
         return [];
     }
     const requests = normalizeLinkedResearchRequests(decision, linkedProjects);
@@ -1492,8 +1626,22 @@ export const prepareLinkedPlanningResearch = async (taskDescription, options = {
         if (!linkedProject) {
             throw new Error(`Linked project ${request.project_id} is no longer available`);
         }
-        const { output } = await runPlannerPrompt(tool, options.model ?? null, options.variant ?? null, prependSkillPromptBlock(buildLinkedProjectResearchPrompt(project, linkedProject, request), options.skills ?? []), linkedProject.repo_path);
-        return normalizeLinkedResearchResponse(extractFirstJsonObject(output), linkedProject, request);
+        const invocation = createPlanningInvocation(options, `Linked Research: ${linkedProject.name}`, 'research');
+        try {
+            const { output } = await runPlannerPrompt(tool, options.model ?? null, options.variant ?? null, prependSkillPromptBlock(buildLinkedProjectResearchPrompt(project, linkedProject, request), options.skills ?? []), linkedProject.repo_path, {
+                agentRunParent: resolvePlannerAgentRunParent(options),
+                executionContext: options.executionContext,
+                cancellationState: options.cancellationState,
+                ...(invocation ? { mainRun: invocation } : {}),
+            });
+            const result = normalizeLinkedResearchResponse(extractFirstJsonObject(output), linkedProject, request);
+            finalizePlanningInvocation(invocation, 'done', output);
+            return result;
+        }
+        catch (error) {
+            finalizePlanningInvocation(invocation, options.cancellationState?.stopRequested ? 'stopped' : 'error', error instanceof Error ? error.message : String(error));
+            throw error;
+        }
     }));
     return linkedResearch;
 };
@@ -1509,7 +1657,7 @@ export const generatePlanText = (title, description, options = {}) => {
             stage: 'plan',
             title,
             description,
-            ...(invocation ? { invocation: { parentType: invocation.parentType, parentId: invocation.parentId, agentRunId: invocation.runId } } : {}),
+            ...(invocation ? { invocation: { parentType: invocation.parentType, parentId: invocation.parentId, agentRunId: invocation.id } } : {}),
         });
         const { output: plannerOutput, responseTiming: plannerTiming, usageSnapshot, transcriptRuns } = await runPlannerPrompt(tool, options.model ?? null, options.variant ?? null, prependSkillPromptBlock(buildSingleTicketPrompt(title, description, linkedResearchContext, projectMemoryBlock, Boolean(project?.memory_enabled)), options.skills ?? []), resolvePlannerCwd(project, options.branch), {
             onProgress: options.onProgress,
@@ -1527,6 +1675,9 @@ export const generatePlanText = (title, description, options = {}) => {
                     },
                 }
                 : {}),
+            executionContext: options.executionContext,
+            cancellationState: options.cancellationState,
+            ...(invocation ? { mainRun: invocation } : {}),
         });
         try {
             const expanded = extractTaggedJsonObjectWithLeadingText(plannerOutput, PLAN_OUTPUT_TAG)
@@ -1549,8 +1700,10 @@ export const generatePlanText = (title, description, options = {}) => {
             return result;
         }
         catch (error) {
-            finalizePlanningInvocation(invocation, 'error', plannerOutput);
-            throw attachPlannerTranscriptRuns(error, transcriptRuns ?? null);
+            const finalStatus = options.cancellationState?.stopRequested ? 'stopped' : 'error';
+            finalizePlanningInvocation(invocation, finalStatus, plannerOutput);
+            const finalTranscriptRuns = transcriptRuns?.map(run => (run.id === invocation?.id ? { ...run, agent_status: finalStatus } : run)) ?? null;
+            throw attachPlannerTranscriptRuns(error, finalTranscriptRuns);
         }
     })();
 };
@@ -1558,23 +1711,27 @@ export const generatePlanningTicketOutline = async (description, options = {}) =
     const tool = options.tool ?? config.tool ?? 'opencode';
     const project = options.projectId ? getProjectById(options.projectId) : null;
     const invocation = createPlanningInvocation(options, 'Planning Outline', 'planning-outline');
-    const linkedResearch = options.linkedResearch ?? await prepareLinkedPlanningResearch(description, options);
-    const linkedResearchContext = project ? buildLinkedResearchContext(project, linkedResearch) : '';
-    const projectMemoryBlock = getProjectMemoryPromptBlock(project?.id, {
-        flow: 'plan',
-        stage: 'plan',
-        title: description,
-        description,
-        ...(invocation ? { invocation: { parentType: invocation.parentType, parentId: invocation.parentId, agentRunId: invocation.runId } } : {}),
-    });
-    const { output } = await runPlannerPrompt(tool, options.model ?? null, options.variant ?? null, prependSkillPromptBlock(buildPlanningAgentOutlinePrompt(description, linkedResearchContext, projectMemoryBlock), options.skills ?? []), resolvePlannerCwd(project, options.branch));
     try {
+        const linkedResearch = options.linkedResearch ?? await prepareLinkedPlanningResearch(description, options);
+        const linkedResearchContext = project ? buildLinkedResearchContext(project, linkedResearch) : '';
+        const projectMemoryBlock = getProjectMemoryPromptBlock(project?.id, {
+            flow: 'plan',
+            stage: 'plan',
+            title: description,
+            description,
+            ...(invocation ? { invocation: { parentType: invocation.parentType, parentId: invocation.parentId, agentRunId: invocation.id } } : {}),
+        });
+        const { output } = await runPlannerPrompt(tool, options.model ?? null, options.variant ?? null, prependSkillPromptBlock(buildPlanningAgentOutlinePrompt(description, linkedResearchContext, projectMemoryBlock), options.skills ?? []), resolvePlannerCwd(project, options.branch), {
+            agentRunParent: resolvePlannerAgentRunParent(options),
+            executionContext: options.executionContext,
+            ...(invocation ? { mainRun: invocation } : {}),
+        });
         const result = extractFirstJsonObject(output);
         finalizePlanningInvocation(invocation, 'done', output);
         return result;
     }
     catch (error) {
-        finalizePlanningInvocation(invocation, 'error', output);
+        finalizePlanningInvocation(invocation, 'error', error instanceof Error ? error.message : String(error));
         throw error;
     }
 };
@@ -1582,23 +1739,27 @@ export const expandPlanningTicketOutline = async (description, outline, options
     const tool = options.tool ?? config.tool ?? 'opencode';
     const project = options.projectId ? getProjectById(options.projectId) : null;
     const invocation = createPlanningInvocation(options, 'Planning Expansion', 'planning-expansion');
-    const linkedResearch = options.linkedResearch ?? await prepareLinkedPlanningResearch(description, options);
-    const linkedResearchContext = project ? buildLinkedResearchContext(project, linkedResearch) : '';
-    const projectMemoryBlock = getProjectMemoryPromptBlock(project?.id, {
-        flow: 'plan',
-        stage: 'plan',
-        title: description,
-        description,
-        ...(invocation ? { invocation: { parentType: invocation.parentType, parentId: invocation.parentId, agentRunId: invocation.runId } } : {}),
-    });
-    const { output } = await runPlannerPrompt(tool, options.model ?? null, options.variant ?? null, prependSkillPromptBlock(buildPlanningAgentExpansionPrompt(description, outline, linkedResearchContext, projectMemoryBlock), options.skills ?? []), resolvePlannerCwd(project, options.branch));
     try {
+        const linkedResearch = options.linkedResearch ?? await prepareLinkedPlanningResearch(description, options);
+        const linkedResearchContext = project ? buildLinkedResearchContext(project, linkedResearch) : '';
+        const projectMemoryBlock = getProjectMemoryPromptBlock(project?.id, {
+            flow: 'plan',
+            stage: 'plan',
+            title: description,
+            description,
+            ...(invocation ? { invocation: { parentType: invocation.parentType, parentId: invocation.parentId, agentRunId: invocation.id } } : {}),
+        });
+        const { output } = await runPlannerPrompt(tool, options.model ?? null, options.variant ?? null, prependSkillPromptBlock(buildPlanningAgentExpansionPrompt(description, outline, linkedResearchContext, projectMemoryBlock), options.skills ?? []), resolvePlannerCwd(project, options.branch), {
+            agentRunParent: resolvePlannerAgentRunParent(options),
+            executionContext: options.executionContext,
+            ...(invocation ? { mainRun: invocation } : {}),
+        });
         const result = extractFirstJsonObject(output);
         finalizePlanningInvocation(invocation, 'done', output);
         return result;
     }
     catch (error) {
-        finalizePlanningInvocation(invocation, 'error', output);
+        finalizePlanningInvocation(invocation, 'error', error instanceof Error ? error.message : String(error));
         throw error;
     }
 };
@@ -1612,114 +1773,292 @@ const updatePlanningProgress = (ticketId, log, response, io) => {
     db.prepare('UPDATE tickets SET agent_status = ?, agent_log = ?, streaming_response = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?').run('running', log ?? null, response ?? null, ticketId);
     emitTicketUpdate(ticketId, io);
 };
+const appendPlanResultLink = (executionContext, ticketId, messageId) => {
+    addExecutionRunLink({
+        projectId: executionContext.projectId,
+        runId: executionContext.runId,
+        link: {
+            entityType: 'ticket_message',
+            entityId: messageId,
+            relationship: 'result',
+            expectedParent: { entityType: 'ticket', entityId: ticketId },
+        },
+    });
+};
+const persistPlanCancellationMessage = (ticketId, executionContext, transcriptRuns) => {
+    const messageId = createTicketMessage({
+        ticketId,
+        role: 'assistant',
+        kind: 'error',
+        content: 'Planning was stopped.',
+        transcriptRuns,
+    });
+    appendPlanResultLink(executionContext, ticketId, messageId);
+};
 export const startPlan = (ticket, io, options = {}) => {
     const jobKey = resolveTicketWorkerKey(ticket, 'plan');
     if (!jobKey || isRunning(jobKey)) {
-        return;
-    }
-    enqueue(jobKey, async () => {
-        registerBundleActivity(ticket, 'plan');
-        beginTicketThinkingRun(ticket.id);
-        db.prepare('UPDATE tickets SET agent_status = ?, agent_log = NULL, streaming_response = NULL, updated_at = CURRENT_TIMESTAMP WHERE id = ?').run('running', ticket.id);
-        clearAndEmitAgentRunsForParent(io, 'ticket', ticket.id);
-        emitTicketUpdate(ticket.id, io);
-        try {
-            const project = getEffectiveProject(ticket);
-            const branch = options.branch === undefined ? resolveTicketBranch(ticket) : options.branch;
-            const planningDescription = await resolveExternalPlanningDescription(project?.id ?? ticket.project_id, ticket.description);
-            const initiativePrompt = ticket.planning_context?.initiative_prompt?.trim() || planningDescription;
-            const planned = await generatePlanText(ticket.title, planningDescription, {
-                tool: resolveTicketTool(ticket, config.tool ?? 'opencode'),
-                model: ticket.model,
-                variant: ticket.variant,
-                skills: options.skills ?? ticket.skills ?? [],
-                projectId: project?.id ?? ticket.project_id,
-                branch,
-                planningSessionId: ticket.planning_session_id,
-                ticketId: ticket.id,
-                io,
-                onProgress: progress => {
-                    updatePlanningProgress(ticket.id, progress.log, progress.response, io);
-                },
-            });
-            const resolvedTool = resolveTicketTool(ticket, config.tool ?? 'opencode');
-            if (resolvedTool === 'opencode') {
-                const freshTicket = getTicket(ticket.id);
-                if (freshTicket?.planning_session_id) {
-                    storeTicketUsageSnapshot(freshTicket.id, freshTicket.planning_session_id);
+        return { accepted: false, reason: 'busy', error: 'Ticket planning is already scheduled or running' };
+    }
+    const project = getEffectiveProject(ticket);
+    if (!project || project.id !== ticket.project_id) {
+        return { accepted: false, reason: 'project_unavailable', error: 'Ticket project is unavailable' };
+    }
+    const executionRun = createExecutionRun({
+        projectId: project.id,
+        kind: 'plan',
+        domainStatus: 'queued',
+        sourceReference: { kind: 'ticket', id: ticket.id, label: ticket.title },
+        eventType: 'plan_created',
+    }, io);
+    const executionContext = {
+        runId: executionRun.id,
+        correlationId: executionRun.correlation_id,
+        projectId: executionRun.project_id,
+        kind: executionRun.kind,
+    };
+    const cancellationState = { researchChildren: new Set(), stopRequested: false };
+    activePlanProcesses.set(ticket.id, cancellationState);
+    let queuedJob;
+    try {
+        queuedJob = enqueue(jobKey, async () => {
+            let callbackStarted = false;
+            let activityRegistered = false;
+            try {
+                registerBundleActivity(ticket, 'plan');
+                activityRegistered = true;
+                transitionExecutionRun({
+                    projectId: executionContext.projectId,
+                    runId: executionContext.runId,
+                    status: 'running',
+                    domainStatus: 'running',
+                    eventType: 'plan_started',
+                }, io);
+                const currentTicket = getTicket(ticket.id);
+                if (!currentTicket || currentTicket.project_id !== executionContext.projectId) {
+                    throw new Error('Ticket no longer exists in the execution project');
                 }
-            }
-            else if (resolvedTool === 'claude' && planned.usageSnapshot) {
-                const freshTicket = getTicket(ticket.id);
-                if (freshTicket) {
-                    storeTicketUsageSnapshotDirect(freshTicket.id, planned.usageSnapshot);
+                beginTicketThinkingRun(ticket.id);
+                db.prepare('UPDATE tickets SET agent_status = ?, agent_log = NULL, streaming_response = NULL, updated_at = CURRENT_TIMESTAMP WHERE id = ?').run('running', ticket.id);
+                emitAgentRunsUpdated(io, 'ticket', ticket.id);
+                emitTicketUpdate(ticket.id, io);
+                callbackStarted = true;
+                if (cancellationState.stopRequested) {
+                    persistPlanCancellationMessage(ticket.id, executionContext);
+                    terminalizeAgentRunsForExecutionRun(executionContext.runId, 'stopped');
+                    db.prepare('UPDATE tickets SET agent_status = ?, streaming_response = NULL, updated_at = CURRENT_TIMESTAMP WHERE id = ?').run('stopped', ticket.id);
+                    emitTicketUpdate(ticket.id, io);
+                    transitionExecutionRun({
+                        projectId: executionContext.projectId,
+                        runId: executionContext.runId,
+                        status: 'cancelled',
+                        domainStatus: 'stopped',
+                        eventType: 'plan_cancelled',
+                    }, io);
+                    return;
                 }
-            }
-            const planningContext = createPlanningContext({
-                sourceKind: 'single',
-                initiativePrompt,
-                relatedTicketIds: [ticket.id],
-                openQuestions: planned.open_questions,
-            });
-            db.prepare('UPDATE tickets SET description = ?, agent_status = ?, streaming_response = NULL, planning_context_json = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?').run(planned.description, 'done', JSON.stringify(planningContext), ticket.id);
-            const suggestionProjectId = project?.id ?? ticket.project_id;
-            if (suggestionProjectId && Boolean(project?.memory_enabled)) {
-                persistProjectMemorySuggestions(suggestionProjectId, ticket.id, 'plan', planned.memory_suggestions);
-            }
-            upsertTicketDescriptionMessage(ticket.id, planned.description);
-            const assistantMessage = buildPlanningAssistantMessage({
-                response: planned.response,
-                openQuestions: planned.open_questions,
-            }) || (planned.transcriptRuns?.length ? planned.description : '');
-            if (assistantMessage) {
-                const messageId = createTicketMessage({
+                const branch = options.branch === undefined ? resolveTicketBranch(ticket) : options.branch;
+                const planningDescription = await resolveExternalPlanningDescription(project.id, ticket.description);
+                const initiativePrompt = ticket.planning_context?.initiative_prompt?.trim() || planningDescription;
+                const planned = await generatePlanText(ticket.title, planningDescription, {
+                    tool: resolveTicketTool(ticket, config.tool ?? 'opencode'),
+                    model: ticket.model,
+                    variant: ticket.variant,
+                    skills: options.skills ?? ticket.skills ?? [],
+                    projectId: project.id,
+                    branch,
+                    planningSessionId: ticket.planning_session_id,
                     ticketId: ticket.id,
-                    role: 'assistant',
-                    kind: 'planning_response',
-                    content: assistantMessage,
-                    responseTiming: planned.responseTiming,
-                    transcriptRuns: planned.transcriptRuns,
+                    io,
+                    executionContext,
+                    cancellationState,
+                    onProgress: progress => {
+                        updatePlanningProgress(ticket.id, progress.log, progress.response, io);
+                    },
                 });
-                if (messageId) {
-                    bindTicketThinkingMessage(ticket.id, messageId);
+                if (cancellationState.stopRequested || getTicket(ticket.id)?.agent_status === 'stopped') {
+                    persistPlanCancellationMessage(ticket.id, executionContext, planned.transcriptRuns);
+                    terminalizeAgentRunsForExecutionRun(executionContext.runId, 'stopped');
+                    db.prepare('UPDATE tickets SET agent_status = ?, streaming_response = NULL, updated_at = CURRENT_TIMESTAMP WHERE id = ?').run('stopped', ticket.id);
+                    emitTicketUpdate(ticket.id, io);
+                    transitionExecutionRun({
+                        projectId: executionContext.projectId,
+                        runId: executionContext.runId,
+                        status: 'cancelled',
+                        domainStatus: 'stopped',
+                        eventType: 'plan_cancelled',
+                    }, io);
+                    return;
                 }
+                const resolvedTool = resolveTicketTool(ticket, config.tool ?? 'opencode');
+                if (resolvedTool === 'opencode') {
+                    const freshTicket = getTicket(ticket.id);
+                    if (freshTicket?.planning_session_id) {
+                        storeTicketUsageSnapshot(freshTicket.id, freshTicket.planning_session_id);
+                    }
+                }
+                else if (resolvedTool === 'claude' && planned.usageSnapshot) {
+                    const freshTicket = getTicket(ticket.id);
+                    if (freshTicket) {
+                        storeTicketUsageSnapshotDirect(freshTicket.id, planned.usageSnapshot);
+                    }
+                }
+                const planningContext = createPlanningContext({
+                    sourceKind: 'single',
+                    initiativePrompt,
+                    relatedTicketIds: [ticket.id],
+                    openQuestions: planned.open_questions,
+                });
+                db.prepare('UPDATE tickets SET description = ?, agent_status = ?, streaming_response = NULL, planning_context_json = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?').run(planned.description, 'done', JSON.stringify(planningContext), ticket.id);
+                if (project.memory_enabled) {
+                    persistProjectMemorySuggestions(project.id, ticket.id, 'plan', planned.memory_suggestions);
+                }
+                upsertTicketDescriptionMessage(ticket.id, planned.description);
+                const assistantMessage = buildPlanningAssistantMessage({
+                    response: planned.response,
+                    openQuestions: planned.open_questions,
+                }) || (planned.transcriptRuns?.length ? planned.description : '');
+                if (assistantMessage) {
+                    const messageId = createTicketMessage({
+                        ticketId: ticket.id,
+                        role: 'assistant',
+                        kind: 'planning_response',
+                        content: assistantMessage,
+                        responseTiming: planned.responseTiming,
+                        transcriptRuns: planned.transcriptRuns,
+                    });
+                    if (messageId) {
+                        bindTicketThinkingMessage(ticket.id, messageId);
+                        appendPlanResultLink(executionContext, ticket.id, messageId);
+                    }
+                }
+                emitTicketUpdate(ticket.id, io);
+                transitionExecutionRun({
+                    projectId: executionContext.projectId,
+                    runId: executionContext.runId,
+                    status: 'completed',
+                    domainStatus: 'done',
+                    eventType: 'plan_completed',
+                }, io);
             }
-            if (planned.transcriptRuns) {
-                clearAndEmitAgentRunsForParent(io, 'ticket', ticket.id);
-            }
-            emitTicketUpdate(ticket.id, io);
-        }
-        catch (err) {
-            const transcriptRuns = getAgentErrorTranscriptRuns(err);
-            const message = err instanceof PlanningReferenceError
-                ? err.message
-                : err instanceof JiraApiError
-                    ? err.publicMessage
-                    : err instanceof GitHubApiError
+            catch (err) {
+                const transcriptRuns = getAgentErrorTranscriptRuns(err);
+                if (cancellationState.stopRequested || getTicket(ticket.id)?.agent_status === 'stopped') {
+                    try {
+                        persistPlanCancellationMessage(ticket.id, executionContext, transcriptRuns);
+                    }
+                    catch {
+                        // The ticket may have been deleted while planning was active.
+                    }
+                    terminalizeAgentRunsForExecutionRun(executionContext.runId, 'stopped');
+                    try {
+                        db.prepare('UPDATE tickets SET agent_status = ?, streaming_response = NULL, updated_at = CURRENT_TIMESTAMP WHERE id = ?').run('stopped', ticket.id);
+                        emitTicketUpdate(ticket.id, io);
+                    }
+                    catch {
+                        // Preserve cancellation history when the domain row disappeared.
+                    }
+                    transitionExecutionRun({
+                        projectId: executionContext.projectId,
+                        runId: executionContext.runId,
+                        status: 'cancelled',
+                        domainStatus: 'stopped',
+                        eventType: 'plan_cancelled',
+                    }, io);
+                    return;
+                }
+                const message = err instanceof PlanningReferenceError
+                    ? err.message
+                    : err instanceof JiraApiError
                         ? err.publicMessage
-                        : err instanceof Error
-                            ? err.message
-                            : String(err);
-            const errorContent = formatAgentErrorForTranscript(err);
-            let errorMessageId = null;
-            if (errorContent) {
-                errorMessageId = createTicketMessage({
-                    ticketId: ticket.id,
-                    role: 'assistant',
-                    kind: 'error',
-                    content: errorContent,
-                    transcriptRuns,
-                });
+                        : err instanceof GitHubApiError
+                            ? err.publicMessage
+                            : err instanceof Error
+                                ? err.message
+                                : String(err);
+                const errorContent = formatAgentErrorForTranscript(err);
+                let errorMessageId = null;
+                try {
+                    if (errorContent) {
+                        errorMessageId = createTicketMessage({
+                            ticketId: ticket.id,
+                            role: 'assistant',
+                            kind: 'error',
+                            content: errorContent,
+                            transcriptRuns,
+                        });
+                    }
+                    if (errorMessageId) {
+                        appendPlanResultLink(executionContext, ticket.id, errorMessageId);
+                    }
+                }
+                catch {
+                    // A missing ticket must not prevent the durable execution from terminalizing.
+                }
+                try {
+                    db.prepare('UPDATE tickets SET agent_status = ?, agent_log = ?, streaming_response = NULL, updated_at = CURRENT_TIMESTAMP WHERE id = ?').run('error', message, ticket.id);
+                    emitTicketUpdate(ticket.id, io);
+                }
+                catch {
+                    // Preserve execution failure history when the ticket row disappeared.
+                }
+                try {
+                    terminalizeAgentRunsForExecutionRun(executionContext.runId, 'error', message);
+                }
+                catch {
+                    // Top-level terminalization remains authoritative if detail finalization fails.
+                }
+                transitionExecutionRun({
+                    projectId: executionContext.projectId,
+                    runId: executionContext.runId,
+                    status: 'failed',
+                    domainStatus: 'error',
+                    failure: { code: callbackStarted ? 'plan_failed' : 'queue_failed', message },
+                    eventType: 'plan_failed',
+                }, io);
             }
-            if (transcriptRuns && errorMessageId) {
-                clearAndEmitAgentRunsForParent(io, 'ticket', ticket.id);
+            finally {
+                if (activityRegistered) {
+                    unregisterBundleActivity(ticket, 'plan');
+                }
+                if (activePlanProcesses.get(ticket.id) === cancellationState) {
+                    activePlanProcesses.delete(ticket.id);
+                }
             }
-            db.prepare('UPDATE tickets SET agent_status = ?, agent_log = ?, streaming_response = NULL, updated_at = CURRENT_TIMESTAMP WHERE id = ?').run('error', message, ticket.id);
-            emitTicketUpdate(ticket.id, io);
-        }
-        finally {
-            unregisterBundleActivity(ticket, 'plan');
-        }
+        });
+    }
+    catch (error) {
+        activePlanProcesses.delete(ticket.id);
+        const message = error instanceof Error ? error.message : String(error);
+        transitionExecutionRun({
+            projectId: executionContext.projectId,
+            runId: executionContext.runId,
+            status: 'failed',
+            domainStatus: ticket.agent_status ?? 'idle',
+            failure: { code: 'queue_failed', message },
+            eventType: 'plan_failed',
+        }, io);
+        return { accepted: false, reason: 'queue_failed', error: message };
+    }
+    queuedJob.catch(() => {
+        // The queued callback owns domain and execution failure finalization.
     });
+    return { accepted: true, executionContext };
+};
+export const stopPlan = async (ticketId) => {
+    const state = activePlanProcesses.get(ticketId);
+    if (!state) {
+        return false;
+    }
+    state.stopRequested = true;
+    const children = [...state.researchChildren];
+    await stopPlannerProcesses(children);
+    return true;
+};
+export const stopAllPlanAgents = async () => {
+    for (const state of activePlanProcesses.values()) {
+        state.stopRequested = true;
+    }
+    await stopPlannerProcesses([...activePlannerProcesses]);
 };
 //# sourceMappingURL=plan.js.map