@awak-app/simy-cli 0.5.71 → 0.5.73

package/src/sqm/request-recovery.js

@@ -0,0 +1,82 @@
+const TRANSIENT_STATUSES = new Set([502, 503, 504]);
+const NETWORK_CODES = new Set(["ECONNRESET", "ECONNREFUSED", "ENETUNREACH", "EAI_AGAIN", "ETIMEDOUT", "UND_ERR_CONNECT_TIMEOUT", "UND_ERR_SOCKET"]);
+
+export function sqmDiagnostic(error, stage = "unknown") {
+  const status = error?.http_status ?? error?.status;
+  const timeout = error?.name === "TimeoutError" || error?.code === "ETIMEDOUT";
+  const network = (error instanceof TypeError && /fetch failed|failed to fetch|network request failed/i.test(error.message)) ||
+    NETWORK_CODES.has(error?.code) || NETWORK_CODES.has(error?.cause?.code);
+  const safeCode = typeof error?.code === "string" && /^[a-z][a-z0-9_]{0,79}$/.test(error.code) ? error.code : null;
+  return {
+    stage: typeof error?.stage === "string" && /^[a-z][a-z0-9_]{0,79}$/.test(error.stage) ? error.stage : stage,
+    code: safeCode || (status === 401 ? "sign_in_required" : status === 403 ? "access_denied" :
+      status === 409 ? "scope_unresolved" : TRANSIENT_STATUSES.has(status) ? "gateway_unavailable" :
+      timeout ? "request_timeout" : network ? "network_unavailable" : "check_failed"),
+    ...(Number.isInteger(status) && status >= 400 && status <= 599 ? { http_status: status } : {}),
+    retryable: error?.retryable !== false && (TRANSIENT_STATUSES.has(status) || timeout || network),
+  };
+}
+
+// This deliberately exposes only GET recovery. Uncertain POST success must be
+// reconciled with a server idempotency contract before it may be replayed.
+export async function fetchSqmRead(url, {
+  headers, signal, fetchImpl = globalThis.fetch,
+  timeoutMs = 45_000, requestTimeoutMs = 15_000, maxAttempts = 3,
+  sleep = abortableSleep, now = Date.now, onRecoveryEvent = async () => {},
+} = {}) {
+  const totalLimit = boundedInteger(timeoutMs, 45_000);
+  const requestLimit = boundedInteger(requestTimeoutMs, 15_000);
+  const deadline = now() + totalLimit;
+  const deadlineSignal = AbortSignal.timeout(totalLimit);
+  const attempts = boundedInteger(maxAttempts, 3);
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    signal?.throwIfAborted();
+    deadlineSignal.throwIfAborted();
+    const remaining = deadline - now();
+    if (remaining <= 0) throw new DOMException("SQM request recovery deadline exceeded.", "TimeoutError");
+    const attemptSignal = AbortSignal.any([
+      deadlineSignal, AbortSignal.timeout(Math.min(requestLimit, remaining)),
+      ...(signal ? [signal] : []),
+    ]);
+    try {
+      const response = await withAbort(fetchImpl(url, { method: "GET", headers, signal: attemptSignal }), attemptSignal);
+      if (!TRANSIENT_STATUSES.has(response.status)) return response;
+      const error = new Error(`SQM Cloud returned HTTP ${response.status}.`);
+      error.status = response.status;
+      if (attempt === attempts) return response;
+      await response.body?.cancel().catch(() => {});
+      throw error;
+    } catch (error) {
+      if (signal?.aborted) throw signal.reason;
+      const diagnostic = sqmDiagnostic(error, "knowledge_loading");
+      if (!diagnostic.retryable || attempt === attempts || deadlineSignal.aborted) throw error;
+      await onRecoveryEvent({ ...diagnostic, attempt, recovery: "retrying" });
+      const delay = Math.min(250 * 2 ** (attempt - 1), Math.max(0, deadline - now()));
+      if (delay <= 0) throw new DOMException("SQM request recovery deadline exceeded.", "TimeoutError");
+      await sleep(delay, AbortSignal.any([deadlineSignal, ...(signal ? [signal] : [])]));
+    }
+  }
+}
+
+function boundedInteger(value, maximum) {
+  return Number.isFinite(value) && value > 0 ? Math.min(maximum, Math.max(1, Math.floor(value))) : maximum;
+}
+
+function withAbort(promise, signal) {
+  return new Promise((resolve, reject) => {
+    const abort = () => { signal.removeEventListener("abort", abort); reject(signal.reason); };
+    if (signal.aborted) abort();
+    else signal.addEventListener("abort", abort, { once: true });
+    Promise.resolve(promise).then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+  });
+}
+
+function abortableSleep(milliseconds, signal) {
+  signal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const finish = () => { signal.removeEventListener("abort", abort); resolve(); };
+    const timer = setTimeout(finish, milliseconds);
+    const abort = () => { clearTimeout(timer); signal.removeEventListener("abort", abort); reject(signal.reason); };
+    signal.addEventListener("abort", abort, { once: true });
+  });
+}

