@straiffi/archon 1.7.2 → 1.7.4

package/dist/server/workers/specSession.js

@@ -1,5 +1,5 @@
 import { formatAgentErrorForTranscript, getAgentErrorTranscriptRuns, registerSpecProcessPlaceholder, runSpecAgent, untrackSpecProcessById } from '../lib/agent.js';
-import { clearAndEmitAgentRunsForParent } from '../lib/agentRuns.js';
+import { createAgentRun, emitAgentRunsUpdated, finalizeAgentRun, getNextAgentRunIndex, terminalizeAgentRunsForExecutionRun } from '../lib/agentRuns.js';
 import { deleteStagedSpecAttachments, linkSpecAttachmentsToMessage, stageSpecAttachmentsForAgent } from '../lib/attachments.js';
 import { createSpecMessage } from '../lib/specMessages.js';
 import { beginSpecSessionThinkingRun, bindSpecSessionThinkingMessage } from '../lib/thinkingState.js';
@@ -12,6 +12,8 @@ import { persistSpecSessionProjectMemorySuggestions } from '../lib/projectMemory
 import { extractProjectMemorySuggestionsFromOutput, getProjectMemorySuggestionPromptRules, } from '../lib/projectMemorySuggestions.js';
 import { enqueue, isRunning } from '../lib/queue.js';
 import { getProjectById } from '../lib/projects.js';
+import { addExecutionRunLink, transitionExecutionRun } from '../lib/executionRuns.js';
+import { TurnStartError } from '../lib/turnExecutionErrors.js';
 import { buildLinkedResearchContext, prepareLinkedPlanningResearch } from './plan.js';
 import { extractGrillQuestionFromOutput, extractSpecArtifactFromOutput, resolveCarriedForwardArtifacts, resolveCarriedForwardStructuredFields, stripMermaidBlocks } from '../lib/specArtifact.js';
 import { IMPLEMENTATION_BODY_DEDUPLICATION_RULES, IMPLEMENTATION_DETAIL_RULES, IMPLEMENTATION_READY_DESCRIPTION_REQUIREMENTS, IMPLEMENTATION_READY_DESCRIPTION_SECTION_TEMPLATE, } from '../lib/ticketDescriptionContract.js';
