edsger 0.57.0 → 0.59.0

package/dist/phases/product-techniques/index.js

@@ -0,0 +1,268 @@
+/**
+ * product-techniques phase: clone the product's repo, ask Claude (via the
+ * `submit_techniques` MCP tool) to write a catalogue of the techniques the
+ * repo uses, and persist the result to product_techniques via the Supabase
+ * SDK.
+ *
+ * Mirrors the screen-flow pattern. Production-grade behaviours layered on
+ * top of the basic generate-and-write loop:
+ *
+ *   - Heartbeat: `last_heartbeat_at` is refreshed on every assistant message
+ *     so the reader can detect stalled / crashed runs (see services/db/
+ *     product-techniques.ts for the lazy reaper).
+ *   - Cancellation-safe writes: markRunning / markSuccess / markFailed only
+ *     touch rows whose status is in {pending, running}. If the user clicked
+ *     Stop and the row is now 'cancelled', the final write no-ops.
+ *   - Tool-based submission: validated server-side via Zod + content checks
+ *     (mcp-server.ts). Falls back to fenced JSON parsing for resilience.
+ */
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { getGitHubConfigByProduct } from '../../api/github.js';
+import { DEFAULT_MODEL } from '../../constants.js';
+import { getSupabase } from '../../supabase/client.js';
+import { logError, logInfo, logSuccess, logWarning, } from '../../utils/logger.js';
+import { cleanupIssueRepo, cloneIssueRepo, ensureWorkspaceDir, } from '../../workspace/workspace-manager.js';
+import { fetchProductBasics } from '../find-shared/mcp.js';
+import { createPromptGenerator, extractTextFromContent, tryExtractResult, } from '../pr-shared/agent-utils.js';
+import { createTechniquesCaptureState, createTechniquesMcpServer, validateContent, } from './mcp-server.js';
+import { createProductTechniquesSystemPrompt, createProductTechniquesUserPrompt, } from './prompts.js';
+import { isTechniquesExtraction, TECHNIQUES_CONTENT_MAX, TECHNIQUES_SUMMARY_MAX, } from './types.js';
+const WORKSPACE_KEY = 'product-techniques';
+const MAX_TURNS = 120;
+// Heartbeat cadence: at most one DB write per HEARTBEAT_MIN_INTERVAL_MS.
+// Triggered on every assistant message so a stalled agent (no messages
+// flowing) lets the row go stale and the reader can mark it failed.
+const HEARTBEAT_MIN_INTERVAL_MS = 15_000;
+export async function runProductTechniquesPhase(options) {
+    const { productId, techniquesId, guidance, verbose } = options;
+    logInfo(`Starting product-techniques generation for product ${productId}`);
+    const supabase = getSupabase();
+    const claimed = await markRunning(supabase, techniquesId);
+    if (!claimed) {
+        return {
+            status: 'cancelled',
+            message: 'Techniques row is no longer in a runnable state (likely cancelled before the CLI started)',
+        };
+    }
+    const githubConfig = await getGitHubConfigByProduct(productId, verbose);
+    if (!githubConfig.configured ||
+        !githubConfig.token ||
+        !githubConfig.owner ||
+        !githubConfig.repo) {
+        const msg = githubConfig.message ||
+            'GitHub repository not configured for this product. Connect a repo first.';
+        await markFailed(supabase, techniquesId, msg);
+        return { status: 'error', message: msg };
+    }
+    let repoPath;
+    let succeeded = false;
+    try {
+        const workspaceRoot = ensureWorkspaceDir();
+        const repoKey = `${WORKSPACE_KEY}-${productId}`;
+        ({ repoPath } = cloneIssueRepo(workspaceRoot, repoKey, githubConfig.owner, githubConfig.repo, githubConfig.token));
+        const product = await fetchProductBasics(productId);
+        const systemPrompt = createProductTechniquesSystemPrompt();
+        const userPrompt = createProductTechniquesUserPrompt({
+            productName: product.name,
+            productDescription: product.description,
+            guidance,
+        });
+        logInfo('Running Claude agent to write techniques catalogue...');
+        const captureState = createTechniquesCaptureState();
+        const mcpServer = createTechniquesMcpServer(captureState);
+        let lastAssistantResponse = '';
+        let lastHeartbeatAt = 0;
+        for await (const message of query({
+            prompt: createPromptGenerator(userPrompt),
+            options: {
+                systemPrompt: {
+                    type: 'preset',
+                    preset: 'claude_code',
+                    append: systemPrompt,
+                },
+                model: DEFAULT_MODEL,
+                maxTurns: MAX_TURNS,
+                permissionMode: 'bypassPermissions',
+                cwd: repoPath,
+                mcpServers: {
+                    'product-techniques': mcpServer,
+                },
+            },
+        })) {
+            if (message.type === 'assistant') {
+                lastAssistantResponse += extractTextFromContent(message.message?.content ?? [], verbose);
+                // Throttled heartbeat. Awaited (cheap UPDATE) so we don't pile up
+                // unresolved promises on a long run.
+                const now = Date.now();
+                if (now - lastHeartbeatAt >= HEARTBEAT_MIN_INTERVAL_MS) {
+                    lastHeartbeatAt = now;
+                    await heartbeat(supabase, techniquesId);
+                }
+                continue;
+            }
+            if (message.type !== 'result') {
+                continue;
+            }
+            // Prefer the MCP-captured extraction. Fall back to fenced JSON only
+            // if the agent ignored the tool — robustness, not a contract.
+            const fromTool = captureState.captured;
+            const fromFallback = fromTool
+                ? null
+                : tryFallbackParse(message, lastAssistantResponse);
+            const extraction = fromTool ?? fromFallback;
+            if (!extraction) {
+                const msg = message.subtype === 'success'
+                    ? 'Techniques generation failed: agent did not call submit_techniques and no parseable fallback was found'
+                    : `Techniques generation failed: agent ${message.subtype}`;
+                const written = await markFailed(supabase, techniquesId, msg);
+                return {
+                    status: written ? 'error' : 'cancelled',
+                    message: written
+                        ? msg
+                        : 'Generation was cancelled while the agent was running',
+                };
+            }
+            if (fromFallback) {
+                logWarning('Agent skipped submit_techniques; used fenced fallback JSON instead');
+            }
+            const written = await markSuccess(supabase, techniquesId, extraction.summary, extraction.content);
+            if (!written) {
+                return {
+                    status: 'cancelled',
+                    message: 'Generation was cancelled before the result could be written',
+                };
+            }
+            succeeded = true;
+            logSuccess(`Techniques catalogue generated (${extraction.content.length} chars of markdown)`);
+            return {
+                status: 'success',
+                message: 'Techniques catalogue generated',
+                summary: extraction.summary,
+            };
+        }
+        // Loop ended without a 'result' message — treat as failure.
+        const msg = 'Techniques generation ended without a result message';
+        await markFailed(supabase, techniquesId, msg);
+        return { status: 'error', message: msg };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logError(`Techniques generation failed: ${errorMessage}`);
+        await markFailed(supabase, techniquesId, errorMessage);
+        return { status: 'error', message: errorMessage };
+    }
+    finally {
+        if (succeeded) {
+            cleanupIssueRepo(repoPath);
+        }
+    }
+}
+// Fallback parser: extract a fenced `techniques` JSON block from the final
+// assistant text if the agent skipped the submit_techniques tool. Backstop
+// only — we expect the tool path to be the norm.
+function tryFallbackParse(resultMessage, assistantText) {
+    const responseText = resultMessage.subtype === 'success'
+        ? resultMessage.result || assistantText
+        : assistantText;
+    const parsed = tryExtractResult(responseText, 'techniques');
+    if (!isTechniquesExtraction(parsed)) {
+        return null;
+    }
+    if (parsed.summary.length > TECHNIQUES_SUMMARY_MAX) {
+        return null;
+    }
+    if (parsed.content.length > TECHNIQUES_CONTENT_MAX) {
+        return null;
+    }
+    const { error } = validateContent(parsed.content);
+    if (error) {
+        return null;
+    }
+    return parsed;
+}
+// ============================================================================
+// Persistence — exported for unit tests
+// ============================================================================
+/**
+ * Claim the row by flipping `pending` → `running`. Returns true on success
+ * (we won the claim) and false when the row has already moved on (e.g. user
+ * cancelled before the CLI started). Bounded by the status filter so we
+ * can't accidentally resurrect a 'cancelled' row.
+ */
+export async function markRunning(supabase, techniquesId) {
+    const { data, error } = await supabase
+        .from('product_techniques')
+        .update({
+        status: 'running',
+        error: null,
+        last_heartbeat_at: new Date().toISOString(),
+    })
+        .eq('id', techniquesId)
+        .in('status', ['pending', 'running'])
+        .select('id')
+        .maybeSingle();
+    if (error) {
+        logWarning(`Could not mark techniques as running: ${error.message}`);
+        return false;
+    }
+    return data !== null;
+}
+/**
+ * Touch the heartbeat. Best-effort — if it fails (network blip, RLS), the
+ * agent loop keeps running; the reader treats this row as stale and marks
+ * it failed on next read, which is the correct behaviour.
+ */
+export async function heartbeat(supabase, techniquesId) {
+    const { error } = await supabase
+        .from('product_techniques')
+        .update({ last_heartbeat_at: new Date().toISOString() })
+        .eq('id', techniquesId)
+        .eq('status', 'running');
+    if (error) {
+        logWarning(`Heartbeat failed: ${error.message}`);
+    }
+}
+/**
+ * Write failure status iff the row is still in an active state. Returns
+ * true if the row was actually updated (so the caller knows whether the
+ * agent's verdict made it to the DB). Returns false when the row has
+ * already been cancelled or otherwise resolved by someone else.
+ */
+export async function markFailed(supabase, techniquesId, errorMessage) {
+    const { data, error } = await supabase
+        .from('product_techniques')
+        .update({
+        status: 'failed',
+        error: errorMessage,
+        completed_at: new Date().toISOString(),
+    })
+        .eq('id', techniquesId)
+        .in('status', ['pending', 'running'])
+        .select('id')
+        .maybeSingle();
+    if (error) {
+        logWarning(`Could not mark techniques as failed: ${error.message}`);
+        return false;
+    }
+    return data !== null;
+}
+export async function markSuccess(supabase, techniquesId, summary, content) {
+    const { data, error } = await supabase
+        .from('product_techniques')
+        .update({
+        status: 'success',
+        summary,
+        content,
+        error: null,
+        completed_at: new Date().toISOString(),
+    })
+        .eq('id', techniquesId)
+        .in('status', ['pending', 'running'])
+        .select('id')
+        .maybeSingle();
+    if (error) {
+        logWarning(`Could not mark techniques as success: ${error.message}`);
+        return false;
+    }
+    return data !== null;
+}

