vigthoria-cli 1.13.18 → 1.13.22

package/dist/commands/chat.js

@@ -3,27 +3,36 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as readline from 'readline';
+import { randomUUID } from 'crypto';
 import { createSpinner } from '../utils/logger.js';
-import { APIClient, CLIError, classifyError, formatCLIError, sanitizeUserFacingErrorText, sanitizeUserFacingPathText, propagateError, VIGTHORIA_SERVER_TEMPORARILY_UNAVAILABLE_MESSAGE } from '../utils/api.js';
+import { CLIError, classifyError, formatCLIError, sanitizeUserFacingErrorText, sanitizeUserFacingPathText, propagateError, VIGTHORIA_SERVER_TEMPORARILY_UNAVAILABLE_MESSAGE } from '../utils/api.js';
+import { createAPIClient } from '../utils/api-client-factory.js';
 import { AgenticTools, robustifyStreamResponse } from '../utils/tools.js';
-import { SessionManager } from '../utils/session.js';
+import { SessionManager, assertAgentStatusTransition } from '../utils/session.js';
 import { BridgeClient, getBridgeClient } from '../utils/bridge-client.js';
 import { WorkspaceWatcher } from '../utils/workspace-stream.js';
 import { TaskDisplay } from '../utils/task-display.js';
 import { ProjectMemoryService } from '../utils/project-memory.js';
 import { WorkspaceBrainService } from '../utils/workspace-brain-service.js';
+import { assembleContextState, contextLayer } from '../utils/context-state.js';
 import { buildPersonaOverlay, normalizePersonaMode } from '../utils/persona.js';
 import { runAgentSessionMenu, shouldShowAgentSessionMenu } from './agent-session-menu.js';
 import { V4Command } from './v4.js';
 import { renderDynamicHelp } from '../utils/command-menu.js';
-import { createLiveOutcome, evaluateExecutorSuccess, handleTaskEvent, isSubstantiveAgentAnswer, isToolEvidenceStubAnswer, normalizeAgentAnswerContent, noteAnalysisToolUse, } from '../utils/agentRunOutcome.js';
+import { resolvePromptWorkspace } from '../utils/prompt-workspace-resolver.js';
+import { isDirectModeFollowUpQuestion, sanitizeDirectModeOutput, stripHiddenThoughtBlocks } from '../utils/direct-output-policy.js';
+import { createLiveOutcome, evaluateExecutorSuccess, handleRunCompleteEvent, handleTaskEvent, isSubstantiveAgentAnswer, isToolEvidenceStubAnswer, normalizeAgentAnswerContent, noteAnalysisToolUse, } from '../utils/agentRunOutcome.js';
 import { looksLikeMarkdownReport, renderMarkdownToTerminal, summarizeMarkdownReport, } from '../utils/terminalMarkdown.js';
 import { emitDeckEvent, isDeckModeEnabled } from '../utils/deckEvents.js';
 import { formatGoaSystemGrounding, splitGoaContextFromInput, } from '../utils/goaEvents.js';
-import { inferAgentTaskType as sharedInferAgentTaskType, inferAgentTaskTypeWithContext, isTrivialHtmlPageRequest, resolvePlannerAgentTimeoutMs, resolveWorkflowType, shouldSkipAnalysisRescue, taskRequiresWorkspaceChanges as promptRequiresWorkspaceChanges, taskRequiresWorkspaceChangesWithContext, buildExecutionHints, isAgentContinuePrompt, isAgentRetryPrompt, isBuiltContinuePrompt, isBuiltRetryPrompt, isBuiltWriteConfirmationPrompt, isConfirmationFollowUp, isWritePermissionGrant, } from '../utils/requestIntent.js';
+import { inferAgentTaskTypeWithContext, resolvePlannerAgentTimeoutMs, resolveWorkflowType, shouldSkipAnalysisRescue, taskRequiresWorkspaceChanges as promptRequiresWorkspaceChanges, taskRequiresWorkspaceChangesWithContext, buildExecutionHints, isAgentContinuePrompt, isAgentRetryPrompt, isBuiltContinuePrompt, isBuiltRetryPrompt, isBuiltWriteConfirmationPrompt, isConfirmationFollowUp, isWritePermissionGrant, } from '../utils/requestIntent.js';
 import { resolveAgentRoute } from '../utils/agentRoute.js';
-import { runTemplateInstantPath } from '../utils/templateInstantPath.js';
 import { isV3StreamKeepaliveEvent } from '../utils/v3-stream-events.js';
+import { resolveAutoApproval } from '../utils/process-policy.js';
+import { ChatToolCallParser } from '../utils/chat-tool-call-parser.js';
+import { ChatPromptPolicy } from '../utils/chat-prompt-policy.js';
+import { AgentStreamState } from '../utils/agent-stream-state.js';
+import { CliCommandError, commandFailure, commandNameFromArgv, failureEnvelope, normalizeCommandError, successEnvelope, } from '../utils/command-contract.js';
 // Stream health policy (corrected 2026-07-04 after TestFarm incident with
 // Gideon Lenz / C:\vigthoria\Apps\monopoly): agentic tasks have no
 // predictable duration, so there is intentionally NO overall wall-clock
