funolio-agent 1.0.75 → 1.1.65

package/dist/workflow-engine.js

@@ -50,6 +50,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WorkflowEngine = void 0;
 exports.resolveWorkflowCliSessionTransportForTest = resolveWorkflowCliSessionTransportForTest;
+exports.resolveWorkflowClaudeUseConptyForTest = resolveWorkflowClaudeUseConptyForTest;
+exports.buildDeferredImageReferenceBlockForTest = buildDeferredImageReferenceBlockForTest;
+exports.parseImageEscalationRequestForTest = parseImageEscalationRequestForTest;
 exports.getWorkflowEngine = getWorkflowEngine;
 const events_1 = require("events");
 const fs_1 = __importDefault(require("fs"));
@@ -68,33 +71,93 @@ const runtime_context_1 = require("./runtime-context");
 const local_cli_pty_manager_1 = require("./local-cli-pty-manager");
 const codex_app_server_manager_1 = require("./codex-app-server-manager");
 const cli_session_epoch_1 = require("./cli-session-epoch");
+const cli_bootstrap_history_1 = require("./cli-bootstrap-history");
+const context_window_1 = require("./context-window");
+const capabilities_1 = require("./orchestration/capabilities");
 // ─── Workflow Engine ─────────────────────────────────────────────
 const MAX_STEP_ATTEMPTS = safeguards_1.SAFEGUARDS.MAX_AGENT_ATTEMPTS;
 const MAX_STEPS = safeguards_1.SAFEGUARDS.MAX_WORKFLOW_STEPS;
 function isInteractiveAuthFailure(text) {
-    return /\b(not logged in|please run \/login|unauthorized|invalid api key|authentication required)\b/i.test(text);
+    return /\b(not logged in|please run \/login|login required|unauthorized|invalid authorization|invalid api key|missing api key|authentication required|invalid authentication credentials|invalid bearer token|token expired|session expired|credentials expired|expired credentials|reauthenticate)\b/i.test(text);
 }
 const LOCAL_WORKFLOW_RUNTIME_RETRY_LIMIT = 2;