package/dist/phases/product-techniques/mcp-server.d.ts

@@ -0,0 +1,41 @@
+/**
+ * In-process MCP server exposing a single tool — `submit_techniques` — that
+ * the Claude Agent SDK session calls to return the final markdown catalogue.
+ *
+ * Using a tool call instead of parsing a fenced JSON block lets the SDK
+ * enforce the schema (via Zod) and lets the agent self-correct when
+ * validation fails: the error message goes back as the tool result and the
+ * agent can re-call the tool with corrected data.
+ *
+ * The capture pattern: callers pass in a `TechniquesCaptureState`. The tool
+ * handler stores the validated args on `state.captured`. The orchestrator
+ * reads it after the SDK loop ends.
+ */
+import { z } from 'zod';
+import { type TechniquesExtraction } from './types.js';
+export interface TechniquesCaptureState {
+    captured: TechniquesExtraction | null;
+}
+export declare function createTechniquesCaptureState(): TechniquesCaptureState;
+/**
+ * Validation that goes beyond the basic Zod schema: enforce that the
+ * markdown actually has the H2 sections the prompt asks for. The agent gets
+ * an actionable error and can re-submit.
+ *
+ * We don't require ALL six sections — agents on tiny repos often legitimately
+ * collapse some. We require at least the first one ("Languages & Runtime")
+ * plus "Notable Techniques", which the prompt calls out as the whole point.
+ */
+export declare function validateContent(content: string): {
+    error: string | null;
+};
+/**
+ * Build the `submit_techniques` tool. Exported separately from the server
+ * so tests can exercise the handler directly without going through MCP
+ * transport.
+ */
+export declare function createSubmitTechniquesTool(state: TechniquesCaptureState): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    summary: z.ZodString;
+    content: z.ZodString;
+}>;
+export declare function createTechniquesMcpServer(state: TechniquesCaptureState): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/phases/product-techniques/mcp-server.js