@@ -62,7 +71,46 @@ const DEFAULT_V3_AGENT_SOFT_TIMEOUT_MS = (() => {
 })();
 /** Block-write agent JSON to VIGTHORIA_AGENT_OUTPUT (Windows KVM fsync path). */
 function emitAgentJsonOutput(payload) {
-    const text = `${JSON.stringify(payload, null, 2)}\n`;
+    const command = commandNameFromArgv(process.argv);
+    const record = payload && typeof payload === 'object' && !Array.isArray(payload)
+        ? { ...payload }
+        : { value: payload };
+    const succeeded = record.success !== false;
+    delete record.success;
+    let envelope;
+    if (succeeded) {
+        const metadata = record.metadata && typeof record.metadata === 'object' && !Array.isArray(record.metadata)
+            ? record.metadata
+            : {};
+        const warnings = Array.isArray(record.warnings)
+            ? record.warnings.filter((warning) => typeof warning === 'string')
+            : [];
+        delete record.metadata;
+        delete record.warnings;
+        envelope = successEnvelope(command, record, metadata, warnings);
+    }
+    else {
+        const message = typeof record.error === 'string' && record.error.trim()
+            ? record.error
+            : 'Agent execution failed.';
+        const category = record.errorCategory === 'auth'
+            ? 'authentication'
+            : record.errorCategory === 'network' || record.errorCategory === 'timeout'
+                ? 'network'
+                : 'execution';
+        const partialMutation = record.partialMutation === true || record.partialMutation === 'unknown' || record.partial === true
+            ? 'unknown'
+            : false;
+        delete record.error;
+        delete record.errorCategory;
+        envelope = failureEnvelope(command, normalizeCommandError(new CliCommandError(message, {
+            code: command === 'operator' ? 'OPERATOR_EXECUTION_FAILED' : command === 'agent' ? 'AGENT_EXECUTION_FAILED' : 'CHAT_EXECUTION_FAILED',
+            category: partialMutation === 'unknown' ? 'partial_mutation' : category,
+            partialMutation,
+            details: record,
+        })));
+    }
+    const text = `${JSON.stringify(envelope, null, 2)}\n`;
     console.log(text.trimEnd());
     const outPath = process.env.VIGTHORIA_AGENT_OUTPUT?.trim();
     if (!outPath) {
@@ -99,6 +147,8 @@ export class ChatCommand {
     modelExplicitlySelected = false;
     autoApprove = false;
     personaOverride = null;
+    toolCallParser = new ChatToolCallParser();
+    promptPolicy;
     // Phase 5: Agent quality gate — track tool usage for evidence thresholds
     agentToolEvidence = { discovery: 0, mutation: 0, searchFailed: 0 };
     operatorMode = false;
@@ -108,12 +158,7 @@ export class ChatCommand {
     modelGovernanceFallback = null;
     retryPromptSignature = null;
     retryPromptStreak = 0;
-    v3SuppressThinkingStream = false;
-    v3StreamedAnswerBuffer = '';
-    v3StreamedAnswerDisplayed = false;
-    v3SeenToolCalls = new Set();
-    v3SeenToolResults = new Set();
-    v3StartSeen = false;
+    streamState;
     lastAgentRoute = null;
     pendingGoaContext = null;
     // Last completed Agent run — used by /retry, /continue, and the final summary block.
@@ -372,16 +417,6 @@ export class ChatCommand {
                 routeReason: 'dispatcher-eligible-agent-default',
             };
         }
-        if (this.lastAgentRoute?.path === 'template-instant') {
-            return {
-                selectedModel: 'agent',
-                explicitModel: false,
-                heavyTask,
-                cloudEligible,
-                cloudSelected: false,
-                routeReason: `template-instant [${this.lastAgentRoute.source}]`,
-            };
-        }
         if (requiresV3Workflow) {
             return {
                 selectedModel: 'agent',
@@ -456,131 +491,37 @@ export class ChatCommand {
         return buildPersonaOverlay(this.getActivePersonaMode(), this.getLastUserPrompt());
     }
     isDiagnosticPrompt(prompt) {
-        if (promptRequiresWorkspaceChanges(prompt))
-            return false;
-        return /(startup|start up|won'?t start|doesn'?t start|crash|crashes|error|errors|failing|fails|issue|issues|bug|bugs|diagnos|debug|runtime|log|logs|exception|traceback|stack trace|yaml|blocking|blocker)/i.test(prompt);
+        return this.promptPolicy.isDiagnostic(prompt);
     }
     /**
      * Returns true when the prompt is a simple lookup / analysis / read-only
      * question — these should use analysis_only workflow, not full_autonomy.
      */
-    isAnalysisLookupPrompt(prompt) {
-        if (promptRequiresWorkspaceChanges(prompt))
-            return false;
-        const trimmed = prompt.trim();
-        if (/^(what|which|where|how many|who|find|list|show|check|inspect|analyze|analyse|audit|explain|describe|summarize|summarise|review|overview|count|read|look at|tell me|locate|search for|does .* exist)/i.test(trimmed)) {
-            return true;
-        }
-        // Mid-conversation accountability / lookup questions (Gideon regression)
-        return /\b(where\s+(?:is|are)|what\s+(?:is|are|have|did|was|were)|how\s+(?:do|does|is|are)|what\s+(?:have\s+)?you\s+(?:done|changed|built)|what\s+(?:is|was)\s+(?:your|the)\s+answer)\b/i.test(trimmed);
-    }
-    extractExplicitLocalPath(prompt) {
-        // Try to extract Windows paths (C:\ D:\ etc.)
-        // Match drive letter followed by colon and path
-        const windowsMatch = prompt.match(/([A-Za-z]:[\\\/][^\s<>"|?*]*)/);
-        if (windowsMatch) {
-            const candidatePath = windowsMatch[1].replace(/\\/g, '\\').trim();
-            try {
-                const resolved = require('path').resolve(candidatePath);
-                const fs = require('fs');
-                if (fs.existsSync(resolved)) {
-                    return resolved;
-                }
-            }
-            catch {
-                // Path resolution failed
-            }
-        }
-        // Try to extract Unix paths: / followed by any characters until we hit quotes, angle brackets, pipes, or sentence boundaries
-        // Supports spaces, special chars, camelCase, etc. (anything a filesystem path might have)
-        if (!prompt.includes('http://') && !prompt.includes('https://') && !prompt.includes('ftp://')) {
-            // Match / and everything after it until we hit delimiters or common sentence words
-            const unixMatch = prompt.match(/(\/(?:[^\s<>"|?*]|\s+(?![^\s<>"|?*]))*)/);
-            if (unixMatch) {
-                let candidatePath = unixMatch[1].trim();
-                // Remove trailing common English words that aren't part of path
-                candidatePath = candidatePath.replace(/\s+(and|or|at|in|the|to|for|with|from|by|on)$/i, '').trim();
-                // Remove trailing punctuation
-                candidatePath = candidatePath.replace(/[.,;!?:)\]]*$/, '').trim();
-                if (candidatePath.length > 1) {
-                    try {
-                        const resolved = require('path').resolve(candidatePath);
-                        const fs = require('fs');
-                        if (fs.existsSync(resolved)) {
-                            return resolved;
-                        }
-                    }
-                    catch {
-                        // Path resolution failed
-                    }
-                }
-            }
-        }
-        return null;
-    }
-    isUnscopedPromptPathOverrideAllowed() {
-        return /^(1|true|yes)$/i.test(String(process.env.VIGTHORIA_ALLOW_UNSCOPED_PROMPT_PATHS || ''));
-    }
-    isPathWithinRoot(candidatePath, rootPath) {
-        const candidate = path.resolve(candidatePath);
-        const root = path.resolve(rootPath);
-        const rel = path.relative(root, candidate);
-        return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
-    }
-    getPromptPathAllowedRoots(baseWorkspace) {
-        const roots = new Set();
-        const addRoot = (rawValue) => {
-            const value = String(rawValue || '').trim();
-            if (!value)
-                return;
-            const resolved = path.resolve(value);
-            try {
-                if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
-                    roots.add(resolved);
-                }
-            }
-            catch {
-                // ignore invalid or unreadable roots
-            }
-        };
-        addRoot(baseWorkspace);
-        addRoot(this.currentProjectPath);
-        addRoot(process.cwd());
-        addRoot(this.config.get('project')?.rootPath || null);
-        const envRootsRaw = String(process.env.VIGTHORIA_ALLOWED_WORKSPACE_ROOTS || '').trim();
-        if (envRootsRaw) {
-            for (const entry of envRootsRaw.split(path.delimiter)) {
-                addRoot(entry);
-            }
-        }
-        return Array.from(roots);
-    }
     resolvePromptWorkspacePath(prompt, baseWorkspace) {
-        const explicitPath = this.extractExplicitLocalPath(prompt);
-        if (!explicitPath) {
-            return null;
-        }
-        const candidate = path.resolve(explicitPath);
-        if (this.isUnscopedPromptPathOverrideAllowed()) {
-            return candidate;
-        }
-        const allowedRoots = this.getPromptPathAllowedRoots(baseWorkspace);
-        const isAllowed = allowedRoots.some((root) => this.isPathWithinRoot(candidate, root));
-        if (isAllowed) {
-            return candidate;
-        }
-        if (!this.jsonOutput) {
-            console.log(chalk.yellow(`Ignoring path outside allowed workspace roots: ${candidate}`));
-            if (allowedRoots.length > 0) {
-                const displayRoots = allowedRoots.map((root) => root.replace(/\\/g, '/')).join(', ');
+        const envRoots = String(process.env.VIGTHORIA_ALLOWED_WORKSPACE_ROOTS || '')
+            .split(path.delimiter)
+            .map((entry) => entry.trim())
+            .filter(Boolean);
+        const result = resolvePromptWorkspace(prompt, {
+            baseWorkspace,
+            currentProjectPath: this.currentProjectPath,
+            cwd: process.cwd(),
+            configuredProjectRoot: this.config.get('project')?.rootPath || null,
+            additionalRoots: envRoots,
+            allowUnscoped: /^(1|true|yes)$/i.test(String(process.env.VIGTHORIA_ALLOW_UNSCOPED_PROMPT_PATHS || '')),
+        });
+        if (result.rejectedPath && !this.jsonOutput) {
+            console.log(chalk.yellow(`Ignoring path outside allowed workspace roots: ${result.rejectedPath}`));
+            if (result.allowedRoots.length > 0) {
+                const displayRoots = result.allowedRoots.map((root) => root.replace(/\\/g, '/')).join(', ');
                 console.log(chalk.gray(`Allowed roots: ${displayRoots}`));
             }
             console.log(chalk.gray('To allow unrestricted prompt path overrides, set VIGTHORIA_ALLOW_UNSCOPED_PROMPT_PATHS=1.'));
         }
-        return null;
+        return result.resolvedPath;
     }
     isBrowserTaskPrompt(prompt) {
-        return /(\bbrowser\b|\bchrome\b|\bdevtools\b|\bconsole\b|\bdom\b|network tab|network request|frontend runtime|client-side|client side|rendering|page load|\bwebsocket\b|ui bug|inspect element)/i.test(prompt);
+        return this.promptPolicy.isBrowserTask(prompt);
     }
     /**
      * Returns true when a prompt can be answered directly without the full
@@ -589,28 +530,7 @@ export class ChatCommand {
      * file scanning, or infrastructure changes.
      */
     isOperatorDirectAnswerable(prompt) {
-        const trimmed = prompt.trim();
-        // Infrastructure status pings are never repo-grounded analysis.
-        if (/^(status(\s+check)?|health(\s+check)?|ping)$/i.test(trimmed)) {
-            return true;
-        }
-        // ── Exclusion guard: any prompt that references code artefacts,
-        // file paths, or analysis verbs MUST go through a tool-backed path
-        // (BMAD or agent loop), never the toolless direct-answer shortcut.
-        const repoGrounded = /\b(src\/|\.js\b|\.ts\b|\.py\b|\.jsx\b|\.tsx\b|\.css\b|\.html\b|\.json\b|\.yaml\b|\.yml\b)/i.test(trimmed)
-            || /\b(file|folder|directory|module|class|function|method|variable|handler|listener|binding|conflict|bug|issue|error)\b/i.test(trimmed)
-            || /\b(inspect|analyze|analyse|audit|review|find|diagnose|debug|trace|compare|diff|check|investigate)\b/i.test(trimmed)
-            || /\b(Camera|InputManager|keydown|KeyS|KeyA|KeyW|stopPropagation|addEventListener|handleKeyDown)\b/.test(trimmed)
-            || /\/[a-zA-Z]/.test(trimmed) // slash-prefixed paths
-            || /[A-Z][a-z]+\.[a-z_][a-zA-Z]+/.test(trimmed) // ClassName.methodName
-            || /\b(key\s*code|keydown|keyup|key\s*bind|event\s*listener|event\s*handler|addEventListener|handleKey|onKey)\b/i.test(trimmed);
-        if (repoGrounded)
-            return false;
-        // Only truly trivial prompts are direct-answerable: short echo/smoke
-        // prompts and factual questions with no code or repo reference.
-        const isTrivialEcho = trimmed.length < 120
-            && /^(reply with|say|echo|respond with|return|ping|hello|hi|test|status|what is \d|how much is)\b/i.test(trimmed);
-        return isTrivialEcho;
+        return this.promptPolicy.isOperatorDirectAnswerable(prompt);
     }
     /**
      * Returns true when the prompt references code artefacts, file paths,
@@ -619,51 +539,10 @@ export class ChatCommand {
      * instead of the toolless BMAD/direct-answer path.
      */
     isRepoGroundedPrompt(prompt) {
-        const trimmed = prompt.trim();
-        return /\b(src\/|\.js\b|\.ts\b|\.py\b|\.jsx\b|\.tsx\b|\.css\b|\.html\b|\.json\b)/i.test(trimmed)
-            || /\b(file|folder|module|class|function|method|handler|listener|binding|conflict|bug|error)\b/i.test(trimmed)
-            || /\b(inspect|analyze|analyse|audit|review|find|diagnose|debug|trace|compare|diff|check|investigate)\b/i.test(trimmed)
-            || /\/[a-zA-Z]/.test(trimmed)
-            || /[A-Z][a-z]+\.[a-z_][a-zA-Z]+/.test(trimmed) // ClassName.methodName patterns
-            || /\b(key\s*code|keydown|keyup|key\s*bind|event\s*listener|event\s*handler|addEventListener|handleKey|onKey)\b/i.test(trimmed);
-    }
-    inferAgentTaskType(prompt) {
-        if (this.isDiagnosticPrompt(prompt))
-            return 'debugging';
-        if (this.isAnalysisLookupPrompt(prompt))
-            return 'analysis';
-        return sharedInferAgentTaskType(prompt);
-    }
-    buildTaskShapingInstructions(prompt) {
-        const instructions = [];
-        const runtime = this.getRuntimeEnvironmentContext();
-        // Platform-aware routing hints
-        if (runtime.platform === 'windows') {
-            instructions.push('Platform: Windows. Use list_dir, glob, read_file, and the grep tool for searching.', 'The grep tool handles Windows automatically — do not use bash to call grep, findstr, or Select-String manually.', 'Do not use bash for Unix commands (cat, head, tail, awk, sed, wc).', 'Use read_file to inspect file contents instead of shell commands.', 'All file paths use forward slashes internally.');
-        }
-        else if (runtime.platform === 'macos') {
-            instructions.push('Platform: macOS. Prefer list_dir, grep, and read_file tools for deterministic results.', 'Use workspace-relative paths and verify file existence before claiming a file is missing.');
-        }
-        else if (runtime.platform === 'linux') {
-            instructions.push('Platform: Linux. Prefer list_dir, grep, and read_file for grounded repository inspection.', 'Use exact file paths from tool output when reporting findings or fixes.');
-        }
-        if (this.isAnalysisLookupPrompt(prompt)) {
-            instructions.push('Read-only analysis mode is active.', 'Inspect the workspace with tools and produce a grounded report of findings, gaps, and blockers.', 'Do not create, modify, or delete files unless the user explicitly asked for changes.');
-        }
-        if (this.isDiagnosticPrompt(prompt)) {
-            instructions.push('Diagnostic mode is active.', 'Treat this as a debugging task, not a generic code review or feature request.', 'Start with concrete evidence: logs, runtime errors, config, launch files, and exact symbol references.', 'If log files exist, inspect them before proposing fixes.', 'Do not claim a file, definition, asset, or symbol is missing until you verify that with tools.', 'If a prior diagnosis mentioned a missing symbol or YAML entry, re-check the actual files before repeating it.', 'Prefer grep plus read_file around the exact references involved in the failure.', 'Separate your reasoning into: Evidence, Confirmed Cause, and Remaining Hypotheses.', 'Do not suggest speculative fixes when the current evidence contradicts them.', 'CRITICAL GROUNDING RULE: Every key name, variable name, symbol, or identifier you mention in your final answer MUST appear verbatim in the tool output you received. If a key/symbol does NOT appear in tool output, you MUST NOT mention it as involved in any conflict or issue.', 'CROSS-FILE ATTRIBUTION: When reporting conflicts between two files, a key/symbol is conflicting ONLY if it appears in BOTH files. Read each file carefully and list only the exact keys that appear in the relevant handler/function of EACH file. Do not assume that because one file handles a key, the other file does too.', 'When reporting conflicts between files, cite the exact file name, line number, and the exact string/key from the tool output. Do not paraphrase or substitute key names.', 'Before concluding, re-check: (1) does every key/symbol in my answer actually appear in the evidence I gathered? (2) for each claimed conflict, did I verify the key appears in BOTH files? If not, correct your answer.');
-        }
-        if (this.isBrowserTaskPrompt(prompt)) {
-            instructions.push('Browser-debug mode is active.', 'Prefer concrete browser evidence such as console errors, network failures, DOM state, and websocket behavior.', 'Use the DevTools Bridge only when the user has explicitly enabled it for this run; otherwise ask for permission before requiring local browser tooling.');
-        }
-        if (instructions.length === 0) {
-            return '';
-        }
-        return instructions.join('\n');
+        return this.promptPolicy.isRepoGrounded(prompt);
     }
     buildExecutionPrompt(prompt) {
-        const shaping = this.buildTaskShapingInstructions(prompt);
-        return shaping ? `${prompt}\n\n${shaping}` : prompt;
+        return this.promptPolicy.buildExecutionPrompt(prompt);
     }
     isProjectBrainRuntimeDisabled() {
         return /^(1|true|yes)$/i.test(String(process.env.VIGTHORIA_NO_BRAIN || process.env.VIGTHORIA_BRAIN_DISABLED || ''));
@@ -688,7 +567,11 @@ export class ChatCommand {
         }
     }
     canPromptForWorkspaceIndex() {
-        if (this.jsonOutput || !process.stdin.isTTY || !process.stdout.isTTY) {
+        // A direct `--prompt` invocation is a bounded automation surface even when
+        // wrapped in `script`/ConPTY and therefore appears to have a TTY. Likewise,
+        // --auto-approve cannot answer an unrelated optional indexing question.
+        // Never block these modes on an interactive Brain opt-in prompt.
+        if (this.jsonOutput || this.directPromptMode || this.autoApprove || !process.stdin.isTTY || !process.stdout.isTTY) {
             return false;
         }
         return !/^(1|true|yes)$/i.test(String(process.env.VIGTHORIA_NO_INDEX_PROMPT || ''));
@@ -788,22 +671,40 @@ export class ChatCommand {
             agentRuntime: this.getRuntimeEnvironmentContext(),
         };
         const brainContext = this.buildProjectBrainRuntimeContext(prompt, this.operatorMode ? 'vigthoria-cli.operator' : this.agentMode ? 'vigthoria-cli.agent' : 'vigthoria-cli.chat');
-        if (brainContext) {
-            runtimeContext.vigthoriaBrain = brainContext;
-            if (typeof brainContext.context === 'string' && brainContext.context.trim()) {
-                runtimeContext.projectMemory = brainContext.context;
-            }
-        }
         const workspaceBrainContext = await this.buildWorkspaceBrainRuntimeContext(prompt);
         if (workspaceBrainContext.workspaceBrain) {
             runtimeContext.workspaceBrain = workspaceBrainContext.workspaceBrain;
         }
-        if (typeof workspaceBrainContext.codebaseContext === 'string' && workspaceBrainContext.codebaseContext.trim()) {
-            runtimeContext.codebaseContext = workspaceBrainContext.codebaseContext;
-        }
-        if (typeof workspaceBrainContext.accountBrainContext === 'string' && workspaceBrainContext.accountBrainContext.trim()) {
-            runtimeContext.accountBrainContext = workspaceBrainContext.accountBrainContext;
-        }
+        const contextState = assembleContextState({
+            ...(this.workflowTarget ? { 'workflow-memory': { metadata: { workflowTarget: this.workflowTarget } } } : {}),
+            'session-memory': { content: this.sessionManager.buildMemoryContext(this.currentSession) },
+            'project-memory': {
+                content: typeof brainContext?.context === 'string' ? brainContext.context : '',
+                metadata: brainContext ? { ...brainContext, context: undefined } : undefined,
+            },
+            'codebase-index': {
+                content: typeof workspaceBrainContext.codebaseContext === 'string' ? workspaceBrainContext.codebaseContext : '',
+                metadata: workspaceBrainContext.workspaceBrain,
+            },
+            'account-brain': {
+                content: typeof workspaceBrainContext.accountBrainContext === 'string' ? workspaceBrainContext.accountBrainContext : '',
+            },
+            'workspace-hashes': { metadata: { role: 'change-priority-only', semanticAuthority: false } },
+        });
+        runtimeContext.contextState = contextState;
+        // Explicit server-compatibility adapters. These values are derived from
+        // contextState and have no independent persistence owner.
+        const projectLayer = contextLayer(contextState, 'project-memory');
+        const codebaseLayer = contextLayer(contextState, 'codebase-index');
+        const accountLayer = contextLayer(contextState, 'account-brain');
+        if (projectLayer) {
+            runtimeContext.projectMemory = projectLayer.content || '';
+            runtimeContext.vigthoriaBrain = { ...(brainContext || {}), context: projectLayer.content || '' };
+        }
+        if (codebaseLayer?.content)
+            runtimeContext.codebaseContext = codebaseLayer.content;
+        if (accountLayer?.content)
+            runtimeContext.accountBrainContext = accountLayer.content;
         if (!this.isBrowserTaskPrompt(prompt)) {
             return runtimeContext;
         }
@@ -835,12 +736,6 @@ export class ChatCommand {
             devtoolsBridgeEndpoint: bridgeStatus.endpoint,
         };
     }
-    v3IterationCount = 0;
-    v3ToolCallCount = 0;
-    v3LastActivity = Date.now();
-    v3IdleWatchInterval = null;
-    v3IdleNoticeShown = false;
-    v3StreamingStarted = false;
     /**
      * Strip server-internal path prefixes from tool output strings.
      * Prevents exposing paths like /var/www/V3-Code-Agent/... to end users.
@@ -848,56 +743,13 @@ export class ChatCommand {
     sanitizeServerPath(text) {
         if (!text)
             return text;
-        return sanitizeUserFacingPathText(this.stripHiddenThoughtBlocks(text));
-    }
-    stripHiddenThoughtBlocks(text) {
-        if (!text)
-            return text;
-        return text
-            .replace(/<\|mask_start\|>[\s\S]*?<\|mask_end\|>/g, '')
-            .replace(/<think>[\s\S]*?<\/redacted_thinking>/gi, '')
-            .replace(/<thinking>[\s\S]*?<\/thinking>/gi, '')
-            .replace(/<\/redacted_thinking>/gi, '')
-            .replace(/<\/thinking>/gi, '')
-            .replace(/<\|(?:mask_start|mask_end)\|>/g, '')
-            .trim();
+        return sanitizeUserFacingPathText(stripHiddenThoughtBlocks(text));
     }
     startV3IdleWatch(spinner) {
-        this.stopV3IdleWatch();
-        this.v3IdleNoticeShown = false;
-        if (this.jsonOutput || !spinner) {
-            return;
-        }
-        this.v3IdleWatchInterval = setInterval(() => {
-            const idleMs = Date.now() - this.v3LastActivity;
-            if (idleMs < 15_000) {
-                // Activity resumed — re-arm the notice so a later stall is reported too.
-                this.v3IdleNoticeShown = false;
-                return;
-            }
-            if (this.v3IdleNoticeShown) {
-                return;
-            }
-            this.v3IdleNoticeShown = true;
-            if (spinner.isSpinning) {
-                spinner.stop();
-            }
-            const seconds = Math.round(idleMs / 1000);
-            const idleTimeoutSec = Math.round(DEFAULT_V3_AGENT_IDLE_TIMEOUT_MS / 1000);
-            process.stderr.write(chalk.yellow(`  [Wait] Model still working (${seconds}s) — this can legitimately take a while for large tasks. ` +
-                (idleTimeoutSec > 0
-                    ? `Only complete silence (~${idleTimeoutSec}s with zero bytes received) will trigger an auto-recover/retry — active progress is never interrupted.\n`
-                    : `\n`)));
-            spinner.start();
-            spinner.text = 'Waiting for model response...';
-        }, 5_000);
+        this.streamState.startIdleWatch(spinner);
     }
     stopV3IdleWatch() {
-        if (this.v3IdleWatchInterval) {
-            clearInterval(this.v3IdleWatchInterval);
-            this.v3IdleWatchInterval = null;
-        }
-        this.v3IdleNoticeShown = false;
+        this.streamState.stopIdleWatch();
     }
     describeV3AgentTool(toolName) {
         const normalized = String(toolName || '').toLowerCase();
@@ -964,7 +816,7 @@ export class ChatCommand {
                 ? (event.body ?? event.stream ?? event.response ?? event)
                 : event;
             for await (const chunk of robustifyStreamResponse(source)) {
-                this.v3LastActivity = Date.now();
+                this.streamState.noteActivity();
                 if (chunk.type === 'error') {
                     if (spinner.isSpinning)
                         spinner.stop();
@@ -991,8 +843,8 @@ export class ChatCommand {
         if (!safeText) {
             return;
         }
-        if (!this.v3StreamingStarted) {
-            this.v3StreamingStarted = true;
+        if (!this.streamState.streamingStarted) {
+            this.streamState.streamingStarted = true;
             spinner.stop();
             if (!this.directPromptMode) {
                 console.log();
@@ -1001,27 +853,27 @@ export class ChatCommand {
         else {
             spinner.stop();
         }
-        this.v3StreamedAnswerBuffer += safeText;
-        spinner.text = looksLikeMarkdownReport(this.v3StreamedAnswerBuffer)
+        this.streamState.streamedAnswerBuffer += safeText;
+        spinner.text = looksLikeMarkdownReport(this.streamState.streamedAnswerBuffer)
             ? 'Writing analysis report...'
             : 'Writing response...';
     }
     displayV3StreamedAnswer() {
-        if (this.jsonOutput || this.v3StreamedAnswerDisplayed) {
+        if (this.jsonOutput || this.streamState.streamedAnswerDisplayed) {
             return;
         }
-        const content = this.v3StreamedAnswerBuffer.trim();
+        const content = this.streamState.streamedAnswerBuffer.trim();
         if (!isSubstantiveAgentAnswer(content)) {
             return;
         }
         emitDeckEvent({ type: 'report_ready', markdown: content });
         if (isDeckModeEnabled()) {
-            this.v3StreamedAnswerDisplayed = true;
+            this.streamState.streamedAnswerDisplayed = true;
             return;
         }
         console.log('');
         console.log(renderMarkdownToTerminal(content, this.getTerminalContentWidth()));
-        this.v3StreamedAnswerDisplayed = true;
+        this.streamState.streamedAnswerDisplayed = true;
     }
     renderAgentAnswerForTerminal(content) {
         const normalized = String(content || '').trim();
@@ -1034,37 +886,7 @@ export class ChatCommand {
         return Math.max(60, Math.min(cols - 2, 100));
     }
     sanitizeV3VisibleStreamText(text) {
-        let output = String(text || '');
-        if (!output)
-            return '';
-        output = output.replace(/<\/think>/gi, '</thinking>');
-        output = output.replace(/<think>/gi, '<thinking>');
-        output = output.replace(/<\/redacted_thinking>/gi, '</thinking>');
-        if (this.v3SuppressThinkingStream) {
-            const closeIdx = output.search(/<\/thinking>/i);
-            if (closeIdx < 0) {
-                return '';
-            }
-            output = output.slice(closeIdx).replace(/^<\/thinking>/i, '');
-            this.v3SuppressThinkingStream = false;
-        }
-        output = output.replace(/<thinking>[\s\S]*?<\/thinking>/gi, '');
-        if (/<thinking>/i.test(output)) {
-            output = output.replace(/<thinking>[\s\S]*$/i, '');
-            this.v3SuppressThinkingStream = true;
-        }
-        output = output
-            .replace(/```json\s*\[\s*\{[\s\S]*?"tool"[\s\S]*?\}\s*\]\s*```/gi, '')
-            .replace(/```json\s*\{[\s\S]*?"tool"[\s\S]*?\}\s*```/gi, '')
-            .replace(/^\s*(?:json\s*)?\[\s*\{[\s\S]*?"tool"[\s\S]*$/gim, '')
-            .replace(/^\s*(?:list_dir|read_file|write_file|edit_file|glob|grep|bash)\s*$/gim, '')
-            .replace(/<tool_call>[\s\S]*?<\/tool_call>/gi, '')
-            .replace(/<tool_code>[\s\S]*?<\/tool_code>/gi, '')
-            .replace(/<read_file>\s*<path>[\s\S]*?<\/path>\s*<\/read_file>/gi, '')
-            .replace(/<(?:grep|list_directory|search_files|glob|tool_result)\b[\s\S]*?<\/(?:grep|list_directory|search_files|glob|tool_result)>/gi, '')
-            .replace(/bootstrap discovery completed\s*[—-]\s*inspect the most relevant files next\.?/gi, '')
-            .replace(/\n{3,}/g, '\n\n');
-        return output;
+        return this.streamState.sanitizeVisibleText(text);
     }
     writeAgentActivityLine(text) {
         if (this.jsonOutput)
@@ -1084,29 +906,29 @@ export class ChatCommand {
         if (!event || typeof event !== 'object') {
             return;
         }
-        this.v3LastActivity = Date.now();
+        this.streamState.noteActivity();
         if (isV3StreamKeepaliveEvent(event)) {
             return;
         }
         if (event.type === 'tool_call') {
             const eventKey = this.toolEventKey(event);
-            if (this.v3SeenToolCalls.has(eventKey)) {
+            if (this.streamState.seenToolCalls.has(eventKey)) {
                 return;
             }
-            this.v3SeenToolCalls.add(eventKey);
-            this.v3ToolCallCount += 1;
+            this.streamState.seenToolCalls.add(eventKey);
+            this.streamState.toolCallCount += 1;
             const toolName = event.name || event.tool || event.tool_name || '';
             emitDeckEvent({
                 type: 'tool_start',
                 tool: toolName,
-                index: this.v3ToolCallCount,
+                index: this.streamState.toolCallCount,
                 target: event.arguments?.path || event.arguments?.file_path || event.arguments?.pattern || '',
             });
             const toolDesc = this.describeV3AgentTool(event.tool || event.name || event.tool_name);
             const toolTarget = event.arguments?.path || event.arguments?.file_path || event.arguments?.pattern || '';
             const sanitizedTarget = this.sanitizeServerPath(String(toolTarget));
             const shortTarget = sanitizedTarget ? ` -> ${sanitizedTarget.replace(/\\/g, '/').split('/').slice(-2).join('/')}` : '';
-            const stepLabel = chalk.cyan(`  [${this.v3ToolCallCount}]`) + ` ${toolDesc}${shortTarget}`;
+            const stepLabel = chalk.cyan(`  [${this.streamState.toolCallCount}]`) + ` ${toolDesc}${shortTarget}`;
             if (spinner.isSpinning)
                 spinner.stop();
             this.writeAgentActivityLine(this.fitTerminalText(stepLabel) + '\n');
@@ -1129,18 +951,18 @@ export class ChatCommand {
         }
         if (event.type === 'tool_result') {
             const eventKey = this.toolEventKey(event);
-            if (eventKey && this.v3SeenToolResults.has(eventKey)) {
+            if (eventKey && this.streamState.seenToolResults.has(eventKey)) {
                 return;
             }
             if (eventKey)
-                this.v3SeenToolResults.add(eventKey);
+                this.streamState.seenToolResults.add(eventKey);
             const success = event.success !== false;
             const toolName = event.name || event.tool || '';
             emitDeckEvent({
                 type: 'tool_end',
                 tool: toolName,
                 success,
-                index: this.v3ToolCallCount,
+                index: this.streamState.toolCallCount,
             });
             const indicator = success ? chalk.green('  ✓') : chalk.red('  ✗');
             if (spinner.isSpinning)
@@ -1206,7 +1028,7 @@ export class ChatCommand {
             return;
         }
         if (event.type === 'thinking') {
-            this.v3IterationCount += 1;
+            this.streamState.iterationCount += 1;
             const iterText = this.sanitizeServerPath(event.content || '');
             const isGenericStep = !iterText
                 || /read-only analysis turn|run at least one discovery tool/i.test(iterText)
@@ -1225,7 +1047,7 @@ export class ChatCommand {
                 ? (event.delta?.text || '')
                 : (event.content || '');
             if (text) {
-                this.v3LastActivity = Date.now();
+                this.streamState.noteActivity();
                 if (event.type === 'message' && /^\[Context\]/i.test(String(text).trim())) {
                     if (spinner.isSpinning)
                         spinner.stop();
@@ -1242,16 +1064,16 @@ export class ChatCommand {
         }
         if (event.type === 'complete') {
             const elapsed = event.elapsed || '';
-            const iters = event.iterations || this.v3IterationCount;
-            const tools = event.tool_calls || this.v3ToolCallCount;
+            const iters = event.iterations || this.streamState.iterationCount;
+            const tools = event.tool_calls || this.streamState.toolCallCount;
             if (spinner.isSpinning)
                 spinner.stop();
             this.displayV3StreamedAnswer();
             emitDeckEvent({
                 type: 'run_complete',
                 success: true,
-                tools: event.tool_calls || this.v3ToolCallCount,
-                iterations: event.iterations || this.v3IterationCount,
+                tools: event.tool_calls || this.streamState.toolCallCount,
+                iterations: event.iterations || this.streamState.iterationCount,
                 elapsed: event.elapsed || '',
             });
             let statLine = `${iters} iterations, ${tools} tool calls`;
@@ -1267,10 +1089,11 @@ export class ChatCommand {
             process.stdout.write(chalk.green(`\n✓ Complete`) + ` - ${this.fitTerminalText(statLine, 14)}\n`);
             // Show seal quality score if available
             if (event.seal_score && typeof event.seal_score.overall === 'number') {
-                const score = event.seal_score.overall;
+                const rawScore = event.seal_score.overall;
+                const score = rawScore <= 10 ? rawScore * 10 : rawScore;
                 const tier = event.seal_score.tier || '';
-                const scoreColor = score >= 7 ? chalk.green : score >= 5 ? chalk.yellow : chalk.red;
-                process.stdout.write(chalk.cyan('  [Quality] ') + scoreColor(`${score}/10`) + (tier ? chalk.gray(` (${tier})`) : '') + '\n');
+                const scoreColor = score >= 70 ? chalk.green : score >= 50 ? chalk.yellow : chalk.red;
+                process.stdout.write(chalk.cyan('  [Quality] ') + scoreColor(`${score}/100`) + (tier ? chalk.gray(` (${tier})`) : '') + '\n');
             }
             return;
         }
@@ -1425,11 +1248,11 @@ export class ChatCommand {
             return;
         }
         if (event.type === 'start') {
-            if (this.v3StartSeen) {
+            if (this.streamState.startSeen) {
                 spinner.text = 'Working...';
                 return;
             }
-            this.v3StartSeen = true;
+            this.streamState.startSeen = true;
             if (spinner.isSpinning)
                 spinner.stop();
             process.stderr.write(chalk.cyan('  [Start] ') + 'Agent initialized\n');
@@ -1503,20 +1326,20 @@ export class ChatCommand {
         this.config = config;
         this.logger = logger;
         this.commandProgram = commandProgram;
-        this.api = new APIClient(config, logger);
+        this.api = createAPIClient(config, logger);
+        this.promptPolicy = new ChatPromptPolicy(() => this.getRuntimeEnvironmentContext());
+        this.streamState = new AgentStreamState({
+            isJsonOutput: () => this.jsonOutput,
+            idleTimeoutMs: () => DEFAULT_V3_AGENT_IDLE_TIMEOUT_MS,
+        });
         this.sessionManager = new SessionManager();
     }
     async run(options) {
         const hasRuntimeToken = Boolean(process.env.VIGTHORIA_TOKEN || process.env.VIGTHORIA_AUTH_TOKEN);
         if (!this.config.isAuthenticated() && !hasRuntimeToken) {
-            if (options.json) {
-                process.exitCode = 1;
-                emitAgentJsonOutput({ success: false, error: 'Not authenticated. Run: vigthoria login' });
-            }
-            else {
-                this.logger.error('Not authenticated. Run: vigthoria login');
-            }
-            return;
+            throw new CliCommandError('Not authenticated. Run: vigthoria login', {
+                code: 'AUTH_REQUIRED', category: 'authentication',
+            });
         }
         this.agentMode = options.agent === true;
         this.operatorMode = options.operator === true;
@@ -1525,7 +1348,7 @@ export class ChatCommand {
             : null;
         this.savePlanToVigFlow = options.savePlan === true;
         this.jsonOutput = options.json === true;
-        this.autoApprove = options.autoApprove === true || this.jsonOutput;
+        this.autoApprove = resolveAutoApproval(options.autoApprove, this.jsonOutput);
         this.personaOverride = options.grant === true ? 'wiener_grant' : null;
         this.modelExplicitlySelected = this.isHardExplicitAgentModelSelection(options);
         this.currentModel = this.resolveInitialModel(options);
@@ -1581,19 +1404,23 @@ export class ChatCommand {
                 this.saveSession();
             }
             this.operatorMode = false;
-            this.logger.error(this.operatorAccessMessage());
-            return;
+            throw new CliCommandError(this.operatorAccessMessage(), { code: 'OPERATOR_ACCESS_REQUIRED', category: 'authorization' });
         }
         if (options.retry || options.continue) {
             if (!this.agentMode) {
-                throw new Error('--retry and --continue require agent mode.');
+                throw new CliCommandError('--retry and --continue require agent mode.', { code: 'AGENT_MODE_REQUIRED', category: 'usage' });
             }
             const followUp = options.retry ? this.buildRetryPrompt() : this.buildContinuePrompt();
             if (!followUp) {
-                throw new Error('No previous agent run to retry or continue. Run an agent prompt first with the same --project, or use --resume.');
+                throw new CliCommandError('No previous agent run to retry or continue. Run an agent prompt first with the same --project, or use --resume.', {
+                    code: 'AGENT_RUN_NOT_FOUND',
+                    category: 'usage',
+                });
             }
             this.directPromptMode = true;
             await this.runAgentTurn(followUp);
+            this.workspaceBrain?.destroy();
+            this.api.destroy();
             return;
         }
         if (options.prompt) {
@@ -1605,35 +1432,34 @@ export class ChatCommand {
                 const parsed = Number.parseInt(rawValue, 10);
                 return Number.isFinite(parsed) && parsed >= 0 ? parsed : 0;
             })();
-            let timedOut = false;
-            const timeoutId = options.bridge && bridgePromptTimeoutMs > 0
-                ? setTimeout(() => {
-                    timedOut = true;
-                    const b = getBridgeClient();
-                    if (b) {
-                        b.emitEnd({ reason: 'timeout' });
-                        b.destroy();
-                    }
-                    if (!this.jsonOutput) {
-                        this.logger.error('Bridge prompt timed out after ' + Math.round(bridgePromptTimeoutMs / 1000) + ' seconds.');
-                    }
-                    process.exitCode = 1;
-                }, bridgePromptTimeoutMs)
-                : null;
-            await this.handleDirectPrompt(options.prompt);
-            if (timeoutId)
-                clearTimeout(timeoutId);
-            if (!timedOut) {
-                const bridge = getBridgeClient();
-                if (bridge) {
-                    bridge.emitEnd({ reason: 'prompt-complete' });
-                    bridge.destroy();
+            let timeoutId = null;
+            try {
+                const promptTask = this.handleDirectPrompt(options.prompt);
+                if (options.bridge && bridgePromptTimeoutMs > 0) {
+                    await Promise.race([
+                        promptTask,
+                        new Promise((_resolve, reject) => {
+                            timeoutId = setTimeout(() => reject(new CliCommandError(`Bridge prompt timed out after ${Math.round(bridgePromptTimeoutMs / 1000)} seconds.`, { code: 'BRIDGE_PROMPT_TIMEOUT', category: 'network' })), bridgePromptTimeoutMs);
+                        }),
+                    ]);
+                }
+                else {
+                    await promptTask;
                 }
+                getBridgeClient()?.emitEnd({ reason: 'prompt-complete' });
             }
-            // Force-exit: undici + chokidar + HTTPS pool keep the Node.js event
-            // loop alive indefinitely in direct prompt mode; a clean exit is safe here.
-            this.api.destroy();
-            process.exit(process.exitCode ?? 0);
+            catch (error) {
+                getBridgeClient()?.emitEnd({ reason: 'prompt-failed' });
+                throw error;
+            }
+            finally {
+                if (timeoutId)
+                    clearTimeout(timeoutId);
+                getBridgeClient()?.destroy();
+                this.workspaceBrain?.destroy();
+                this.api.destroy();
+            }
+            return;
         }
         await this.startInteractiveChat();
         const bridge = getBridgeClient();
@@ -1641,6 +1467,8 @@ export class ChatCommand {
             bridge.emitEnd({ reason: 'interactive-exit' });
             bridge.destroy();
         }
+        this.workspaceBrain?.destroy();
+        this.api.destroy();
     }
     /** Handle an inbound admin command from the Commando Bridge. */
     handleAdminCommand(cmd) {
@@ -1660,7 +1488,9 @@ export class ChatCommand {
                 if (!this.jsonOutput)
                     console.log(chalk.red(`[bridge] Abort requested by admin`));
                 getBridgeClient()?.emitEnd({ reason: 'admin-abort' });
-                process.exit(0);
+                process.exitCode = 130;
+                this.workspaceBrain?.destroy();
+                this.api.destroy();
                 break;
             default:
                 getBridgeClient()?.emitError({ message: `Unknown admin command: ${cmd.action}` });
@@ -1838,6 +1668,35 @@ export class ChatCommand {
                         originalPrompt: saved.originalPrompt ?? null,
                     };
                 }
+                else if (this.currentSession.activeAgentRun?.prompt) {
+                    const checkpoint = this.currentSession.activeAgentRun;
+                    this.lastAgentRunOutcome = {
+                        prompt: checkpoint.prompt,
+                        originalPrompt: checkpoint.originalPrompt || checkpoint.prompt,
+                        taskId: checkpoint.executionId,
+                        contextId: checkpoint.contextId,
+                        tasksSucceeded: 0,
+                        tasksTotal: 0,
+                        failedTaskIds: [...(checkpoint.failedTaskIds || [])],
+                        unfinishedTaskIds: checkpoint.unfinishedTaskIds?.length
+                            ? [...checkpoint.unfinishedTaskIds]
+                            : ['resume-interrupted-agent-run'],
+                        qualityScore: null,
+                        qualityMissing: [],
+                        qualityBlockers: checkpoint.error ? [checkpoint.error] : [],
+                        hasOutput: false,
+                        answerContent: null,
+                        selfHealStatus: 'skipped',
+                        selfHealTool: null,
+                        plannerError: null,
+                        executorError: checkpoint.error || 'The previous client process ended before the agent run completed.',
+                        clientToolErrors: [],
+                        transportErrors: [],
+                        workspacePath: checkpoint.workspacePath || this.currentProjectPath,
+                        workspaceSyncIssue: null,
+                        finishedAt: Date.parse(checkpoint.updatedAt) || Date.now(),
+                    };
+                }
                 return;
             }
         }
@@ -1906,8 +1765,7 @@ export class ChatCommand {
         }
         if (this.operatorMode) {
             if (!this.hasOperatorAccess()) {
-                this.logger.error(this.operatorAccessMessage());
-                return;
+                throw new CliCommandError(this.operatorAccessMessage(), { code: 'OPERATOR_ACCESS_REQUIRED', category: 'authorization' });
             }
             await this.runOperatorTurn(effectivePrompt);
             return;
@@ -1987,13 +1845,13 @@ export class ChatCommand {
                 spinner.stop();
             }
             if (this.jsonOutput) {
-                console.log(JSON.stringify({
+                emitAgentJsonOutput({
                     success: true,
                     workflow: resolvedWorkflow,
                     mode: invocationMode,
                     execution,
                     content,
-                }, null, 2));
+                });
                 return;
             }
             this.logger.success(`Workflow target ${resolvedWorkflow.name} ${execution.status}`);
@@ -2014,8 +1872,7 @@ export class ChatCommand {
     }
     async runOperatorTurn(prompt) {
         if (!this.hasOperatorAccess()) {
-            this.logger.error(this.operatorAccessMessage());
-            return;
+            throw new CliCommandError(this.operatorAccessMessage(), { code: 'OPERATOR_ACCESS_REQUIRED', category: 'authorization' });
         }
         // ── Fast-path: direct-answerable prompts skip the full BMAD workflow ──
         // The BMAD orchestrator scans the entire workspace (can be 1000+ files)
@@ -2075,7 +1932,7 @@ export class ChatCommand {
                 throw new CLIError('Operator workflow returned a non-actionable acknowledgement instead of a grounded result.', 'model_backend');
             }
             if (this.jsonOutput) {
-                console.log(JSON.stringify({
+                emitAgentJsonOutput({
                     success: true,
                     mode: 'operator',
                     workflowId: response.workflowId,
@@ -2083,7 +1940,7 @@ export class ChatCommand {
                     contextId: response.contextId || null,
                     content: response.content || 'Operator workflow completed.',
                     metadata: response.metadata || {},
-                }, null, 2));
+                });
             }
             else {
                 console.log(response.content || 'Operator workflow completed.');
@@ -2101,23 +1958,8 @@ export class ChatCommand {
             }
             const cliErr = error instanceof CLIError ? error : classifyError(error);
             const errorMsg = formatCLIError(cliErr);
-            if (!this.jsonOutput) {
-                this.logger.error('Operator workflow failed');
-            }
             this.rememberBrainEvent('issue', `GoA operator workflow failed: ${errorMsg}`, 'operator');
-            if (this.jsonOutput) {
-                process.exitCode = 1;
-                console.log(JSON.stringify({
-                    success: false,
-                    mode: 'operator',
-                    content: '',
-                    error: errorMsg,
-                    errorCategory: cliErr.category,
-                }, null, 2));
-            }
-            else {
-                this.logger.error(errorMsg);
-            }
+            throw commandFailure(error, { code: 'OPERATOR_EXECUTION_FAILED', message: errorMsg });
         }
     }
     /**
@@ -2163,12 +2005,12 @@ export class ChatCommand {
                 throw new CLIError('Operator returned a non-actionable acknowledgement instead of a grounded result.', 'model_backend');
             }
             if (this.jsonOutput) {
-                console.log(JSON.stringify({
+                emitAgentJsonOutput({
                     success: true,
                     mode: 'operator',
                     content,
                     metadata: { source: 'operator-direct', mode: 'operator' },
-                }, null, 2));
+                });
             }
             else {
                 console.log(content);
@@ -2182,20 +2024,7 @@ export class ChatCommand {
                 spinner.stop();
             const cliErr = error instanceof CLIError ? error : classifyError(error);
             const errorMsg = formatCLIError(cliErr);
-            if (this.jsonOutput) {
-                process.exitCode = 1;
-                console.log(JSON.stringify({
-                    success: false,
-                    mode: 'operator',
-                    content: '',
-                    error: errorMsg,
-                    errorCategory: cliErr.category,
-                }, null, 2));
-            }
-            else {
-                this.logger.error('Operator direct answer failed');
-                this.logger.error(errorMsg);
-            }
+            throw commandFailure(error, { code: 'OPERATOR_DIRECT_FAILED', message: errorMsg });
         }
     }
     async runSimplePrompt(prompt) {
@@ -2294,20 +2123,20 @@ export class ChatCommand {
             const response = await this.callApi('Send chat message', () => this.api.chat(this.getMessagesForModel(), this.currentModel));
             if (spinner)
                 spinner.stop();
-            const finalText = this.sanitizeDirectModeOutput(this.stripHiddenThoughtBlocks(response.message || '')).trim();
+            const finalText = sanitizeDirectModeOutput(stripHiddenThoughtBlocks(response.message || '')).trim();
             const effectiveModel = String(response.model || this.currentModel);
             const metadata = this.modelGovernanceFallback
                 ? { modelFallback: this.modelGovernanceFallback }
                 : undefined;
             if (this.jsonOutput) {
-                console.log(JSON.stringify({
+                emitAgentJsonOutput({
                     success: true,
                     mode: 'chat',
                     model: effectiveModel,
                     requestedModel: this.modelGovernanceFallback?.requestedModel || this.currentModel,
                     metadata,
                     content: finalText || 'The model returned an empty response. Try rephrasing or use --agent for grounded file analysis.',
-                }, null, 2));
+                });
             }
             else if (finalText) {
                 console.log(finalText);
@@ -2323,20 +2152,7 @@ export class ChatCommand {
                 spinner.stop();
             const cliErr = error instanceof CLIError ? error : classifyError(error);
             const errorMsg = formatCLIError(cliErr);
-            if (this.jsonOutput) {
-                process.exitCode = 1;
-                console.log(JSON.stringify({
-                    success: false,
-                    mode: 'chat',
-                    model: this.currentModel,
-                    content: '',
-                    error: errorMsg,
-                    errorCategory: cliErr.category,
-                }, null, 2));
-            }
-            else {
-                this.logger.error(errorMsg);
-            }
+            throw commandFailure(error, { code: 'CHAT_EXECUTION_FAILED', message: errorMsg });
         }
     }
     async runAgentTurn(prompt) {
@@ -2376,10 +2192,9 @@ export class ChatCommand {
             return;
         }
         const errorMessage = 'The V3 planner/executor workflow is unavailable. Refusing to fall back to legacy template, direct-file, or local write paths.';
-        this.logger.error(errorMessage);
         this.messages.push({ role: 'assistant', content: errorMessage });
-        process.exitCode = 1;
         this.saveSession();
+        throw new CliCommandError(errorMessage, { code: 'AGENT_UNAVAILABLE', category: 'execution' });
     }
     resolveAgentTurnPrompt(prompt) {
         if (isBuiltContinuePrompt(prompt) || isBuiltRetryPrompt(prompt) || isBuiltWriteConfirmationPrompt(prompt)) {
@@ -2551,33 +2366,38 @@ export class ChatCommand {
                             spinner.stop();
                         const evidenceSummary = this.synthesizeEvidenceFromHistory();
                         if (evidenceSummary) {
-                            const fallbackContent = this.sanitizeDirectModeOutput(evidenceSummary);
+                            const fallbackContent = sanitizeDirectModeOutput(evidenceSummary);
                             const liveOutcome = this.buildLocalLoopLiveOutcome(prompt);
                             const evaluation = evaluateExecutorSuccess(liveOutcome);
                             this.persistLocalLoopOutcome(prompt, evaluation, liveOutcome);
                             if (this.jsonOutput) {
-                                process.exitCode = evaluation.executorSucceeded ? 0 : 1;
-                                console.log(JSON.stringify({
-                                    success: evaluation.executorSucceeded,
-                                    mode: 'agent',
-                                    model: this.currentModel,
-                                    partial: !evaluation.executorSucceeded,
-                                    content: fallbackContent,
-                                    statusHeadline: evaluation.statusHeadline,
-                                    metadata: {
-                                        executionPath: 'local-agent-loop',
-                                        recovered: true,
-                                        outcomeTruth: {
-                                            executorSucceeded: evaluation.executorSucceeded,
-                                            uiTheme: evaluation.uiTheme,
+                                if (evaluation.executorSucceeded)
+                                    emitAgentJsonOutput({
+                                        success: true,
+                                        mode: 'agent',
+                                        model: this.currentModel,
+                                        partial: !evaluation.executorSucceeded,
+                                        content: fallbackContent,
+                                        statusHeadline: evaluation.statusHeadline,
+                                        metadata: {
+                                            executionPath: 'local-agent-loop',
+                                            recovered: true,
+                                            outcomeTruth: {
+                                                executorSucceeded: evaluation.executorSucceeded,
+                                                uiTheme: evaluation.uiTheme,
+                                            },
                                         },
-                                    },
-                                }, null, 2));
+                                    });
                             }
                             else {
                                 console.log(fallbackContent);
                             }
                             this.saveSession();
+                            if (!evaluation.executorSucceeded) {
+                                throw new CliCommandError(evaluation.statusHeadline, {
+                                    code: 'AGENT_INCOMPLETE', details: { content: fallbackContent, executionPath: 'local-agent-loop' },
+                                });
+                            }
                             return;
                         }
                         throw retryErr;
@@ -2589,23 +2409,7 @@ export class ChatCommand {
                     if (spinner)
                         spinner.stop();
                     this.rememberBrainEvent('issue', 'Agent API preflight failed: ' + formatted, 'agent');
-                    if (this.jsonOutput) {
-                        process.exitCode = 1;
-                        console.log(JSON.stringify({
-                            success: false,
-                            mode: 'agent',
-                            model: this.currentModel,
-                            partial: false,
-                            content: '',
-                            error: formatted,
-                            errorCategory: cliErr.category,
-                            metadata: { executionPath: 'local-agent-loop' },
-                        }, null, 2));
-                    }
-                    else {
-                        this.logger.error(formatted);
-                    }
-                    return;
+                    throw commandFailure(firstErr, { code: 'AGENT_PREFLIGHT_FAILED', message: formatted });
                 }
             }
             if (spinner)
@@ -2627,8 +2431,8 @@ export class ChatCommand {
                     const isPolicyAck = /^(i will follow|i understand|i('ll| will) adhere|understood[.,!]|sure[.,!]|i('ll| will) use the tools|i('ll| will) proceed|let me know|provide your|waiting for)/i.test(visibleText.trim());
                     // Detect if the response is effectively empty or just a follow-up
                     // question after we strip tool output echoes.
-                    const sanitized = this.sanitizeDirectModeOutput(visibleText.trim());
-                    const isFollowUp = this.isDirectModeFollowUpQuestion(sanitized);
+                    const sanitized = sanitizeDirectModeOutput(visibleText.trim());
+                    const isFollowUp = isDirectModeFollowUpQuestion(sanitized);
                     const isEmptyAfterSanitize = !sanitized || sanitized.length < 10;
                     // Detect resignation: model gives up saying files/things were "not found"
                     // without having tried list_dir to discover the correct path.
@@ -2671,29 +2475,34 @@ export class ChatCommand {
                     const evaluation = evaluateExecutorSuccess(liveOutcome);
                     this.persistLocalLoopOutcome(prompt, evaluation, liveOutcome);
                     if (this.jsonOutput) {
-                        process.exitCode = evaluation.executorSucceeded ? 0 : 1;
-                        console.log(JSON.stringify({
-                            success: evaluation.executorSucceeded,
-                            mode: 'agent',
-                            model: this.currentModel,
-                            partial: !evaluation.executorSucceeded,
-                            content: finalContent,
-                            statusHeadline: evaluation.statusHeadline,
-                            metadata: {
-                                executionPath: 'local-agent-loop',
-                                outcomeTruth: {
-                                    executorSucceeded: evaluation.executorSucceeded,
-                                    uiTheme: evaluation.uiTheme,
-                                    analysisToolsUsed: liveOutcome.analysisToolsUsed,
-                                    changedFileCount: liveOutcome.changedFileCount,
+                        if (evaluation.executorSucceeded)
+                            emitAgentJsonOutput({
+                                success: true,
+                                mode: 'agent',
+                                model: this.currentModel,
+                                partial: !evaluation.executorSucceeded,
+                                content: finalContent,
+                                statusHeadline: evaluation.statusHeadline,
+                                metadata: {
+                                    executionPath: 'local-agent-loop',
+                                    outcomeTruth: {
+                                        executorSucceeded: evaluation.executorSucceeded,
+                                        uiTheme: evaluation.uiTheme,
+                                        analysisToolsUsed: liveOutcome.analysisToolsUsed,
+                                        changedFileCount: liveOutcome.changedFileCount,
+                                    },
                                 },
-                            },
-                        }, null, 2));
+                            });
                     }
                     else {
                         console.log(finalContent);
                     }
                     this.saveSession();
+                    if (!evaluation.executorSucceeded) {
+                        throw new CliCommandError(evaluation.statusHeadline, {
+                            code: 'AGENT_INCOMPLETE', details: { content: finalContent, executionPath: 'local-agent-loop' },
+                        });
+                    }
                     return;
                 }
                 await this.executeToolCalls(toolCalls);
@@ -2710,25 +2519,7 @@ export class ChatCommand {
                 const cliErr = error instanceof CLIError ? error : classifyError(error);
                 const errorMsg = formatCLIError(cliErr);
                 this.rememberBrainEvent('issue', `Agent turn failed: ${errorMsg}`, 'agent');
-                if (this.jsonOutput) {
-                    process.exitCode = 1;
-                    console.log(JSON.stringify({
-                        success: false,
-                        mode: 'agent',
-                        model: this.currentModel,
-                        partial: false,
-                        content: '',
-                        error: errorMsg,
-                        errorCategory: cliErr.category,
-                        metadata: {
-                            executionPath: 'local-agent-loop',
-                        },
-                    }, null, 2));
-                }
-                else {
-                    this.logger.error(errorMsg);
-                }
-                return;
+                throw commandFailure(error, { code: 'AGENT_TURN_FAILED', message: errorMsg });
             }
         }
         const liveOutcome = this.buildLocalLoopLiveOutcome(prompt);
@@ -2738,29 +2529,11 @@ export class ChatCommand {
             executorError: 'Agent exhausted the maximum local tool loop turns before reaching a clean completion.',
         });
         this.persistLocalLoopOutcome(prompt, exhaustedEval, liveOutcome);
-        if (this.jsonOutput) {
-            process.exitCode = 1;
-            console.log(JSON.stringify({
-                success: false,
-                mode: 'agent',
-                model: this.currentModel,
-                partial: true,
-                content: 'Task complete.',
-                error: 'Agent exhausted the maximum local tool loop turns before reaching a clean completion.',
-                statusHeadline: exhaustedEval.statusHeadline,
-                metadata: {
-                    executionPath: 'local-agent-loop',
-                    outcomeTruth: {
-                        executorSucceeded: false,
-                        uiTheme: exhaustedEval.uiTheme,
-                    },
-                },
-            }, null, 2));
-        }
-        else {
-            console.log('Task complete.');
-        }
         this.saveSession();
+        throw new CliCommandError('Agent exhausted the maximum local tool loop turns before reaching a clean completion.', {
+            code: 'AGENT_TURN_LIMIT_EXHAUSTED',
+            details: { statusHeadline: exhaustedEval.statusHeadline, executionPath: 'local-agent-loop' },
+        });
     }
     async primeBypassedTargetFileContext(prompt) {
         if (!this.directPromptMode || !this.tools) {
@@ -2791,235 +2564,6 @@ export class ChatCommand {
             this.messages.push({ role: 'system', content: readSummary });
         }
     }
-    /**
-     * Sub-second path for trivial HTML/hello-world: Template Service → index.html (no V3 planner).
-     */
-    async tryTemplateInstantPath(prompt) {
-        const route = this.lastAgentRoute;
-        if (route?.path !== 'template-instant' && !isTrivialHtmlPageRequest(prompt)) {
-            return false;
-        }
-        let workspacePath = this.currentProjectPath;
-        try {
-            const fromPrompt = this.resolvePromptWorkspacePath(prompt, this.currentProjectPath);
-            if (fromPrompt)
-                workspacePath = fromPrompt;
-        }
-        catch {
-            // use default workspace
-        }
-        if (!this.jsonOutput) {
-            console.log();
-            console.log(chalk.gray('━━━ ROUTING DECISION ━━━'));
-            const r = this.lastAgentRoute;
-            console.log(chalk.gray(`Reason: ${r?.reason || 'template-instant (trivial HTML page)'}`));
-            console.log(chalk.gray(`Path: template-instant [${r?.source || 'regex'}]`));
-            console.log(chalk.gray('Model: template-service'));
-            console.log(chalk.gray('Cloud Eligible: false'));
-            console.log(chalk.gray('Cloud Selected: false'));
-            console.log(chalk.gray('━'.repeat(30)));
-            console.log();
-            console.log(chalk.cyan('⚡ Template instant path — matching template and writing index.html...'));
-        }
-        this.messages.push({ role: 'user', content: prompt });
-        const mustComplete = route?.path === 'template-instant';
-        let result = await runTemplateInstantPath(this.api, prompt, workspacePath, {
-            allowFallback: true,
-        });
-        if (!result.ok && mustComplete) {
-            result = await runTemplateInstantPath(this.api, prompt, workspacePath, {
-                allowFallback: true,
-                forceMinimalFallback: true,
-            });
-        }
-        if (!result.ok) {
-            if (!this.jsonOutput) {
-                console.log(chalk.yellow(`Template instant path skipped: ${result.error || 'no match'}`));
-            }
-            return false;
-        }
-        const summary = [
-            `Created ${result.entryPath || 'index.html'} via template-instant`,
-            result.templateName ? `(${result.templateName})` : '',
-            result.processingMs ? `in ${Math.round(result.processingMs)}ms` : '',
-            result.usedFallback ? '(minimal fallback)' : '',
-        ].filter(Boolean).join(' ');
-        this.messages.push({ role: 'assistant', content: summary });
-        const liveOutcome = createLiveOutcome();
-        liveOutcome.requiresWorkspaceChanges = true;
-        liveOutcome.workspaceHasOutput = true;
-        liveOutcome.changedFileCount = 1;
-        liveOutcome.tasksTotal = 1;
-        liveOutcome.tasksSucceeded = 1;
-        liveOutcome.answerContent = summary;
-        const evaluation = evaluateExecutorSuccess(liveOutcome);
-        this.commitAgentRunOutcome({
-            prompt,
-            originalPrompt: null,
-            taskId: null,
-            contextId: null,
-            tasksSucceeded: 1,
-            tasksTotal: 1,
-            failedTaskIds: [],
-            unfinishedTaskIds: [],
-            qualityScore: null,
-            qualityMissing: [],
-            qualityBlockers: [],
-            hasOutput: true,
-            answerContent: summary,
-            selfHealStatus: 'skipped',
-            selfHealTool: null,
-            plannerError: null,
-            executorError: null,
-            clientToolErrors: [],
-            transportErrors: [],
-            workspacePath: workspacePath || null,
-            workspaceSyncIssue: null,
-            finishedAt: Date.now(),
-        }, prompt);
-        if (!this.jsonOutput) {
-            console.log(chalk.green(`✓ ${summary}`));
-            console.log(chalk.gray('  Run: vigthoria preview'));
-            this.printAgentRunSummary(this.lastAgentRunOutcome, evaluation, 1);
-        }
-        else {
-            const routingPolicy = this.resolveAgentExecutionPolicy(prompt);
-            console.log(JSON.stringify({
-                success: evaluation.executorSucceeded,
-                mode: 'agent',
-                model: routingPolicy.selectedModel,
-                routingPolicy,
-                taskId: null,
-                contextId: null,
-                partial: false,
-                content: summary,
-                statusHeadline: evaluation.statusHeadline,
-                tasksSucceeded: 1,
-                tasksTotal: 1,
-                metadata: {
-                    source: 'template-instant',
-                    templateName: result.templateName,
-                    processingMs: result.processingMs,
-                    route: this.lastAgentRoute,
-                },
-            }, null, 2));
-        }
-        return true;
-    }
-    async tryDirectSingleFileFlow(prompt) {
-        if (!this.directPromptMode || !this.tools) {
-            return false;
-        }
-        const targetFile = this.inferTargetFileFromPrompt(prompt);
-        if (!targetFile) {
-            return false;
-        }
-        if (this.shouldBypassDirectSingleFileFlow(targetFile, prompt)) {
-            return false;
-        }
-        const readCall = {
-            tool: 'read_file',
-            args: { path: targetFile },
-        };
-        if (!this.jsonOutput) {
-            console.log(chalk.cyan(`⚙ Executing: ${readCall.tool}`));
-        }
-        const readResult = await this.tools.execute(readCall);
-        const readSummary = this.formatToolResult(readCall, readResult);
-        if (!this.jsonOutput) {
-            console.log(readResult.success ? chalk.gray(readSummary) : chalk.red(readSummary));
-        }
-        this.messages.push({ role: 'system', content: readSummary });
-        if (!readResult.success || !readResult.output) {
-            return false;
-        }
-        let rewrittenContent = this.tryDeterministicSingleFileRewrite(prompt, targetFile, readResult.output);
-        if (!rewrittenContent) {
-            const rewriteMessages = [
-                {
-                    role: 'system',
-                    content: [
-                        'You are repairing a single file for a CLI agent task.',
-                        `Return only the final contents for ${targetFile}.`,
-                        'Do not use Markdown fences.',
-                        'Do not add explanations before or after the file contents.',
-                        'Produce complete, runnable code or markup.',
-                    ].join('\n'),
-                },
-                {
-                    role: 'user',
-                    content: [
-                        `Task: ${prompt}`,
-                        `Target file: ${targetFile}`,
-                        'Current file contents:',
-                        readResult.output,
-                    ].join('\n\n'),
-                },
-            ];
-            const rewriteResponse = await this.callApi('Rewrite target file', () => this.api.chat(rewriteMessages, this.currentModel));
-            rewrittenContent = this.extractFinalFileContent(rewriteResponse.message, targetFile);
-        }
-        if (!rewrittenContent) {
-            return false;
-        }
-        const writeCall = {
-            tool: 'write_file',
-            args: {
-                path: targetFile,
-                content: rewrittenContent,
-            },
-        };
-        if (!this.jsonOutput) {
-            console.log(chalk.cyan(`⚙ Executing: ${writeCall.tool}`));
-        }
-        const writeResult = await this.tools.execute(writeCall);
-        const writeSummary = this.formatToolResult(writeCall, writeResult);
-        if (!this.jsonOutput) {
-            console.log(writeResult.success ? chalk.gray(writeSummary) : chalk.red(writeSummary));
-        }
-        this.messages.push({ role: 'system', content: writeSummary });
-        if (!writeResult.success) {
-            return false;
-        }
-        const previewGate = await this.callApi('Run Template Service preview gate', () => this.api.runTemplateServicePreviewGate(prompt, {
-            workspacePath: this.currentProjectPath,
-            projectPath: this.currentProjectPath,
-            targetPath: this.currentProjectPath,
-            rawPrompt: prompt,
-            executionSurface: 'cli',
-            clientSurface: 'cli',
-        }));
-        const success = previewGate.required ? previewGate.passed === true : true;
-        if (!success) {
-            process.exitCode = 1;
-        }
-        if (this.jsonOutput) {
-            console.log(JSON.stringify({
-                success,
-                mode: 'agent',
-                model: this.currentModel,
-                partial: false,
-                content: `Updated ${targetFile}.`,
-                metadata: {
-                    executionPath: 'direct-single-file',
-                    targetFile,
-                    previewGate,
-                },
-            }, null, 2));
-        }
-        else {
-            console.log(`Updated ${targetFile}.`);
-            if (previewGate.required) {
-                if (previewGate.passed) {
-                    console.log(chalk.gray(`Template Service preview gate: passed via ${previewGate.backendUrl || 'unknown backend'}`));
-                }
-                else {
-                    console.log(chalk.yellow(`Template Service preview gate: failed${previewGate.error ? ` - ${previewGate.error}` : ''}`));
-                }
-            }
-        }
-        return true;
-    }
     taskRequiresWorkspaceChanges(prompt) {
         return promptRequiresWorkspaceChanges(prompt);
     }
@@ -3099,15 +2643,7 @@ export class ChatCommand {
             console.log();
         }
         // Reset streaming counters for new workflow
-        this.v3IterationCount = 0;
-        this.v3ToolCallCount = 0;
-        this.v3LastActivity = Date.now();
-        this.v3StreamingStarted = false;
-        this.v3StreamedAnswerBuffer = '';
-        this.v3StreamedAnswerDisplayed = false;
-        this.v3StartSeen = false;
-        this.v3SeenToolCalls.clear();
-        this.v3SeenToolResults.clear();
+        this.streamState.reset();
         emitDeckEvent({ type: 'agent_start' });
         const taskDisplay = new TaskDisplay(['Analyse workspace', 'Execute tasks', 'Validate output', 'Self-heal'], false);
         taskDisplay.start(0);
@@ -3186,6 +2722,12 @@ export class ChatCommand {
             || isAgentRetryPrompt(contextualPrompt)
             || isBuiltContinuePrompt(contextualPrompt)
             || isBuiltRetryPrompt(contextualPrompt);
+        const initialExecutionStatus = isAgentRetryPrompt(contextualPrompt)
+            || isBuiltRetryPrompt(contextualPrompt)
+            ? 'retry'
+            : shouldResumePlan
+                ? 'continue'
+                : 'submitted';
         const agentExecutionHints = shouldResumePlan
             ? {
                 ...executionHints,
@@ -3193,18 +2735,39 @@ export class ChatCommand {
                 ...(resumeTaskIds.length > 0 ? { remaining_task_ids: resumeTaskIds } : {}),
             }
             : executionHints;
+        const previousExecutionId = this.currentSession?.activeAgentRun?.executionId || null;
+        const executionId = `cli-${Date.now()}-${randomUUID().slice(0, 8)}`;
         const workspaceContext = {
             workspacePath: workspacePath,
             projectPath: workspacePath,
             targetPath: workspacePath,
+            contextId: executionId,
+            executionId,
             ...runtimeContext,
         };
+        this.persistAgentExecutionCheckpoint({
+            executionId,
+            parentExecutionId: shouldResumePlan ? previousExecutionId : null,
+            contextId: executionId,
+            prompt,
+            originalPrompt: priorOutcome?.originalPrompt || priorOutcome?.prompt || prompt,
+            workspacePath,
+            userTier: String(this.config.get('subscription')?.plan || '').trim() || null,
+            taskType: agentTaskType,
+            workflowType,
+            status: initialExecutionStatus,
+            submittedAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+            failedTaskIds: resumeTaskIds,
+            unfinishedTaskIds: resumeTaskIds.length ? resumeTaskIds : ['agent-run-in-progress'],
+            error: null,
+        });
         // Start workspace watcher for bidirectional real-time sync
         let watcher = null;
         if (this.shouldStartWorkspaceWatcher(workspacePath)) {
             watcher = new WorkspaceWatcher({
                 workspaceRoot: workspacePath,
-                onFileChange: (relativePath, content, action) => {
+                onFileChange: (relativePath, _content, action) => {
                     this.logger.debug(`Local change detected: ${action} ${relativePath}`);
                 },
             });
@@ -3252,6 +2815,7 @@ export class ChatCommand {
                         return;
                     }
                     if (event.type === 'plan') {
+                        this.updateAgentExecutionCheckpoint({ status: 'running' });
                         taskDisplay.complete(0);
                         const tasks = event?.plan?.tasks;
                         if (Array.isArray(tasks) && tasks.length > 0) {
@@ -3277,10 +2841,7 @@ export class ChatCommand {
                             noteAnalysisToolUse(toolName, liveOutcome);
                     }
                     else if (event.type === 'complete') {
-                        const tt = Number(event.tasks_total);
-                        if (Number.isFinite(tt) && tt > 0) {
-                            liveOutcome.tasksTotal = tt;
-                        }
+                        handleRunCompleteEvent(event, liveOutcome);
                         if (Number(event.discovery_tools_used) > 0) {
                             liveOutcome.analysisToolsUsed = Math.max(liveOutcome.analysisToolsUsed, Number(event.discovery_tools_used));
                         }
@@ -3327,23 +2888,23 @@ export class ChatCommand {
             if (spinner) {
                 spinner.stop();
             }
-            if (this.v3StreamingStarted && !this.v3StreamedAnswerDisplayed) {
+            if (this.streamState.streamingStarted && !this.streamState.streamedAnswerDisplayed) {
                 this.displayV3StreamedAnswer();
             }
             const previewGate = (response.metadata?.previewGate || null);
             const workspaceHasOutput = this.api.hasAgentWorkspaceOutput(workspaceContext);
             const changedFileCount = response.changedFiles ? Object.keys(response.changedFiles).length : 0;
             const requiresWorkspaceChanges = taskRequiresWorkspaceChangesWithContext(contextualPrompt, intentContext);
-            const answerContent = normalizeAgentAnswerContent(response.content, this.v3StreamedAnswerBuffer);
+            const answerContent = normalizeAgentAnswerContent(response.content, this.streamState.streamedAnswerBuffer);
             liveOutcome.changedFileCount = changedFileCount;
             liveOutcome.requiresWorkspaceChanges = requiresWorkspaceChanges;
             liveOutcome.workspaceHasOutput = requiresWorkspaceChanges ? workspaceHasOutput : false;
             liveOutcome.answerContent = answerContent;
             const success = previewGate?.required === true
-                ? (previewGate?.passed === true || workspaceHasOutput)
+                ? previewGate?.passed === true && previewGate?.skipped !== true
                 : true;
             if (!success) {
-                if (this.isLegacyAgentFallbackAllowed()) {
+                if (previewGate?.required !== true && this.isLegacyAgentFallbackAllowed()) {
                     if (spinner) {
                         spinner.stop();
                     }
@@ -3356,25 +2917,16 @@ export class ChatCommand {
                 if (spinner) {
                     spinner.stop();
                 }
-                this.logger.error(errorMessage);
+                if (!this.jsonOutput)
+                    this.logger.error(errorMessage);
                 this.messages.push({ role: 'assistant', content: errorMessage });
-                if (this.jsonOutput) {
-                    process.exitCode = 1;
-                    console.log(JSON.stringify({
-                        success: false,
-                        mode: 'agent',
-                        model: routingPolicy.selectedModel,
-                        partial: false,
-                        content: '',
-                        error: errorMessage,
-                        metadata: { executionPath: 'v3-agent', previewGate },
-                    }, null, 2));
-                }
                 watcher?.stop();
-                return true;
-            }
-            if (!this.jsonOutput && previewGate?.required && previewGate?.passed !== true && workspaceHasOutput) {
-                console.log(chalk.yellow(`Template Service preview gate did not fully validate this output, but generated workspace files were preserved${previewGate?.error ? `: ${previewGate.error}` : '.'}`));
+                throw new CliCommandError(errorMessage, {
+                    code: 'AGENT_PREVIEW_FAILED',
+                    category: previewGate?.partialMutation === false ? 'execution' : 'partial_mutation',
+                    partialMutation: previewGate?.partialMutation ?? 'unknown',
+                    details: { executionPath: 'v3-agent', previewGate },
+                });
             }
             if (!this.jsonOutput && previewGate?.required) {
                 if (previewGate.passed) {
@@ -3407,7 +2959,10 @@ export class ChatCommand {
                 liveOutcome.answerContent = '';
             }
             const runEvaluation = evaluateExecutorSuccess(liveOutcome);
-            let executorSucceeded = runEvaluation.executorSucceeded;
+            let executorSucceeded = runEvaluation.executorSucceeded && success;
+            if (!success && !liveOutcome.executorError) {
+                liveOutcome.executorError = previewGate?.error || 'Template Service preview proof did not pass.';
+            }
             let finalAnswer = answerContent;
             if (isToolEvidenceStubAnswer(finalAnswer)) {
                 finalAnswer = '';
@@ -3427,7 +2982,7 @@ export class ChatCommand {
                 executorSucceeded = false;
             }
             if (!this.jsonOutput && !this.directPromptMode) {
-                if (this.v3StreamedAnswerDisplayed) {
+                if (this.streamState.streamedAnswerDisplayed) {
                     // Highlighted report already printed once above.
                 }
                 else if (isSubstantiveAgentAnswer(finalAnswer)) {
@@ -3523,9 +3078,6 @@ export class ChatCommand {
             }
             taskDisplay.finalize();
             // ────────────────────────────────────────────────────────────────
-            if (!executorSucceeded) {
-                process.exitCode = 1;
-            }
             this.commitAgentRunOutcome({
                 prompt,
                 originalPrompt: null,
@@ -3552,15 +3104,38 @@ export class ChatCommand {
                     : null,
                 finishedAt: Date.now(),
             }, prompt);
+            this.updateAgentExecutionCheckpoint({
+                status: executorSucceeded ? 'completed' : 'failed',
+                contextId: response.contextId || executionId,
+                failedTaskIds: [...liveOutcome.failedTaskIds],
+                unfinishedTaskIds: [...liveOutcome.unfinishedTaskIds],
+                error: executorSucceeded
+                    ? null
+                    : (liveOutcome.executorError || liveOutcome.plannerError || runEvaluation.statusHeadline),
+            });
             if (!this.jsonOutput && !this.directPromptMode) {
                 if (this.lastAgentRunOutcome) {
                     this.printAgentRunSummary(this.lastAgentRunOutcome, runEvaluation, changedFileCount);
                 }
             }
+            if (!executorSucceeded) {
+                throw new CliCommandError(runEvaluation.statusHeadline, {
+                    code: 'AGENT_INCOMPLETE',
+                    category: response.partial === true || liveOutcome.tasksSucceeded > 0 ? 'partial_mutation' : 'execution',
+                    partialMutation: response.partial === true || liveOutcome.tasksSucceeded > 0 ? 'unknown' : false,
+                    details: {
+                        mode: 'agent',
+                        model: routingPolicy.selectedModel,
+                        taskId: response.taskId || null,
+                        contextId: response.contextId || null,
+                        statusHeadline: runEvaluation.statusHeadline,
+                        tasksSucceeded: liveOutcome.tasksSucceeded,
+                        tasksTotal: liveOutcome.tasksTotal,
+                        previewGate,
+                    },
+                });
+            }
             if (this.jsonOutput) {
-                if (!executorSucceeded) {
-                    process.exitCode = 1;
-                }
                 emitAgentJsonOutput({
                     success: executorSucceeded,
                     mode: 'agent',
@@ -3593,6 +3168,11 @@ export class ChatCommand {
         catch (error) {
             this.stopV3IdleWatch();
             watcher?.stop();
+            if (error instanceof CliCommandError) {
+                if (spinner)
+                    spinner.stop();
+                throw error;
+            }
             if (!this.api.hasAgentWorkspaceOutput(workspaceContext)) {
                 const recovered = await this.tryRecoverV3ServiceAndRetry(executionPrompt, prompt, workspaceContext, routingPolicy, spinner, error);
                 if (recovered) {
@@ -3653,25 +3233,13 @@ export class ChatCommand {
                 workspaceSyncIssue: null,
                 finishedAt: Date.now(),
             }, prompt);
-            if (!this.jsonOutput) {
-                process.exitCode = 1;
-            }
-            if (this.jsonOutput) {
-                process.exitCode = 1;
-                console.log(JSON.stringify({
-                    success: false,
-                    mode: 'agent',
-                    model: routingPolicy.selectedModel,
-                    partial: liveOutcome.tasksSucceeded > 0 && liveOutcome.tasksTotal > 0,
-                    content: '',
-                    error: errorMessage,
-                    statusHeadline: evaluateExecutorSuccess(liveOutcome).statusHeadline,
-                    tasksSucceeded: liveOutcome.tasksSucceeded,
-                    tasksTotal: liveOutcome.tasksTotal,
-                    metadata: { executionPath: 'v3-agent' },
-                }, null, 2));
-            }
-            else if (!this.directPromptMode) {
+            this.updateAgentExecutionCheckpoint({
+                status: 'failed',
+                failedTaskIds: [...liveOutcome.failedTaskIds],
+                unfinishedTaskIds: [...liveOutcome.unfinishedTaskIds],
+                error: liveOutcome.executorError || safeDetail || 'Connection aborted',
+            });
+            if (!this.jsonOutput && !this.directPromptMode) {
                 const failedEval = evaluateExecutorSuccess({
                     ...liveOutcome,
                     executorFailed: true,
@@ -3684,7 +3252,20 @@ export class ChatCommand {
                     this.printAgentRunSummary(this.lastAgentRunOutcome, failedEval, 0);
                 }
             }
-            return true;
+            throw new CliCommandError(errorMessage, {
+                code: 'AGENT_EXECUTION_FAILED',
+                category: liveOutcome.tasksSucceeded > 0 ? 'partial_mutation' : 'execution',
+                partialMutation: liveOutcome.tasksSucceeded > 0 ? 'unknown' : false,
+                details: {
+                    executionPath: 'v3-agent',
+                    mode: 'agent',
+                    model: routingPolicy.selectedModel,
+                    tasksSucceeded: liveOutcome.tasksSucceeded,
+                    tasksTotal: liveOutcome.tasksTotal,
+                    statusHeadline: evaluateExecutorSuccess(liveOutcome).statusHeadline,
+                },
+                cause: error,
+            });
         }
     }
     async tryRecoverV3ServiceAndRetry(executionPrompt, rawPrompt, workspaceContext, routingPolicy, spinner, error) {
@@ -3698,12 +3279,13 @@ export class ChatCommand {
         if (!this.jsonOutput) {
             console.log(chalk.yellow(`V3 recovery: ${recovery.message} Retrying once...`));
         }
-        this.v3IterationCount = 0;
-        this.v3ToolCallCount = 0;
-        this.v3LastActivity = Date.now();
-        this.v3StreamingStarted = false;
-        this.v3StartSeen = false;
+        this.streamState.iterationCount = 0;
+        this.streamState.toolCallCount = 0;
+        this.streamState.noteActivity();
+        this.streamState.streamingStarted = false;
+        this.streamState.startSeen = false;
         try {
+            this.updateAgentExecutionCheckpoint({ status: 'running' });
             const retryPriorPrompt = this.getPreviousActionablePrompt();
             const retryContext = { priorPrompt: retryPriorPrompt || null };
             const retryTaskType = inferAgentTaskTypeWithContext(rawPrompt, retryContext);
@@ -3730,27 +3312,40 @@ export class ChatCommand {
             if (spinner && spinner.isSpinning) {
                 spinner.stop();
             }
-            if (this.v3StreamingStarted) {
+            if (this.streamState.streamingStarted) {
                 process.stdout.write('\n');
             }
+            if (retryResponse.partial === true) {
+                this.updateAgentExecutionCheckpoint({
+                    status: 'failed',
+                    contextId: retryResponse.contextId || this.currentSession?.activeAgentRun?.contextId,
+                    error: 'Recovery run returned a partial result.',
+                });
+                return false;
+            }
             if (this.jsonOutput) {
-                console.log(JSON.stringify({
+                emitAgentJsonOutput({
                     success: true,
                     mode: 'agent',
                     model: routingPolicy.selectedModel,
                     routingPolicy,
                     taskId: retryResponse.taskId || null,
                     contextId: retryResponse.contextId || null,
-                    partial: retryResponse.partial === true,
+                    partial: false,
                     content: retryResponse.content || 'V3 agent workflow completed after recovery.',
                     metadata: { ...(retryResponse.metadata || {}), recoveryAttempted: true },
-                }, null, 2));
+                });
             }
-            else if (!this.v3StreamingStarted && retryResponse.content) {
+            else if (!this.streamState.streamingStarted && retryResponse.content) {
                 console.log(chalk.gray(`Agent routing: ${routingPolicy.cloudSelected ? 'Vigthoria Cloud' : 'V3 Agent'}`));
                 console.log(retryResponse.content);
             }
             this.messages.push({ role: 'assistant', content: retryResponse.content || 'V3 agent workflow completed after recovery.' });
+            this.updateAgentExecutionCheckpoint({
+                status: 'completed',
+                contextId: retryResponse.contextId || this.currentSession?.activeAgentRun?.contextId,
+                error: null,
+            });
             return true;
         }
         catch {
@@ -4357,6 +3952,13 @@ export class ChatCommand {
     }
     inferTargetFilesFromPrompt(prompt) {
         const candidates = [];
+        const sourceExtensions = new Set([
+            '.c', '.cc', '.cpp', '.cs', '.css', '.csv', '.go', '.graphql', '.h', '.hpp',
+            '.htm', '.html', '.ini', '.java', '.js', '.json', '.jsx', '.less', '.md',
+            '.mjs', '.php', '.prisma', '.py', '.rb', '.rs', '.sass', '.scss', '.sh',
+            '.sql', '.svelte', '.svg', '.toml', '.ts', '.tsx', '.txt', '.vue', '.xml',
+            '.yaml', '.yml',
+        ]);
         const matches = Array.from(prompt.matchAll(/([A-Za-z0-9_./-]+\.[A-Za-z0-9_-]+)/g));
         for (const match of matches) {
             const candidate = match[1];
@@ -4364,7 +3966,15 @@ export class ChatCommand {
                 continue;
             }
             const resolved = path.resolve(this.currentProjectPath, candidate);
-            if (resolved.startsWith(this.currentProjectPath)) {
+            const extension = path.extname(candidate).toLowerCase();
+            // Dotted API/property references (for example `element.style`) are not
+            // workspace files. Accept a non-standard extension only when that exact
+            // path already exists, so real uncommon project files remain addressable.
+            if (!sourceExtensions.has(extension) && !fs.existsSync(resolved)) {
+                continue;
+            }
+            const relative = path.relative(this.currentProjectPath, resolved);
+            if (relative && !relative.startsWith('..') && !path.isAbsolute(relative)) {
                 if (!candidates.includes(candidate)) {
                     candidates.push(candidate);
                 }
@@ -4375,36 +3985,6 @@ export class ChatCommand {
     inferTargetFileFromPrompt(prompt) {
         return this.inferTargetFilesFromPrompt(prompt)[0] || null;
     }
-    workspaceContainsHtmlEntry(rootDir) {
-        const stack = [rootDir];
-        while (stack.length > 0) {
-            const currentDir = stack.pop();
-            if (!currentDir) {
-                continue;
-            }
-            let entries = [];
-            try {
-                entries = fs.readdirSync(currentDir, { withFileTypes: true });
-            }
-            catch {
-                continue;
-            }
-            for (const entry of entries) {
-                if (entry.name === 'node_modules' || entry.name === '.git') {
-                    continue;
-                }
-                const fullPath = path.join(currentDir, entry.name);
-                if (entry.isDirectory()) {
-                    stack.push(fullPath);
-                    continue;
-                }
-                if (entry.isFile() && entry.name.toLowerCase().endsWith('.html')) {
-                    return true;
-                }
-            }
-        }
-        return false;
-    }
     shouldBypassDirectSingleFileFlow(targetFile, prompt) {
         const referencedFiles = this.inferTargetFilesFromPrompt(prompt);
         const editableFiles = referencedFiles.filter((filePath) => !this.isProtectedFileReferenceSafe(prompt, filePath));
@@ -4421,36 +4001,6 @@ export class ChatCommand {
             return true;
         return false;
     }
-    shouldPreferLocalAgentLoop(prompt) {
-        if (this.shouldRequireV3AgentWorkflow(prompt)) {
-            return false;
-        }
-        const forceV3 = /^(1|true|yes)$/i.test(String(process.env.VIGTHORIA_FORCE_V3_AGENT || ''));
-        if (forceV3) {
-            return false;
-        }
-        if (this.isBrowserTaskPrompt(prompt)) {
-            return false;
-        }
-        // Product default: Agent mode routes through V3.
-        // Local loop is opt-in for explicit offline/debug scenarios only.
-        // Explicit local paths now influence project root resolution, not routing mode.
-        const preferLocalOptIn = /^(1|true|yes)$/i.test(String(process.env.VIGTHORIA_PREFER_LOCAL_AGENT_LOOP || ''));
-        if (!preferLocalOptIn) {
-            return false;
-        }
-        const runtime = this.getRuntimeEnvironmentContext();
-        if (this.directPromptMode && this.isRepoGroundedPrompt(prompt)) {
-            return false;
-        }
-        if (!runtime.serverBindableWorkspace) {
-            return true;
-        }
-        if (!this.directPromptMode) {
-            return true;
-        }
-        return runtime.platform !== 'linux';
-    }
     getRuntimeEnvironmentContext() {
         const osPlatform = os.platform();
         const platform = osPlatform === 'win32'
@@ -4538,16 +4088,6 @@ export class ChatCommand {
         ];
         return protectedPhrases.some((phrase) => normalizedPrompt.includes(phrase));
     }
-    isProtectedFileReference(prompt, filePath) {
-        const escapedPath = filePath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-        const protectedPatterns = [
-            new RegExp(`do not modify\\s+[-\u001f\s\-\"][` + "'" + `]?${escapedPath}[` + "'" + `]?`, 'i'),
-            new RegExp(`don't modify\\s+[-\u001f\s\-\"][` + "'" + `]?${escapedPath}[` + "'" + `]?`, 'i'),
-            new RegExp(`leave\\s+[-\u001f\s\-\"][` + "'" + `]?${escapedPath}[` + "'" + `]?\\s+unchanged`, 'i'),
-            new RegExp(`without modifying\\s+[-\u001f\s\-\"][` + "'" + `]?${escapedPath}[` + "'" + `]?`, 'i'),
-        ];
-        return protectedPatterns.some((pattern) => pattern.test(prompt));
-    }
     buildContinuationPrompt() {
         const { discovery, searchFailed } = this.agentToolEvidence;
         const evidenceLines = [];
@@ -4641,109 +4181,10 @@ export class ChatCommand {
         return lines.join('\n');
     }
     extractToolCalls(message) {
-        const calls = [];
-        const seen = new Set();
-        const addCall = (call) => {
-            if (!call)
-                return;
-            const key = `${call.tool}::${JSON.stringify(call.args)}`;
-            if (!seen.has(key)) {
-                seen.add(key);
-                calls.push(call);
-            }
-        };
-        const wrapperRegex = /<tool_call>([\s\S]*?)<\/tool_call>/g;
-        for (const match of message.matchAll(wrapperRegex)) {
-            addCall(this.parseToolPayload(match[1] || ''));
-        }
-        for (const call of this.parseLegacyFunctionToolCalls(message)) {
-            addCall(call);
-        }
-        return calls;
-    }
-    normalizeCliToolName(name) {
-        const normalized = name.trim().toLowerCase();
-        const aliases = {
-            list_directory: 'list_dir',
-            listdirectory: 'list_dir',
-            ls: 'list_dir',
-            dir: 'list_dir',
-            readfile: 'read_file',
-            writefile: 'write_file',
-            editfile: 'edit_file',
-            shell: 'bash',
-            command: 'bash',
-            run_command: 'bash',
-        };
-        return aliases[normalized] || normalized;
-    }
-    parseLegacyFunctionToolCalls(message) {
-        const calls = [];
-        const functionRegex = /<function\s*=\s*["']?([A-Za-z0-9_-]+)["']?>\s*([\s\S]*?)(?:<\/function>|$)/gi;
-        for (const match of message.matchAll(functionRegex)) {
-            const tool = this.normalizeCliToolName(match[1] || '');
-            if (!tool)
-                continue;
-            const body = match[2] || '';
-            const args = {};
-            const parameterRegex = /<parameter\s*=\s*["']?([A-Za-z0-9_-]+)["']?>\s*([\s\S]*?)(?=<parameter\s*=|<\/function>|<\/parameter>|$)/gi;
-            for (const paramMatch of body.matchAll(parameterRegex)) {
-                const key = paramMatch[1] || '';
-                if (!key)
-                    continue;
-                args[key] = (paramMatch[2] || '').replace(/<\/parameter>\s*$/i, '').trim();
-            }
-            calls.push({ tool, args });
-        }
-        return calls;
-    }
-    parseToolPayload(payload) {
-        const normalized = payload.trim();
-        if (!normalized) {
-            return null;
-        }
-        try {
-            const parsed = JSON.parse(normalized);
-            if (typeof parsed.tool !== 'string') {
-                return null;
-            }
-            const args = {};
-            if (parsed.args && typeof parsed.args === 'object') {
-                for (const [key, value] of Object.entries(parsed.args)) {
-                    args[key] = typeof value === 'string' ? value : JSON.stringify(value);
-                }
-            }
-            return { tool: this.normalizeCliToolName(parsed.tool), args };
-        }
-        catch {
-            return null;
-        }
+        return this.toolCallParser.extract(message);
     }
     stripToolPayloads(message) {
-        return message
-            .replace(/<tool_call>[\s\S]*?<\/tool_call>/g, '')
-            .replace(/<function\s*=\s*["']?[A-Za-z0-9_-]+["']?>[\s\S]*?(?:<\/function>|$)/gi, '')
-            .trim();
-    }
-    extractFinalFileContent(message, targetFile) {
-        const trimmed = message.trim();
-        if (!trimmed) {
-            return '';
-        }
-        const fencedMatch = trimmed.match(/```(?:[A-Za-z0-9_-]+)?\n([\s\S]*?)```/);
-        if (fencedMatch && fencedMatch[1]) {
-            return fencedMatch[1].trim();
-        }
-        const extension = path.extname(targetFile).toLowerCase();
-        if (extension === '.html') {
-            const htmlStart = trimmed.indexOf('<!DOCTYPE html>') >= 0
-                ? trimmed.indexOf('<!DOCTYPE html>')
-                : trimmed.indexOf('<html');
-            if (htmlStart >= 0) {
-                return trimmed.slice(htmlStart).trim();
-            }
-        }
-        return trimmed;
+        return this.toolCallParser.strip(message);
     }
     /**
      * Synthesize a best-effort answer from tool evidence already collected
@@ -4772,8 +4213,8 @@ export class ChatCommand {
     resolveDirectModeCompletion(prompt, visibleText) {
         // Sanitize first — strip tool output and echoed instructions before
         // deciding if the model actually answered the question.
-        const sanitized = this.sanitizeDirectModeOutput((visibleText || '').trim());
-        if (sanitized && !this.isDirectModeFollowUpQuestion(sanitized)) {
+        const sanitized = sanitizeDirectModeOutput((visibleText || '').trim());
+        if (sanitized && !isDirectModeFollowUpQuestion(sanitized)) {
             return sanitized;
         }
         const fallback = this.buildLocalAnalysisFallback(prompt);
@@ -4782,95 +4223,6 @@ export class ChatCommand {
         }
         return sanitized || 'Task complete.';
     }
-    /**
-     * Strip system-prompt echoes, tool execution headers, grounding-rule
-     * parroting, recovery banners, and multi-line tool output blocks from
-     * the model's final answer so that --json output contains only the
-     * substantive answer.
-     */
-    sanitizeDirectModeOutput(text) {
-        let cleaned = this.stripHiddenThoughtBlocks(text);
-        cleaned = cleaned
-            .replace(/<\|mask_start\|>[\s\S]*?<\|mask_end\|>/g, '')
-            .replace(/<think>[\s\S]*?<\/think>/gi, '')
-            .replace(/<\|(?:mask_start|mask_end)\|>/g, '');
-        // ── Phase 1: Strip entire tool-output blocks ──
-        // Matches "Tool <name> succeeded/FAILED." through the next blank line,
-        // next tool header, or end-of-string.  The DOTALL-like [\s\S]*? is
-        // terminated by whichever boundary comes first.
-        cleaned = cleaned.replace(/Tool (?:read_file|grep|list_dir|glob|bash|write_file|edit_file|ssh_exec|task|multi_edit|codebase_search) (?:succeeded|FAILED)\.[\s\S]*?(?=\nTool |\n\n|$)/g, '');
-        // ── Phase 2: Strip echoed system-prompt / grounding lines ──
-        const contaminationPatterns = [
-            /^\[Agent recovered from backend failure[^\]]*\]\s*/m,
-            /^Evidence gathered before backend failure:?\s*/m,
-            /^MANDATORY CROSS-FILE EVIDENCE[^\n]*\n?/m,
-            /^CONFIRMED CONFLICTING keys[^\n]*/m,
-            /^Keys found ONLY in [^\n]*/m,
-            /^CONSTRAINT: Your answer MUST[^\n]*/m,
-            /^GROUNDING CHECK:[^\n]*/m,
-            /^VERIFICATION PROTOCOL[^\n]*/m,
-            /^Quality gate:[^\n]*/m,
-            /^Evidence collected:[^\n]*/m,
-            /^Warning: \d+ search tool[^\n]*/m,
-            /^Tool results received for direct mode[^\n]*/m,
-            /^Step \d+ complete\. Task:[^\n]*/m,
-            /^Original user request:[^\n]*/m,
-            /^Project root boundary:[^\n]*/m,
-            /^Do not declare success[^\n]*/m,
-            /^Keep working from concrete[^\n]*/m,
-            /^Continue with tool calls if more[^\n]*/m,
-            /^IMPORTANT: Your response must be ONLY[^\n]*/m,
-            /^Because this is a debugging[^\n]*/m,
-            /^If a user is asking which file[^\n]*/m,
-            /^If the request is already[^\n]*/m,
-            /^If more work is required[^\n]*/m,
-            /^Do not ask follow-up[^\n]*/m,
-            /^CRITICAL GROUNDING RULE:[^\n]*/m,
-            /^CROSS-FILE ATTRIBUTION:[^\n]*/m,
-            /^EVIDENCE-GROUNDING RULE:[^\n]*/m,
-            /^CROSS-FILE RULE:[^\n]*/m,
-            /^OUTPUT DISCIPLINE:[^\n]*/m,
-            /^Vigthoria CLI agent operating contract\.[^\n]*/m,
-            /^You are operating inside the project root:[^\n]*/m,
-            /^CRITICAL: Begin working on the user's task[^\n]*/m,
-            /^File: \S+\s*$/m,
-            /^Search status: \S+\s*$/m,
-            /^Output:\s*$/m,
-            /^\[\.\.\. ?truncated\]\s*$/m,
-            /^---\s*$/m,
-        ];
-        for (const pat of contaminationPatterns) {
-            cleaned = cleaned.replace(pat, '');
-        }
-        // ── Phase 3: Paragraph-level filter ──
-        // Split into paragraph blocks and discard any that are pure tool
-        // output, file content dumps, or system-instruction echoes.
-        const paragraphs = cleaned.split(/\n\n+/);
-        const kept = paragraphs.filter(p => {
-            const t = p.trim();
-            if (!t)
-                return false;
-            // Discard lingering tool headers
-            if (/^Tool (?:read_file|grep|list_dir|glob|bash|write_file) /i.test(t))
-                return false;
-            // Discard paragraphs that are mostly file-content dumps (many
-            // lines of code with typical code tokens like { } ; = function class)
-            const lines = t.split('\n');
-            if (lines.length > 6) {
-                const codeLines = lines.filter(l => /[{};=]|function |class |const |let |var |import |export |switch |case /.test(l));
-                if (codeLines.length / lines.length > 0.4)
-                    return false;
-            }
-            return true;
-        });
-        cleaned = kept.join('\n\n');
-        // Collapse multiple blank lines
-        cleaned = cleaned.replace(/\n{3,}/g, '\n\n').trim();
-        return cleaned || this.stripHiddenThoughtBlocks(text);
-    }
-    isDirectModeFollowUpQuestion(text) {
-        return /^(would you like me|do you want me|which aspect|what aspect|can you clarify|could you clarify|should i focus on|i will follow|i understand|i('ll| will) adhere|provide your|waiting for)/i.test(text.trim());
-    }
     buildLocalAnalysisFallback(prompt) {
         if (!/(analyse|analyze|audit|overview|inspect|review|summari[sz]e|actual state)/i.test(prompt)) {
             return '';
@@ -4912,42 +4264,6 @@ export class ChatCommand {
             return '';
         }
     }
-    tryDeterministicSingleFileRewrite(prompt, targetFile, currentContent) {
-        const extension = path.extname(targetFile).toLowerCase();
-        if (extension !== '.html') {
-            return null;
-        }
-        const exactText = this.extractExactTextRequirement(prompt);
-        if (!exactText) {
-            return null;
-        }
-        if (!/hero\s+(?:paragraph|copy)/i.test(prompt)) {
-            return null;
-        }
-        const heroCopyPattern = /(<p[^>]*class=["'][^"']*hero-copy[^"']*["'][^>]*>)([\s\S]*?)(<\/p>)/i;
-        if (heroCopyPattern.test(currentContent)) {
-            const nextContent = currentContent.replace(heroCopyPattern, `$1${exactText}$3`);
-            return nextContent !== currentContent ? nextContent : null;
-        }
-        const heroParagraphPattern = /(<main[^>]*class=["'][^"']*hero[^"']*["'][^>]*>[\s\S]*?<p[^>]*>)([\s\S]*?)(<\/p>)/i;
-        if (heroParagraphPattern.test(currentContent)) {
-            const nextContent = currentContent.replace(heroParagraphPattern, `$1${exactText}$3`);
-            return nextContent !== currentContent ? nextContent : null;
-        }
-        return null;
-    }
-    extractExactTextRequirement(prompt) {
-        const match = prompt.match(/reads exactly:\s*([\s\S]*?)(?:\s+Do not\b|\s+Do\b|$)/i);
-        if (!match || !match[1]) {
-            return null;
-        }
-        const normalized = match[1]
-            .trim()
-            .replace(/^[`"']+/, '')
-            .replace(/[`"']+$/, '')
-            .trim();
-        return normalized || null;
-    }
     async executeToolCalls(toolCalls) {
         if (!this.tools) {
             throw new Error('Agent tools are not initialized.');
@@ -5056,17 +4372,41 @@ export class ChatCommand {
             sessionSummary: this.currentSession.memorySummary || '',
         });
     }
+    persistAgentExecutionCheckpoint(checkpoint) {
+        if (!this.currentSession) {
+            this.currentSession = this.sessionManager.create(this.currentProjectPath, this.currentModel, this.agentMode, this.operatorMode);
+        }
+        this.currentSession.activeAgentRun = checkpoint;
+        this.saveSession();
+    }
+    updateAgentExecutionCheckpoint(update) {
+        if (!this.currentSession?.activeAgentRun) {
+            return;
+        }
+        if (update.status) {
+            assertAgentStatusTransition(this.currentSession.activeAgentRun.status, update.status);
+        }
+        this.currentSession.activeAgentRun = {
+            ...this.currentSession.activeAgentRun,
+            ...update,
+            updatedAt: new Date().toISOString(),
+        };
+        this.saveSession();
+    }
     async requestPermission(action) {
         if (this.autoApprove) {
             return true;
         }
+        if (this.jsonOutput) {
+            return false;
+        }
         const rl = readline.createInterface({
             input: process.stdin,
             output: process.stdout,
         });
         console.log(action);
         const answer = await new Promise((resolve) => {
-            rl.question(chalk.yellow('Approve? [y]es / [n]o / [a]ll this turn / [p]ersist: '), resolve);
+            rl.question(chalk.yellow('Approve? [y]es / [n]o / [a] exact operation this turn / [p]ersist exact operation: '), resolve);
         });
         rl.close();
         const normalized = answer.trim().toLowerCase();