package/src/sqm/review-worker.js

@@ -3,6 +3,7 @@ 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 {
   webApiErrorMessage,
@@ -88,7 +89,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 = () => {},
@@ -96,12 +98,30 @@ export function createSqmLocalReviewWorker({
   getWorkspaceUrl = () => null,
   recordHistory = async () => {},
   onHistoryError = () => {},
+  now = () => Date.now(),
+  providerFailureCooldownMs = 5 * 60_000,
+  getRecoveryKey = () => null,
 } = {}) {
   if (!api || typeof api.request !== "function") throw new TypeError("api.request is required");
   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();
+  const contextKey = (provider, scope) => JSON.stringify([scope?.webOrigin, scope?.accountId, scope?.organizationId, provider]);
+  const currentPause = () => pauses.get(contextKey(getProvider(), getHistoryScope()));
+  const pauseForFailure = (error, provider, scope, recoveryKey) => {
+    const failure = failureDetails.get(error) || reviewFailure(error, "claim", provider);
+    if (!["provider_sign_in_required", "provider_model_unsupported", "codex_local_unavailable", "claude_local_unavailable", "desktop_access_required"].includes(failure.code) && ![401, 403].includes(failure.status)) return;
+    const key = contextKey(provider, scope);
+    const failures = Math.min((pauses.get(key)?.failures || 0) + 1, 4);
+    const delay = Math.min(30 * 60_000, Math.max(1000, providerFailureCooldownMs) * 2 ** (failures - 1));
+    pauses.set(key, { code: failure.code, stage: failure.stage, status: failure.status, failures, recoveryKey,
+      retryAt: now() + delay, message: `${formatFailure(failure)}\nNew SQM claims are paused. After fixing this cause, refresh the local AI connection or wait for the next recovery attempt.` });
+    if (pauses.size > 32) pauses.delete(pauses.keys().next().value);
+  };
   const history = [];
   const historyScopes = new WeakMap();
   const visibleHistory = () => history.filter(item => historyScopes.get(item) === JSON.stringify(getHistoryScope()));
@@ -114,7 +134,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; }
       await persist(scope, item);
     }
     onChange();
