@awak-app/simy-cli 0.5.73 → 0.5.74

package/README.md

@@ -99,6 +99,19 @@ retains the authoritative analysis history. Persistent provider login, model or
 access errors pause new local claims with a visible recovery hint; refreshing
 after reconnecting permits another probe, with bounded automatic cooldowns.
 
+Conversation checks blocked by **Sign-in required** automatically recheck after
+a fresh Codex or Claude login probe succeeds, including after an app restart.
+An unchanged ready status cannot repeatedly re-run a failed check. Manual retry
+remains available; continuing the conversation still requires **Auto-continue**.
+
+Claude read-only structured reviews retry once when the provider explicitly
+reports exhausted turns or structured-output repair attempts, within the original
+timeout. Other failures retain distinct codes and recovery hints. Safe native
+result subtype, exit status, output size and recognized model identifiers survive
+restart in SQM history and correlate with the task ID in diagnostic logs. Provider
+responses, prompts and credentials are not retained. Older generic failure records
+cannot acquire details that were never recorded.
+
 Detached daemon and desktop-host diagnostics are saved to
 `$SIMY_HOME/logs/daemon.log` and `$SIMY_HOME/logs/desktop-host.log`
 (`SIMY_HOME` defaults to `~/.simy`). Each log is limited to 1 MiB plus two

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awak-app/simy-cli",
-  "version": "0.5.73",
+  "version": "0.5.74",
   "description": "Local SIMY executor for non-coding Local Tasks and Agentic Loop runs.",
   "type": "module",
   "bin": {

package/src/cli-contract.js

@@ -13,7 +13,7 @@ import {
 } from "./durable-local-task-steps-contract.js";
 import { buildExecutionCapabilityContract } from "./execution-capability-contract.js";
 
-export const CLI_VERSION = "0.5.73";
+export const CLI_VERSION = "0.5.74";
 export const CLI_API_CONTRACT_VERSION = 10;
 
 export function withCliContract(

package/src/desktop-host.js

@@ -231,6 +231,7 @@ export async function startDesktopHost({ input = process.stdin, output = process
         if (!closed && !relay) emitStatus(status);
         return;
       }
+      await analysisManager.updateProviderStatuses?.(status.providers);
       const records = await recordReader.list();
       const projection = await actionAssociations.beginProjection?.({ records });
       status.deliveryHooks = await (dependencies.deliveryHookStatus || deliveryHookStatus)({ root: deliveryRoot, records: projection?.records || records }).catch(() => ({ error: "Delivery hook status unavailable", providers: {}, runs: [] }));

package/src/diagnostic-log.js

@@ -2,6 +2,7 @@ import { randomUUID, createHash } from "node:crypto";
 import { mkdir, appendFile, rename, writeFile, readdir, readFile, rm } from "node:fs/promises";
 import { join } from "node:path";
 import { defaultSessionRoot } from "./session-store.js";
+import { safeProviderDiagnostic } from "./sqm/provider-diagnostics.js";
 
 const writers = new Map();
 const scopeDir = (root, scope) => join(root, "diagnostics", createHash("sha256").update(JSON.stringify([
@@ -12,7 +13,10 @@ const safeIdentifier = value => typeof value === "string" && /^[a-z][a-z0-9_.-]{
 // Only structured diagnostics are durable. Never retain prompts, arbitrary error
 // messages, tokens, source paths, or provider stdout/stderr.
 export function safeDiagnosticEvent(value, now = () => Date.now()) {
+  const providerDiagnostic = safeProviderDiagnostic(value?.provider_diagnostic);
   return { at: Number.isFinite(Date.parse(value?.at)) ? value.at : new Date(now()).toISOString(),
+    ...(/^(?:sqm-check:)?[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(value?.task_id || "") ? { task_id: value.task_id } : {}),
+    ...(Object.keys(providerDiagnostic).length ? { provider_diagnostic: providerDiagnostic } : {}),
     kind: ["analysis", "check", "preflight"].includes(value?.kind) ? value.kind : "check",
     stage: safeIdentifier(value?.stage) || "unknown",
     code: safeIdentifier(value?.code) || "failure_unclassified",

package/src/session-supervision/analysis-manager.js

@@ -5,6 +5,7 @@ import { analyzeContinuation, CONTINUATION_ANALYSIS_VERSION } from './continuati
 
 const BACKFILL_LIMIT = 10;
 const MAX_CACHE_ENTRIES = 2000;
+const AUTH_RECOVERY_COOLDOWN_MS = 60_000;
 const RESULT_STATES = new Set(['continue', 'no_action', 'needs_user', 'waiting', 'uncertain']);
 const keyOf = candidate => `${candidate.provider}:${candidate.session}`;
 const activityOf = candidate => Number.isFinite(candidate.lastActivityAt) ? candidate.lastActivityAt : 0;
@@ -49,6 +50,7 @@ export async function createContinuationAnalysisManager({ root, analyze = analyz
   const known = new Map(document.known.slice(-MAX_CACHE_ENTRIES));
   const entries = new Map(document.entries.slice(-MAX_CACHE_ENTRIES));
   const candidates = new Map();
+  const providerStatuses = new Map(), signedOutChecks = new Map();
   for (const [key, entry] of entries) {
     if (entry.result?.state === 'analyzing') entry.result = { state: 'queued' };
   }
@@ -79,9 +81,34 @@ export async function createContinuationAnalysisManager({ root, analyze = analyz
       forceAnalysis: forceAnalysis || entry?.forceAnalysis === true && ['queued', 'analyzing'].includes(entry.result?.state),
       settledResult: entry?.cwd === candidate.cwd ? entry.settledResult : null,
       requestId: entry?.cwd === candidate.cwd && ['queued', 'analyzing'].includes(entry.result?.state) ? entry.requestId : undefined,
+      ...(entry?.revision === revision ? { authRecoveryAttemptedAt: entry.authRecoveryAttemptedAt, authRecoverySignedOutAt: entry.authRecoverySignedOutAt } : {}),
       result: { state: 'queued' } });
     return true;
   };
+  // A successful login probe must postdate the failed inference. Cache hits and
+  // opening a login terminal are not recovery evidence. One automatic attempt
+  // survives restarts; only a new observed sign-out/sign-in cycle can rearm it.
+  const recoverAuthentication = () => {
+    let dirty = false;
+    for (const [key, candidate] of candidates) {
+      const entry = entries.get(key), status = providerStatuses.get(candidate.provider);
+      const checkedAt = Date.parse(status?.checkedAt);
+      if (!eligible(candidate) || candidate.isRunning === true || jobs.has(key) ||
+          entry?.revision !== continuationAnalysisRevision(candidate) ||
+          !['uncertain', 'failed'].includes(entry.result?.state) || entry.result?.reasonCode !== 'provider_sign_in_required' ||
+          status?.state !== 'ready' || !Number.isFinite(checkedAt) || checkedAt <= (entry.completedAt || entry.result.analyzedAt || 0)) continue;
+      const signedOutAt = signedOutChecks.get(candidate.provider) || 0;
+      if (entry.authRecoveryAttemptedAt !== undefined &&
+          (signedOutAt <= (entry.authRecoverySignedOutAt || 0) || now() - entry.authRecoveryAttemptedAt < AUTH_RECOVERY_COOLDOWN_MS)) continue;
+      if (enqueue(candidate, true, true)) {
+        const queued = entries.get(key);
+        queued.authRecoveryAttemptedAt = now();
+        queued.authRecoverySignedOutAt = signedOutAt;
+        dirty = true;
+      }
+    }
+    return dirty;
+  };
   const finishedAnalysis = (result, previous) => RESULT_STATES.has(result.state) && result.awaitingTurn !== true && result.contextDigest
     ? { ...result, awaitingTurn: false, analyzedAt: result.contextDigest && result.contextDigest === previous?.contextDigest ? previous.analyzedAt : now() }
     : previous;
@@ -136,6 +163,7 @@ export async function createContinuationAnalysisManager({ root, analyze = analyz
       }
       const settledResult = finishedAnalysis(result, selected.previousAnalysis || entry.settledResult);
       entries.set(selected.key, { revision: selected.revision, analysisVersion: CONTINUATION_ANALYSIS_VERSION, cwd: current.cwd, settledResult,
+        completedAt: now(), authRecoveryAttemptedAt: selected.entry.authRecoveryAttemptedAt, authRecoverySignedOutAt: selected.entry.authRecoverySignedOutAt,
         requestId: selected.entry.requestId, result: { ...result, analyzedAt: settledResult?.analyzedAt || now() } });
       await persist(); changed();
     });
@@ -183,6 +211,22 @@ export async function createContinuationAnalysisManager({ root, analyze = analyz
     });
   };
   return {
+    async updateProviderStatuses(statuses = {}) {
+      await exclusive(async () => {
+        if (closed) return;
+        for (const provider of ['codex', 'claude']) {
+          const status = statuses[provider];
+          if (!status) continue;
+          const checkedAt = Date.parse(status.checkedAt);
+          const previousAt = Date.parse(providerStatuses.get(provider)?.checkedAt);
+          if (Number.isFinite(previousAt) && (!Number.isFinite(checkedAt) || checkedAt < previousAt)) continue;
+          providerStatuses.set(provider, status);
+          if (status.state === 'signed_out' && Number.isFinite(checkedAt)) signedOutChecks.set(provider, checkedAt);
+        }
+        if (recoverAuthentication()) { await persist(); changed(); }
+      });
+      startDrain();
+    },
     async update(sessions) {
       await exclusive(async () => {
         if (closed) return;
@@ -230,6 +274,7 @@ export async function createContinuationAnalysisManager({ root, analyze = analyz
         }
         // Empty discovery during provider startup must not consume backfill.
         if (sorted.length) document.initialized = true;
+        dirty = recoverAuthentication() || dirty;
         if (dirty) await persist();
       });
       startDrain();

package/src/session-supervision/continuation-analysis.js

@@ -64,7 +64,7 @@ async function unavailableAnalysis(candidate, error, inspectProvider, signal) {
   if (signal?.aborted) return uncertain('Conversation analysis was cancelled.', 'cancelled');
   if (error?.code === 'provider_sign_in_required' || status?.state === 'signed_out') {
     const label = candidate.provider === 'claude' ? 'Claude Code' : 'Codex';
-    return uncertain(`Sign in to ${label} to check this conversation and continue its unfinished work. After signing in, retry this check.`, 'provider_sign_in_required');
+    return uncertain(`Sign in to ${label}. SIMY rechecks this conversation automatically when sign-in is detected. You can also retry manually. Unfinished work can continue automatically only when Auto Continue is on.`, 'provider_sign_in_required');
   }
   return uncertain('The local AI app could not check this turn. Check its connection, then retry.', 'analysis_unavailable');
 }

package/src/sqm/history-store.js

@@ -1,4 +1,5 @@
 import { diagnosticLogger } from "../diagnostic-log.js";
+import { safeProviderDiagnostic } from "./provider-diagnostics.js";
 import { safeSqmDiagnostic, formatSqmDiagnostic } from "./diagnostics.js";
 import { createHash, randomUUID } from "node:crypto";
 import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
@@ -47,7 +48,9 @@ export function createSqmHistoryStore({ root = defaultSessionRoot(), now = () =>
         await writeFile(temp, JSON.stringify(item), { mode: 0o600 });
         await rename(temp, target);
         if (["failed", "unavailable"].includes(item.state)) await diagnosticLogger({ root, scope }).record({
-          kind: item.kind, stage: entry.errorStage || item.phase || "unknown", code: item.errorCode, provider: item.provider, http_status: entry.httpStatus, at: item.finishedAt || item.startedAt });
+          kind: item.kind, stage: item.errorStage || item.phase || "unknown", code: item.errorCode, provider: item.provider,
+          task_id: item.id, provider_diagnostic: item.providerDiagnostic,
+          http_status: item.errorStatus ?? item.httpStatus, at: item.finishedAt || item.startedAt });
       } finally { await rm(temp, { force: true }); cache.delete(dir); }
       const items = await list(scope);
       for (const kind of ["analysis", "check"]) {
@@ -78,6 +81,8 @@ function metadata(entry) {
   }
   if (Number.isInteger(entry.errorStatus) && entry.errorStatus >= 400 && entry.errorStatus <= 599) item.errorStatus = entry.errorStatus;
   if (Number.isInteger(entry.httpStatus) && entry.httpStatus >= 400 && entry.httpStatus <= 599) item.httpStatus = entry.httpStatus;
+  const providerDiagnostic = safeProviderDiagnostic(entry.providerDiagnostic);
+  if (Object.keys(providerDiagnostic).length) item.providerDiagnostic = providerDiagnostic;
   return item;
 }
 

package/src/sqm/provider-diagnostics.js

@@ -0,0 +1,35 @@
+const SUBTYPES = new Set(["success", "error_max_turns", "error_during_execution", "error_max_budget_usd", "error_max_structured_output_retries", "unknown"]);
+const SIGNALS = new Set(["SIGTERM", "SIGKILL", "SIGABRT", "SIGSEGV", "SIGINT", "SIGHUP", "SIGPIPE"]);
+
+// Reuse at every persistence boundary. Provider envelopes may contain prompts,
+// paths, request IDs or credentials; none of their free-form text is retained.
+export function safeProviderDiagnostic(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const result = {};
+  if (typeof value.subtype === "string") result.subtype = SUBTYPES.has(value.subtype) ? value.subtype : "unknown";
+  if (Number.isInteger(value.exitCode) && value.exitCode >= 0 && value.exitCode <= 255) result.exitCode = value.exitCode;
+  if (SIGNALS.has(value.signal)) result.signal = value.signal;
+  if (Number.isInteger(value.outputBytes) && value.outputBytes >= 0 && value.outputBytes <= 2147483647) result.outputBytes = value.outputBytes;
+  if (value.retryAttempt === 0 || value.retryAttempt === 1) result.retryAttempt = value.retryAttempt;
+  if (typeof value.model === "string" && /^(?:gpt-6-(?:astra)|gpt-6\.1-sol|claude-(?:sonnet|opus|haiku)-[0-9]+(?:-[0-9]+){0,3})$/.test(value.model) && value.model.length <= 64) result.model = value.model;
+  return result;
+}
+
+export const PROVIDER_FAILURE_HINTS = Object.freeze({
+  provider_turn_limit_reached: "The local AI reached its turn limit before completing structured output. Retry this analysis; if it repeats, update the local AI app or report this error code.",
+  provider_structured_output_exhausted: "The local AI exhausted its structured-output repair attempts. Retry the analysis; if it repeats, report this error code and update the local AI app.",
+  provider_budget_exceeded: "The local AI stopped at its configured budget. Check that provider's budget before retrying.",
+  provider_execution_error: "The local AI reported an execution error. Check its local status and retry the analysis.",
+  provider_invalid_json: "The local AI returned invalid JSON. Retry the analysis; if it repeats, update the local AI app.",
+  provider_invalid_envelope: "The local AI returned an unsupported response envelope. Update the local AI app and retry.",
+  provider_missing_structured_output: "The local AI returned no schema-constrained output. Update the local AI app and retry this analysis.",
+  provider_non_object_output: "The local AI returned a structured value that was not an object. Retry this analysis; if it repeats, report this error code.",
+  provider_process_failed: "The local AI process exited before completing the review. Check the recorded exit code and the local AI app, then retry.",
+  provider_spawn_failed: "The local AI process could not start. Check its installation and local execution permissions.",
+  provider_output_too_large: "The local AI response exceeded the output-size limit. Reduce the evidence size before retrying.",
+  provider_network_unavailable: "The local AI could not reach its provider. Check its network or proxy connection, then retry.",
+  provider_schema_rejected: "The local AI rejected the output schema. Update the local AI app; if it repeats, report this error code.",
+  provider_rate_limited: "The local AI provider is rate limited. Wait for its limit to reset before retrying.",
+  provider_tool_use_blocked: "The local AI attempted to use a tool during a read-only analysis. The analysis was stopped.",
+  analysis_cancelled: "The local AI analysis was cancelled.",
+});

package/src/sqm/review-worker.js

@@ -5,6 +5,7 @@ import { join } from "node:path";
 
 import { inspectProviderStatus } from "../desktop-status.js";
 import { inspectDesktopExecutor } from "../desktop-executor.js";
+import { safeProviderDiagnostic, PROVIDER_FAILURE_HINTS } from "./provider-diagnostics.js";
 import {
   webApiErrorMessage,
   webApiHeaders,
@@ -21,13 +22,14 @@ export const SQM_CODEX_MODELS = Object.freeze(["gpt-6-astra", "gpt-6.1-sol"]);
 export const SQM_CODEX_MODEL = SQM_CODEX_MODELS[0];
 
 export class SqmLocalReviewError extends Error {
-  constructor(message, { status = null, code = "sqm_local_review_error", stage = null, jobId = null, failureRecorded = false, validationFeedback = "" } = {}) {
+  constructor(message, { status = null, code = "sqm_local_review_error", stage = null, jobId = null, failureRecorded = false, validationFeedback = "", providerDiagnostic } = {}) {
     super(message);
     this.name = "SqmLocalReviewError";
     this.status = status;
     this.code = code;
     this.stage = stage; this.jobId = jobId; this.failureRecorded = failureRecorded;
     this.validationFeedback = typeof validationFeedback === "string" ? validationFeedback.slice(0, 2000) : "";
+    if (providerDiagnostic) this.providerDiagnostic = safeProviderDiagnostic(providerDiagnostic);
   }
 }
 
@@ -134,7 +136,7 @@ export function createSqmLocalReviewWorker({
       item.state = state; item.finishedAt = new Date().toISOString();
       item.result = state === "completed" ? "SQM review submitted." : "";
       item.error = state === "failed" ? formatFailure(failure, failureReported) : "";
-      if (failure) { item.phase = failure.stage; item.errorStage = failure.stage; item.errorCode = failure.code; item.httpStatus = failure.status; }
+      if (failure) { item.phase = failure.stage; item.errorStage = failure.stage; item.errorCode = failure.code; item.httpStatus = failure.status; item.providerDiagnostic = failure.providerDiagnostic; }
       await persist(scope, item);
     }
     onChange();
@@ -379,9 +381,11 @@ async function runSingleProviderReview(
     ].join("\n\n");
     const deadline = deadlineAt ?? Date.now() + executionTimeoutMs;
     const models = provider === "codex" ? SQM_CODEX_MODELS : [null];
-    let stdout;
+    let processResult;
     let selectedModel;
-    for (const model of models) {
+    let modelIndex = 0, retryAttempt = 0, claudeTurnLimit = 1;
+    while (modelIndex < models.length) {
+      const model = models[modelIndex];
       await beforeDispatch();
       if (signal?.aborted) throw new SqmLocalReviewError('Local analysis was cancelled.', { code: 'analysis_cancelled' });
       const remaining = deadline - Date.now();
@@ -389,7 +393,7 @@ async function runSingleProviderReview(
       // Never consume a partial/stale output file left by a rejected model.
       await rm(outputPath, { force: true });
       try {
-        stdout = await spawnReview(
+        processResult = await spawnReview(
           inspection.executable,
           provider === "claude" ? [
             "--print", "--output-format", "json",
@@ -397,7 +401,7 @@ async function runSingleProviderReview(
             "--no-session-persistence", "--tools", "",
             "--setting-sources", "", "--settings", '{"disableAllHooks":true}',
             "--strict-mcp-config", "--mcp-config", '{"mcpServers":{}}',
-            ...(readOnlyAnalysis ? ["--system-prompt", request.system, "--max-turns", "1"] : []),
+            ...(readOnlyAnalysis ? ["--system-prompt", request.system, "--max-turns", String(claudeTurnLimit)] : []),
           ] : [
             "exec",
             "--model",
@@ -416,27 +420,43 @@ async function runSingleProviderReview(
             "-",
           ],
           prompt,
-          { spawnImpl, executionTimeoutMs: remaining, label, cwd: workDir, environment, provider, signal, readOnlyAnalysis, model,
+          { spawnImpl, executionTimeoutMs: remaining, label, cwd: workDir, environment, provider, signal, readOnlyAnalysis, model, retryAttempt,
             terminationGraceMs: Number.isInteger(terminationGraceMs) ? Math.max(1, Math.min(terminationGraceMs, 5_000)) : 1_000 },
         );
         selectedModel = model;
         break;
       } catch (error) {
+        // Repair only an explicit native structured-generation limit. Keep
+        // initial calls unchanged, the original deadline and dispatch guard,
+        // and never retry authentication/schema/process/security failures.
+        if (provider === "claude" && readOnlyAnalysis && retryAttempt === 0
+          && ["provider_turn_limit_reached", "provider_structured_output_exhausted"].includes(error.code)) {
+          retryAttempt = 1;
+          if (error.code === "provider_turn_limit_reached") claudeTurnLimit = 3;
+          continue;
+        }
         if (error.code !== "provider_model_unsupported" || model === models.at(-1)) throw error;
+        modelIndex += 1;
       }
     }
-    const envelope = provider === "claude" ? JSON.parse(stdout) : null;
-    if (envelope?.is_error || (envelope && envelope.subtype !== "success")) {
-      if (readOnlyAnalysis && envelope?.is_error === true && providerSignInRequired(envelope.result)) {
-        throw new SqmLocalReviewError('Sign in to the local AI app again.', { code: 'provider_sign_in_required' });
+    let output;
+    if (provider === "claude") {
+      const envelope = parseProviderJson(processResult.stdout, processResult.diagnostic);
+      const failure = claudeEnvelopeFailure(envelope, processResult.diagnostic);
+      if (failure) throw failure;
+      if (!Object.hasOwn(envelope, "structured_output")) throw providerFailure("provider_missing_structured_output", processResult.diagnostic);
+      output = envelope.structured_output;
+    } else {
+      let text;
+      try { text = await readFile(outputPath, "utf8"); }
+      catch (error) {
+        if (error.code === "ENOENT") throw providerFailure("provider_missing_structured_output", processResult.diagnostic);
+        throw error;
       }
-      throw new Error("Claude Code did not complete a structured review");
+      output = parseProviderJson(text, processResult.diagnostic);
     }
-    const output = provider === "claude"
-      ? envelope?.structured_output
-      : JSON.parse(await readFile(outputPath, "utf8"));
     if (!output || Array.isArray(output) || typeof output !== "object") {
-      throw new Error(`${label} returned a non-object structured result`);
+      throw providerFailure("provider_non_object_output", processResult.diagnostic);
     }
     return {
       output,
@@ -444,7 +464,7 @@ async function runSingleProviderReview(
     };
   } catch (error) {
     if (error instanceof SqmLocalReviewError || error?.code === 'desktop_access_required') throw error;
-    throw new SqmLocalReviewError(`Local ${label} review failed: ${errorMessage(error)}`, {
+    throw new SqmLocalReviewError(`Local ${label} review failed before producing a structured result.`, {
       code: `${provider}_local_review_failed`,
     });
   } finally {
@@ -465,120 +485,156 @@ function codexAnalysisArguments(system) {
     '-c', `developer_instructions=${JSON.stringify(system)}`];
 }
 
-function spawnReview(command, args, prompt, { spawnImpl, executionTimeoutMs, label, cwd, environment, provider, signal, readOnlyAnalysis, terminationGraceMs, model }) {
+function spawnReview(command, args, prompt, { spawnImpl, executionTimeoutMs, cwd, environment, provider, signal, readOnlyAnalysis, terminationGraceMs, model, retryAttempt }) {
   return new Promise((resolve, reject) => {
-    if (signal?.aborted) return reject(new Error('Local analysis was cancelled'));
-    const child = spawnImpl(command, args, {
-      env: safeReviewEnvironment(environment, provider),
-      cwd,
-      windowsHide: true,
-      stdio: ["pipe", "pipe", "pipe"],
-    });
-    let stdout = "";
-    let stderr = "";
-    let stderrPending = "";
-    let settled = false;
-    let terminalError = null;
-    let killTimer = null;
+    if (signal?.aborted) return reject(providerFailure("analysis_cancelled"));
+    let child;
+    try {
+      child = spawnImpl(command, args, {
+        env: safeReviewEnvironment(environment, provider), cwd, windowsHide: true, stdio: ["pipe", "pipe", "pipe"],
+      });
+    } catch { reject(providerFailure("provider_spawn_failed", { model })); return; }
+    let stdout = "", stderrPending = "", outputBytes = 0;
+    let settled = false, terminalError = null, killTimer = null;
+    let diagnostic = safeProviderDiagnostic({ model, retryAttempt });
     const halt = error => {
       if (settled || terminalError) return;
       terminalError = error;
-      child.kill?.('SIGTERM');
+      child.kill?.("SIGTERM");
       if (!settled) killTimer = setTimeout(() => {
-        child.kill?.('SIGKILL');
-        // Do not acknowledge cancellation while an owned provider is still
-        // shutting down. A broken process API is nevertheless bounded.
-        if (!settled) killTimer = setTimeout(() => finish(new Error('Local analysis process did not confirm termination')), terminationGraceMs);
+        child.kill?.("SIGKILL");
+        // Keep the original timeout/cancellation if the process API never
+        // acknowledges termination; do not replace it with an opaque error.
+        if (!settled) killTimer = setTimeout(() => finish(terminalError), terminationGraceMs);
       }, terminationGraceMs);
     };
-    const cancelled = () => halt(new Error('Local analysis was cancelled'));
-    const timer = setTimeout(() => {
-      halt(readOnlyAnalysis ? new SqmLocalReviewError('Local analysis timed out.', { code: 'analysis_timeout' }) : new Error(`${label} timed out after ${executionTimeoutMs}ms`));
-    }, executionTimeoutMs);
+    const cancelled = () => halt(providerFailure("analysis_cancelled"));
+    const timer = setTimeout(() => halt(providerFailure("analysis_timeout")), executionTimeoutMs);
     timer.unref?.();
     const finish = (error = null) => {
       if (settled) return;
       settled = true;
-      clearTimeout(timer);
-      clearTimeout(killTimer);
-      signal?.removeEventListener('abort', cancelled);
-      error ? reject(error) : resolve(stdout);
+      clearTimeout(timer); clearTimeout(killTimer);
+      signal?.removeEventListener("abort", cancelled);
+      diagnostic = safeProviderDiagnostic({ ...diagnostic, outputBytes });
+      if (error) {
+        error.providerDiagnostic = safeProviderDiagnostic({ ...error.providerDiagnostic, ...diagnostic });
+        reject(error);
+      } else resolve({ stdout, diagnostic });
+    };
+    const nativeFailure = message => {
+      if (providerSignInRequired(message)) return providerFailure("provider_sign_in_required");
+      if (provider === "codex" && providerModelUnsupported(message, model)) return modelUnsupportedError(model);
+      const code = nativeProviderFailureCode(message);
+      return code ? providerFailure(code) : null;
+    };
+    const checkStderr = line => {
+      // Only native CLI error lines, never arbitrary warnings or model prose.
+      const match = line.match(/^\s*(?:ERROR:|Error:|API Error:)\s*(.*)$/);
+      if (!match) return;
+      let message = match[1];
+      try {
+        const event = JSON.parse(message);
+        if (event.type !== "error") return;
+        message = event.error?.message ?? event.message;
+      } catch { /* Older CLIs print a plain native ERROR line. */ }
+      const error = nativeFailure(message);
+      if (error) halt(error);
     };
     child.stdout?.setEncoding?.("utf8");
-    child.stdout?.on?.("data", (chunk) => {
-      if (settled) return;
+    child.stdout?.on?.("data", chunk => {
+      if (settled || terminalError) return;
+      outputBytes = Math.min(2147483647, outputBytes + Buffer.byteLength(chunk, "utf8"));
+      if (outputBytes > 2 * 1024 * 1024) { halt(providerFailure("provider_output_too_large")); return; }
       stdout += chunk;
-      if (readOnlyAnalysis && provider === 'codex') {
-        for (const line of stdout.split('\n').filter(Boolean)) {
+      if (readOnlyAnalysis && provider === "codex") {
+        for (const line of stdout.split("\n").filter(Boolean)) {
           let event;
           try { event = JSON.parse(line); } catch { continue; }
-          if (['error', 'turn.failed'].includes(event.type)) {
-            const message = event.message ?? event.error?.message;
-            if (providerSignInRequired(message)) {
-              halt(new SqmLocalReviewError('Sign in to the local AI app again.', { code: 'provider_sign_in_required' }));
-              return;
-            }
-            if (providerModelUnsupported(message, model)) {
-              halt(modelUnsupportedError(model));
-              return;
-            }
+          if (["error", "turn.failed"].includes(event.type)) {
+            const error = nativeFailure(event.message ?? event.error?.message);
+            if (error) { halt(error); return; }
           }
-          if (/command_execution|mcp_tool_call|web_search|file_change|tool_call/.test(event.item?.type || '')) {
-            halt(new Error('Read-only analysis attempted to use a tool'));
-            return;
+          if (/command_execution|mcp_tool_call|web_search|file_change|tool_call/.test(event.item?.type || "")) {
+            halt(providerFailure("provider_tool_use_blocked")); return;
           }
         }
       }
-      if (Buffer.byteLength(stdout, "utf8") > 2 * 1024 * 1024) {
-        halt(new Error(`${label} structured output exceeded the size limit`));
-      }
     });
-    child.stdin?.on?.("error", finish);
+    child.stdin?.on?.("error", () => halt(providerFailure("provider_process_failed")));
     child.stderr?.setEncoding?.("utf8");
-    child.stderr?.on?.("data", (chunk) => {
-      if (!readOnlyAnalysis) stderr = `${stderr}${chunk}`.slice(-4000);
-      if (provider === "codex") {
-        stderrPending = `${stderrPending}${chunk}`.slice(-8000);
-        const lines = stderrPending.split(/\r?\n/);
-        stderrPending = lines.pop() || "";
-        for (const line of lines) checkStderr(line);
-      }
+    child.stderr?.on?.("data", chunk => {
+      if (settled || terminalError) return;
+      stderrPending = `${stderrPending}${chunk}`.slice(-8000);
+      const lines = stderrPending.split(/\r?\n/);
+      stderrPending = lines.pop() || "";
+      for (const line of lines) checkStderr(line);
     });
-    const checkStderr = line => {
-      // Native CLI diagnostics only; never match warnings or assistant text.
-      const match = line.match(/^\s*ERROR:\s*(.*)$/);
-      if (!match) return;
-      let message = match[1];
-      try {
-        const event = JSON.parse(message);
-        if (event.type !== "error") return;
-        message = event.error?.message ?? event.message;
-      } catch { /* Older CLIs print a plain native ERROR line. */ }
-      if (providerSignInRequired(message)) {
-        halt(new SqmLocalReviewError('Sign in to the local AI app again.', { code: 'provider_sign_in_required' }));
-      } else if (providerModelUnsupported(message, model)) {
-        halt(modelUnsupportedError(model));
-      }
-    };
-    child.on("error", finish);
-    child.on("close", (code) => {
-      if (provider === "codex") checkStderr(stderrPending);
-      if (readOnlyAnalysis && provider === 'claude' && !terminalError) {
+    child.on("error", () => finish(providerFailure("provider_spawn_failed")));
+    child.on("close", (exitCode, exitSignal) => {
+      diagnostic = safeProviderDiagnostic({ ...diagnostic, exitCode, signal: exitSignal });
+      checkStderr(stderrPending);
+      if (provider === "claude") {
         let envelope;
-        try { envelope = JSON.parse(stdout); } catch { /* Non-JSON failure remains unavailable. */ }
-        if (envelope?.is_error === true && providerSignInRequired(envelope.result)) {
-          finish(new SqmLocalReviewError('Sign in to the local AI app again.', { code: 'provider_sign_in_required' }));
-          return;
+        try { envelope = JSON.parse(stdout); } catch { /* Classified after a successful process exit. */ }
+        if (envelope && typeof envelope === "object" && !Array.isArray(envelope)) {
+          const models = Object.keys(envelope.modelUsage || {});
+          diagnostic = safeProviderDiagnostic({ ...diagnostic, subtype: envelope.subtype,
+            model: models.length === 1 ? models[0] : envelope.model });
+          terminalError ||= claudeEnvelopeFailure(envelope, diagnostic);
         }
       }
-      finish(terminalError || (code === 0 ? null : new Error(stderr.trim() || `${label} exited with code ${code}`)));
+      finish(terminalError || (exitCode === 0 ? null : providerFailure("provider_process_failed")));
     });
-    signal?.addEventListener('abort', cancelled, { once: true });
+    signal?.addEventListener("abort", cancelled, { once: true });
     if (signal?.aborted) { cancelled(); return; }
     child.stdin?.end(prompt);
   });
 }
 
+function providerFailure(code, providerDiagnostic) {
+  return new SqmLocalReviewError(PROVIDER_FAILURE_HINTS[code]
+    || (code === "provider_sign_in_required" ? "Sign in to the local AI app again." : "The local AI analysis exceeded its time limit."),
+  { code, providerDiagnostic });
+}
+
+function parseProviderJson(text, diagnostic) {
+  try { return JSON.parse(text); }
+  catch { throw providerFailure("provider_invalid_json", diagnostic); }
+}
+
+function claudeEnvelopeFailure(envelope, diagnostic) {
+  if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) return providerFailure("provider_invalid_envelope", diagnostic);
+  if (typeof envelope.subtype !== "string" || (Object.hasOwn(envelope, "is_error") && typeof envelope.is_error !== "boolean")) return providerFailure("provider_invalid_envelope", diagnostic);
+  if (envelope.is_error === true || envelope.subtype !== "success") {
+    // Only inspect native failure envelopes, never a successful model result.
+    const messages = [envelope.result, ...(Array.isArray(envelope.errors) ? envelope.errors.slice(0, 8) : [])];
+    for (const message of messages) if (providerSignInRequired(message)) return providerFailure("provider_sign_in_required", diagnostic);
+    for (const message of messages) {
+      const code = nativeProviderFailureCode(message);
+      if (code) return providerFailure(code, diagnostic);
+    }
+    // An explicit auth/schema/network cause takes precedence over a limit
+    // subtype, so a mixed failure envelope cannot trigger a semantic retry.
+    const subtypeCode = {
+      error_max_turns: "provider_turn_limit_reached", error_max_budget_usd: "provider_budget_exceeded",
+      error_max_structured_output_retries: "provider_structured_output_exhausted",
+    }[envelope.subtype];
+    if (subtypeCode) return providerFailure(subtypeCode, diagnostic);
+    return providerFailure("provider_execution_error", diagnostic);
+  }
+  return null;
+}
+
+function nativeProviderFailureCode(message) {
+  if (typeof message !== "string") return null;
+  const text = message.slice(0, 4000);
+  if (/\b(?:invalid|unsupported)\s+(?:json\s+|output\s+)?schema\b|\bschema validation (?:failed|error)\b/i.test(text)) return "provider_schema_rejected";
+  if (/\b429\b.*(?:rate|limit)|\brate limit(?:ed| exceeded)\b/i.test(text)) return "provider_rate_limited";
+  if (/^(?:API Error:\s*)?(?:Connection error\b|(?:connect )?(?:ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN)\b|fetch failed\b|network (?:error|unavailable)\b)/i.test(text.trim())) return "provider_network_unavailable";
+  return null;
+}
+
 function providerModelUnsupported(message, model) {
   if (typeof message !== "string" || typeof model !== "string") return false;
   const rejection = message.trim().match(/^The ['"]([^'"]+)['"] model is not supported(?: when using Codex with a ChatGPT account)?\.?$/i);
@@ -648,7 +704,8 @@ function reviewFailure(error, stage, provider) {
     else if (stage === "analysis" || stage === "adjudication") code = `${provider}_local_review_failed`;
   }
   return { stage: /^[a-z_]{1,40}$/.test(error?.stage || "") ? error.stage : stage, code,
-    status: Number.isInteger(error?.status) && error.status >= 400 && error.status <= 599 ? error.status : null };
+    status: Number.isInteger(error?.status) && error.status >= 400 && error.status <= 599 ? error.status : null,
+    providerDiagnostic: safeProviderDiagnostic(error?.providerDiagnostic) };
 }
 
 function formatFailure(failure, failureReported = null) {
@@ -660,9 +717,11 @@ function formatFailure(failure, failureReported = null) {
     : failure.status === 403 || failure.code === "desktop_access_required" ? "Check SQM and Developer access for the selected organization."
     : failure.status === 401 ? "Reconnect your SIMY session."
     : failure.code.endsWith("_local_unavailable") ? "Install or update the selected local AI app."
+    : PROVIDER_FAILURE_HINTS[failure.code] ? PROVIDER_FAILURE_HINTS[failure.code]
     : failure.code.endsWith("_local_review_failed") ? "The local AI app did not complete a valid structured review."
     : "Open analysis details to inspect the task state.";
-  return `${failure.stage} · ${failure.code}${failure.status ? ` · HTTP ${failure.status}` : ""}\n${hint}${failureReported === false ? "\nThe failure could not be reported to SIMY Web. The web task may still show as analyzing until its lease expires." : ""}`;
+  const diagnostic = Object.entries(safeProviderDiagnostic(failure.providerDiagnostic)).map(([key, value]) => `${key}=${value}`).join(" · ");
+  return `${failure.stage} · ${failure.code}${failure.status ? ` · HTTP ${failure.status}` : ""}\n${hint}${failure.providerDiagnostic?.retryAttempt === 1 ? "\nOne automatic retry was attempted." : ""}${diagnostic ? `\n${diagnostic}` : ""}${failureReported === false ? "\nThe failure could not be reported to SIMY Web. The web task may still show as analyzing until its lease expires." : ""}`;
 }
 
 function analysisTaskUrl(workspaceUrl, id) {