@awak-app/simy-cli 0.5.72 → 0.5.74

package/src/sqm/review-worker.js

@@ -3,7 +3,9 @@ import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 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,
@@ -20,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);
   }
 }
 
@@ -88,7 +91,8 @@ export function createSqmLocalReviewWorker({
   leaseSeconds = DEFAULT_LEASE_SECONDS,
   heartbeatIntervalMs = Math.max(10_000, Math.floor(leaseSeconds * 500)),
   getProvider = () => "codex",
-  runReview = (request, provider) => runStructuredProviderReview(provider, request),
+  runReview = (request, provider, options) => runStructuredProviderReview(provider, request, { ...options, beforeDispatch: options?.beforeLeaseDispatch }),
+  getEnvironmentKey = () => null,
   beginWork = () => () => {},
   onError = () => {},
   onChange = () => {},
@@ -104,7 +108,7 @@ export function createSqmLocalReviewWorker({
   let activeJobId = null;
   let pollPromise = null;
   let closed = false;
-  let issue = null;
+  let issue = null, pausedEnvironment = null, pauseReason = null;
   let issueContext = null;
   const failureDetails = new WeakMap();
   const pauses = new Map();
@@ -132,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.errorCode = failure.code; }
+      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();
@@ -148,11 +152,11 @@ export function createSqmLocalReviewWorker({
 
   // Repair only a rejected model result, under the same live lease. Network,
   // authorization, and persistence failures must not repeat provider execution.
-  const validatedReview = async (request, provider, code, submit, setStage) => {
+  const validatedReview = async (request, provider, code, submit, setStage, reviewOptions) => {
     let nextRequest = request;
     for (let attempt = 0; ; attempt += 1) {
       setStage(false);
-      const review = await runReview(nextRequest, provider);
+      const review = await runReview(nextRequest, provider, reviewOptions);
       setStage(true);
       try {
         return { review, response: await submit(review) };
@@ -180,22 +184,33 @@ export function createSqmLocalReviewWorker({
     heartbeatTimer = setInterval(heartbeat, heartbeatIntervalMs);
     heartbeatTimer.unref?.();
     let stage = "analysis";
+    const reviewOptions = { providerReportingSupported: claim.capabilities?.reported_executor_provider === true,
+      beforeLeaseDispatch: () => api.request({ action: "heartbeat", ...leaseBody(claim, provider) }) };
+    const providerReport = (review, selectedProvider = provider) => claim.capabilities?.reported_executor_provider === true
+      ? { reported_executor_provider: review.provider || selectedProvider } : {};
     try {
       const { review: analysis, response: advanced } = await validatedReview(claim.request, provider, "invalid_sqm_analysis_output", analysis => api.request({
         action: "advance",
         ...leaseBody(claim, provider),
         analysis_output: analysis.output,
         executor_model: analysis.model,
-      }), submitting => { stage = submitting ? "advance" : "analysis"; if (submitting) pauses.delete(contextKey(provider, historyScope)); });
+        ...providerReport(analysis),
+      }), submitting => { stage = submitting ? "advance" : "analysis"; if (submitting) pauses.delete(contextKey(provider, historyScope)); }, reviewOptions);
+      const analysisProvider = analysis.provider || provider;
+      const item = history.find(item => item.id === claim.job_id);
+      if (item) item.provider = analysisProvider;
       if (advanced.completed) { await updateTask(claim.job_id, "completed", historyScope); return advanced; }
       stage = "adjudication";
-      const { response: completed } = await validatedReview(advanced.request, provider, "invalid_sqm_adjudication_output", adjudication => api.request({
+      const { review: adjudication, response: completed } = await validatedReview(advanced.request, analysisProvider, "invalid_sqm_adjudication_output", adjudication => api.request({
         action: "complete",
         ...leaseBody(claim, provider),
         analysis_output: analysis.output,
         adjudication_output: adjudication.output,
         executor_model: adjudication.model || analysis.model,
-      }), submitting => { stage = submitting ? "complete" : "adjudication"; if (submitting) pauses.delete(contextKey(provider, historyScope)); });
+        ...providerReport(adjudication, analysisProvider),
+        ...(claim.capabilities?.reported_executor_provider === true ? { analysis_executor_provider: analysisProvider, analysis_executor_model: analysis.model } : {}),
+      }), submitting => { stage = submitting ? "complete" : "adjudication"; if (submitting) pauses.delete(contextKey(provider, historyScope)); }, reviewOptions);
+      if (item) item.provider = adjudication.provider || analysisProvider;
       await updateTask(claim.job_id, "completed", historyScope);
       return completed;
     } catch (error) {
@@ -221,7 +236,7 @@ export function createSqmLocalReviewWorker({
   return {
     snapshot() {
       const pause = currentPause();
-      return { active_job_id: activeJobId, polling: Boolean(pollPromise), closed, issue: issueContext === contextKey(getProvider(), getHistoryScope()) ? issue : null,
+      return { active_job_id: activeJobId, polling: Boolean(pollPromise), closed, paused: pausedEnvironment !== null, pause_reason: pauseReason, issue: issueContext === contextKey(getProvider(), getHistoryScope()) ? issue : null,
         ...(pause ? { provider_pause: { code: pause.code, status: pause.status, retry_at: new Date(pause.retryAt).toISOString(), message: pause.message } } : {}) };
     },
     desktopTasks() { return { activeCount: activeJobId ? 1 : 0, items: visibleHistory().map(item => ({ ...item })) }; },
@@ -229,9 +244,13 @@ export function createSqmLocalReviewWorker({
       const item = visibleHistory().find(item => item.key === key);
       return item ? { key, instruction: `SQM local review · ${item.provider}`, result: item.state === "completed" ? "SQM review submitted." : "", error: item.error || "", links: item.webUrl ? [{ label: "Analysis details", url: item.webUrl }] : [] } : null;
     },
-    resetHistory() { if (!pollPromise) { history.splice(0); issue = null; } },
+    retry() { if (closed || pollPromise) return false; pausedEnvironment = null; pauseReason = null; pauses.delete(contextKey(getProvider(), getHistoryScope())); issue = null; onChange(); return true; },
+    resetHistory() { if (!pollPromise) { history.splice(0); issue = null; pausedEnvironment = null; pauseReason = null; } },
     poll() {
       if (closed || pollPromise) return pollPromise || Promise.resolve(null);
+      const environmentKey = getEnvironmentKey();
+      if (pausedEnvironment !== null && pausedEnvironment === environmentKey) return Promise.resolve(null);
+      if (pausedEnvironment !== null) { pausedEnvironment = null; pauseReason = null; pauses.delete(contextKey(getProvider(), getHistoryScope())); issue = null; }
       const provider = getProvider();
       if (provider == null) return Promise.resolve(null);
       assertProvider(provider);
@@ -273,6 +292,9 @@ export function createSqmLocalReviewWorker({
             history.unshift(item); historyScopes.set(item, JSON.stringify(scope)); history.splice(50);
             await persist(scope, item);
           }
+          if (["provider_model_unsupported", "codex_local_unavailable", "claude_local_unavailable", "provider_sign_in_required", "provider_status_unknown"].includes(error.code)) {
+            pausedEnvironment = environmentKey; pauseReason = error.code;
+          }
           issueContext = key;
           issue = error.status === 403 ? "forbidden" : error.status === 401 ? "signed_out" : "unavailable";
           onError(error);
@@ -296,7 +318,33 @@ export function runStructuredCodexReview(request, options) {
   return runStructuredProviderReview("codex", request, options);
 }
 
-export async function runStructuredProviderReview(
+export async function runStructuredProviderReview(provider, request, options = {}) {
+  const fallbackProviders = options.enableEngineFallback === true && options.providerReportingSupported === true && options.readOnlyAnalysis !== false && Array.isArray(options.allowedFallbackProviders)
+    ? [...new Set(options.allowedFallbackProviders.filter(candidate => ["codex", "claude"].includes(candidate) && candidate !== provider))] : [];
+  if (!fallbackProviders.length) return runSingleProviderReview(provider, request, options);
+  const deadlineAt = Date.now() + (options.executionTimeoutMs ?? DEFAULT_EXECUTION_TIMEOUT_MS);
+  const attempts = [];
+  for (const candidate of [provider, ...fallbackProviders]) {
+    if (options.signal?.aborted) throw new SqmLocalReviewError("Local analysis was cancelled.", { code: "analysis_cancelled" });
+    if (Date.now() >= deadlineAt) throw new SqmLocalReviewError("Local analysis timed out.", { code: "analysis_timeout" });
+    if (candidate !== provider) {
+      await options.beforeDispatch?.(candidate);
+      const readiness = await (options.inspectProviderStatus || inspectProviderStatus)(candidate);
+      if (readiness.state !== "ready") throw new SqmLocalReviewError("Fallback provider is not signed in and ready.", {
+        code: readiness.state === "signed_out" ? "provider_sign_in_required" : "provider_status_unknown" });
+    }
+    try {
+      const result = await runSingleProviderReview(candidate, request, { ...options, deadlineAt,
+        beforeDispatch: () => options.beforeDispatch?.(candidate) });
+      return { ...result, provider: candidate, provider_attempts: [...attempts, { provider: candidate, code: "completed" }] };
+    } catch (error) {
+      attempts.push({ provider: candidate, code: error.code });
+      if (!["provider_model_unsupported", "codex_local_unavailable", "claude_local_unavailable"].includes(error.code) || candidate === fallbackProviders.at(-1)) throw error;
+    }
+  }
+}
+
+async function runSingleProviderReview(
   provider,
   request,
   {
@@ -308,6 +356,7 @@ export async function runStructuredProviderReview(
     readOnlyAnalysis = true,
     terminationGraceMs = 1_000,
     beforeDispatch = async () => {},
+    deadlineAt,
   } = {},
 ) {
   assertProvider(provider);
@@ -330,11 +379,13 @@ export async function runStructuredProviderReview(
       "Return only JSON that strictly matches the provided output schema.",
       request.prompt,
     ].join("\n\n");
-    const deadline = Date.now() + executionTimeoutMs;
+    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();
@@ -342,7 +393,7 @@ export async function runStructuredProviderReview(
       // 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",
@@ -350,7 +401,7 @@ export async function runStructuredProviderReview(
             "--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",
@@ -369,27 +420,43 @@ export async function runStructuredProviderReview(
             "-",
           ],
           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,
@@ -397,7 +464,7 @@ export async function runStructuredProviderReview(
     };
   } 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 {
@@ -418,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);
@@ -601,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) {
@@ -613,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) {

package/src/sqm/session.js

@@ -18,10 +18,18 @@ export async function ensureSqmSession(
     startAgentImpl = startAgent,
     openAuthorizationUrlImpl = openAuthorizationUrl,
     createAgentShutdownImpl = createAgentShutdown,
+    expectedScope,
+    signal,
+    rejectedToken,
   } = {},
 ) {
   let session = await readSessionImpl(webOrigin);
-  if (sqmSessionReady(session, webOrigin, now(), isSessionValidImpl)) return session;
+  const pinnedScope = expectedScope || sqmSessionScope(session, webOrigin);
+  signal?.throwIfAborted();
+  if (session?.token !== rejectedToken && sqmSessionReady(session, webOrigin, now(), isSessionValidImpl)) {
+    assertSqmSessionScope(session, webOrigin, pinnedScope);
+    return session;
+  }
 
   const agent = await startAgentImpl({ requestedPort: 0, webOrigin, quiet: true });
   const shutdown = createAgentShutdownImpl(agent);
@@ -35,19 +43,41 @@ export async function ensureSqmSession(
 
     const deadline = now() + timeoutMs;
     while (now() < deadline) {
+      signal?.throwIfAborted();
       await sleep(Math.min(500, Math.max(1, deadline - now())));
       session = await readSessionImpl(webOrigin);
-      if (sqmSessionReady(session, webOrigin, now(), isSessionValidImpl)) {
+      if (session?.token !== rejectedToken && sqmSessionReady(session, webOrigin, now(), isSessionValidImpl)) {
+        assertSqmSessionScope(session, webOrigin, pinnedScope);
         logger.log("SIMY CLI authorization completed. Continuing SQM check.");
         return session;
       }
     }
-    throw new Error("SIMY authorization timed out. Complete the browser sign-in and rerun the SQM command.");
+    const error = new Error("SIMY authorization timed out. Complete the browser sign-in and rerun the SQM command.");
+    error.code = "authorization_timeout";
+    throw error;
   } finally {
     await shutdown();
   }
 }
 
+export function sqmSessionScope(session, webOrigin) {
+  return { account_id: session?.account_id || session?.auth_user_id || null,
+    organization_id: session?.organization_id || session?.org_id || null,
+    device_id: session?.device_id || null, api_base_url: session?.api_base_url || null,
+    web_origin: new URL(webOrigin).origin };
+}
+
+export function assertSqmSessionScope(session, webOrigin, expected) {
+  const current = sqmSessionScope(session, webOrigin);
+  for (const field of ["account_id", "organization_id", "device_id", "api_base_url", "web_origin"]) {
+    if (expected?.[field] && expected[field] !== current[field]) {
+      const error = new Error(`SQM authorization changed its ${field}; resume the original authorized scope.`);
+      error.code = "authorization_scope_changed";
+      throw error;
+    }
+  }
+}
+
 function sqmSessionReady(session, webOrigin, now, isSessionValidImpl) {
   return Boolean(
     isSessionValidImpl(session, now, webOrigin) &&