@@ -130,11 +150,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) };
@@ -162,26 +182,38 @@ 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"; });
+        ...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"; });
+        ...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) {
       const failure = reviewFailure(error, stage, provider);
+      if (error && typeof error === "object") failureDetails.set(error, failure);
       let failureReported = error.failureRecorded === true;
       if (!failureReported) {
         try {
@@ -201,22 +233,33 @@ export function createSqmLocalReviewWorker({
 
   return {
     snapshot() {
-      return { active_job_id: activeJobId, polling: Boolean(pollPromise), closed, issue };
+      const pause = currentPause();
+      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 })) }; },
     desktopTaskDetail(key) {
       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);
+      const historyScope = getHistoryScope();
+      const key = contextKey(provider, historyScope);
+      const recoveryKey = getRecoveryKey(provider);
+      const pause = pauses.get(key);
+      if (pause && pause.recoveryKey === recoveryKey && now() < pause.retryAt) return Promise.resolve(null);
+      if (pause && pause.recoveryKey !== recoveryKey) pauses.delete(key);
       const releaseWork = beginWork?.();
       if (!releaseWork) return Promise.resolve(null);
-      const historyScope = getHistoryScope();
       const workspaceUrl = getWorkspaceUrl();
       pollPromise = (async () => {
         const claim = await api.request({
@@ -226,10 +269,18 @@ export function createSqmLocalReviewWorker({
           lease_seconds: leaseSeconds,
         });
         if (issue) { issue = null; onChange(); }
-        if (!claim?.claimed) return null;
-        return processClaim(claim, provider, historyScope, workspaceUrl);
+        if (!claim?.claimed) {
+          // A successful empty claim proves SIMY access recovered, but it says
+          // nothing about a local provider that has not executed again yet.
+          if (pause?.stage === "claim") pauses.delete(key);
+          return null;
+        }
+        const result = await processClaim(claim, provider, historyScope, workspaceUrl);
+        pauses.delete(key);
+        return result;
       })()
         .catch(async (error) => {
+          pauseForFailure(error, provider, historyScope, recoveryKey);
           if (error.jobId && /^[a-f0-9-]{36}$/i.test(error.jobId) && !history.some(item => item.id === error.jobId)) {
             const scope = historyScope;
             const failure = reviewFailure(error, "claim", provider);
@@ -239,6 +290,10 @@ 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);
           return null;
@@ -261,7 +316,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,
   {
@@ -273,6 +354,7 @@ export async function runStructuredProviderReview(
     readOnlyAnalysis = true,
     terminationGraceMs = 1_000,
     beforeDispatch = async () => {},
+    deadlineAt,
   } = {},
 ) {
   assertProvider(provider);
@@ -295,7 +377,7 @@ 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 selectedModel;

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) &&

package/src/startup-preflight.js

@@ -0,0 +1,44 @@
+import { createCodingLoopSnapshot } from "./orchestrator/contract.js";
+import { validateCharter } from "./orchestrator/charter-validation.js";
+
+// Reuse the execution charter rather than inventing a second approval policy.
+// These checks inspect local metadata only; model access requires real dispatch.
+export function startupRequirementChecks(request = {}) {
+  const checks = [{ key: "model_access", status: "unknown", blocking: false,
+    summary: "Signing in does not prove access to the requested model. Access is checked on dispatch without a paid preflight request.",
+    action: { id: "review_model_access", type: "inspect_provider", label: "Review provider and model settings" } }];
+  if (!String(request.requirement || "").trim()) {
+    checks.push({ key: "task_requirements", status: "unknown", blocking: false,
+      summary: "Environment check only. Supply the task requirement to check acceptance criteria and design approval.",
+      action: { id: "provide_requirement", type: "edit_requirements", label: "Provide task requirements" } });
+    return checks;
+  }
+  const { charter } = createCodingLoopSnapshot({ runId: "preflight", request });
+  const findings = validateCharter(charter);
+  for (const [key, code, passed, actionId, label] of [
+    ["acceptance_criteria", "EXPLICIT_ACCEPTANCE_CRITERIA_REQUIRED", "Acceptance criteria satisfy the task risk policy.", "provide_acceptance_criteria", "Provide explicit acceptance criteria"],
+    ["design_review", "DESIGN_REVIEW_REQUIRED", "Design approval satisfies the task risk policy.", "approve_design", "Provide design review and approval evidence"],
+    ["required_checks", "REQUIRED_CI_CHECKS_MISSING", "Required checks satisfy the task risk policy.", "provide_required_checks", "Provide CI and security check names"],
+  ]) {
+    const finding = findings.find(item => item.code === code);
+    checks.push({ key, status: finding ? "failed" : "passed", blocking: Boolean(finding),
+      summary: finding?.explanation || passed,
+      ...(finding ? { code, action: { id: actionId, type: "edit_requirements", label } } : {}) });
+  }
+  checks.push({ key: "assurance_selection", status: "unknown", blocking: false,
+    summary: "The executor must verify the five-level comparison and user selection in existing decision evidence before material implementation.",
+    action: { id: "review_assurance_selection", type: "review_decision_evidence", label: "Review assurance level and selection evidence" } });
+  checks.push({ key: "external_dependencies", status: "unknown", blocking: false,
+    summary: "Confirm test accounts, external resources and permissions required by the acceptance criteria. Local readiness does not certify Cloud entitlement.",
+    action: { id: "confirm_external_dependencies", type: "edit_requirements", label: "Confirm external inputs and permissions" } });
+  return checks;
+}
+
+export function summarizeStartupChecks(checks) {
+  const blockers = checks.filter(check => check.status === "failed" && check.blocking !== false);
+  const unknown = checks.filter(check => check.status === "unknown");
+  return { status: blockers.length ? "blocked" : unknown.length ? "needs_confirmation" : "ready",
+    blocker_keys: blockers.map(check => check.key), unknown_keys: unknown.map(check => check.key),
+    actions: checks.flatMap(check => check.action ? [{ check_key: check.key, ...check.action }]
+      : (check.recovery?.actions || []).map(action => ({ check_key: check.key, ...action }))) };
+}