+function shouldUseConptyForWorkflowClaudePty() {
+    // ConPTY can surface transient console-host flashes on Windows during
+    // long-running Claude PTY worker turns. Keep direct chat unchanged, but use
+    // the legacy hidden winpty backend for orchestration/workflow Claude runs.
+    return process.platform !== 'win32';
+}
+function isClaudeFreshWorkflowSessionStartupFailure(err) {
+    return err?.code === 'CLAUDE_FRESH_SESSION_STARTUP_TIMEOUT'
+        || err?.name === 'ClaudeFreshSessionStartupTimeoutError'
+        || /fresh session startup timed out/i.test(String(err?.message || err || ''));
+}
+function createWorkflowAbortError() {
+    const err = new Error('aborted');
+    err.name = 'AbortError';
+    err.code = 'ABORT_ERR';
+    return err;
+}
+function isWorkflowAbortError(err) {
+    return err?.name === 'AbortError'
+        || err?.code === 'ABORT_ERR'
+        || /\baborted\b/i.test(String(err?.message || err || ''));
+}
+function throwIfWorkflowAborted(abortSignal) {
+    if (!abortSignal?.aborted)
+        return;
+    throw createWorkflowAbortError();
+}
 function shouldRetrySelectedWorkflowRuntime(err) {
     const text = String(err?.message || err || '').toLowerCase();
     if (!text)
         return false;
-    if (/\b(no api key|configure one in settings|not available on this machine|not installed|please run \/login|not logged in|invalid api key)\b/i.test(text)) {
+    if (/\b(no api key|missing api key|configure one in settings|not available on this machine|not installed|please run \/login|login required|not logged in|unauthorized|invalid authorization|invalid api key|authentication required|invalid authentication credentials|invalid bearer token|token expired|session expired|credentials expired|expired credentials|reauthenticate)\b/i.test(text)) {
         return false;
     }
-    return /\b(429|rate limit|timeout|timed out|temporar|temporarily|econnreset|etimedout|enotfound|econnrefused|socket hang up|network|try again|overloaded|busy)\b/i.test(text);
+    return /\b(429|rate limit|timeout|timed out|temporar|temporarily|econnreset|etimedout|enotfound|econnrefused|socket hang up|network|try again|overloaded|busy|no meaningful pty activity)\b/i.test(text);
 }
-async function pauseWorkflowRuntimeRetry(attempt) {
+async function pauseWorkflowRuntimeRetry(attempt, abortSignal) {
     const delayMs = attempt <= 1 ? 750 : 1500;
-    await new Promise((resolve) => setTimeout(resolve, delayMs));
+    throwIfWorkflowAborted(abortSignal);
+    await Promise.race([
+        new Promise((resolve) => setTimeout(resolve, delayMs)),
+        new Promise((_, reject) => {
+            if (!abortSignal)
+                return;
+            const onAbort = () => {
+                abortSignal.removeEventListener('abort', onAbort);
+                reject(createWorkflowAbortError());
+            };
+            abortSignal.addEventListener('abort', onAbort, { once: true });
+        }),
+    ]);
+    throwIfWorkflowAborted(abortSignal);
 }
-function buildWorkflowPtyConversationKey(conversationId, step, workflowContext) {
+function buildWorkflowPtyConversationKey(conversationId, step, workflowContext, cliSessionScopeKey) {
+    const explicitScope = String(cliSessionScopeKey || '').trim();
+    if (explicitScope)
+        return explicitScope;
     if (conversationId)
         return conversationId;
     if (workflowContext?.workflowId)
         return `workflow:${workflowContext.workflowId}`;
     return `adhoc:${step.agentId}:${step.id}`;
 }
+function clearFailedWorkflowCliSessionEpoch(conversationId, botId, sessionId, cliSessionScopeKey) {
+    const normalizedSessionId = String(sessionId || '').trim();
+    if (!conversationId || !normalizedSessionId)
+        return;
+    try {
+        const cleared = data.clearCliSessionEpochIfMatches(conversationId, botId, normalizedSessionId, cliSessionScopeKey);
+        if (cleared) {
+            console.warn(`[workflow-engine] cleared poisoned cli_session_epoch conversationId=${conversationId} botId=${botId} sessionId=${normalizedSessionId}`);
+        }
+    }
+    catch (err) {
+        console.warn(`[workflow-engine] failed to clear cli_session_epoch conversationId=${conversationId} botId=${botId} sessionId=${normalizedSessionId}: ${err?.message || err}`);
+    }
+}
 function resolveWorkflowCliSessionTransport(providerName, isLocalCliSession) {
     if (!isLocalCliSession)
         return 'none';
@@ -105,6 +168,42 @@ function resolveWorkflowCliSessionTransport(providerName, isLocalCliSession) {
 function resolveWorkflowCliSessionTransportForTest(providerName, isLocalCliSession) {
     return resolveWorkflowCliSessionTransport(providerName, isLocalCliSession);
 }
+function resolveWorkflowClaudeUseConptyForTest() {
+    return shouldUseConptyForWorkflowClaudePty();
+}
+function listImageAttachments(attachments) {
+    return (attachments || []).filter((attachment) => attachment.mimeType?.startsWith('image/'));
+}
+function buildDeferredImageReferenceBlock(attachments) {
+    const imageAttachments = listImageAttachments(attachments);
+    if (imageAttachments.length === 0)
+        return '';
+    const lines = [
+        '[Original Image Context Available]',
+        ...imageAttachments.map((attachment) => `- id: ${attachment.id} (${attachment.filename})`),
+        'Use the assigned task, prior worker artifacts, and any available memory/history search tools first.',
+        'If you still need the original image, reply exactly with one line:',
+        'ESCALATE_IMAGE <id>',
+        'Use one of the listed ids. Do not include any other text.',
+    ];
+    return lines.join('\n');
+}
+function buildDeferredImageReferenceBlockForTest(attachments) {
+    return buildDeferredImageReferenceBlock(attachments);
+}
+function parseImageEscalationRequest(text, attachments) {
+    const imageAttachments = listImageAttachments(attachments);
+    if (imageAttachments.length === 0)
+        return null;
+    const match = String(text || '').match(/^\s*ESCALATE_IMAGE\s+([A-Za-z0-9._:-]+)\s*$/m);
+    if (!match)
+        return null;
+    const requestedId = match[1].trim();
+    return imageAttachments.find((attachment) => attachment.id === requestedId) || null;
+}
+function parseImageEscalationRequestForTest(text, attachments) {
+    return parseImageEscalationRequest(text, attachments)?.id || null;
+}
 class WorkflowEngine extends events_1.EventEmitter {
     projectDir;
     runtimeMode;
@@ -343,8 +442,12 @@ class WorkflowEngine extends events_1.EventEmitter {
                 throw new Error(`Workflow step ${index + 1} references missing bot ${templateStep.agent_id}`);
             }
             const instruction = templateStep.instruction?.trim() || `Complete stage ${index + 1} for this TODO item.`;
-            const inferredRole = this.inferRoleForStep({ description: instruction });
-            const isCheckpointLike = templateStep.is_checkpoint === 1 || inferredRole === 'qa';
+            // Role comes from the agent's structured role_class; checkpoint
+            // status comes from the template's explicit is_checkpoint flag
+            // or a QA-role agent. No prose scanning.
+            const agentRole = agent.role_class || undefined;
+            const agentIsQa = this.inferRoleForStep({ role: agentRole }) === 'qa';
+            const isCheckpointLike = templateStep.is_checkpoint === 1 || agentIsQa;
             return {
                 id: templateStep.id,
                 index,
@@ -354,6 +457,7 @@ class WorkflowEngine extends events_1.EventEmitter {
                 agentName: agent.name,
                 provider: agent.provider,
                 model: agent.model,
+                role: agentRole,
                 dependsOn: index === 0 ? [] : [index - 1],
                 status: 'pending',
                 attempts: 0,
@@ -509,6 +613,11 @@ class WorkflowEngine extends events_1.EventEmitter {
                 const mapped = plannedSteps.slice(0, MAX_STEPS).map((step, index) => {
                     // Route to the named agent or default
                     const targetAgent = this.resolveStepAgent(step, agents, defaultProfile, roleAssignments);
+                    // Prefer an explicit role on the planned step; otherwise carry the
+                    // resolved agent's role so downstream code doesn't fall back to
+                    // regex classification on prose.
+                    const explicitRole = typeof step.role === 'string' && step.role.trim() ? step.role.trim().toLowerCase() : undefined;
+                    const agentRole = targetAgent.role_class || undefined;
                     return {
                         id: `step-${index}`,
                         index,
@@ -518,6 +627,7 @@ class WorkflowEngine extends events_1.EventEmitter {
                         agentName: targetAgent.name,
                         provider: targetAgent.provider,
                         model: targetAgent.model,
+                        role: explicitRole || agentRole,
                         dependsOn: step.dependsOn || [],
                         status: 'pending',
                         expectedOutput: step.expectedOutput || undefined,
@@ -543,7 +653,7 @@ class WorkflowEngine extends events_1.EventEmitter {
                         step.loopCount = 0;
                     }
                 }
-                return this.pruneTrailingPostQaSteps(mapped);
+                return mapped;
             }
         }
         catch {
@@ -593,6 +703,14 @@ class WorkflowEngine extends events_1.EventEmitter {
         }
         return steps.length >= 2 ? steps : null;
     }
+    /**
+     * @deprecated Phase B of orchestration-plan.txt.
+     * The LLM-tool-dispatch path in local_desktop creates TODOs directly with
+     * the LLM's explicit step list, so this regex-based role inference no
+     * longer drives dispatch. Still called from decomposeTask's fallback for
+     * non-local_desktop and legacy planner paths. Remove after those are
+     * migrated to tool dispatch.
+     */
     determineDesiredRoleSequence(prompt, roleAssignments) {
         const normalized = prompt.toLowerCase();
         const explicitResearch = /\b(brain|gpt|research(?:es|ed|ing)?|investigat|analy[sz]e|analysis|sound idea|review the idea|pressure[- ]?test|brainstorm(?:ing)?)\b/.test(normalized)
@@ -646,6 +764,7 @@ class WorkflowEngine extends events_1.EventEmitter {
                     agentName: agent.name,
                     provider: agent.provider,
                     model: agent.model,
+                    role: 'research',
                     dependsOn,
                     status: 'pending',
                     expectedOutput: 'Clear implementation guidance, risks, and recommendations for the downstream coder.',
@@ -662,6 +781,7 @@ class WorkflowEngine extends events_1.EventEmitter {
                     agentName: agent.name,
                     provider: agent.provider,
                     model: agent.model,
+                    role: 'coding',
                     dependsOn,
                     status: 'pending',
                     expectedOutput: 'Completed deliverable that satisfies the user request.',
@@ -678,6 +798,7 @@ class WorkflowEngine extends events_1.EventEmitter {
                     agentName: agent.name,
                     provider: agent.provider,
                     model: agent.model,
+                    role: 'qa',
                     dependsOn,
                     status: 'pending',
                     expectedOutput: 'PASS if the deliverable fully satisfies the request, otherwise FAIL with actionable defects.',
@@ -724,17 +845,45 @@ class WorkflowEngine extends events_1.EventEmitter {
             : role === 'qa'
                 ? 'Your role is QA. Verify the delivered work, then complete the TODO through the worker tool or create the next fix handoff.'
                 : 'Your role is implementer. Do the assigned work, then complete the TODO through the worker tool.';
+        const botSettingsPrompt = this.buildBotSettingsPrompt(profile);
+        const capabilityInstructions = profile
+            ? (0, capabilities_1.buildCapabilityInstructionBlock)(data.getAgentRolePriorities(profile))
+            : '';
         return [
-            `You are ${profile?.name || 'a workflow worker'}.`,
+            botSettingsPrompt || `You are ${profile?.name || 'a workflow worker'}.`,
+            '',
+            '[Orchestrated Worker Guardrails]',
             'You are executing one orchestrated TODO task.',
             roleLine,
             'Follow the assignment in the user message exactly.',
             'Use available tools when needed.',
             'Do not return a plain-text final answer until you have called complete_worker_task or block_worker_task.',
+            'Do not create side TODOs with add_task while working an assigned TODO. Use complete_worker_task.handoff_prompt or insert_task when follow-up work is needed.',
             'Do not add workflow planning, orchestration narration, or TODO-management commentary outside those tools.',
             'If blocked after checking available context, call block_worker_task with blocker_summary, checked_context, and user_question.',
             'If the task is complete, call complete_worker_task with output_summary and any needed handoff prompt or inserted next task.',
-        ].join('\n');
+            capabilityInstructions ? '' : null,
+            capabilityInstructions || null,
+        ].filter(Boolean).join('\n');
+    }
+    buildBotSettingsPrompt(profile) {
+        if (!profile)
+            return '';
+        const directPrompt = String(profile.final_prompt || profile.soul_md || '').trim();
+        if (directPrompt)
+            return directPrompt;
+        const sections = [`You are ${profile.name}.`];
+        const addSection = (label, value) => {
+            const text = String(value || '').trim();
+            if (text)
+                sections.push('', label, text);
+        };
+        addSection('PURPOSE', profile.purpose_md);
+        addSection('IDENTITY', profile.identity_summary);
+        addSection('SKILLS', profile.skills_md);
+        addSection('TOOLS', profile.tools_md);
+        addSection('MEMORY', profile.memory_md);
+        return sections.join('\n');
     }
     buildOrchestratedTodoHandledResult(taskId) {
         if (!taskId)
@@ -758,12 +907,11 @@ class WorkflowEngine extends events_1.EventEmitter {
             || data.getTodoTask(taskId, 'active')?.blocker_summary);
     }
     buildWorkflowStepPrompt(step, pinnedContext, handoffArtifacts, handoffPrompts = [], localDesktopHandoffMode = false) {
-        const primaryPrompt = localDesktopHandoffMode && handoffPrompts.length > 0
-            ? handoffPrompts[handoffPrompts.length - 1].trim()
-            : step.prompt.trim();
-        const sections = [primaryPrompt || step.prompt.trim()];
-        if (localDesktopHandoffMode && handoffPrompts.length > 1) {
-            sections.push(`Earlier handoff context:\n${handoffPrompts.slice(0, -1).join('\n\n')}`);
+        const primaryPrompt = step.prompt.trim();
+        const sections = [primaryPrompt];
+        if (localDesktopHandoffMode && handoffPrompts.length > 0) {
+            const label = handoffPrompts.length === 1 ? 'Previous worker handoff' : 'Previous worker handoffs';
+            sections.push(`${label}:\n${handoffPrompts.join('\n\n')}`);
         }
         if (pinnedContext.length > 0) {
             sections.push(`Pinned context:\n${pinnedContext.join('\n\n')}`);
@@ -811,68 +959,39 @@ class WorkflowEngine extends events_1.EventEmitter {
         }
         return defaultProfile;
     }
+    /**
+     * Resolve a step's role. Prefers the structured `role` field set at plan
+     * creation (from an explicit planner decision or the bot's role_class).
+     * Falls through to a small normalizer that maps common role synonyms
+     * (e.g. "verify" → "qa") onto the three canonical workflow roles.
+     * Does NOT scan prose. Phase B of orchestration-plan.txt: pass/fail,
+     * routing, and task creation must come from structured data, not from
+     * English wording.
+     */
     inferRoleForStep(step) {
-        const description = `${step.description || ''}`.toLowerCase();
-        const prompt = `${step.prompt || ''} ${step.expectedOutput || ''}`.toLowerCase();
-        const leadingVerbMatch = description.match(/^(?:[a-z0-9_.-]+\s+)?(qa|review(?:s|ed|ing)?|verif(?:y|ies|ied|ying)|validation|test(?:s|ed|ing)?|check(?:s|ed|ing)?|research(?:es|ed|ing)?|investigat(?:e|es|ed|ing)|analysis|analy[sz](?:e|es|ed|ing)|compar(?:e|es|ed|ing)|inspect(?:s|ed|ing)?|discover(?:s|ed|ing)?|defin(?:e|es|ed|ing)|build(?:s|ed|ing)?|creat(?:e|es|ed|ing)|write(?:s|n)?|writ(?:ing)?|fix(?:es|ed|ing)?|edit(?:s|ed|ing)?|updat(?:e|es|ed|ing)|refactor(?:s|ed|ing)?|implement(?:s|ed|ing)?|code(?:s|d|ing)?)\b/);
-        const qaPattern = /\b(qa|quality assurance|review(?:s|ed|ing)?|verif(?:y|ies|ied|ying|ication)?|validation|test(?:s|ed|ing)?|check(?:s|ed|ing)?)\b/;
-        const researchPattern = /\b(research(?:es|ed|ing)?|investigat(?:e|es|ed|ing)|analysis|analy[sz](?:e|es|ed|ing)|compar(?:e|es|ed|ing)|inspect(?:s|ed|ing)?|look up|discover(?:s|ed|ing)?|defin(?:e|es|ed|ing)|direction|spec(?:ification)?s?|requirements?)\b/;
-        const codingPattern = /\b(code(?:s|d|ing)?|implement(?:s|ed|ing)?|build(?:s|ed|ing)?|creat(?:e|es|ed|ing)|write(?:s|n)?|writ(?:ing)?|fix(?:es|ed|ing)?|edit(?:s|ed|ing)?|updat(?:e|es|ed|ing)|refactor(?:s|ed|ing)?)\b/;
-        if (leadingVerbMatch) {
-            const verb = leadingVerbMatch[1];
-            if (/(qa|review|verif|validation|test|check)/.test(verb))
-                return 'qa';
-            if (/(research|investigat|analysis|analy|compar|inspect|discover|defin)/.test(verb))
-                return 'research';
-            if (/(build|creat|write|writ|fix|edit|updat|refactor|implement|code)/.test(verb))
-                return 'coding';
-        }
-        if (qaPattern.test(description) && !codingPattern.test(description))
+        const raw = typeof step.role === 'string' ? step.role.trim().toLowerCase() : '';
+        if (!raw)
+            return null;
+        if (raw === 'qa' || raw === 'review' || raw === 'reviewer' || raw === 'quality' || raw === 'quality assurance')
             return 'qa';
-        if (codingPattern.test(description))
-            return 'coding';
-        if (researchPattern.test(description))
-            return 'research';
-        if (codingPattern.test(prompt) && !qaPattern.test(prompt))
-            return 'coding';
-        if (qaPattern.test(prompt))
+        if (raw === 'verify' || raw === 'verification')
+            return 'qa';
+        if (/\b(verify|verification)\b/.test(raw))
             return 'qa';
-        if (researchPattern.test(prompt))
+        if (raw === 'research' || raw === 'researcher' || raw === 'analysis' || raw === 'analyst' || raw === 'planning' || raw === 'planner' || raw === 'brainstorming' || raw === 'design' || raw === 'designer')
             return 'research';
-        if (codingPattern.test(prompt))
+        if (raw === 'coding' || raw === 'code' || raw === 'coder' || raw === 'build' || raw === 'building' || raw === 'builder' || raw === 'implement' || raw === 'implementation' || raw === 'dev' || raw === 'developer' || raw === 'engineering' || raw === 'commit' || raw === 'deploy')
             return 'coding';
+        // Comma-separated multi-roles (legacy) — take the first canonical match.
+        if (!/[,/]/.test(raw))
+            return null;
+        for (const part of raw.split(/[,/]/).map((s) => s.trim()).filter(Boolean)) {
+            const mapped = this.inferRoleForStep({ role: part });
+            if (mapped)
+                return mapped;
+        }
         return null;
     }
-    pruneTrailingPostQaSteps(steps) {
-        const firstQaIndex = steps.findIndex((step) => this.inferRoleForStep(step) === 'qa');
-        if (firstQaIndex < 0)
-            return steps;
-        const shouldDrop = (step) => {
-            if (step.index <= firstQaIndex)
-                return false;
-            const normalized = `${step.description || ''} ${step.prompt || ''}`.toLowerCase();
-            return /\b(if applicable|based on qa feedback|based on feedback|revise|revision|finalize|confirm completion|compile instructions|ensure the file is accessible|ensure file is accessible)\b/.test(normalized);
-        };
-        const filtered = steps.filter((step) => !shouldDrop(step));
-        if (filtered.length === steps.length)
-            return steps;
-        return filtered.map((step, newIndex) => {
-            const oldIndex = step.index;
-            const retainedPriorSteps = filtered
-                .filter((candidate) => candidate.index < oldIndex)
-                .map((candidate) => candidate.index);
-            const reindexedDeps = (step.dependsOn || [])
-                .filter((dep) => retainedPriorSteps.includes(dep))
-                .map((dep) => filtered.findIndex((candidate) => candidate.index === dep))
-                .filter((dep) => dep >= 0);
-            return {
-                ...step,
-                index: newIndex,
-                id: step.id || `step-${newIndex}`,
-                dependsOn: reindexedDeps,
-            };
-        });
-    }
     findPriorCodingStepIndex(steps, currentIndex) {
         const priorCodingStep = [...steps]
             .filter((candidate) => candidate.index < currentIndex)
@@ -913,6 +1032,15 @@ class WorkflowEngine extends events_1.EventEmitter {
         const failed = new Set();
         const allowMissingFooterForDirectStep = !opts?.isOrchestrated && !!opts?.disableDecomposition && steps.length === 1;
         while (completed.size + failed.size < steps.length) {
+            if (opts?.abortSignal?.aborted) {
+                for (const step of steps) {
+                    if (step.status === 'pending' || step.status === 'running') {
+                        step.status = 'skipped';
+                        step.error = 'Cancelled by user';
+                    }
+                }
+                break;
+            }
             // Find steps that are ready to run (all deps met)
             const ready = steps.filter(s => s.status === 'pending' &&
                 s.dependsOn.every(dep => completed.has(dep)));
@@ -928,6 +1056,11 @@ class WorkflowEngine extends events_1.EventEmitter {
             }
             // Execute ready steps in parallel
             await Promise.all(ready.map(async (step) => {
+                if (opts?.abortSignal?.aborted) {
+                    step.status = 'skipped';
+                    step.error = 'Cancelled by user';
+                    return;
+                }
                 // Build context from completed dependency results — pass only RESULT artifact
                 const handoffArtifacts = [];
                 const handoffPrompts = [];
@@ -956,6 +1089,7 @@ class WorkflowEngine extends events_1.EventEmitter {
                         }
                     }
                 }
+                const initialImageDeliveryMode = opts?.workerImageDeliveryMode || 'inline';
                 const fullPrompt = this.buildWorkflowStepPrompt(step, pinnedContext, handoffArtifacts, handoffPrompts, localDesktopHandoffMode);
                 // approvalRequired gate: when enabled, emit an approval request
                 // event and wait for the listener to resolve before proceeding.
@@ -1005,6 +1139,7 @@ class WorkflowEngine extends events_1.EventEmitter {
                 }
                 catch { /* best effort */ }
                 try {
+                    throwIfWorkflowAborted(opts?.abortSignal);
                     // Build previous steps summary for workflow context
                     const prevStepsText = steps
                         .filter(s => s.status === 'completed' && s.index < step.index)
@@ -1023,8 +1158,40 @@ class WorkflowEngine extends events_1.EventEmitter {
                         retryCount: step.attempts,
                         loopCount: step.loopCount,
                     };
-                    const result = await this.executeStep(step, fullPrompt, conversationId, opts, opts?.apiKey, wfContext);
+                    let activeImageDeliveryMode = initialImageDeliveryMode;
+                    let result = await this.executeStep(step, fullPrompt, conversationId, { ...opts, workerImageDeliveryMode: activeImageDeliveryMode }, opts?.apiKey, wfContext);
+                    const requestedImage = activeImageDeliveryMode === 'reference'
+                        ? parseImageEscalationRequest(result, opts?.storedAttachments)
+                        : null;
+                    if (requestedImage) {
+                        throwIfWorkflowAborted(opts?.abortSignal);
+                        this.emitProgress(workflowId, step, steps, 'step-progress', opts?.onProgress, `${step.agentName} requested the original image for ${step.description}`);
+                        activeImageDeliveryMode = 'inline';
+                        result = await this.executeStep(step, fullPrompt, conversationId, { ...opts, workerImageDeliveryMode: activeImageDeliveryMode }, opts?.apiKey, wfContext);
+                        const repeatedEscalation = parseImageEscalationRequest(result, opts?.storedAttachments);
+                        if (repeatedEscalation) {
+                            step.status = 'failed';
+                            step.result = result;
+                            step.error = `Worker requested image escalation again after the original image was already provided (${repeatedEscalation.id}).`;
+                            step.completedAt = Date.now();
+                            failed.add(step.index);
+                            this.emitProgress(workflowId, step, steps, 'step-failed', opts?.onProgress, undefined, opts?.onWorkerChunk);
+                            try {
+                                const execId = step._execId;
+                                if (execId)
+                                    data.updateStepExecution(execId, {
+                                        status: 'failed',
+                                        attempts: step.attempts,
+                                        error: step.error,
+                                        completedAt: new Date().toISOString().replace('T', ' ').replace('Z', ''),
+                                    });
+                            }
+                            catch { /* best effort */ }
+                            return;
+                        }
+                    }
                     if (opts?.isOrchestrated && opts.taskId) {
+                        throwIfWorkflowAborted(opts?.abortSignal);
                         const completedTodo = data.getTodoTask(opts.taskId, 'completed');
                         if (completedTodo) {
                             step._handoffPrompt = completedTodo.handoff_prompt || '';
@@ -1304,6 +1471,31 @@ class WorkflowEngine extends events_1.EventEmitter {
                     catch { /* best effort */ }
                 }
                 catch (err) {
+                    if (isWorkflowAbortError(err)) {
+                        step.status = 'skipped';
+                        step.error = 'Cancelled by user';
+                        step.completedAt = Date.now();
+                        for (const s of steps) {
+                            if (s.status === 'pending') {
+                                s.status = 'skipped';
+                                s.error = 'Cancelled by user';
+                            }
+                        }
+                        this.emitProgress(workflowId, step, steps, 'step-failed', opts?.onProgress, undefined, opts?.onWorkerChunk);
+                        try {
+                            const execId = step._execId;
+                            if (execId) {
+                                data.updateStepExecution(execId, {
+                                    status: 'failed',
+                                    attempts: step.attempts,
+                                    error: step.error,
+                                    completedAt: new Date().toISOString().replace('T', ' ').replace('Z', ''),
+                                });
+                            }
+                        }
+                        catch { /* best effort */ }
+                        return;
+                    }
                     const authLikeFailure = typeof err?.message === 'string'
                         && (err.message.startsWith('AUTH_REQUIRED:')
                             || /invalid_grant/i.test(err.message)
@@ -1364,14 +1556,40 @@ class WorkflowEngine extends events_1.EventEmitter {
                     }
                     step.attempts++;
                     step.error = err.message;
-                    if (typeof err?.message === 'string' && this.isTerminalProviderFailure(err.message)) {
+                    const providerLimitFailure = typeof err?.message === 'string'
+                        ? this.classifyProviderLimitFailure(err.message)
+                        : null;
+                    const terminalProviderFailure = typeof err?.message === 'string' && this.isTerminalProviderFailure(err.message);
+                    if (providerLimitFailure || terminalProviderFailure) {
                         step.status = 'failed';
+                        step.result = providerLimitFailure?.exactMessage || err.message;
+                        step.error = providerLimitFailure?.exactMessage || err.message;
                         step.completedAt = Date.now();
                         failed.add(step.index);
                         for (const s of steps) {
                             if (s.dependsOn.includes(step.index) && s.status === 'pending') {
                                 s.status = 'skipped';
-                                s.error = 'Stopped because a prior step failed with a provider/runtime error';
+                                s.error = providerLimitFailure
+                                    ? 'Stopped because a prior step hit a provider usage/rate limit'
+                                    : 'Stopped because a prior step failed with a provider/runtime error';
+                            }
+                        }
+                        if (opts?.taskId) {
+                            try {
+                                data.markTodoTaskRuntimeBlocked(opts.taskId, {
+                                    actor: { actorType: 'orchestrator', actorId: 'Workflow Engine' },
+                                    blockerSummary: providerLimitFailure?.exactMessage || String(err?.message || err),
+                                    checkedContext: providerLimitFailure
+                                        ? 'Provider returned a quota/rate-limit error during worker execution. The exact provider message is preserved verbatim.'
+                                        : 'Provider/runtime error during worker execution. The exact provider or PTY/app-server failure reason is preserved verbatim.',
+                                    userQuestion: providerLimitFailure
+                                        ? 'Fix the provider account limit or wait until the provider retry window resets, then resume this plan.'
+                                        : 'Fix the provider/runtime issue, then resume this plan.',
+                                    reasonCode: providerLimitFailure?.reasonCode || 'provider_runtime_error',
+                                });
+                            }
+                            catch (blockErr) {
+                                console.warn(`[workflow-engine] failed to mark TODO ${opts.taskId} blocked after provider/runtime failure: ${blockErr?.message || blockErr}`);
                             }
                         }
                         this.emitProgress(workflowId, step, steps, 'step-failed', opts?.onProgress, undefined, opts?.onWorkerChunk);
@@ -1382,6 +1600,7 @@ class WorkflowEngine extends events_1.EventEmitter {
                                     status: 'failed',
                                     attempts: step.attempts,
                                     error: step.error,
+                                    resultSummary: step.result?.slice(0, 200),
                                     completedAt: new Date().toISOString().replace('T', ' ').replace('Z', ''),
                                 });
                             }
@@ -1514,21 +1733,216 @@ class WorkflowEngine extends events_1.EventEmitter {
         const effectivePrompt = opts?.isOrchestrated && opts?.taskId
             ? `CURRENT TODO ID: ${opts.taskId}\nUse this TODO id when calling complete_worker_task or block_worker_task.\n\n${prompt}`
             : prompt;
-        const messages = [{ role: 'user', content: effectivePrompt }];
+        const workerImageDeliveryMode = opts?.workerImageDeliveryMode || 'inline';
+        const deferredImageReferenceBlock = workerImageDeliveryMode === 'reference'
+            ? buildDeferredImageReferenceBlock(opts?.storedAttachments)
+            : '';
+        if (deferredImageReferenceBlock) {
+            systemPrompt = [
+                systemPrompt,
+                '',
+                'If the user message includes an "Original Image Context Available" section and you truly need the original image, reply exactly with ESCALATE_IMAGE <id> and no other text.',
+            ].join('\n');
+        }
+        const promptWithDeferredImageNote = deferredImageReferenceBlock
+            ? `${effectivePrompt}\n\n${deferredImageReferenceBlock}`
+            : effectivePrompt;
+        // Build user message — include native images if the worker's provider supports them
+        const workerAttachments = opts?.storedAttachments;
+        const workerSupportsImages = activeRuntime.providerName === 'anthropic'
+            || activeRuntime.providerName === 'openai'
+            || activeRuntime.providerName === 'google'
+            || activeRuntime.providerName === 'codex-cli'
+            || activeRuntime.providerName === 'claude-cli';
+        let userContent = promptWithDeferredImageNote;
+        if (workerImageDeliveryMode === 'inline' && workerAttachments && workerAttachments.length > 0 && workerSupportsImages) {
+            const parts = [
+                { type: 'text', text: promptWithDeferredImageNote },
+            ];
+            for (const att of workerAttachments) {
+                if (att.storagePath && att.mimeType?.startsWith('image/')) {
+                    try {
+                        const imageData = fs_1.default.readFileSync(att.storagePath).toString('base64');
+                        parts.push({ type: 'image', mimeType: att.mimeType, data: imageData });
+                    }
+                    catch { /* file may not exist */ }
+                }
+            }
+            if (parts.length > 1)
+                userContent = parts;
+        }
+        const messages = [{ role: 'user', content: userContent }];
         const promptChars = effectivePrompt.length;
         const systemChars = systemPrompt.length;
         const isLocalCliSession = effectiveRuntimeMode === 'local_desktop'
             && (activeRuntime.providerName === 'claude-cli' || activeRuntime.providerName === 'codex-cli');
         const workflowCliSessionTransport = resolveWorkflowCliSessionTransport(activeRuntime.providerName, isLocalCliSession);
+        const cliSessionScopeKey = String(opts?.cliSessionScopeKey || '').trim() || null;
         const hasPersistentConversation = isLocalCliSession && !!conversationId;
         const cliSessionEpochPlan = hasPersistentConversation
-            ? (0, cli_session_epoch_1.selectCliSessionEpoch)(conversationId, step.agentId, activeRuntime.providerName)
-            : { existing: undefined, resumeSessionId: null, resetReason: null };
+            ? (0, cli_session_epoch_1.evaluateWarmSessionReuse)(conversationId, step.agentId, activeRuntime.providerName, undefined, cliSessionScopeKey)
+            : {
+                outcome: 'cold_start',
+                existing: undefined,
+                resumeSessionId: null,
+                resetReason: null,
+                topicId: null,
+            };
         let activeCliSessionId = cliSessionEpochPlan.resumeSessionId;
         const cliEpochStartedAt = cliSessionEpochPlan.resumeSessionId
             ? (cliSessionEpochPlan.existing?.epoch_started_at || (0, cli_session_epoch_1.localTimestamp)())
             : (0, cli_session_epoch_1.localTimestamp)();
-        const ptyConversationKey = buildWorkflowPtyConversationKey(conversationId, step, workflowContext);
+        const ptyConversationKey = buildWorkflowPtyConversationKey(conversationId, step, workflowContext, cliSessionScopeKey);
+        let cliEpochResetReason = cliSessionEpochPlan.resetReason;
+        // Resolve prompt context window early for session launch classification,
+        // cross-bot context injection, and bootstrap decisions.
+        const promptContextWindow = hasPersistentConversation
+            ? (0, context_window_1.getPromptContextWindow)(conversationId, 5, {
+                targetBotId: step.agentId,
+                targetBotName: step.agentName,
+            })
+            : { summary: null, turns: [], sourceConversationId: conversationId || '', carriedForward: false, mode: 'new_topic', allowBootstrap: false, lastCrossBotTurn: null };
+        // Session lifecycle logging — mirrors local-server.ts invariant plus
+        // structured telemetry events for diagnostics.
+        const sessionLaunchReason = cliSessionEpochPlan.resumeSessionId
+            ? 'resumed'
+            : promptContextWindow.mode === 'new_topic'
+                ? 'new_topic/no_context'
+                : cliSessionEpochPlan.resetReason
+                    ? cliSessionEpochPlan.resetReason
+                    : 'fresh_with_bootstrap';
+        console.info(`[workflow-engine] session_launch_reason=${sessionLaunchReason} agent=${step.agentName} provider=${activeRuntime.providerName} conversationId=${conversationId || '(none)'} resumeSessionId=${cliSessionEpochPlan.resumeSessionId || '(none)'} mode=${promptContextWindow.mode || 'unknown'} bootstrap=${!!promptContextWindow.allowBootstrap}`);
+        console.info(`[workflow-engine] cli_session_selected conversationId=${conversationId || '(none)'} botId=${step.agentId} provider=${activeRuntime.providerName} selectedSessionId=${cliSessionEpochPlan.resumeSessionId || '(none)'} resetReason=${cliSessionEpochPlan.resetReason || '(none)'}`);
+        if (workflowCliSessionTransport === 'codex-app-server'
+            && cliSessionEpochPlan.outcome === 'epoch_reset'
+            && cliSessionEpochPlan.resetReason === 'token_limit') {
+            console.info(`[workflow-engine] codex_thread_reset_token_limit conversationId=${conversationId || '(none)'} botId=${step.agentId} provider=${activeRuntime.providerName} previousSessionId=${cliSessionEpochPlan.existing?.session_id || '(none)'} topicId=${cliSessionEpochPlan.topicId || '(none)'}`);
+        }
+        if (cliSessionEpochPlan.resumeSessionId) {
+            console.info(`[workflow-engine] cli_session_resuming conversationId=${conversationId || '(none)'} botId=${step.agentId} provider=${activeRuntime.providerName} sessionId=${cliSessionEpochPlan.resumeSessionId}`);
+        }
+        else if (promptContextWindow.mode === 'new_topic') {
+            console.info(`[workflow-engine] cli_session_fresh_without_bootstrap_new_topic conversationId=${conversationId || '(none)'} botId=${step.agentId} provider=${activeRuntime.providerName}`);
+        }
+        else if (promptContextWindow.allowBootstrap) {
+            console.info(`[workflow-engine] cli_session_fresh_bootstrap_applied conversationId=${conversationId || '(none)'} botId=${step.agentId} provider=${activeRuntime.providerName}`);
+        }
+        else {
+            console.warn(`[workflow-engine] cli_session_fresh_without_bootstrap_unexpected conversationId=${conversationId || '(none)'} botId=${step.agentId} provider=${activeRuntime.providerName} mode=${promptContextWindow.mode || 'unknown'}`);
+        }
+        // For initial fresh sessions (not resumed) with existing context, write
+        // bootstrap history and inject cross-bot context into the user message.
+        // This ensures the invariant: fresh session for existing context = bootstrap required.
+        if (hasPersistentConversation
+            && !cliSessionEpochPlan.resumeSessionId
+            && promptContextWindow.allowBootstrap
+            && conversationId) {
+            const topicId = data.getPrimaryTopicIdForConversation(conversationId) || undefined;
+            const bootstrapHistoryFilePath = (0, cli_bootstrap_history_1.writeConversationBootstrapHistoryFile)({
+                conversationId,
+                topicId,
+                botId: step.agentId,
+                botName: step.agentName,
+            });
+            if (bootstrapHistoryFilePath) {
+                const bootstrapInstruction = [
+                    `Please read the history file at: ${bootstrapHistoryFilePath}`,
+                    'Use it for context only.',
+                    'There is no need to mention the file, its path, or that you loaded context unless the user explicitly asks about it.',
+                    'Then respond to the user request below.',
+                    '',
+                ].join('\n');
+                const currentUserContent = messages[0]?.content;
+                const currentText = typeof currentUserContent === 'string'
+                    ? currentUserContent
+                    : Array.isArray(currentUserContent)
+                        ? currentUserContent.filter((p) => p?.type === 'text').map((p) => p.text).join('\n')
+                        : String(currentUserContent || '');
+                messages[0] = { role: 'user', content: `${bootstrapInstruction}${currentText}` };
+            }
+        }
+        // Inject cross-bot context for fresh sessions (not resumed) when the
+        // previous turn was from a different bot. Do not rely on CLI session
+        // memory for cross-bot context.
+        if (hasPersistentConversation
+            && !cliSessionEpochPlan.resumeSessionId
+            && promptContextWindow.lastCrossBotTurn) {
+            const crossBotBlock = (0, context_window_1.formatCrossBotPreviousTurn)(promptContextWindow.lastCrossBotTurn);
+            const currentUserContent = messages[0]?.content;
+            if (typeof currentUserContent === 'string') {
+                messages[0] = { role: 'user', content: `${crossBotBlock}\n\n${currentUserContent}` };
+            }
+        }
+        // For resumed sessions, inject cross-bot context into the user message
+        // since the CLI session memory only has same-bot context.
+        if (hasPersistentConversation
+            && !!cliSessionEpochPlan.resumeSessionId
+            && promptContextWindow.lastCrossBotTurn) {
+            const crossBotBlock = (0, context_window_1.formatCrossBotPreviousTurn)(promptContextWindow.lastCrossBotTurn);
+            const currentUserContent = messages[0]?.content;
+            if (typeof currentUserContent === 'string') {
+                messages[0] = { role: 'user', content: `${crossBotBlock}\n\n${currentUserContent}` };
+            }
+        }
+        // Bootstrap fallback: when a resumed CLI session fails, rebuild the prompt
+        // with bootstrap context (running summary + last 5 turns) before retrying
+        // with a fresh session. Ensures prompt-building path and session runtime
+        // reality always agree.
+        let freshCliBootstrapFallbackApplied = false;
+        let freshCliBootstrapFileWritten = false;
+        const applyFreshCliBootstrapFallback = (reason) => {
+            if (freshCliBootstrapFallbackApplied)
+                return;
+            freshCliBootstrapFallbackApplied = true;
+            cliEpochResetReason = reason;
+            if (!conversationId)
+                return;
+            const topicId = data.getPrimaryTopicIdForConversation(conversationId) || undefined;
+            const freshPromptContextWindow = (0, context_window_1.getPromptContextWindow)(conversationId, 5, {
+                targetBotId: step.agentId,
+                targetBotName: step.agentName,
+            });
+            const bootstrapHistoryFilePath = freshPromptContextWindow.allowBootstrap
+                ? (0, cli_bootstrap_history_1.writeConversationBootstrapHistoryFile)({
+                    conversationId,
+                    topicId,
+                    botId: step.agentId,
+                    botName: step.agentName,
+                })
+                : null;
+            freshCliBootstrapFileWritten = !!bootstrapHistoryFilePath;
+            if (bootstrapHistoryFilePath) {
+                const bootstrapInstruction = [
+                    `Please read the history file at: ${bootstrapHistoryFilePath}`,
+                    'Use it for context only.',
+                    'There is no need to mention the file, its path, or that you loaded context unless the user explicitly asks about it.',
+                    'Then respond to the user request below.',
+                    '',
+                ].join('\n');
+                const currentUserContent = messages[0]?.content;
+                const currentText = typeof currentUserContent === 'string'
+                    ? currentUserContent
+                    : Array.isArray(currentUserContent)
+                        ? currentUserContent.filter((p) => p?.type === 'text').map((p) => p.text).join('\n')
+                        : String(currentUserContent || '');
+                messages[0] = { role: 'user', content: `${bootstrapInstruction}${currentText}` };
+            }
+            if (freshPromptContextWindow.lastCrossBotTurn) {
+                const crossBotBlock = (0, context_window_1.formatCrossBotPreviousTurn)(freshPromptContextWindow.lastCrossBotTurn);
+                const currentUserContent = messages[0]?.content;
+                if (typeof currentUserContent === 'string') {
+                    messages[0] = { role: 'user', content: `${crossBotBlock}\n\n${currentUserContent}` };
+                }
+            }
+            console.info(`[workflow-engine] session_launch_reason=resume_failed agent=${step.agentName} provider=${activeRuntime.providerName} conversationId=${conversationId} bootstrap=${!!bootstrapHistoryFilePath}`);
+            console.warn(`[workflow-engine] cli_session_resume_failed conversationId=${conversationId || '(none)'} botId=${step.agentId} provider=${activeRuntime.providerName} bootstrap=${!!bootstrapHistoryFilePath}`);
+            if (bootstrapHistoryFilePath) {
+                console.info(`[workflow-engine] cli_session_fresh_bootstrap_applied conversationId=${conversationId || '(none)'} botId=${step.agentId} provider=${activeRuntime.providerName} bootstrapReason=resume_failed`);
+            }
+            else {
+                console.warn(`[workflow-engine] cli_session_fresh_without_bootstrap_unexpected conversationId=${conversationId || '(none)'} botId=${step.agentId} provider=${activeRuntime.providerName} bootstrapReason=resume_failed`);
+            }
+        };
         console.info(`[workflow-engine] step runtime: agent=${step.agentName} provider=${activeRuntime.providerName} model=${activeRuntime.model} runtime=${activeRuntime.runtimeLabel || 'unknown'} promptChars=${promptChars} systemChars=${systemChars} tools=${opts?.disableTools ? 0 : toolDefs.length}`);
         // Agentic loop
         let iteration = 0;
@@ -1536,6 +1950,7 @@ class WorkflowEngine extends events_1.EventEmitter {
         let incompleteExecutionRecoveries = 0;
         let selectedRuntimeRetryCount = 0;
         while (iteration < MAX_ITERATIONS) {
+            throwIfWorkflowAborted(opts?.abortSignal);
             if (opts?.isOrchestrated && this.orchestratedTodoHandled(opts.taskId)) {
                 return this.buildOrchestratedTodoHandledResult(opts.taskId);
             }
@@ -1559,8 +1974,10 @@ class WorkflowEngine extends events_1.EventEmitter {
                     const codexAppServerManager = (0, codex_app_server_manager_1.getCodexAppServerManager)();
                     let appServerAttempt = 0;
                     while (true) {
+                        throwIfWorkflowAborted(opts?.abortSignal);
                         appServerAttempt++;
                         try {
+                            console.info(`[workflow-engine] codex_app_server_turn_start workflow=${workflowContext?.workflowId || '(none)'} step=${workflowContext?.stepIndex ?? 0} agent=${step.agentName} conversationId=${ptyConversationKey} taskId=${opts?.taskId ?? '(none)'} attempt=${appServerAttempt}`);
                             const appServerResult = await codexAppServerManager.runTurn({
                                 runtimeMode: 'local_desktop',
                                 conversationId: ptyConversationKey,
@@ -1569,7 +1986,8 @@ class WorkflowEngine extends events_1.EventEmitter {
                                 cwd: effectiveProjectDir,
                                 systemPrompt,
                                 messages,
-                                forceFreshSession: !hasPersistentConversation || (iteration === 1 && !cliSessionEpochPlan.resumeSessionId),
+                                abortSignal: opts?.abortSignal,
+                                forceFreshSession: !hasPersistentConversation || (iteration === 1 && !codexAppServerManager.hasActiveSession(ptyConversationKey, step.agentId) && !cliSessionEpochPlan.resumeSessionId),
                                 resumeSessionId: cliSessionEpochPlan.resumeSessionId || undefined,
                                 model: activeRuntime.model,
                                 projectId: opts?.projectId ?? null,
@@ -1604,10 +2022,61 @@ class WorkflowEngine extends events_1.EventEmitter {
                                         : [step];
                                     this.emitProgress(workflowContext?.workflowId || 'workflow', step, activeSteps, 'step-progress', opts?.onProgress, `${step.agentName} is still working on ${step.description}`);
                                 },
+                                // Forward Codex app-server tool/file events as worker_terminal_chunk-style detail lines.
+                                // This populates the worker child card details panel for Codex workers.
+                                onDetail: async (detail) => {
+                                    if (!detail || !opts?.onWorkerChunk)
+                                        return;
+                                    opts.onWorkerChunk({
+                                        type: 'worker_terminal_chunk',
+                                        stepId: step.id,
+                                        agentName: step.agentName,
+                                        description: step.description,
+                                        stepIndex: workflowContext?.stepIndex ?? 0,
+                                        totalSteps: workflowContext?.totalSteps ?? 1,
+                                        rawText: detail,
+                                    });
+                                },
+                                // Forward structured tool call/result events from Codex app-server
+                                // (command_execution, file_change, mcpToolCall items) as
+                                // worker_tool_call / worker_tool_result events. This gives Codex
+                                // workers the same structured tool visibility as API-key workers.
+                                onToolEvent: async (event) => {
+                                    if (!opts?.onWorkerChunk)
+                                        return;
+                                    if (event.kind === 'call') {
+                                        opts.onWorkerChunk({
+                                            type: opts?.isOrchestrated ? 'worker_tool_call' : 'tool_call',
+                                            stepId: step.id,
+                                            agentName: step.agentName,
+                                            description: step.description,
+                                            stepIndex: workflowContext?.stepIndex ?? 0,
+                                            totalSteps: workflowContext?.totalSteps ?? 1,
+                                            toolCallId: event.toolCallId,
+                                            toolName: event.toolName,
+                                            toolArguments: event.arguments,
+                                        });
+                                    }
+                                    else {
+                                        opts.onWorkerChunk({
+                                            type: opts?.isOrchestrated ? 'worker_tool_result' : 'tool_result',
+                                            stepId: step.id,
+                                            agentName: step.agentName,
+                                            description: step.description,
+                                            stepIndex: workflowContext?.stepIndex ?? 0,
+                                            totalSteps: workflowContext?.totalSteps ?? 1,
+                                            toolCallId: event.toolCallId,
+                                            toolName: event.toolName,
+                                            toolOutput: event.output,
+                                            toolIsError: event.isError,
+                                        });
+                                    }
+                                },
                             });
                             if (appServerResult.sessionId) {
                                 activeCliSessionId = appServerResult.sessionId;
                             }
+                            console.info(`[workflow-engine] codex_app_server_turn_done workflow=${workflowContext?.workflowId || '(none)'} step=${workflowContext?.stepIndex ?? 0} agent=${step.agentName} conversationId=${ptyConversationKey} taskId=${opts?.taskId ?? '(none)'} contentChars=${String(appServerResult.content || '').length}`);
                             response = {
                                 content: appServerResult.content || '',
                                 usage: appServerResult.usage,
@@ -1615,13 +2084,20 @@ class WorkflowEngine extends events_1.EventEmitter {
                             break;
                         }
                         catch (appServerErr) {
-                            codexAppServerManager.closeSessionByConversation(ptyConversationKey, step.agentId);
+                            console.error(`[workflow-engine] codex_app_server_turn_error workflow=${workflowContext?.workflowId || '(none)'} step=${workflowContext?.stepIndex ?? 0} agent=${step.agentName} conversationId=${ptyConversationKey} taskId=${opts?.taskId ?? '(none)'} attempt=${appServerAttempt}: ${appServerErr?.stack || appServerErr?.message || String(appServerErr)}`);
+                            if (!isWorkflowAbortError(appServerErr)) {
+                                clearFailedWorkflowCliSessionEpoch(conversationId, step.agentId, activeCliSessionId || cliSessionEpochPlan.resumeSessionId, cliSessionScopeKey);
+                                codexAppServerManager.closeSessionByConversation(ptyConversationKey, step.agentId);
+                            }
                             if (appServerAttempt >= LOCAL_WORKFLOW_RUNTIME_RETRY_LIMIT
                                 || !shouldRetrySelectedWorkflowRuntime(appServerErr)) {
                                 throw appServerErr;
                             }
-                            console.warn(`[workflow-engine] ${step.agentName} selected runtime failed, retrying the same connection (${appServerAttempt + 1}/${LOCAL_WORKFLOW_RUNTIME_RETRY_LIMIT})`);
-                            await pauseWorkflowRuntimeRetry(appServerAttempt);
+                            if (cliSessionEpochPlan.resumeSessionId) {
+                                applyFreshCliBootstrapFallback('resume_failed');
+                            }
+                            console.warn(`[workflow-engine] ${step.agentName} selected runtime failed, retrying with a fresh session (${appServerAttempt + 1}/${LOCAL_WORKFLOW_RUNTIME_RETRY_LIMIT})`);
+                            await pauseWorkflowRuntimeRetry(appServerAttempt, opts?.abortSignal);
                         }
                     }
                 }
@@ -1631,17 +2107,46 @@ class WorkflowEngine extends events_1.EventEmitter {
                     }
                     const ptyManager = (0, local_cli_pty_manager_1.getLocalCliPtySessionManager)();
                     let ptyAttempt = 0;
+                    let forceFreshInteractiveCliSession = false;
+                    let currentAttemptSessionId = null;
+                    let currentAttemptWasFreshSession = false;
                     while (true) {
+                        throwIfWorkflowAborted(opts?.abortSignal);
                         ptyAttempt++;
                         try {
+                            const hasLivePtySession = ptyManager.hasActiveSession(ptyConversationKey, step.agentId);
+                            const isFreshSession = forceFreshInteractiveCliSession
+                                || !hasPersistentConversation
+                                || (iteration === 1 && !hasLivePtySession && !cliSessionEpochPlan.resumeSessionId);
+                            const newSessionId = activeRuntime.providerName === 'claude-cli' && isFreshSession
+                                ? data.generateNextSessionId()
+                                : undefined;
+                            currentAttemptWasFreshSession = isFreshSession;
+                            currentAttemptSessionId = newSessionId || cliSessionEpochPlan.resumeSessionId || activeCliSessionId || null;
                             const ptyResult = await ptyManager.runTurn({
                                 conversationId: ptyConversationKey,
                                 botId: step.agentId,
                                 provider: 'claude-cli',
+                                botSettings: {
+                                    claude: {
+                                        model: activeRuntime.model,
+                                        effortLevel: profile?.claude_effort_level,
+                                        outputStyle: profile?.claude_output_style,
+                                        fastMode: profile?.claude_fast_mode === 1,
+                                        permissionsJson: profile?.claude_permissions_json,
+                                    },
+                                },
                                 cwd: effectiveProjectDir,
+                                toolActorId: step.agentName,
+                                toolProjectId: opts?.projectId ?? null,
+                                currentTodoTaskId: opts?.taskId,
+                                useConpty: shouldUseConptyForWorkflowClaudePty(),
                                 systemPrompt,
                                 messages,
-                                forceFreshSession: !hasPersistentConversation || (iteration === 1 && !cliSessionEpochPlan.resumeSessionId),
+                                abortSignal: opts?.abortSignal,
+                                forceFreshSession: isFreshSession,
+                                resumeSessionId: isFreshSession ? undefined : (cliSessionEpochPlan.resumeSessionId || undefined),
+                                newSessionId,
                                 onRawChunk: async (chunk) => {
                                     if (opts?.onWorkerChunk) {
                                         opts.onWorkerChunk({
@@ -1655,6 +2160,93 @@ class WorkflowEngine extends events_1.EventEmitter {
                                         });
                                     }
                                 },
+                                // Forward Claude PTY tool_use detail markers as worker_terminal_chunk
+                                // detail lines so they appear in the worker child card details panel.
+                                // Also detect __ACTIVITY__ markers and emit structured worker_tool_call
+                                // events so PTY workers get the same tool visibility as API-key workers.
+                                onDetail: async (detail) => {
+                                    if (!detail || !opts?.onWorkerChunk)
+                                        return;
+                                    // Always forward as terminal chunk for textual details panel.
+                                    opts.onWorkerChunk({
+                                        type: 'worker_terminal_chunk',
+                                        stepId: step.id,
+                                        agentName: step.agentName,
+                                        description: step.description,
+                                        stepIndex: workflowContext?.stepIndex ?? 0,
+                                        totalSteps: workflowContext?.totalSteps ?? 1,
+                                        rawText: detail,
+                                    });
+                                    // Detect __ACTIVITY__<JSON> markers from PTY parser and translate
+                                    // tool activities into structured worker_tool_call / worker_tool_result events.
+                                    if (detail.startsWith('__ACTIVITY__')) {
+                                        try {
+                                            const json = detail.slice('__ACTIVITY__'.length);
+                                            const activity = JSON.parse(json);
+                                            if (!activity || typeof activity !== 'object')
+                                                return;
+                                            if (activity.type === 'tool_call' && typeof activity.label === 'string') {
+                                                // Every tool_use block from the Claude PTY parser
+                                                opts.onWorkerChunk({
+                                                    type: opts?.isOrchestrated ? 'worker_tool_call' : 'tool_call',
+                                                    stepId: step.id,
+                                                    agentName: step.agentName,
+                                                    description: step.description,
+                                                    stepIndex: workflowContext?.stepIndex ?? 0,
+                                                    totalSteps: workflowContext?.totalSteps ?? 1,
+                                                    toolCallId: typeof activity.key === 'string' ? activity.key : `claude-tool-${Date.now()}`,
+                                                    toolName: activity.label,
+                                                    toolArguments: undefined,
+                                                });
+                                            }
+                                            else if (activity.type === 'tool_result' && typeof activity.label === 'string') {
+                                                // Result block from the Claude PTY parser
+                                                opts.onWorkerChunk({
+                                                    type: opts?.isOrchestrated ? 'worker_tool_result' : 'tool_result',
+                                                    stepId: step.id,
+                                                    agentName: step.agentName,
+                                                    description: step.description,
+                                                    stepIndex: workflowContext?.stepIndex ?? 0,
+                                                    totalSteps: workflowContext?.totalSteps ?? 1,
+                                                    toolCallId: typeof activity.key === 'string' ? activity.key : `claude-tool-result-${Date.now()}`,
+                                                    toolName: 'tool',
+                                                    toolOutput: activity.label,
+                                                    toolIsError: !!activity.isError,
+                                                });
+                                            }
+                                            else if (activity.type === 'working' && typeof activity.label === 'string') {
+                                                // Legacy 'working' activities (sub-agent updates from child files)
+                                                opts.onWorkerChunk({
+                                                    type: opts?.isOrchestrated ? 'worker_tool_call' : 'tool_call',
+                                                    stepId: step.id,
+                                                    agentName: step.agentName,
+                                                    description: step.description,
+                                                    stepIndex: workflowContext?.stepIndex ?? 0,
+                                                    totalSteps: workflowContext?.totalSteps ?? 1,
+                                                    toolCallId: typeof activity.key === 'string' ? activity.key : `claude-tool-${Date.now()}`,
+                                                    toolName: activity.label,
+                                                    toolArguments: undefined,
+                                                });
+                                            }
+                                            else if (activity.type === 'subagent_started' && typeof activity.label === 'string') {
+                                                opts.onWorkerChunk({
+                                                    type: opts?.isOrchestrated ? 'worker_tool_call' : 'tool_call',
+                                                    stepId: step.id,
+                                                    agentName: step.agentName,
+                                                    description: step.description,
+                                                    stepIndex: workflowContext?.stepIndex ?? 0,
+                                                    totalSteps: workflowContext?.totalSteps ?? 1,
+                                                    toolCallId: typeof activity.key === 'string' ? activity.key : `claude-agent-${Date.now()}`,
+                                                    toolName: 'Agent',
+                                                    toolArguments: { description: activity.label },
+                                                });
+                                            }
+                                        }
+                                        catch {
+                                            // malformed __ACTIVITY__ marker — ignore
+                                        }
+                                    }
+                                },
                                 onChunk: async (chunk) => {
                                     streamedContent += chunk;
                                     if (opts?.onWorkerChunk) {
@@ -1688,12 +2280,41 @@ class WorkflowEngine extends events_1.EventEmitter {
                             break;
                         }
                         catch (ptyErr) {
+                            if (isWorkflowAbortError(ptyErr)) {
+                                throw ptyErr;
+                            }
+                            const startupRetry = isClaudeFreshWorkflowSessionStartupFailure(ptyErr);
+                            if (startupRetry || currentAttemptWasFreshSession || cliSessionEpochPlan.resumeSessionId) {
+                                ptyManager.logSessionFailureByConversation(ptyConversationKey, step.agentId, startupRetry
+                                    ? 'workflow_fresh_session_startup_failure_before_kill'
+                                    : currentAttemptWasFreshSession
+                                        ? 'workflow_fresh_session_failure_before_kill'
+                                        : 'workflow_resume_session_failure_before_kill', ptyErr);
+                            }
+                            clearFailedWorkflowCliSessionEpoch(conversationId, step.agentId, currentAttemptSessionId || activeCliSessionId || cliSessionEpochPlan.resumeSessionId, cliSessionScopeKey);
+                            if (startupRetry || currentAttemptWasFreshSession) {
+                                forceFreshInteractiveCliSession = true;
+                                ptyManager.closeSessionByConversation(ptyConversationKey, step.agentId);
+                            }
+                            const resumeFailureFallback = !!cliSessionEpochPlan.resumeSessionId && !currentAttemptWasFreshSession;
+                            if (resumeFailureFallback) {
+                                forceFreshInteractiveCliSession = true;
+                                applyFreshCliBootstrapFallback('resume_failed');
+                                ptyManager.closeSessionByConversation(ptyConversationKey, step.agentId);
+                            }
                             if (ptyAttempt >= LOCAL_WORKFLOW_RUNTIME_RETRY_LIMIT
                                 || !shouldRetrySelectedWorkflowRuntime(ptyErr)) {
                                 throw ptyErr;
                             }
-                            console.warn(`[workflow-engine] ${step.agentName} selected runtime failed, retrying the same connection (${ptyAttempt + 1}/${LOCAL_WORKFLOW_RUNTIME_RETRY_LIMIT})`);
-                            await pauseWorkflowRuntimeRetry(ptyAttempt);
+                            const retryDetail = startupRetry
+                                ? `[workflow-engine] Fresh ${activeRuntime.providerName} session ${currentAttemptSessionId || '(unknown)'} did not finish startup before the transcript became available; killing it and retrying with a new session (${ptyAttempt + 1}/${LOCAL_WORKFLOW_RUNTIME_RETRY_LIMIT})`
+                                : resumeFailureFallback
+                                    ? `[workflow-engine] Stored ${activeRuntime.providerName} session ${currentAttemptSessionId || '(unknown)'} failed to resume (${ptyErr?.message || ptyErr}); retrying with a fresh bootstrapped session (${ptyAttempt + 1}/${LOCAL_WORKFLOW_RUNTIME_RETRY_LIMIT})`
+                                    : currentAttemptWasFreshSession
+                                        ? `[workflow-engine] Fresh ${activeRuntime.providerName} session ${currentAttemptSessionId || '(unknown)'} failed (${ptyErr?.message || ptyErr}); killing it and retrying with a new session (${ptyAttempt + 1}/${LOCAL_WORKFLOW_RUNTIME_RETRY_LIMIT})`
+                                        : `[workflow-engine] ${step.agentName} selected runtime failed (${ptyErr?.message || ptyErr}), retrying the same connection (${ptyAttempt + 1}/${LOCAL_WORKFLOW_RUNTIME_RETRY_LIMIT})`;
+                            console.warn(retryDetail);
+                            await pauseWorkflowRuntimeRetry(ptyAttempt, opts?.abortSignal);
                         }
                     }
                 }
@@ -1740,6 +2361,7 @@ class WorkflowEngine extends events_1.EventEmitter {
                         },
                         tools: opts?.disableTools ? undefined : toolDefs,
                         cwd: effectiveProjectDir,
+                        abortSignal: opts?.abortSignal,
                     });
                     // Flush remaining chunk buffer
                     if (opts?.onWorkerChunk && chunkBuffer) {
@@ -1764,7 +2386,7 @@ class WorkflowEngine extends events_1.EventEmitter {
                     && shouldRetrySelectedWorkflowRuntime(err)) {
                     selectedRuntimeRetryCount++;
                     console.warn(`[workflow-engine] ${step.agentName} selected runtime failed, retrying the same connection (${selectedRuntimeRetryCount + 1}/${LOCAL_WORKFLOW_RUNTIME_RETRY_LIMIT})`);
-                    await pauseWorkflowRuntimeRetry(selectedRuntimeRetryCount);
+                    await pauseWorkflowRuntimeRetry(selectedRuntimeRetryCount, opts?.abortSignal);
                     iteration--;
                     continue;
                 }
@@ -1792,29 +2414,43 @@ class WorkflowEngine extends events_1.EventEmitter {
                 throw err;
             }
             if (hasPersistentConversation && activeCliSessionId && !response.toolCalls?.length) {
+                if (cliSessionEpochPlan.resumeSessionId && !freshCliBootstrapFallbackApplied) {
+                    console.info(`[workflow-engine] cli_session_resume_succeeded conversationId=${conversationId} botId=${step.agentId} provider=${activeRuntime.providerName} sessionId=${activeCliSessionId}`);
+                }
+                const usedBootstrap = freshCliBootstrapFileWritten
+                    || (!cliSessionEpochPlan.resumeSessionId && !!promptContextWindow.allowBootstrap);
+                const bootstrapReason = freshCliBootstrapFileWritten
+                    ? 'resume_failed'
+                    : (!cliSessionEpochPlan.resumeSessionId && !!promptContextWindow.allowBootstrap)
+                        ? 'fresh_with_context'
+                        : null;
+                console.info(`[workflow-engine] cli_turn_telemetry conversationId=${conversationId || '(none)'} botId=${step.agentId} provider=${activeRuntime.providerName} selectedSessionId=${cliSessionEpochPlan.resumeSessionId || '(none)'} actualSessionId=${activeCliSessionId} promptContextMode=${promptContextWindow.mode || 'unknown'} usedBootstrap=${usedBootstrap} bootstrapReason=${bootstrapReason || '(none)'} resetReason=${cliEpochResetReason || '(none)'}`);
                 const nextEpochTurnCount = cliSessionEpochPlan.resumeSessionId
                     ? ((cliSessionEpochPlan.existing?.epoch_turn_count || 0) + 1)
                     : 1;
                 data.upsertCliSessionEpoch({
                     conversationId: conversationId,
+                    sessionScopeKey: cliSessionScopeKey,
                     botId: step.agentId,
                     provider: activeRuntime.providerName,
                     sessionId: activeCliSessionId,
                     epochTurnCount: nextEpochTurnCount,
                     lastInputTokens: response.usage?.inputTokens ?? null,
                     lastOutputTokens: response.usage?.outputTokens ?? null,
-                    resetReason: cliSessionEpochPlan.resetReason,
+                    resetReason: cliEpochResetReason,
                     epochStartedAt: cliEpochStartedAt,
                     lastUsedAt: (0, cli_session_epoch_1.localTimestamp)(),
                 });
             }
             if (response.toolCalls && response.toolCalls.length > 0) {
+                throwIfWorkflowAborted(opts?.abortSignal);
                 messages.push({
                     role: 'assistant',
                     content: response.content || '',
                     toolCalls: response.toolCalls,
                 });
                 for (const tc of response.toolCalls) {
+                    throwIfWorkflowAborted(opts?.abortSignal);
                     const permMode = unrestrictedCliProvider
                         ? 'autopilot'
                         : (profile?.permission_mode || 'autopilot');
@@ -1838,6 +2474,7 @@ class WorkflowEngine extends events_1.EventEmitter {
                     }
                     const result = await (0, index_2.executeAndVerify)({ id: tc.id, name: tc.name, arguments: tc.arguments }, toolCtx);
                     const output = result.success ? result.output : `ERROR: ${result.error || 'Unknown'}`;
+                    throwIfWorkflowAborted(opts?.abortSignal);
                     messages.push({ role: 'tool', content: output, toolCallId: tc.id, toolName: tc.name });
                     // Emit tool_result event
                     if (opts?.onWorkerChunk) {
@@ -2291,15 +2928,38 @@ class WorkflowEngine extends events_1.EventEmitter {
         return count >= ERROR_LOOP_THRESHOLD;
     }
     isTerminalProviderFailure(errorMessage) {
+        const normalized = String(errorMessage || '').toLowerCase();
+        return Boolean(this.classifyProviderLimitFailure(errorMessage))
+            || this.isProviderAuthFailure(errorMessage)
+            || /\b(pty session|app-server|fresh session startup timed out|transcript file|no meaningful pty activity|session exited while waiting|failed to resume|session closed during active turn)\b/i.test(normalized);
+    }
+    isProviderAuthFailure(errorMessage) {
         const normalized = errorMessage.toLowerCase();
-        return normalized.includes('api error 429')
+        return normalized.includes('refresh_token_reused')
+            || normalized.includes('invalid_grant')
+            || normalized.includes('oauth token refresh failed');
+    }
+    classifyProviderLimitFailure(errorMessage) {
+        const exactMessage = String(errorMessage || '').trim();
+        const normalized = exactMessage.toLowerCase();
+        if (!exactMessage)
+            return null;
+        if (normalized.includes('rate limit')
             || normalized.includes('rate limited')
+            || normalized.includes('api error 429')
+            || normalized.includes('current session limit')) {
+            return { reasonCode: 'provider_rate_limit', exactMessage };
+        }
+        if (normalized.includes("you've hit your org's monthly usage limit")
+            || normalized.includes('monthly usage limit')
+            || normalized.includes('usage limit reached')
+            || normalized.includes('quota exceeded')
             || normalized.includes('exceeded your current quota')
             || normalized.includes('insufficient_quota')
-            || normalized.includes('billing details')
-            || normalized.includes('refresh_token_reused')
-            || normalized.includes('invalid_grant')
-            || normalized.includes('oauth token refresh failed');
+            || normalized.includes('billing details')) {
+            return { reasonCode: 'provider_quota_limit', exactMessage };
+        }
+        return null;
     }
     /**
      * Replan remaining work when retries are exhausted.