@@ -39,7 +41,7 @@ const formatPreviousSpecStateBlock = (snapshot) => {
     if (snapshot.likely_files.length > 0) {
         lines.push('Likely files:');
         for (const file of snapshot.likely_files) {
-            lines.push(`- ${file.path} — ${file.reason}`);
+            lines.push(`- [${file.is_new ? 'new' : 'existing'}] ${file.path} — ${file.reason}`);
         }
     }
     if (snapshot.assumptions.length > 0) {
@@ -124,7 +126,7 @@ const buildStandardModeTail = ({ existingMermaid, existingMockup, existingFileRe
             '',
             '4. A machine-readable artifact block with the spec structured data, using exactly these markers:',
             '   <archon-spec-artifact>',
-            '   {"summary":"short plan summary","likely_files":[{"path":"src/foo.ts","reason":"Add bar helper"},{"path":"src/consumer.ts","reason":"Call the new bar helper"}],"tickets":[{"key":"add-foo-bar","title":"Add bar helper to foo module","description":"## Problem Statement\\nThe foo module is missing the `bar` helper, blocking downstream consumers from validating inputs consistently.\\n\\n## Acceptance Criteria\\n- [ ] A `bar(input)` function is exported from `src/foo.ts`.\\n- [ ] Invalid inputs throw a typed error with a clear message.\\n- [ ] All existing callers of foo continue to work unchanged.\\n\\n## Implementation Approach\\n1. Add `bar` to `src/foo.ts` following the existing `baz` helper signature pattern.\\n2. Reuse the project existing validation utilities instead of inlining checks.\\n3. Export `bar` from the module barrel file.\\n\\n## Edge Cases and Error Handling\\n- Empty string inputs should throw the same typed error as other invalid inputs.\\n- Preserve current behavior for `undefined`/`null` (do not coerce).\\n\\n## Constraints and Things to Avoid\\n- Do not introduce a new dependency.\\n- Do not change the public signature of existing exports."},{"key":"use-bar-in-consumer","title":"Call bar from consumer module","description":"## Problem Statement\\nThe consumer module duplicates input validation that `bar` now provides.\\n\\n## Acceptance Criteria\\n- [ ] Consumer calls `bar` instead of its own inline validation.\\n- [ ] Existing consumer tests still pass.\\n\\n## Implementation Approach\\n1. Replace the inline check in consumer with a call to `bar`.\\n2. Remove the now-unused validation helper from consumer.\\n\\n## Edge Cases and Error Handling\\n- Consumer must handle the typed errors thrown by `bar`.\\n\\n## Constraints and Things to Avoid\\n- Do not change the consumer public API."}],"dependencies":[{"blocker_key":"add-foo-bar","dependent_key":"use-bar-in-consumer"}]}',
+            '   {"summary":"short plan summary","likely_files":[{"path":"src/foo.ts","reason":"Add bar helper","is_new":false},{"path":"src/newHelper.ts","reason":"Provide the new shared helper","is_new":true}],"tickets":[{"key":"add-foo-bar","title":"Add bar helper to foo module","description":"## Problem Statement\\nThe foo module is missing the `bar` helper, blocking downstream consumers from validating inputs consistently.\\n\\n## Acceptance Criteria\\n- [ ] A `bar(input)` function is exported from `src/foo.ts`.\\n- [ ] Invalid inputs throw a typed error with a clear message.\\n- [ ] All existing callers of foo continue to work unchanged.\\n\\n## Implementation Approach\\n1. Add `bar` to `src/foo.ts` following the existing `baz` helper signature pattern.\\n2. Reuse the project existing validation utilities instead of inlining checks.\\n3. Export `bar` from the module barrel file.\\n\\n## Edge Cases and Error Handling\\n- Empty string inputs should throw the same typed error as other invalid inputs.\\n- Preserve current behavior for `undefined`/`null` (do not coerce).\\n\\n## Constraints and Things to Avoid\\n- Do not introduce a new dependency.\\n- Do not change the public signature of existing exports."},{"key":"use-bar-in-consumer","title":"Call bar from consumer module","description":"## Problem Statement\\nThe consumer module duplicates input validation that `bar` now provides.\\n\\n## Acceptance Criteria\\n- [ ] Consumer calls `bar` instead of its own inline validation.\\n- [ ] Existing consumer tests still pass.\\n\\n## Implementation Approach\\n1. Replace the inline check in consumer with a call to `bar`.\\n2. Remove the now-unused validation helper from consumer.\\n\\n## Edge Cases and Error Handling\\n- Consumer must handle the typed errors thrown by `bar`.\\n\\n## Constraints and Things to Avoid\\n- Do not change the consumer public API."}],"dependencies":[{"blocker_key":"add-foo-bar","dependent_key":"use-bar-in-consumer"}]}',
             '   </archon-spec-artifact>',
             '',
             'The artifact represents the complete current state of the spec. On follow-up turns, re-emit every field',
@@ -135,9 +137,11 @@ const buildStandardModeTail = ({ existingMermaid, existingMockup, existingFileRe
             '  what this turn did, what was emitted, or what changed; the summary describes the plan itself.',
             '- `assumptions` — array of assumptions that affect the plan.',
             '- `open_questions` — array of unresolved questions needing clarification.',
-            '- `likely_files` — array of {"path": "...", "reason": "..."} objects for files you expect to create or',
-            '  modify. If your human-readable text includes a table of files to change, include the same files here.',
-            '  The `reason` should describe what change is needed, not just repeat the path.',
+            '- `likely_files` — array of {"path": "...", "reason": "...", "is_new": boolean} objects for files you',
+            '  expect to create or modify. Inspect the repository before classifying each path: set `is_new` to true',
+            '  only when the path does not exist and the implementation will create it; use false for an existing file',
+            '  that will be modified. If your human-readable text includes a table of files to change, include the same',
+            '  files here. The `reason` should describe what change is needed, not just repeat the path.',
             '- `tickets` (required) — proposed board tickets with stable kebab-case keys (always at least one).',
             '  Each ticket will later be implemented by a separate build agent that has no access to this planning',
             '  conversation, so every ticket `description` must be self-contained and implementation-ready.',
@@ -312,7 +316,62 @@ const emitUpdatedSpecSession = (specSessionId, io) => {
         io.emit('spec-session:updated', specSession);
     }
 };
-export const startSpecSessionTurn = ({ specSessionId, instruction, attachments = [], tool, model, variant, skills = [], io, }) => {
+const failSpecTurn = ({ specSessionId, executionContext, existingTriggerMessageId, providerContinuation, conversationContext, priorSnapshotId, turnMode, mainRunId, error, io, }) => {
+    const failureMessage = getErrorMessage(error);
+    untrackSpecProcessById(specSessionId);
+    try {
+        if (mainRunId) {
+            finalizeAgentRun(mainRunId, 'error', null, failureMessage);
+        }
+        terminalizeAgentRunsForExecutionRun(executionContext.runId, 'error', failureMessage);
+    }
+    catch {
+        // Preserve the top-level execution even if detail finalization fails.
+    }
+    try {
+        const errorContent = formatAgentErrorForTranscript(error);
+        if (errorContent) {
+            const errorMessageId = createSpecMessage({
+                specSessionId,
+                role: 'assistant',
+                kind: 'error',
+                content: errorContent,
+                transcriptRuns: getAgentErrorTranscriptRuns(error),
+            });
+            bindSpecSessionThinkingMessage(specSessionId, errorMessageId);
+            addExecutionRunLink({
+                projectId: executionContext.projectId,
+                runId: executionContext.runId,
+                link: {
+                    entityType: 'spec_message',
+                    entityId: errorMessageId,
+                    relationship: 'result',
+                    expectedParent: { entityType: 'spec_session', entityId: specSessionId },
+                },
+            });
+        }
+    }
+    catch {
+        // Terminal state must not depend on secondary error-message persistence.
+    }
+    try {
+        updateSpecSessionStatus(specSessionId, 'error', failureMessage, null);
+        emitUpdatedSpecSession(specSessionId, io);
+    }
+    catch {
+        // Preserve the top-level execution even if domain projection fails.
+    }
+    transitionExecutionRun({
+        projectId: executionContext.projectId,
+        runId: executionContext.runId,
+        status: 'failed',
+        domainStatus: 'error',
+        failure: { code: 'spec_turn_failed', message: failureMessage },
+        eventType: 'spec_turn_failed',
+    }, io);
+    emitAgentRunsUpdated(io, 'spec', specSessionId);
+};
+export const startSpecSessionTurn = ({ specSessionId, instruction, attachments = [], tool, model, variant, skills = [], io, executionContext, existingTriggerMessageId, providerContinuation, conversationContext, priorSnapshotId, turnMode, }) => {
     const specSession = getSpecSession(specSessionId, { includeMessages: true });
     if (!specSession) {
         return false;
@@ -331,13 +390,25 @@ export const startSpecSessionTurn = ({ specSessionId, instruction, attachments =
     if (specSession.agent_status === 'running' || isRunning(jobKey)) {
         return false;
     }
-    const userMessageId = createSpecMessage({
+    const userMessageId = existingTriggerMessageId ?? createSpecMessage({
         specSessionId,
         role: 'user',
         kind: 'prompt',
         content: trimmedInstruction,
     });
-    if (attachments.length > 0) {
+    if (!existingTriggerMessageId) {
+        addExecutionRunLink({
+            projectId: executionContext.projectId,
+            runId: executionContext.runId,
+            link: {
+                entityType: 'spec_message',
+                entityId: userMessageId,
+                relationship: 'trigger',
+                expectedParent: { entityType: 'spec_session', entityId: specSessionId },
+            },
+        });
+    }
+    if (!existingTriggerMessageId && attachments.length > 0) {
         linkSpecAttachmentsToMessage({
             specMessageId: userMessageId,
             attachments,
@@ -363,7 +434,6 @@ export const startSpecSessionTurn = ({ specSessionId, instruction, attachments =
     }
     beginSpecSessionThinkingRun(specSessionId);
     updateSpecSessionStatus(specSessionId, 'running', null, null);
-    clearAndEmitAgentRunsForParent(io, 'spec', specSessionId);
     // Register a cancellation token before any async work so an interrupt during
     // the pre-response window (prepareLinkedPlanningResearch) is accepted rather
     // than returning a 409. runSpecAgent will overwrite this entry with the real
@@ -371,279 +441,389 @@ export const startSpecSessionTurn = ({ specSessionId, instruction, attachments =
     // stopRequested below and finalizes to 'stopped' without starting the agent.
     const specCancellation = registerSpecProcessPlaceholder(specSessionId);
     emitUpdatedSpecSession(specSessionId, io);
-    enqueue(jobKey, async () => {
-        let stagedAgentAttachmentsDirectoryPath = null;
-        try {
-            const latestSession = getSpecSession(specSessionId);
-            if (!latestSession) {
-                return;
-            }
-            // The prior snapshot (if any) is read once and reused both to guide the
-            // prompt (don't redraw established artifacts) and to carry its mermaid/
-            // mockup forward when the current turn omits them. No new snapshot is
-            // created mid-run, so this reference stays valid through the done path.
-            const previousSnapshot = latestSession.latest_snapshot_id
-                ? getSpecSnapshot(latestSession.latest_snapshot_id)
-                : null;
-            const promptContext = latestSession.title === getDefaultSpecSessionTitle()
-                ? null
-                : latestSession.title;
-            const projectMemory = getProjectMemoryPromptBlock(project.id, {
-                flow: 'spec',
-                stage: 'plan',
-                title: trimmedInstruction || 'Attached images only',
-                description: promptContext,
-                currentInstruction: trimmedInstruction,
-                invocation: { parentType: 'spec', parentId: specSessionId },
-            });
-            const cwd = project.repo_path;
-            const linkedResearch = trimmedInstruction
-                ? await prepareLinkedPlanningResearch(trimmedInstruction, {
-                    projectId: project.id,
+    let queuedJob;
+    try {
+        queuedJob = enqueue(jobKey, async () => {
+            let stagedAgentAttachmentsDirectoryPath = null;
+            let mainRunId = null;
+            try {
+                transitionExecutionRun({
+                    projectId: executionContext.projectId,
+                    runId: executionContext.runId,
+                    status: 'running',
+                    domainStatus: 'running',
+                    eventType: 'spec_turn_started',
+                }, io);
+                const mainRunIndex = getNextAgentRunIndex(executionContext.runId);
+                mainRunId = createAgentRun({
+                    executionRunId: executionContext.runId,
+                    parentType: 'spec',
+                    parentId: specSessionId,
+                    label: 'Main agent',
+                    role: 'main',
+                });
+                const latestSession = getSpecSession(specSessionId);
+                if (!latestSession) {
+                    throw new Error('Spec session no longer exists');
+                }
+                // The prior snapshot (if any) is read once and reused both to guide the
+                // prompt (don't redraw established artifacts) and to carry its mermaid/
+                // mockup forward when the current turn omits them. No new snapshot is
+                // created mid-run, so this reference stays valid through the done path.
+                const resolvedPriorSnapshotId = priorSnapshotId === undefined ? latestSession.latest_snapshot_id : priorSnapshotId;
+                const previousSnapshot = resolvedPriorSnapshotId
+                    ? getSpecSnapshot(resolvedPriorSnapshotId)
+                    : null;
+                const promptContext = latestSession.title === getDefaultSpecSessionTitle()
+                    ? null
+                    : latestSession.title;
+                const projectMemory = getProjectMemoryPromptBlock(project.id, {
+                    flow: 'spec',
+                    stage: 'plan',
+                    title: trimmedInstruction || 'Attached images only',
+                    description: promptContext,
+                    currentInstruction: trimmedInstruction,
+                    invocation: { parentType: 'spec', parentId: specSessionId, agentRunId: mainRunId },
+                });
+                const cwd = project.repo_path;
+                const linkedResearch = trimmedInstruction
+                    ? await prepareLinkedPlanningResearch(trimmedInstruction, {
+                        projectId: project.id,
+                        tool: resolvedTool,
+                        model: resolvedModel,
+                        variant: resolvedVariant,
+                        skills: resolvedSkills,
+                        executionContext,
+                        cancellationState: specCancellation,
+                        agentRunParent: { parentType: 'spec', parentId: specSessionId, io },
+                    })
+                    : [];
+                // Honor an interrupt that arrived during the pre-response window. There
+                // is no child to kill and no partial response to save; transition straight
+                // to 'stopped' (worker-owned, mirroring how Chat finalizes after a stop).
+                if (specCancellation.stopRequested) {
+                    untrackSpecProcessById(specSessionId);
+                    finalizeAgentRun(mainRunId, 'stopped', null);
+                    updateSpecSessionStatus(specSessionId, 'stopped', null, null);
+                    emitUpdatedSpecSession(specSessionId, io);
+                    transitionExecutionRun({
+                        projectId: executionContext.projectId,
+                        runId: executionContext.runId,
+                        status: 'cancelled',
+                        domainStatus: 'stopped',
+                        eventType: 'spec_turn_cancelled',
+                    }, io);
+                    emitAgentRunsUpdated(io, 'spec', specSessionId);
+                    return;
+                }
+                const linkedResearchContext = buildLinkedResearchContext(project, linkedResearch);
+                const stagedAgentAttachments = resolvedTool === 'opencode'
+                    ? stageSpecAttachmentsForAgent({
+                        specSessionId,
+                        cwd,
+                        attachments,
+                    })
+                    : { directoryPath: null, files: [] };
+                stagedAgentAttachmentsDirectoryPath = stagedAgentAttachments.directoryPath;
+                const specPrompt = buildSpecPrompt({
+                    projectName: project.name,
+                    projectPath: cwd,
+                    instruction: conversationContext
+                        ? `<conversation_before_retry>\n${conversationContext}\n</conversation_before_retry>\n\n${trimmedInstruction}`
+                        : trimmedInstruction,
+                    hasAttachments: attachments.length > 0,
+                    projectMemory,
+                    memoryEnabled: Boolean(project.memory_enabled),
+                    previousSnapshot,
+                    linkedResearchContext,
+                    mode: turnMode ?? resolveSpecModeValue(latestSession.mode),
+                });
+                const specRunResult = await runSpecAgent({
+                    specSessionId,
                     tool: resolvedTool,
+                    prompt: specPrompt,
+                    cwd,
+                    files: stagedAgentAttachments.files,
+                    io,
                     model: resolvedModel,
                     variant: resolvedVariant,
-                    skills: resolvedSkills,
-                })
-                : [];
-            // Honor an interrupt that arrived during the pre-response window. There
-            // is no child to kill and no partial response to save; transition straight
-            // to 'stopped' (worker-owned, mirroring how Chat finalizes after a stop).
-            if (specCancellation.stopRequested) {
-                untrackSpecProcessById(specSessionId);
-                updateSpecSessionStatus(specSessionId, 'stopped', null, null);
-                emitUpdatedSpecSession(specSessionId, io);
-                return;
-            }
-            const linkedResearchContext = buildLinkedResearchContext(project, linkedResearch);
-            const stagedAgentAttachments = resolvedTool === 'opencode'
-                ? stageSpecAttachmentsForAgent({
-                    specSessionId,
-                    cwd,
-                    attachments,
-                })
-                : { directoryPath: null, files: [] };
-            stagedAgentAttachmentsDirectoryPath = stagedAgentAttachments.directoryPath;
-            const specPrompt = buildSpecPrompt({
-                projectName: project.name,
-                projectPath: cwd,
-                instruction: trimmedInstruction,
-                hasAttachments: attachments.length > 0,
-                projectMemory,
-                memoryEnabled: Boolean(project.memory_enabled),
-                previousSnapshot,
-                linkedResearchContext,
-                mode: resolveSpecModeValue(latestSession.mode),
-            });
-            const specRunResult = await runSpecAgent({
-                specSessionId,
-                tool: resolvedTool,
-                prompt: specPrompt,
-                cwd,
-                files: stagedAgentAttachments.files,
-                io,
-                model: resolvedModel,
-                variant: resolvedVariant,
-                resumeSessionId: resolvedTool === 'claude'
-                    ? latestSession.claude_session_id
-                    : latestSession.opencode_session_id,
-            });
-            if (specRunResult.completionStatus === 'stopped') {
-                const interruptedSession = getSpecSession(specSessionId);
-                const interruptedResponse = interruptedSession?.streaming_response?.trim()
-                    || specRunResult.finalResponse?.trim()
+                    resumeSessionId: providerContinuation === 'fresh'
+                        ? null
+                        : resolvedTool === 'claude'
+                            ? latestSession.claude_session_id
+                            : latestSession.opencode_session_id,
+                    executionContext,
+                    mainRun: { id: mainRunId, label: 'Main agent', role: 'main', runIndex: mainRunIndex },
+                });
+                if (specRunResult.completionStatus === 'stopped') {
+                    const interruptedSession = getSpecSession(specSessionId);
+                    const interruptedResponse = interruptedSession?.streaming_response?.trim()
+                        || specRunResult.finalResponse?.trim()
+                        || getTranscriptContentFallback(specRunResult.transcriptRuns)
+                        || '';
+                    if (resolvedTool === 'opencode' && interruptedSession?.title === getDefaultSpecSessionTitle()) {
+                        updateSpecSessionTitle(specSessionId, deriveSpecSessionTitle(trimmedInstruction));
+                    }
+                    if (interruptedResponse) {
+                        const messageId = createSpecMessage({
+                            specSessionId,
+                            role: 'assistant',
+                            kind: 'final_response',
+                            content: interruptedResponse,
+                            responseTiming: specRunResult.responseTiming,
+                            transcriptRuns: specRunResult.transcriptRuns,
+                        });
+                        if (messageId) {
+                            bindSpecSessionThinkingMessage(specSessionId, messageId);
+                            addExecutionRunLink({
+                                projectId: executionContext.projectId,
+                                runId: executionContext.runId,
+                                link: {
+                                    entityType: 'spec_message',
+                                    entityId: messageId,
+                                    relationship: 'result',
+                                    expectedParent: { entityType: 'spec_session', entityId: specSessionId },
+                                },
+                            });
+                        }
+                    }
+                    updateSpecSessionUsageSnapshot(specSessionId, specRunResult.usageSnapshot);
+                    updateSpecSessionStatus(specSessionId, 'stopped', interruptedSession?.agent_log ?? null, null);
+                    emitUpdatedSpecSession(specSessionId, io);
+                    finalizeAgentRun(mainRunId, 'stopped', interruptedResponse || null);
+                    transitionExecutionRun({
+                        projectId: executionContext.projectId,
+                        runId: executionContext.runId,
+                        status: 'cancelled',
+                        domainStatus: 'stopped',
+                        eventType: 'spec_turn_cancelled',
+                    }, io);
+                    emitAgentRunsUpdated(io, 'spec', specSessionId);
+                    return;
+                }
+                // Done path: process the completed response.
+                const latestCompletedSession = getSpecSession(specSessionId);
+                const streamedAssistantMessage = latestCompletedSession?.streaming_response?.trim() ?? '';
+                const rawResponse = typeof specRunResult.finalResponse === 'string'
+                    ? specRunResult.finalResponse
+                    : '';
+                // Resolve the session mode at the moment the turn completed. NULL/legacy
+                // values normalize to 'standard'. The worker's per-mode output branch is
+                // decided here, not from a re-read after the artifact path, so an
+                // auto-finalize mode flip does not change how THIS turn's output parses.
+                const sessionMode = turnMode ?? resolveSpecModeValue(latestCompletedSession?.mode);
+                // Grill mode: try the grill-question extractor first. If a payload is
+                // returned, store it as a 'grill-question' assistant message and skip the
+                // snapshot. If no payload is returned, fall through to the standard
+                // artifact path (the agent signaled it has no more questions and is
+                // emitting the full plan — this is the auto-finalize path).
+                if (sessionMode === 'grill' && rawResponse) {
+                    const grillResult = extractGrillQuestionFromOutput(rawResponse);
+                    if (grillResult.grillQuestion) {
+                        const cleanedGrillText = grillResult.cleanedOutput.trim()
+                            || grillResult.grillQuestion.question
+                            || streamedAssistantMessage.trim();
+                        const grillMessageId = createSpecMessage({
+                            specSessionId,
+                            role: 'assistant',
+                            kind: 'grill-question',
+                            content: cleanedGrillText,
+                            metadata: { grill_question: grillResult.grillQuestion },
+                            responseTiming: specRunResult.responseTiming,
+                            transcriptRuns: specRunResult.transcriptRuns,
+                        });
+                        if (grillMessageId) {
+                            bindSpecSessionThinkingMessage(specSessionId, grillMessageId);
+                            addExecutionRunLink({
+                                projectId: executionContext.projectId,
+                                runId: executionContext.runId,
+                                link: {
+                                    entityType: 'spec_message',
+                                    entityId: grillMessageId,
+                                    relationship: 'result',
+                                    expectedParent: { entityType: 'spec_session', entityId: specSessionId },
+                                },
+                            });
+                        }
+                        if (resolvedTool === 'opencode' && latestCompletedSession?.title === getDefaultSpecSessionTitle()) {
+                            updateSpecSessionTitle(specSessionId, deriveSpecSessionTitle(trimmedInstruction));
+                        }
+                        updateSpecSessionUsageSnapshot(specSessionId, specRunResult.usageSnapshot);
+                        updateSpecSessionStatus(specSessionId, 'done', getSpecSession(specSessionId)?.agent_log ?? null, null);
+                        emitUpdatedSpecSession(specSessionId, io);
+                        finalizeAgentRun(mainRunId, 'done', cleanedGrillText);
+                        transitionExecutionRun({
+                            projectId: executionContext.projectId,
+                            runId: executionContext.runId,
+                            status: 'completed',
+                            domainStatus: 'done',
+                            eventType: 'spec_turn_completed',
+                        }, io);
+                        emitAgentRunsUpdated(io, 'spec', specSessionId);
+                        return;
+                    }
+                }
+                const artifactResult = rawResponse
+                    ? extractSpecArtifactFromOutput(rawResponse)
+                    : { cleanedOutput: '', artifact: null, error: null };
+                const parsedResponse = extractProjectMemorySuggestionsFromOutput(artifactResult.cleanedOutput);
+                if (project.memory_enabled && parsedResponse.suggestions && parsedResponse.suggestions.length > 0) {
+                    persistSpecSessionProjectMemorySuggestions(project.id, specSessionId, parsedResponse.suggestions);
+                }
+                const cleanedPlanText = stripMermaidBlocks(parsedResponse.cleanedOutput).trim()
+                    || stripMermaidBlocks(streamedAssistantMessage).trim();
+                let assistantMessage = cleanedPlanText
                     || getTranscriptContentFallback(specRunResult.transcriptRuns)
-                    || '';
-                if (resolvedTool === 'opencode' && interruptedSession?.title === getDefaultSpecSessionTitle()) {
-                    updateSpecSessionTitle(specSessionId, deriveSpecSessionTitle(trimmedInstruction));
+                    || (attachments.length > 0 ? ATTACHMENT_ONLY_EMPTY_RESPONSE_FALLBACK : '');
+                // Create snapshot from artifact if present. Presence is populated
+                // alongside artifact by the extractor, so the two are non-null together.
+                if (artifactResult.artifact && artifactResult.presence) {
+                    // A block re-emitted this turn overrides the previous snapshot's value;
+                    // an omitted block is carried forward so established artifacts don't
+                    // disappear when a follow-up turn omits the diagram/mockup.
+                    const { mermaid: mermaidBlock, mockup: mockupBlock, fileRelationGraph: fileRelationGraphBlock } = resolveCarriedForwardArtifacts({
+                        rawResponse,
+                        previousMermaid: previousSnapshot?.mermaid ?? null,
+                        previousMockup: previousSnapshot?.mockup ?? null,
+                        previousFileRelationGraph: previousSnapshot?.file_relation_graph ?? null,
+                    });
+                    // Optional structured array fields use the same carry-forward contract:
+                    // a field the LLM emitted this turn (including an explicit empty array)
+                    // overrides the prior snapshot; a field the LLM omitted is carried
+                    // forward unchanged so follow-up turns never silently drop information.
+                    const carriedFields = resolveCarriedForwardStructuredFields({
+                        artifact: artifactResult.artifact,
+                        presence: artifactResult.presence,
+                        previous: previousSnapshot
+                            ? {
+                                assumptions: previousSnapshot.assumptions,
+                                openQuestions: previousSnapshot.open_questions,
+                                likelyFiles: previousSnapshot.likely_files,
+                                dependencies: previousSnapshot.dependencies,
+                            }
+                            : null,
+                    });
+                    const snapshotId = createSpecSnapshot({
+                        specSessionId,
+                        summary: artifactResult.artifact.summary,
+                        assumptions: carriedFields.assumptions,
+                        openQuestions: carriedFields.openQuestions,
+                        likelyFiles: carriedFields.likelyFiles,
+                        tickets: artifactResult.artifact.tickets,
+                        dependencies: carriedFields.dependencies,
+                        mermaid: mermaidBlock,
+                        mockup: mockupBlock,
+                        fileRelationGraph: fileRelationGraphBlock,
+                        planText: cleanedPlanText,
+                    });
+                    updateSpecSessionLatestSnapshot(specSessionId, snapshotId);
+                    addExecutionRunLink({
+                        projectId: executionContext.projectId,
+                        runId: executionContext.runId,
+                        link: {
+                            entityType: 'spec_snapshot',
+                            entityId: snapshotId,
+                            relationship: 'result',
+                            expectedParent: { entityType: 'spec_session', entityId: specSessionId },
+                        },
+                    });
+                    // Auto-finalize: when an artifact is emitted during grill mode, the
+                    // agent has signaled that it has no remaining questions. Flip the
+                    // session mode back to 'standard' so subsequent turns run the standard
+                    // prompt. This runs inside the same queued job that wrote the snapshot,
+                    // so it cannot race with a concurrent user-initiated mode change.
+                    if (sessionMode === 'grill') {
+                        updateSpecSessionMode(specSessionId, 'standard');
+                    }
                 }
-                if (interruptedResponse) {
+                // Append artifact error note to the visible message if extraction failed.
+                // Suppress the "no block found" note — it is normal for Q&A turns where the
+                // agent intentionally omitted the artifact because the specification did not change.
+                if (artifactResult.error && assistantMessage && artifactResult.error !== 'No spec artifact block found in planner response') {
+                    assistantMessage += `\n\n[Note: ${artifactResult.error}. No specification snapshot was saved. You can try refining the spec or asking the planner to regenerate the artifact.]`;
+                }
+                if (assistantMessage) {
                     const messageId = createSpecMessage({
                         specSessionId,
                         role: 'assistant',
                         kind: 'final_response',
-                        content: interruptedResponse,
+                        content: assistantMessage,
                         responseTiming: specRunResult.responseTiming,
                         transcriptRuns: specRunResult.transcriptRuns,
                     });
                     if (messageId) {
                         bindSpecSessionThinkingMessage(specSessionId, messageId);
+                        addExecutionRunLink({
+                            projectId: executionContext.projectId,
+                            runId: executionContext.runId,
+                            link: {
+                                entityType: 'spec_message',
+                                entityId: messageId,
+                                relationship: 'result',
+                                expectedParent: { entityType: 'spec_session', entityId: specSessionId },
+                            },
+                        });
                     }
                 }
-                if (specRunResult.transcriptRuns) {
-                    clearAndEmitAgentRunsForParent(io, 'spec', specSessionId);
+                if (resolvedTool === 'opencode' && latestCompletedSession?.title === getDefaultSpecSessionTitle()) {
+                    updateSpecSessionTitle(specSessionId, deriveSpecSessionTitle(trimmedInstruction));
                 }
                 updateSpecSessionUsageSnapshot(specSessionId, specRunResult.usageSnapshot);
-                updateSpecSessionStatus(specSessionId, 'stopped', interruptedSession?.agent_log ?? null, null);
+                updateSpecSessionStatus(specSessionId, 'done', getSpecSession(specSessionId)?.agent_log ?? null, null);
                 emitUpdatedSpecSession(specSessionId, io);
-                return;
+                finalizeAgentRun(mainRunId, 'done', assistantMessage || rawResponse || null);
+                transitionExecutionRun({
+                    projectId: executionContext.projectId,
+                    runId: executionContext.runId,
+                    status: 'completed',
+                    domainStatus: 'done',
+                    eventType: 'spec_turn_completed',
+                }, io);
+                emitAgentRunsUpdated(io, 'spec', specSessionId);
             }
-            // Done path: process the completed response.
-            const latestCompletedSession = getSpecSession(specSessionId);
-            const streamedAssistantMessage = latestCompletedSession?.streaming_response?.trim() ?? '';
-            const rawResponse = typeof specRunResult.finalResponse === 'string'
-                ? specRunResult.finalResponse
-                : '';
-            // Resolve the session mode at the moment the turn completed. NULL/legacy
-            // values normalize to 'standard'. The worker's per-mode output branch is
-            // decided here, not from a re-read after the artifact path, so an
-            // auto-finalize mode flip does not change how THIS turn's output parses.
-            const sessionMode = resolveSpecModeValue(latestCompletedSession?.mode);
-            // Grill mode: try the grill-question extractor first. If a payload is
-            // returned, store it as a 'grill-question' assistant message and skip the
-            // snapshot. If no payload is returned, fall through to the standard
-            // artifact path (the agent signaled it has no more questions and is
-            // emitting the full plan — this is the auto-finalize path).
-            if (sessionMode === 'grill' && rawResponse) {
-                const grillResult = extractGrillQuestionFromOutput(rawResponse);
-                if (grillResult.grillQuestion) {
-                    const cleanedGrillText = grillResult.cleanedOutput.trim()
-                        || grillResult.grillQuestion.question
-                        || streamedAssistantMessage.trim();
-                    const grillMessageId = createSpecMessage({
-                        specSessionId,
-                        role: 'assistant',
-                        kind: 'grill-question',
-                        content: cleanedGrillText,
-                        metadata: { grill_question: grillResult.grillQuestion },
-                        responseTiming: specRunResult.responseTiming,
-                        transcriptRuns: specRunResult.transcriptRuns,
-                    });
-                    if (grillMessageId) {
-                        bindSpecSessionThinkingMessage(specSessionId, grillMessageId);
-                    }
-                    if (specRunResult.transcriptRuns) {
-                        clearAndEmitAgentRunsForParent(io, 'spec', specSessionId);
+            catch (error) {
+                if (specCancellation.stopRequested) {
+                    untrackSpecProcessById(specSessionId);
+                    if (mainRunId) {
+                        finalizeAgentRun(mainRunId, 'stopped', null);
                     }
-                    if (resolvedTool === 'opencode' && latestCompletedSession?.title === getDefaultSpecSessionTitle()) {
-                        updateSpecSessionTitle(specSessionId, deriveSpecSessionTitle(trimmedInstruction));
-                    }
-                    updateSpecSessionUsageSnapshot(specSessionId, specRunResult.usageSnapshot);
-                    updateSpecSessionStatus(specSessionId, 'done', getSpecSession(specSessionId)?.agent_log ?? null, null);
+                    updateSpecSessionStatus(specSessionId, 'stopped', null, null);
                     emitUpdatedSpecSession(specSessionId, io);
+                    transitionExecutionRun({
+                        projectId: executionContext.projectId,
+                        runId: executionContext.runId,
+                        status: 'cancelled',
+                        domainStatus: 'stopped',
+                        eventType: 'spec_turn_cancelled',
+                    }, io);
+                    emitAgentRunsUpdated(io, 'spec', specSessionId);
                     return;
                 }
-            }
-            const artifactResult = rawResponse
-                ? extractSpecArtifactFromOutput(rawResponse)
-                : { cleanedOutput: '', artifact: null, error: null };
-            const parsedResponse = extractProjectMemorySuggestionsFromOutput(artifactResult.cleanedOutput);
-            if (project.memory_enabled && parsedResponse.suggestions && parsedResponse.suggestions.length > 0) {
-                persistSpecSessionProjectMemorySuggestions(project.id, specSessionId, parsedResponse.suggestions);
-            }
-            const cleanedPlanText = stripMermaidBlocks(parsedResponse.cleanedOutput).trim()
-                || stripMermaidBlocks(streamedAssistantMessage).trim();
-            let assistantMessage = cleanedPlanText
-                || getTranscriptContentFallback(specRunResult.transcriptRuns)
-                || (attachments.length > 0 ? ATTACHMENT_ONLY_EMPTY_RESPONSE_FALLBACK : '');
-            // Create snapshot from artifact if present. Presence is populated
-            // alongside artifact by the extractor, so the two are non-null together.
-            if (artifactResult.artifact && artifactResult.presence) {
-                // A block re-emitted this turn overrides the previous snapshot's value;
-                // an omitted block is carried forward so established artifacts don't
-                // disappear when a follow-up turn omits the diagram/mockup.
-                const { mermaid: mermaidBlock, mockup: mockupBlock, fileRelationGraph: fileRelationGraphBlock } = resolveCarriedForwardArtifacts({
-                    rawResponse,
-                    previousMermaid: previousSnapshot?.mermaid ?? null,
-                    previousMockup: previousSnapshot?.mockup ?? null,
-                    previousFileRelationGraph: previousSnapshot?.file_relation_graph ?? null,
-                });
-                // Optional structured array fields use the same carry-forward contract:
-                // a field the LLM emitted this turn (including an explicit empty array)
-                // overrides the prior snapshot; a field the LLM omitted is carried
-                // forward unchanged so follow-up turns never silently drop information.
-                const carriedFields = resolveCarriedForwardStructuredFields({
-                    artifact: artifactResult.artifact,
-                    presence: artifactResult.presence,
-                    previous: previousSnapshot
-                        ? {
-                            assumptions: previousSnapshot.assumptions,
-                            openQuestions: previousSnapshot.open_questions,
-                            likelyFiles: previousSnapshot.likely_files,
-                            dependencies: previousSnapshot.dependencies,
-                        }
-                        : null,
-                });
-                const snapshotId = createSpecSnapshot({
-                    specSessionId,
-                    summary: artifactResult.artifact.summary,
-                    assumptions: carriedFields.assumptions,
-                    openQuestions: carriedFields.openQuestions,
-                    likelyFiles: carriedFields.likelyFiles,
-                    tickets: artifactResult.artifact.tickets,
-                    dependencies: carriedFields.dependencies,
-                    mermaid: mermaidBlock,
-                    mockup: mockupBlock,
-                    fileRelationGraph: fileRelationGraphBlock,
-                    planText: cleanedPlanText,
-                });
-                updateSpecSessionLatestSnapshot(specSessionId, snapshotId);
-                // Auto-finalize: when an artifact is emitted during grill mode, the
-                // agent has signaled that it has no remaining questions. Flip the
-                // session mode back to 'standard' so subsequent turns run the standard
-                // prompt. This runs inside the same queued job that wrote the snapshot,
-                // so it cannot race with a concurrent user-initiated mode change.
-                if (sessionMode === 'grill') {
-                    updateSpecSessionMode(specSessionId, 'standard');
-                }
-            }
-            // Append artifact error note to the visible message if extraction failed.
-            // Suppress the "no block found" note — it is normal for Q&A turns where the
-            // agent intentionally omitted the artifact because the specification did not change.
-            if (artifactResult.error && assistantMessage && artifactResult.error !== 'No spec artifact block found in planner response') {
-                assistantMessage += `\n\n[Note: ${artifactResult.error}. No specification snapshot was saved. You can try refining the spec or asking the planner to regenerate the artifact.]`;
-            }
-            if (assistantMessage) {
-                const messageId = createSpecMessage({
-                    specSessionId,
-                    role: 'assistant',
-                    kind: 'final_response',
-                    content: assistantMessage,
-                    responseTiming: specRunResult.responseTiming,
-                    transcriptRuns: specRunResult.transcriptRuns,
-                });
-                if (messageId) {
-                    bindSpecSessionThinkingMessage(specSessionId, messageId);
+                const latestSession = getSpecSession(specSessionId);
+                if (resolvedTool === 'opencode' && latestSession?.title === getDefaultSpecSessionTitle()) {
+                    updateSpecSessionTitle(specSessionId, deriveSpecSessionTitle(trimmedInstruction));
                 }
+                failSpecTurn({ specSessionId, executionContext, mainRunId, error, io });
             }
-            if (specRunResult.transcriptRuns) {
-                clearAndEmitAgentRunsForParent(io, 'spec', specSessionId);
-            }
-            if (resolvedTool === 'opencode' && latestCompletedSession?.title === getDefaultSpecSessionTitle()) {
-                updateSpecSessionTitle(specSessionId, deriveSpecSessionTitle(trimmedInstruction));
+            finally {
+                deleteStagedSpecAttachments(stagedAgentAttachmentsDirectoryPath);
             }
-            updateSpecSessionUsageSnapshot(specSessionId, specRunResult.usageSnapshot);
-            updateSpecSessionStatus(specSessionId, 'done', getSpecSession(specSessionId)?.agent_log ?? null, null);
-            emitUpdatedSpecSession(specSessionId, io);
-        }
-        catch (error) {
-            const transcriptRuns = getAgentErrorTranscriptRuns(error);
-            const latestSession = getSpecSession(specSessionId);
-            if (resolvedTool === 'opencode' && latestSession?.title === getDefaultSpecSessionTitle()) {
-                updateSpecSessionTitle(specSessionId, deriveSpecSessionTitle(trimmedInstruction));
-            }
-            const errorContent = formatAgentErrorForTranscript(error);
-            if (errorContent) {
-                createSpecMessage({
-                    specSessionId,
-                    role: 'assistant',
-                    kind: 'error',
-                    content: errorContent,
-                    transcriptRuns,
-                });
-            }
-            if (transcriptRuns) {
-                clearAndEmitAgentRunsForParent(io, 'spec', specSessionId);
-            }
-            updateSpecSessionStatus(specSessionId, 'error', getErrorMessage(error), null);
-            emitUpdatedSpecSession(specSessionId, io);
+        });
+    }
+    catch (error) {
+        untrackSpecProcessById(specSessionId);
+        const failureMessage = getErrorMessage(error);
+        updateSpecSessionStatus(specSessionId, 'error', failureMessage, null);
+        emitUpdatedSpecSession(specSessionId, io);
+        throw new TurnStartError('queue_failed', failureMessage);
+    }
+    queuedJob.catch(error => {
+        try {
+            failSpecTurn({ specSessionId, executionContext, mainRunId: null, error, io });
         }
-        finally {
-            deleteStagedSpecAttachments(stagedAgentAttachmentsDirectoryPath);
+        catch {
+            // Startup reconciliation remains the final repair boundary for database failures.
         }
-    }).catch(error => {
-        updateSpecSessionStatus(specSessionId, 'error', getErrorMessage(error), null);
-        emitUpdatedSpecSession(specSessionId, io);
     });
     return true;
 };