@@ -0,0 +1,96 @@
+/**
+ * In-process MCP server exposing a single tool — `submit_techniques` — that
+ * the Claude Agent SDK session calls to return the final markdown catalogue.
+ *
+ * Using a tool call instead of parsing a fenced JSON block lets the SDK
+ * enforce the schema (via Zod) and lets the agent self-correct when
+ * validation fails: the error message goes back as the tool result and the
+ * agent can re-call the tool with corrected data.
+ *
+ * The capture pattern: callers pass in a `TechniquesCaptureState`. The tool
+ * handler stores the validated args on `state.captured`. The orchestrator
+ * reads it after the SDK loop ends.
+ */
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { TECHNIQUES_CONTENT_MAX, TECHNIQUES_SUMMARY_MAX, } from './types.js';
+export function createTechniquesCaptureState() {
+    return { captured: null };
+}
+/**
+ * Validation that goes beyond the basic Zod schema: enforce that the
+ * markdown actually has the H2 sections the prompt asks for. The agent gets
+ * an actionable error and can re-submit.
+ *
+ * We don't require ALL six sections — agents on tiny repos often legitimately
+ * collapse some. We require at least the first one ("Languages & Runtime")
+ * plus "Notable Techniques", which the prompt calls out as the whole point.
+ */
+export function validateContent(content) {
+    const required = [
+        /^##\s+Languages\s*&\s*Runtime\b/im,
+        /^##\s+Notable\s+Techniques\b/im,
+    ];
+    for (const re of required) {
+        if (!re.test(content)) {
+            return {
+                error: `content is missing the required section matching ${re.source}. Add the section and re-call submit_techniques.`,
+            };
+        }
+    }
+    return { error: null };
+}
+/**
+ * Build the `submit_techniques` tool. Exported separately from the server
+ * so tests can exercise the handler directly without going through MCP
+ * transport.
+ */
+export function createSubmitTechniquesTool(state) {
+    return tool('submit_techniques', [
+        'Submit the final techniques catalogue. Call this EXACTLY once, when',
+        'you have finished cataloguing every technique. Pass the summary and',
+        'the full markdown content as arguments. After this call succeeds, end',
+        'your turn — do NOT also paste the same content as a fenced code block.',
+        'If validation fails, the error message tells you what to fix; call the',
+        'tool again with corrected data.',
+    ].join(' '), {
+        summary: z
+            .string()
+            .min(1)
+            .max(TECHNIQUES_SUMMARY_MAX)
+            .describe('1-2 sentence summary suitable for a tab header. Plain text, no markdown.'),
+        content: z
+            .string()
+            .min(1)
+            .max(TECHNIQUES_CONTENT_MAX)
+            .describe('Full markdown body with H2 sections: Languages & Runtime, Frameworks & Libraries, Architecture Patterns, State & Data Techniques, Build & Deploy Techniques, Notable Techniques.'),
+    }, async (args) => {
+        const extraction = {
+            summary: args.summary,
+            content: args.content,
+        };
+        const { error } = validateContent(extraction.content);
+        if (error) {
+            return {
+                content: [{ type: 'text', text: error }],
+                isError: true,
+            };
+        }
+        state.captured = extraction;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Captured techniques catalogue (${extraction.content.length} chars). End your turn now.`,
+                },
+            ],
+        };
+    });
+}
+export function createTechniquesMcpServer(state) {
+    return createSdkMcpServer({
+        name: 'product-techniques',
+        version: '1.0.0',
+        tools: [createSubmitTechniquesTool(state)],
+    });
+}

package/dist/phases/product-techniques/prompts.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Prompts for the product-level techniques phase.
+ *
+ * Agent's job: explore the cloned product repo and write a markdown catalogue
+ * of the techniques it actually uses — languages, frameworks, patterns, state
+ * idioms, build/deploy choices, plus the clever non-obvious bits. Focused on
+ * what a new engineer needs to recognize and recreate, not feature lists.
+ *
+ * The final result is submitted via the `submit_techniques` MCP tool, NOT a
+ * fenced JSON block. Tool calls let the SDK enforce the schema with Zod and
+ * let the agent self-correct on validation errors. See mcp-server.ts.
+ */
+export interface ProductTechniquesPromptContext {
+    productName: string;
+    productDescription?: string;
+    guidance?: string;
+}
+export declare function createProductTechniquesSystemPrompt(): string;
+export declare function createProductTechniquesUserPrompt(context: ProductTechniquesPromptContext): string;

package/dist/phases/product-techniques/prompts.js

@@ -0,0 +1,66 @@
+/**
+ * Prompts for the product-level techniques phase.
+ *
+ * Agent's job: explore the cloned product repo and write a markdown catalogue
+ * of the techniques it actually uses — languages, frameworks, patterns, state
+ * idioms, build/deploy choices, plus the clever non-obvious bits. Focused on
+ * what a new engineer needs to recognize and recreate, not feature lists.
+ *
+ * The final result is submitted via the `submit_techniques` MCP tool, NOT a
+ * fenced JSON block. Tool calls let the SDK enforce the schema with Zod and
+ * let the agent self-correct on validation errors. See mcp-server.ts.
+ */
+export function createProductTechniquesSystemPrompt() {
+    return `You are a senior staff engineer cataloguing the techniques a product's codebase uses.
+
+The current working directory is a fresh clone of the product's repository. Use Glob/Grep/Read (and Bash for git/log when helpful) to explore it before writing.
+
+Your audience: a new engineer joining the team. They need to recognize WHICH techniques this repo employs — what frameworks, what patterns, what idioms — so they can read code without surprise and contribute in the codebase's existing style. This is not a feature list and not an architecture proposal. Anchor every technique in the actual code; reference real file paths.
+
+## Output protocol
+
+When you are ready to submit, call the \`submit_techniques\` tool EXACTLY ONCE with:
+- \`summary\` — 1-2 sentence summary suitable for a tab header (plain text, no markdown).
+- \`content\` — the full markdown body, structured as described below.
+
+Do NOT also paste the same content as a fenced code block — the tool call is the only channel for the result. If validation fails, the tool response tells you what to fix; call the tool again with corrected data.
+
+## Required sections in \`content\`
+
+The markdown body MUST contain these H2 sections, in this order:
+
+1. **## Languages & Runtime** — languages used (with versions if pinned), runtime targets (Node / Bun / Deno / browser / native / etc), package manager.
+2. **## Frameworks & Libraries** — the major frameworks and libraries this repo depends on, and what each one is doing here. Don't just list package names; explain the role. Group by area (UI, server, data, infra) if it helps.
+3. **## Architecture Patterns** — the architectural choices the code embodies: layering / module boundaries / dependency direction / how features are organised. Include one Mermaid \`flowchart TD\` showing the dominant pattern (≤ 10 nodes). Name the pattern when you can ("repository pattern", "feature-sliced design", "hexagonal", "BFF", etc.).
+4. **## State & Data Techniques** — state management, data fetching, caching, optimistic updates, validation, type-safety across boundaries. How is server state vs client state handled? How are forms managed? How is data flowing between server and client?
+5. **## Build & Deploy Techniques** — bundler / compiler choices, code-splitting, environment handling, monorepo tooling, CI/CD specifics, deployment target (edge / serverless / containers / static).
+6. **## Notable Techniques** — the genuinely interesting bits that aren't obvious from the stack: clever abstractions, performance optimizations, security hardening, custom hooks/utilities worth knowing, intentional deviations from defaults, surprising workarounds. Each one: what it is, where it lives (file path), why it matters. This section is the whole point — be specific and useful here.
+
+The validator will reject content missing the "Languages & Runtime" or "Notable Techniques" headings.
+
+## Rules
+
+- Use relative file paths from the repo root (e.g. \`src/services/auth.ts\`). Link to specific files where the technique is most visible.
+- Mermaid blocks must be valid (no unclosed quotes, no unsupported node shapes). Prefer simple \`flowchart TD\` syntax.
+- Don't invent or guess. If a section has nothing distinctive ("just a stock CRA app"), say so briefly — don't pad.
+- Focus on TECHNIQUES, not features. Bad: "the app has a login screen". Good: "uses next-auth's credentials provider with a custom JWT callback at src/lib/auth.ts:42".
+- The whole document should fit in one screen-readable scroll — aim for ~1500-3000 words of content. Less is fine for small repos.`;
+}
+export function createProductTechniquesUserPrompt(context) {
+    const lines = [];
+    lines.push(`# Product: ${context.productName}`);
+    if (context.productDescription) {
+        lines.push('');
+        lines.push('## Description');
+        lines.push(context.productDescription);
+    }
+    if (context.guidance && context.guidance.trim()) {
+        lines.push('');
+        lines.push('## Reviewer guidance (focus or exclusions)');
+        lines.push(context.guidance.trim());
+    }
+    lines.push('');
+    lines.push('## Task');
+    lines.push('Explore the cloned repository and produce the techniques catalogue, then submit it via the `submit_techniques` MCP tool as specified in your system prompt. Pay particular attention to the "Notable Techniques" section — that is the real value to the reader.');
+    return lines.join('\n');
+}

package/dist/phases/product-techniques/types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shape returned by the agent via the `submit_techniques` MCP tool. Mirrors
+ * the Zod schema in `mcp-server.ts` — kept duplicated as a plain TS type so
+ * consumers (the phase orchestrator, persistence helpers, tests) don't have
+ * to inflate Zod into their dependency graph.
+ */
+export interface TechniquesExtraction {
+    summary: string;
+    content: string;
+}
+export declare function isTechniquesExtraction(v: unknown): v is TechniquesExtraction;
+export declare const TECHNIQUES_SUMMARY_MAX = 500;
+export declare const TECHNIQUES_CONTENT_MAX = 200000;

package/dist/phases/product-techniques/types.js

@@ -0,0 +1,13 @@
+export function isTechniquesExtraction(v) {
+    if (!v || typeof v !== 'object') {
+        return false;
+    }
+    const obj = v;
+    return typeof obj.summary === 'string' && typeof obj.content === 'string';
+}
+// Defensive caps mirroring the DB CHECK constraints from
+// 20260521000000_create_product_techniques.sql. Keeping the limits here
+// too lets the MCP tool reject oversized output with an actionable error
+// message instead of getting a Postgres constraint violation.
+export const TECHNIQUES_SUMMARY_MAX = 500;
+export const TECHNIQUES_CONTENT_MAX = 200_000;

package/dist/phases/screen-flow/index.js

@@ -15,6 +15,7 @@ import { logError, logInfo, logSuccess, logWarning } from '../../utils/logger.js
 import { cleanupIssueRepo, cloneIssueRepo, ensureWorkspaceDir, } from '../../workspace/workspace-manager.js';
 import { fetchProductBasics } from '../find-shared/mcp.js';
 import { createPromptGenerator, extractTextFromContent, tryExtractResult, } from '../pr-shared/agent-utils.js';
+import { createScreenFlowCaptureState, createScreenFlowMcpServer, validateConsistency, } from './mcp-server.js';
 import { createScreenFlowSystemPrompt, createScreenFlowUserPrompt, } from './prompts.js';
 import { extractTheme } from './theme.js';
 import { isScreenFlowExtraction, } from './types.js';
@@ -61,6 +62,17 @@ export async function runScreenFlowPhase(options) {
             guidance,
         });
         logInfo('Running Claude screen-flow extraction...');
+        // The agent submits the extraction by calling submit_screen_flow on the
+        // in-process MCP server. The handler validates with Zod + cross-field
+        // checks and stores the result in `captureState.captured`. If the agent
+        // never calls the tool, we fall back to parsing a fenced screen_flow
+        // block out of the assistant text.
+        const captureState = createScreenFlowCaptureState();
+        const mcpServer = createScreenFlowMcpServer(captureState, {
+            onProgress: ({ phase, message }) => {
+                logInfo(`[${phase}] ${message}`);
+            },
+        });
         let lastAssistantResponse = '';
         let extraction = null;
         for await (const message of query({
@@ -75,28 +87,19 @@ export async function runScreenFlowPhase(options) {
                 maxTurns: MAX_TURNS,
                 permissionMode: 'bypassPermissions',
                 cwd: repoPath,
+                mcpServers: {
+                    'screen-flow': mcpServer,
+                },
             },
         })) {
-            if (message.type === 'assistant') {
-                lastAssistantResponse += extractTextFromContent(message.message?.content ?? [], verbose);
-                continue;
-            }
-            if (message.type !== 'result') {
-                continue;
-            }
-            const responseText = message.subtype === 'success'
-                ? message.result || lastAssistantResponse
-                : lastAssistantResponse;
-            const parsed = tryExtractResult(responseText, 'screen_flow');
-            if (isScreenFlowExtraction(parsed)) {
-                extraction = parsed;
-            }
-            else if (message.subtype !== 'success') {
-                logError(`Extraction incomplete: ${message.subtype}`);
+            const { assistantBuffer, extraction: nextExtraction } = processSdkMessage(message, lastAssistantResponse, captureState, verbose);
+            lastAssistantResponse = assistantBuffer;
+            if (nextExtraction) {
+                extraction = nextExtraction;
             }
         }
         if (!extraction) {
-            const msg = 'Screen flow extraction failed: could not parse a screen_flow result from the agent';
+            const msg = 'Screen flow extraction failed: agent did not call submit_screen_flow and no parseable screen_flow block was found in the response';
             await markFlowFailed(supabase, flowId, msg);
             return { status: 'error', message: msg };
         }
@@ -125,6 +128,59 @@ export async function runScreenFlowPhase(options) {
         }
     }
 }
