@the-open-engine/zeroshot 6.34.2 → 6.34.3

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@the-open-engine/zeroshot",
-  "version": "6.34.2",
+  "version": "6.34.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@the-open-engine/zeroshot",
-      "version": "6.34.2",
+      "version": "6.34.3",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-open-engine/zeroshot",
-  "version": "6.34.2",
+  "version": "6.34.3",
   "description": "Independent executor–verifier orchestration for software changes.",
   "main": "src/orchestrator.js",
   "bin": {

package/src/agent/agent-lifecycle.js

@@ -24,6 +24,7 @@ const { findPlatformMismatchReason } = require('./validation-platform');
 const { calculateRateLimitDelay, isRateLimitError } = require('./rate-limit-backoff');
 const { updateAgentProviderSession } = require('./provider-session');
 const { rebuildProviderSessionAfterCommit } = require('./agent-task-executor');
+const providerFailures = require('./provider-terminal-failure');
 const {
   buildStructuredOutputClusterFailure,
   isStructuredOutputInvalidError,
@@ -660,6 +661,7 @@ async function runTaskAttempt(agent, triggeringMessage) {
     error.code = result.code || result.errorType || null;
     error.taskId = result.taskId || null;
     error.vertexModelError = result.vertexModelError || null;
+    providerFailures.decorateError(error, result.providerFailure);
     throw error;
   }
 
@@ -795,6 +797,16 @@ ${'='.repeat(80)}`);
 
   // Non-validator agents: publish error and stop
   agent.state = 'error';
+  const workerFailure = providerFailures.workerFailure(error);
+  // Synchronous terminal listeners must see the final failure truth before persisting a stop.
+  agent.cluster.failureInfo = providerFailures.buildFinalFailureInfo({
+    agent,
+    error,
+    attempts: failureAttempts,
+    worker: workerFailure,
+    unsupportedCapability,
+    structuredOutputInvalid,
+  });
 
   // Hook failure: fail the whole cluster so it gets stopped + persisted (prevents deadlocked "running" clusters).
   if (error?.hookFailure) {
@@ -872,25 +884,14 @@ ${'='.repeat(80)}`);
     });
   }
 
-  // Save failure info to cluster for resume capability
-  agent.cluster.failureInfo = {
-    ...(error?.terminationExhausted ? agent.cluster.failureInfo : {}),
-    agentId: agent.id,
-    taskId: error?.taskId || agent.currentTaskId,
-    iteration: agent.iteration,
-    error: error.message,
+  providerFailures.publishCriticalFailure({
+    agent,
+    error,
     attempts: failureAttempts,
-    ...(unsupportedCapability
-      ? {
-          code: error.code,
-          permanent: true,
-          provider: error.provider,
-          capability: error.capability,
-        }
-      : {}),
-    ...(structuredOutputInvalid ? { code: error.code, details: error.details ?? null } : {}),
-    timestamp: Date.now(),
-  };
+    worker: workerFailure,
+    unsupportedCapability,
+    structuredOutputInvalid,
+  });
 
   // Publish error to message bus for visibility in logs
   agent._publish({
@@ -900,7 +901,7 @@ ${'='.repeat(80)}`);
       text: `Task execution failed after ${failureAttempts} attempts: ${error.message}`,
       data: {
         error: error.message,
-        stack: error.stack,
+        stack: error?.provider ? undefined : error.stack,
         hookFailure: error?.hookFailure === true,
         restartExhausted: error?.restartExhausted === true,
         terminationExhausted: error?.terminationExhausted === true,
@@ -911,6 +912,10 @@ ${'='.repeat(80)}`);
         iteration: agent.iteration,
         taskId: error?.taskId || agent.currentTaskId,
         attempts: failureAttempts,
+        ...providerFailures.receiptFields(error),
+        ...(error?.provider
+          ? { workerCode: workerFailure.code, workerReason: workerFailure.reason }
+          : {}),
         ...(unsupportedCapability
           ? {
               code: error.code,

package/src/agent/agent-task-executor.js

@@ -54,6 +54,10 @@ const {
   validateCompletedResumeIdentity,
 } = require('./provider-session');
 const { extractClaudeVertexModelError } = require('./output-extraction');
+const {
+  extractProviderFailure,
+  redactTerminalFailureForControlPlane,
+} = require('./provider-terminal-failure');
 const {
   createStructuredOutputInvalidError,
   isStructuredOutputInvalidError,
@@ -66,6 +70,8 @@ const MAX_LIVE_OUTPUT_BYTES = 512 * 1024;
 const MAX_LIVE_OUTPUT_RECORDS = 512;
 const CONTROL_PLANE_OMISSION_MARKER_BYTES = 1024;
 const LOG_READ_CHUNK_BYTES = 64 * 1024;
+const MAX_FAILURE_ERROR_BYTES = 4096;
+const FAILURE_ERROR_TRUNCATION_SUFFIX = '… [truncated]';
 function runCommandWithTimeout(command, args, options = {}, callback = null) {
   const timeout = options.timeout ?? 30000;
   if (timeout <= 0) {
@@ -175,6 +181,22 @@ function buildClaudeEnv(modelSpec, options = {}) {
 function sanitizeErrorMessage(error) {
   if (!error) return null;
 
+  const original = String(error);
+  const suffixBytes = Buffer.byteLength(FAILURE_ERROR_TRUNCATION_SUFFIX);
+  const contentBudget = MAX_FAILURE_ERROR_BYTES - suffixBytes;
+  let boundedError = original;
+  if (Buffer.byteLength(original) > MAX_FAILURE_ERROR_BYTES) {
+    let bytes = 0;
+    let prefix = '';
+    for (const character of original) {
+      const characterBytes = Buffer.byteLength(character);
+      if (bytes + characterBytes > contentBudget) break;
+      prefix += character;
+      bytes += characterBytes;
+    }
+    boundedError = `${prefix}${FAILURE_ERROR_TRUNCATION_SUFFIX}`;
+  }
+
   // Patterns that look like TypeScript type annotations (not real error messages)
   const typeAnnotationPatterns = [
     /^string\s*\|\s*null$/i,
@@ -187,7 +209,7 @@ function sanitizeErrorMessage(error) {
     /^[A-Z][a-zA-Z]*\s*\|\s*(?:null|undefined)$/, // e.g., "Error | null"
   ];
 
-  const trimmedError = error.trim();
+  const trimmedError = boundedError.trim();
 
   // Check if it's a union type like "string | number | boolean" (ReDoS-safe approach)
   const unionParts = trimmedError.split(/\s*\|\s*/);
@@ -196,14 +218,16 @@ function sanitizeErrorMessage(error) {
   for (const pattern of typeAnnotationPatterns) {
     if (pattern.test(trimmedError) || isUnionType) {
       console.warn(
-        `[agent-task-executor] WARNING: Error message looks like a TypeScript type annotation: "${error}". ` +
+        `[agent-task-executor] WARNING: Error message looks like a TypeScript type annotation: "${boundedError}". ` +
           `This indicates corrupted data. Replacing with generic error.`
       );
-      return `Task failed with corrupted error data (original: "${error}")`;
+      return sanitizeErrorMessage(
+        `Task failed with corrupted error data (original: "${boundedError}")`
+      );
     }
   }
 
-  return error;
+  return boundedError;
 }
 
 function safeTail(text, maxChars) {
@@ -295,6 +319,30 @@ function logNoMessagesReturned({ taskId, output, statusOutput, debug }) {
   console.error('[AgentTaskExecutor] Claude CLI returned no messages', payload);
 }
 
+function extractKnownCliFailure({ fullOutput, taskId, statusOutput, debug }) {
+  if (fullOutput.includes('exceeds maximum allowed size') || fullOutput.includes('256KB')) {
+    return sanitizeErrorMessage(
+      `FILE TOO LARGE (Claude Code 256KB limit). ` +
+        `Use offset and limit parameters when reading large files. ` +
+        `Example: Read tool with offset=0, limit=1000 to read first 1000 lines.`
+    );
+  }
+  if (fullOutput.includes('only prompt commands are supported in streaming mode')) {
+    return sanitizeErrorMessage(
+      `STREAMING MODE ERROR: Agent tried to use interactive tools in streaming mode. ` +
+        `This usually happens with AskUserQuestion or interactive prompts. ` +
+        `Zeroshot agents must run non-interactively.`
+    );
+  }
+  if (fullOutput.includes('No messages returned')) {
+    logNoMessagesReturned({ taskId, output: fullOutput, statusOutput, debug });
+    return sanitizeErrorMessage(
+      `Claude CLI returned no messages. This is usually transient; retry the task or resume the cluster.`
+    );
+  }
+  return null;
+}
+
 /**
  * Extract error context from task output.
  * Shared by both isolated and non-isolated modes.
@@ -307,7 +355,15 @@ function logNoMessagesReturned({ taskId, output, statusOutput, debug }) {
  * @param {Object} [params.debug] - Additional debug context for logging
  * @returns {string|null} Sanitized error context or null if extraction failed
  */
-function extractErrorContext({ output, statusOutput, taskId, isNotFound = false, debug }) {
+function extractErrorContext({
+  output,
+  statusOutput,
+  taskId,
+  isNotFound = false,
+  providerName = getDefaultProviderId(),
+  providerFailure = null,
+  debug,
+}) {
   // Task not found - explicit error
   if (isNotFound) {
     return sanitizeErrorMessage(`Task ${taskId} not found (may have crashed or been killed)`);
@@ -321,37 +377,15 @@ function extractErrorContext({ output, statusOutput, taskId, isNotFound = false,
     }
   }
 
-  // KNOWN CLAUDE CODE LIMITATIONS - detect and provide actionable guidance
-  const fullOutput = output || '';
-
-  // 256KB file limit error
-  if (fullOutput.includes('exceeds maximum allowed size') || fullOutput.includes('256KB')) {
-    return sanitizeErrorMessage(
-      `FILE TOO LARGE (Claude Code 256KB limit). ` +
-        `Use offset and limit parameters when reading large files. ` +
-        `Example: Read tool with offset=0, limit=1000 to read first 1000 lines.`
-    );
+  const terminalFailure = providerFailure || extractProviderFailure(output, providerName);
+  if (terminalFailure) {
+    return sanitizeErrorMessage(terminalFailure.error);
   }
 
-  // Streaming mode error (interactive tools in non-interactive mode)
-  if (fullOutput.includes('only prompt commands are supported in streaming mode')) {
-    return sanitizeErrorMessage(
-      `STREAMING MODE ERROR: Agent tried to use interactive tools in streaming mode. ` +
-        `This usually happens with AskUserQuestion or interactive prompts. ` +
-        `Zeroshot agents must run non-interactively.`
-    );
-  }
-
-  // Claude CLI transient failure: no messages returned
-  if (fullOutput.includes('No messages returned')) {
-    logNoMessagesReturned({ taskId, output: fullOutput, statusOutput, debug });
-    return sanitizeErrorMessage(
-      `Claude CLI returned no messages. This is usually transient; retry the task or resume the cluster.`
-    );
-  }
+  const fullOutput = output || '';
+  const knownFailure = extractKnownCliFailure({ fullOutput, taskId, statusOutput, debug });
+  if (knownFailure) return knownFailure;
 
-  // NEVER TRUNCATE OUTPUT - truncation corrupts structured JSON and causes false "crash" status
-  // If output is too verbose, that's a prompt problem - fix the prompts, not the data
   const trimmedOutput = (output || '').trim();
   if (!trimmedOutput) {
     return sanitizeErrorMessage(
@@ -1490,10 +1524,15 @@ function broadcastAgentLine({ agent, providerName, state, line }) {
   if (shouldSkipLogLine(content)) {
     return;
   }
+  const controlPlaneContent = redactTerminalFailureForControlPlane(
+    followerState,
+    providerName,
+    content
+  );
 
-  const isValidJson = isValidJsonLine(content);
+  const isValidJson = isValidJsonLine(controlPlaneContent);
   const record = appendControlPlaneRecord(followerState.controlPlaneOutput, {
-    content,
+    content: controlPlaneContent,
     timestamp,
     type: isValidJson ? 'json' : 'text',
   });
@@ -1703,11 +1742,13 @@ async function evaluateStructuredSuccess({ agent, taskId, state, success, allowR
   }
 }
 
-function buildFailureContext({ agent, taskId, providerName, state, stdout }) {
+function buildFailureContext({ agent, taskId, providerName, state, stdout, providerFailure }) {
   return extractErrorContext({
     output: state.output,
     statusOutput: stdout,
     taskId,
+    providerName,
+    providerFailure,
     debug: {
       agentId: agent.id,
       providerName,
@@ -1720,6 +1761,19 @@ function buildFailureContext({ agent, taskId, providerName, state, stdout }) {
   });
 }
 
+function resolveCompletionFailure({ classified, agent, taskId, providerName, state, stdout }) {
+  if (classified.success) return { providerFailure: null, errorContext: classified.error };
+  const providerFailure =
+    state.providerFailure || extractProviderFailure(state.output, providerName);
+  return {
+    providerFailure,
+    errorContext:
+      providerFailure?.error ||
+      classified.error ||
+      buildFailureContext({ agent, taskId, providerName, state, stdout, providerFailure }),
+  };
+}
+
 async function buildCompletionResult({
   agent,
   taskId,
@@ -1753,10 +1807,14 @@ async function buildCompletionResult({
   if (vertexModelError) {
     classified.success = false;
   }
-  let errorContext = classified.error;
-  if (!errorContext && !classified.success) {
-    errorContext = buildFailureContext({ agent, taskId, providerName, state, stdout });
-  }
+  const { providerFailure, errorContext } = resolveCompletionFailure({
+    classified,
+    agent,
+    taskId,
+    providerName,
+    state,
+    stdout,
+  });
 
   return {
     success: classified.success,
@@ -1772,6 +1830,7 @@ async function buildCompletionResult({
       taskInfo,
       logicalSuccess: classified.success,
     }),
+    providerFailure,
     vertexModelError,
   };
 }
@@ -2633,7 +2692,13 @@ async function resolveIsolatedLogFilePath(manager, clusterId, taskId, state) {
   return state.logFilePath;
 }
 
-async function captureIsolatedFinalOutputTail(manager, clusterId, logFilePath, state) {
+async function captureIsolatedFinalOutputTail(
+  manager,
+  clusterId,
+  logFilePath,
+  state,
+  providerName
+) {
   stopIsolatedTailForSettlement(state);
   const sizeResult = await manager.execInContainer(clusterId, [
     'sh',
@@ -2658,16 +2723,58 @@ async function captureIsolatedFinalOutputTail(manager, clusterId, logFilePath, s
         state.lineBuffer = createLogRecordBuffer();
       }
       appendIsolatedContent(state, finalReadResult.stdout, (line) =>
-        retainIsolatedLine(state, line)
+        retainIsolatedLine(state, providerName, line)
       );
     }
   }
 
   if (state.lineBuffer.byteLength > 0) {
-    completeLogRecord(state.lineBuffer, (line) => retainIsolatedLine(state, line), true);
+    completeLogRecord(
+      state.lineBuffer,
+      (line) => retainIsolatedLine(state, providerName, line),
+      true
+    );
   }
 }
 
+function resolveIsolatedFailure({
+  success,
+  structuredError,
+  agent,
+  taskId,
+  providerName,
+  state,
+  status,
+  isNotFound,
+  clusterId,
+  logFilePath,
+}) {
+  if (success) return { providerFailure: null, errorContext: structuredError };
+  const providerFailure =
+    state.providerFailure || extractProviderFailure(state.fullOutput, providerName);
+  const errorContext =
+    providerFailure?.error ||
+    structuredError ||
+    extractErrorContext({
+      output: state.fullOutput,
+      statusOutput: status ? `Status: ${status}` : '',
+      taskId,
+      isNotFound,
+      providerName,
+      debug: {
+        agentId: agent.id,
+        providerName,
+        pid: agent.processPid,
+        cwd: agent.config.cwd || process.cwd(),
+        worktreePath: agent.worktree?.path || null,
+        isolation: true,
+        clusterId,
+        logFilePath,
+      },
+    });
+  return { providerFailure, errorContext };
+}
+
 function settleIsolatedTerminalStatus({
   agent,
   manager,
@@ -2693,7 +2800,7 @@ function settleIsolatedTerminalStatus({
     const logFilePath = await resolveIsolatedLogFilePath(manager, clusterId, taskId, state);
     await new Promise((settle) => setTimeout(settle, 200));
     if (state.resolved) return;
-    await captureIsolatedFinalOutputTail(manager, clusterId, logFilePath, state);
+    await captureIsolatedFinalOutputTail(manager, clusterId, logFilePath, state, providerName);
     if (state.resolved) return;
     flushIsolatedOutput(agent, providerName, taskId, state);
 
@@ -2720,26 +2827,18 @@ function settleIsolatedTerminalStatus({
       success = evaluated.success;
       structuredError = evaluated.error;
     }
-    const errorContext =
-      structuredError ||
-      (!success
-        ? extractErrorContext({
-            output: state.fullOutput,
-            statusOutput: status ? `Status: ${status}` : '',
-            taskId,
-            isNotFound,
-            debug: {
-              agentId: agent.id,
-              providerName,
-              pid: agent.processPid,
-              cwd: agent.config.cwd || process.cwd(),
-              worktreePath: agent.worktree?.path || null,
-              isolation: true,
-              clusterId,
-              logFilePath,
-            },
-          })
-        : null);
+    const { providerFailure, errorContext } = resolveIsolatedFailure({
+      success,
+      structuredError,
+      agent,
+      taskId,
+      providerName,
+      state,
+      status,
+      isNotFound,
+      clusterId,
+      logFilePath,
+    });
     let parsedResult = null;
     if (success && !state.skipStructuredResultCheck && !vertexModelError) {
       parsedResult = staleCandidate
@@ -2759,6 +2858,7 @@ function settleIsolatedTerminalStatus({
         parsedResult,
         error: errorContext,
         tokenUsage: extractTokenUsage(state.fullOutput, providerName),
+        providerFailure,
         vertexModelError,
       },
     });
@@ -2880,18 +2980,19 @@ function publishIsolatedOutputRecord(agent, providerName, taskId, record) {
   });
 }
 
-function retainIsolatedLine(state, line) {
+function retainIsolatedLine(state, providerName, line) {
   const { timestamp, content } = parseIsolatedLogLine(line);
+  const controlPlaneContent = redactTerminalFailureForControlPlane(state, providerName, content);
   return appendControlPlaneRecord(state.controlPlaneOutput, {
-    content,
+    content: controlPlaneContent,
     timestamp,
-    type: isValidJsonLine(content) ? 'json' : 'text',
+    type: isValidJsonLine(controlPlaneContent) ? 'json' : 'text',
   });
 }
 
 function broadcastIsolatedLine({ agent, providerName, taskId, state, line }) {
   const followerState = ensureControlPlaneOutputState(state);
-  const record = retainIsolatedLine(followerState, line);
+  const record = retainIsolatedLine(followerState, providerName, line);
   publishLiveControlPlaneRecord(followerState.controlPlaneOutput, record, (item) =>
     publishIsolatedOutputRecord(agent, providerName, taskId, item)
   );

package/src/agent/output-extraction.js

@@ -16,8 +16,51 @@
  * 4. Direct JSON parse of entire output
  */
 
+const { createHash } = require('node:crypto');
 const { parseProviderChunk } = require('../providers');
 
+const MAX_CLI_ERROR_BYTES = 4096;
+const CLI_ERROR_TRUNCATION_SUFFIX = '… [truncated]';
+
+function truncateUtf8(text, maxBytes = MAX_CLI_ERROR_BYTES) {
+  if (Buffer.byteLength(text) <= maxBytes) return text;
+
+  const suffixBytes = Buffer.byteLength(CLI_ERROR_TRUNCATION_SUFFIX);
+  const contentBudget = Math.max(0, maxBytes - suffixBytes);
+  let bytes = 0;
+  let truncated = '';
+  for (const character of text) {
+    const characterBytes = Buffer.byteLength(character);
+    if (bytes + characterBytes > contentBudget) break;
+    truncated += character;
+    bytes += characterBytes;
+  }
+  return `${truncated}${CLI_ERROR_TRUNCATION_SUFFIX}`;
+}
+
+function primitiveErrorText(value) {
+  return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
+    ? String(value)
+    : '';
+}
+
+function cliErrorDetail(value, fallback) {
+  const candidate = Array.isArray(value)
+    ? value
+        .map(primitiveErrorText)
+        .filter((message) => message.trim())
+        .join('; ')
+    : primitiveErrorText(value);
+  const raw = candidate.trim() ? candidate : fallback;
+  return {
+    error: truncateUtf8(raw.trim()),
+    diagnostic: {
+      byteLength: Buffer.byteLength(raw),
+      sha256: createHash('sha256').update(raw).digest('hex'),
+    },
+  };
+}
+
 /**
  * Strip timestamp prefix from log lines.
  * Format: [epochMs]content or [epochMs]{json...}
@@ -308,60 +351,87 @@ function extractClaudeVertexModelError(output, { useVertex = false } = {}) {
  * @param {string} providerName - Active provider whose terminal errors may be inspected
  * @returns {{error: string, provider: string}|null} Error info or null
  */
-function extractCliError(output, providerName = 'claude') {
+function claudeFailureFromObject(obj) {
+  if (obj.type !== 'result') return null;
+  if (obj.is_error === true) {
+    const detail = cliErrorDetail(
+      Array.isArray(obj.errors) ? obj.errors : obj.error || obj.result,
+      'Unknown CLI error'
+    );
+    return { ...detail, provider: 'claude' };
+  }
+  if (obj.subtype !== 'error') return null;
+  return {
+    ...cliErrorDetail(obj.error || obj.result, 'CLI returned error'),
+    provider: 'claude',
+  };
+}
+
+function codexFailureFromObject(obj) {
+  if (obj.type !== 'turn.failed') return null;
+  return {
+    ...cliErrorDetail(obj.error?.message || obj.error?.code || obj.error, 'Turn failed'),
+    provider: 'codex',
+  };
+}
+
+function geminiFailureFromObject(obj) {
+  const geminiFailure =
+    (obj.type === 'result' && obj.status === 'error') ||
+    (obj.type === 'error' && obj.severity === 'error');
+  if (!geminiFailure) return null;
+  return {
+    ...cliErrorDetail(obj.error?.message || obj.message, 'Gemini CLI error'),
+    provider: 'gemini',
+  };
+}
+
+function opencodeFailureFromObject(obj) {
+  if (obj.type !== 'session.error' && obj.type !== 'error') return null;
+  return {
+    ...cliErrorDetail(
+      obj.error?.data?.message || obj.error?.message || obj.error?.name,
+      'Session error'
+    ),
+    provider: 'opencode',
+  };
+}
+
+function failureFromProviderObject(obj, providerName) {
+  if (providerName === 'claude') return claudeFailureFromObject(obj);
+  if (providerName === 'codex') return codexFailureFromObject(obj);
+  if (providerName === 'gemini') return geminiFailureFromObject(obj);
+  if (providerName === 'opencode') return opencodeFailureFromObject(obj);
+  return null;
+}
+
+function extractCliFailure(output, providerName = 'claude') {
   if (!output || typeof output !== 'string') return null;
 
   const lines = output.split('\n');
+  // Codex terminal truth is a turn.failed record at the newest end of JSONL output.
+  // Search it newest-first so a preserved terminal tail wins over older provider chatter.
+  if (providerName === 'codex') lines.reverse();
 
   for (const line of lines) {
     const content = stripTimestamp(line);
     if (!content.startsWith('{')) continue;
-
-    let obj;
     try {
-      obj = JSON.parse(content);
+      const failure = failureFromProviderObject(JSON.parse(content), providerName);
+      if (failure) return failure;
     } catch {
-      continue;
-    }
-
-    if (providerName === 'claude' && obj.type === 'result' && obj.is_error === true) {
-      const errorMsg = Array.isArray(obj.errors)
-        ? obj.errors.join('; ')
-        : obj.error || obj.result || 'Unknown CLI error';
-      return { error: errorMsg, provider: 'claude' };
-    }
-
-    if (providerName === 'claude' && obj.type === 'result' && obj.subtype === 'error') {
-      const errorMsg = obj.error || obj.result || 'CLI returned error';
-      return { error: errorMsg, provider: 'claude' };
-    }
-
-    if (providerName === 'codex' && obj.type === 'turn.failed') {
-      const errorMsg = obj.error?.message || obj.error || 'Turn failed';
-      return { error: errorMsg, provider: 'codex' };
-    }
-
-    if (
-      providerName === 'gemini' &&
-      ((obj.type === 'result' && obj.status === 'error') ||
-        (obj.type === 'error' && obj.severity === 'error'))
-    ) {
-      return {
-        error: obj.error?.message || obj.message || 'Gemini CLI error',
-        provider: 'gemini',
-      };
-    }
-
-    if (providerName === 'opencode' && (obj.type === 'session.error' || obj.type === 'error')) {
-      const errorMsg =
-        obj.error?.data?.message || obj.error?.message || obj.error?.name || 'Session error';
-      return { error: errorMsg, provider: 'opencode' };
+      // Ignore non-JSON output lines.
     }
   }
 
   return null;
 }
 
+function extractCliError(output, providerName = 'claude') {
+  const failure = extractCliFailure(output, providerName);
+  return failure ? { error: failure.error, provider: failure.provider } : null;
+}
+
 /**
  * Detects fatal standalone output lines that indicate no task output was produced.
  * Only matches when the line itself is the fatal message (not when it appears inside JSON).
@@ -419,8 +489,10 @@ function extractJsonFromOutput(output, providerName = 'claude') {
 }
 
 module.exports = {
+  MAX_CLI_ERROR_BYTES,
   extractJsonFromOutput,
   extractModelTextFromOutput,
+  extractCliFailure,
   extractCliError,
   extractClaudeVertexModelError,
   extractFromResultWrapper,

package/src/agent/provider-terminal-failure.js

@@ -0,0 +1,186 @@
+// @ts-nocheck
+
+const { getProvider } = require('../providers');
+const { extractCliFailure } = require('./output-extraction');
+
+function categoryForProviderFailure(error, classification) {
+  const isPermanent = classification.retryable === false;
+  const authenticationPattern =
+    /(?:invalid[_ -]?api[_ -]?key|api[_ -]?key.*invalid|unauthori[sz]ed|forbidden|authentication|permission denied)/i;
+  if (isPermanent && authenticationPattern.test(error)) return 'authentication';
+
+  const quotaPattern = /(?:insufficient[_ -]?quota|quota exceeded|resource_exhausted)/i;
+  if (isPermanent && quotaPattern.test(error)) return 'quota';
+  if (isPermanent) return 'permanent';
+  return classification.kind === 'unknown-retryable' ? 'unknown' : 'transient';
+}
+
+function classifyProviderFailure(providerName, error) {
+  let rawClassification = { retryable: true, kind: 'unknown-retryable' };
+  try {
+    rawClassification = getProvider(providerName).adapter.classifyError(new Error(error));
+  } catch {
+    // Extraction remains available if a provider adapter cannot be loaded.
+  }
+  return {
+    retryable: rawClassification?.retryable !== false,
+    kind:
+      typeof rawClassification?.kind === 'string' ? rawClassification.kind : 'unknown-retryable',
+  };
+}
+
+function extractProviderFailure(output, providerName) {
+  const cliError = extractCliFailure(output, providerName);
+  if (!cliError) return null;
+
+  const classification = classifyProviderFailure(providerName, cliError.error);
+  const category = categoryForProviderFailure(cliError.error, classification);
+  return {
+    error: `Provider ${cliError.provider} failed (${category}; ${classification.kind})`,
+    provider: cliError.provider,
+    event: cliError.provider === 'codex' ? 'turn.failed' : 'terminal_error',
+    category,
+    classification,
+    diagnostic: cliError.diagnostic,
+  };
+}
+
+function redactTerminalFailureForControlPlane(state, providerName, content) {
+  const failure = extractProviderFailure(content, providerName);
+  if (!failure) return content;
+
+  state.providerFailure = failure;
+  let eventType = 'provider.failure';
+  try {
+    const parsed = JSON.parse(content);
+    if (typeof parsed?.type === 'string') eventType = parsed.type;
+  } catch {
+    // extractProviderFailure already proved a supported terminal envelope.
+  }
+  return JSON.stringify({
+    type: eventType,
+    ...(providerName === 'claude' ? { is_error: true } : {}),
+    ...(providerName === 'gemini' ? { status: 'error', severity: 'error' } : {}),
+    error: { message: failure.error },
+    zeroshot_failure: {
+      provider: failure.provider,
+      event: failure.event,
+      category: failure.category,
+      kind: failure.classification.kind,
+      retryable: failure.classification.retryable,
+      diagnostic: failure.diagnostic,
+    },
+  });
+}
+
+function decorateError(error, failure) {
+  if (!failure) return error;
+  error.provider = failure.provider || null;
+  error.providerEvent = failure.event || null;
+  error.providerCategory = failure.category || null;
+  error.classification = failure.classification || null;
+  error.providerDiagnostic = failure.diagnostic || null;
+  if (failure.classification?.retryable === false) error.permanent = true;
+  return error;
+}
+
+function receiptFields(error) {
+  if (!error?.provider) return {};
+  return {
+    provider: error.provider,
+    event: error.providerEvent,
+    category: error.providerCategory,
+    kind: error.classification?.kind,
+    retryable: error.classification?.retryable,
+    diagnostic: error.providerDiagnostic,
+  };
+}
+
+function workerFailure(error) {
+  const authenticationFailure =
+    error?.provider &&
+    error?.classification?.retryable === false &&
+    error?.providerCategory === 'authentication';
+  return authenticationFailure
+    ? { code: 'refusal', reason: 'authentication_required' }
+    : { code: 'crash', reason: 'declared_failure' };
+}
+
+function publishCriticalFailure({
+  agent,
+  error,
+  attempts,
+  worker,
+  unsupportedCapability,
+  structuredOutputInvalid,
+}) {
+  const specific =
+    error?.hookFailure ||
+    structuredOutputInvalid ||
+    unsupportedCapability ||
+    error?.vertexModelError ||
+    error?.terminationExhausted;
+  const critical =
+    agent.role === 'implementation' ||
+    agent.role === 'coordinator' ||
+    agent.id === 'consensus-coordinator';
+  if (!critical || specific) return worker;
+
+  agent._publish({
+    topic: 'CLUSTER_FAILED',
+    receiver: 'broadcast',
+    content: {
+      text: `Critical agent ${agent.id} exhausted its retry budget`,
+      data: {
+        reason: error?.provider ? 'provider_execution_failed' : 'critical_agent_exhausted',
+        agentId: agent.id,
+        role: agent.role,
+        attempts,
+        code: worker.code,
+        workerReason: worker.reason,
+        ...receiptFields(error),
+      },
+    },
+  });
+  return worker;
+}
+
+function buildFinalFailureInfo({
+  agent,
+  error,
+  attempts,
+  worker,
+  unsupportedCapability,
+  structuredOutputInvalid,
+}) {
+  return {
+    ...(error?.terminationExhausted ? agent.cluster.failureInfo : {}),
+    agentId: agent.id,
+    taskId: error?.taskId || agent.currentTaskId,
+    iteration: agent.iteration,
+    error: error.message,
+    attempts,
+    ...receiptFields(error),
+    ...(error?.provider ? { code: worker.code, workerReason: worker.reason } : {}),
+    ...(unsupportedCapability
+      ? {
+          code: error.code,
+          permanent: true,
+          provider: error.provider,
+          capability: error.capability,
+        }
+      : {}),
+    ...(structuredOutputInvalid ? { code: error.code, details: error.details ?? null } : {}),
+    timestamp: Date.now(),
+  };
+}
+
+module.exports = {
+  buildFinalFailureInfo,
+  decorateError,
+  extractProviderFailure,
+  publishCriticalFailure,
+  receiptFields,
+  redactTerminalFailureForControlPlane,
+  workerFailure,
+};

package/src/orchestrator.js

@@ -275,6 +275,7 @@ class Orchestrator {
     // Track if orchestrator is closed (prevents _saveClusters race conditions during cleanup)
     this.closed = false;
     this._conductorWatchdogs = new Set();
+    this._clusterRunBoundaries = new Map();
 
     // Track if clusters are loaded (for lazy loading pattern)
     this._clustersLoaded = options.skipLoad === true;
@@ -1575,11 +1576,17 @@ class Orchestrator {
   }
 
   _registerAgentErrorHandler(messageBus, clusterId) {
+    this._recordClusterRunBoundary(messageBus, clusterId);
     this._subscribeToClusterTopic(messageBus, clusterId, 'AGENT_ERROR', async (message) => {
       const agentRole = message.content?.data?.role;
       const attempts = message.content?.data?.attempts || 1;
       const hookFailure = message.content?.data?.hookFailure === true;
       const restartExhausted = message.content?.data?.restartExhausted === true;
+      const durableClusterFailure = this._findCurrentRunClusterFailure(
+        messageBus,
+        clusterId,
+        message.sequence
+      );
 
       await this._saveClusters();
 
@@ -1587,7 +1594,10 @@ class Orchestrator {
         agentRole === 'implementation' ||
         agentRole === 'coordinator' ||
         message.sender === 'consensus-coordinator';
-      const shouldStop = shouldStopForRole && (hookFailure || restartExhausted || attempts >= 3);
+      const shouldStop =
+        !durableClusterFailure &&
+        shouldStopForRole &&
+        (hookFailure || restartExhausted || attempts >= 3);
 
       if (shouldStop) {
         this._log(`\n${'='.repeat(80)}`);
@@ -1610,6 +1620,25 @@ class Orchestrator {
     });
   }
 
+  _recordClusterRunBoundary(messageBus, clusterId) {
+    const latest = messageBus.findLast({ cluster_id: clusterId, orderBySequence: true });
+    this._clusterRunBoundaries.set(clusterId, latest?.sequence ?? null);
+  }
+
+  _findCurrentRunClusterFailure(messageBus, clusterId, throughId) {
+    const boundary = this._clusterRunBoundaries.get(clusterId);
+    return (
+      messageBus.query({
+        cluster_id: clusterId,
+        topic: 'CLUSTER_FAILED',
+        order: 'desc',
+        limit: 1,
+        ...(boundary === null ? {} : { afterId: boundary }),
+        ...(throughId === undefined ? {} : { throughId }),
+      })[0] || null
+    );
+  }
+
   _registerPushBlockedHandler(messageBus, clusterId) {
     this._subscribeToClusterTopic(messageBus, clusterId, 'PUSH_BLOCKED', async (message) => {
       const reason = message.content?.data?.blocked_reason || 'unknown';
@@ -2425,6 +2454,7 @@ class Orchestrator {
 
     // Now remove from memory after persisting
     this.clusters.delete(clusterId);
+    this._clusterRunBoundaries.delete(clusterId);
   }
 
   /**
@@ -2462,6 +2492,7 @@ class Orchestrator {
       watchdog.dispose();
     }
     this._conductorWatchdogs.clear();
+    this._clusterRunBoundaries.clear();
 
     for (const cluster of this.clusters.values()) {
       if (typeof cluster.snapshotter?.stop === 'function') {
@@ -2902,6 +2933,7 @@ class Orchestrator {
   }
 
   async _restartClusterAgents(cluster) {
+    this._recordClusterRunBoundary(cluster.messageBus, cluster.id);
     cluster.state = 'running';
     cluster.pid = process.pid;
     for (const agent of cluster.agents) {