+// Per-message handler — extracted out of the SDK loop to keep
+// runScreenFlowPhase under the eslint complexity ceiling.
+//
+function processSdkMessage(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+message, assistantBuffer, captureState, verbose) {
+    if (message.type === 'assistant') {
+        const next = assistantBuffer +
+            extractTextFromContent(message.message?.content ?? [], verbose);
+        return { assistantBuffer: next, extraction: null };
+    }
+    if (message.type === 'user' && verbose) {
+        // Surface tool_result blocks (incl. submit_screen_flow validation
+        // errors) so verbose mode shows the round-trip.
+        const userContent = message.message?.content;
+        if (Array.isArray(userContent)) {
+            extractTextFromContent(userContent, verbose);
+        }
+        return { assistantBuffer, extraction: null };
+    }
+    if (message.type !== 'result') {
+        return { assistantBuffer, extraction: null };
+    }
+    if (captureState.captured) {
+        return { assistantBuffer, extraction: captureState.captured };
+    }
+    const fallback = tryFallbackParse(message, assistantBuffer);
+    if (fallback) {
+        logWarning('Agent emitted a fenced screen_flow block instead of calling submit_screen_flow; using the parsed text as a fallback.');
+        return { assistantBuffer, extraction: fallback };
+    }
+    if (message.subtype !== 'success') {
+        logError(`Extraction incomplete: ${message.subtype}`);
+    }
+    return { assistantBuffer, extraction: null };
+}
+// Fallback parser: extract a screen_flow JSON block from the final assistant
+// text if the agent skipped the submit_screen_flow tool call.
+function tryFallbackParse(resultMessage, assistantText) {
+    const responseText = resultMessage.subtype === 'success'
+        ? resultMessage.result || assistantText
+        : assistantText;
+    const parsed = tryExtractResult(responseText, 'screen_flow');
+    if (!isScreenFlowExtraction(parsed)) {
+        return null;
+    }
+    const { error } = validateConsistency(parsed);
+    if (error) {
+        logWarning(`Fallback extraction failed consistency check: ${error}`);
+        return null;
+    }
+    return parsed;
+}
 // ============================================================================
 // Persistence
 // ============================================================================