@awak-app/simy-cli 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,6 @@
 # SIMY CLI
 
-Local execution agent for SIMY coding loops.
+Local execution agent for SIMY Agentic Loop runs.
 
 ```bash
 npx @awak-app/simy-cli
@@ -18,16 +18,50 @@ available for automation, but the command-line flag takes precedence.
 
 The CLI starts a loopback HTTP agent on a random available port, keeps a
 48-hour, origin-scoped local session, and opens a native coding chat. The first
-chat message creates the remote audit ledger and starts the local coding-loop
+chat message creates the remote audit ledger and starts the local Agentic Loop
 state machine; SIMY Web mirrors the lifecycle but is not required as the task
 entry point. The CLI also accepts backend-issued launch challenges for Web-led
 runs. It builds the requirement charter, runs Codex or Claude Code, audits
 structured completion evidence, and re-instructs the executor within the
 configured attempt budget.
 
+## Executor compatibility
+
+SIMY checks the selected executor with `--version` before an Agentic Loop can
+start. The currently validated compatibility floors are Codex `0.144.0` and
+Claude Code `2.1.200`. A missing, older, or unversioned executable fails the
+preflight and returns the installed version, required version, and a recovery
+command to SIMY Web. Update Codex with
+`npm install -g @openai/codex@latest`; update Claude Code with `claude update`.
+
+## Your Desktop executor
+
+SIMY CLI is the `desktop` execution target, shown to users as **Your Desktop**.
+It can run either Codex or Claude Code as a child process inside the verified
+local Git checkout. Device heartbeats advertise both desktop provider
+capabilities and their installed/required versions. Preflight and every standard
+provider dispatch fail closed unless the selected binary is compatible; there
+is no fallback to an unverified executable name.
+
+Legacy local requests without `execution_target` continue to resolve to
+`desktop`. A request marked for the hosted `simy` target is rejected by the
+local CLI boundary so hosted and desktop execution cannot be confused. The
+target and bound device id are preserved in the run Charter, redacted Web
+ledger snapshot, and restored run.
+
+## Blocked recovery contract
+
+Every `waiting_human`, `blocked`, or `failed` lifecycle event includes a
+versioned `detail.recovery` object. It provides a stable reason code, a
+user-safe explanation, a primary action, executable action metadata, and
+bounded technical details. Preflight failures use the same contract for
+executor updates, repository selection, and CLI reconnection. Web clients must
+validate the action type before rendering or executing it; raw local error text
+is not copied into the recovery contract.
+
 ## Interactive console
 
-Running `simy` in a terminal opens the Coding Loop chat. It discovers the
+Running `simy` in a terminal opens the Agentic Loop chat. It discovers the
 current GitHub repository and branch, selects an available executor, and keeps
 the composer active so a natural-language request can start immediately. Each
 run appears in a selectable list with its lifecycle state, process ID, and a
@@ -74,7 +108,7 @@ The local PR lifecycle is intentionally separate from deployment:
    and human approval all pass.
 
 The Web UI can refresh review and CI evidence with
-`POST /v1/coding-loop/:run_id/recheck`. Passing the local implementation gate
+`POST /v1/agentic-loop/:run_id/recheck`. Passing the local implementation gate
 does not by itself make a PR merge-ready.
 
 Start `simy` from the selected repository or a workspace containing it. Set
@@ -86,7 +120,7 @@ from an empty CLI chat, types repository, branch, executor, attachment, and task
 input through a pseudoterminal, creates the Web ledger, spawns real child
 processes, and exercises HIL plus lifecycle controls. It regenerates the
 screenshots, terminal frames, raw transcript, and SHA-256 manifest under
-`docs/pr-evidence/cli-coding-loop-console/`.
+`docs/pr-evidence/cli-agentic-loop-console/`.
 
 ## Publishing
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@awak-app/simy-cli",
-  "version": "0.1.2",
-  "description": "Local SIMY coding-loop agent for Codex and Claude Code.",
+  "version": "0.1.4",
+  "description": "Local SIMY Agentic Loop executor for Codex and Claude Code.",
   "type": "module",
   "bin": {
     "simy": "src/index.js"
@@ -14,11 +14,21 @@
     "start": "node ./src/index.js",
     "test": "node --test",
     "test:e2e:console": "node ./scripts/console-e2e.js",
+    "test:e2e:audit-gate": "node ./scripts/audit-gate-e2e.js",
+    "test:e2e:retry-circuit": "node ./scripts/retry-circuit-e2e.js",
+    "test:e2e:follow-up-charter": "node ./scripts/follow-up-charter-e2e.js",
+    "test:e2e:task-routing": "node ./scripts/task-routing-e2e.js",
+    "test:e2e:executor-version-preflight": "node ./scripts/executor-version-preflight-e2e.js",
+    "test:e2e:blocked-recovery": "node ./scripts/blocked-recovery-e2e.js",
+    "test:e2e:process-localization": "node ./scripts/process-localization-e2e.js",
+    "test:e2e:hypothesis-retries": "node ./scripts/hypothesis-retries-e2e.js",
+    "test:e2e:budgets": "node ./scripts/budget-enforcement-e2e.js",
+    "test:e2e:desktop-executor": "node ./scripts/desktop-executor-e2e.js",
     "test:e2e:console:real-provider": "node ./scripts/real-provider-console-e2e.js",
     "test:e2e:console:fullstack": "node ./scripts/fullstack-cli-smoke.js",
-    "check": "npm run check:syntax && npm run check:real-provider-syntax && npm test && npm run check:package",
+    "check": "node --check ./src/desktop-executor.js && node --check ./scripts/desktop-executor-e2e.js && node --check ./scripts/fixtures/fake-desktop-provider.js && npm run check:syntax && npm run check:real-provider-syntax && npm test && npm run check:package",
     "check:real-provider-syntax": "node --check ./scripts/real-codex-probe.js && node --check ./scripts/real-claude-probe.js && node --check ./scripts/real-provider-console-fixture.js && node --check ./scripts/real-provider-console-e2e.js",
-    "check:syntax": "node --check ./src/index.js && node --check ./src/agent.js && node --check ./src/browser.js && node --check ./src/web-api.js && node --check ./src/run-registry.js && node --check ./src/backend-executable.js && node --check ./src/provider-stream.js && node --check ./src/console/index.js && node --check ./src/console/app.js && node --check ./src/console/commands.js && node --check ./src/local-attachments.js && node --check ./src/repository-inventory.js && node --check ./src/session-store.js && node --check ./src/web-origin.js && node --check ./src/workspace-context.js && node --check ./src/orchestrator/index.js && node --check ./src/orchestrator/shared.js && node --check ./src/orchestrator/risk.js && node --check ./src/orchestrator/contract.js && node --check ./src/orchestrator/instruction.js && node --check ./src/orchestrator/execution-io.js && node --check ./src/orchestrator/presentation.js && node --check ./src/orchestrator/result.js && node --check ./src/orchestrator/evidence.js && node --check ./src/orchestrator/independent-audit.js && node --check ./src/orchestrator/audit.js && node --check ./src/orchestrator/loop.js && node --check ./src/runner.js && node --check ./scripts/fixtures/fake-coding-backend.js && node --check ./scripts/console-e2e-fixture.js && node --check ./scripts/console-e2e.js && node --check ./scripts/real-provider-console-fixture.js && node --check ./scripts/real-provider-console-e2e.js && node --check ./scripts/fullstack-cli-smoke.js && node --check ./scripts/check-package-contents.js",
+    "check:syntax": "node --check ./src/index.js && node --check ./src/agent.js && node --check ./src/browser.js && node --check ./src/web-api.js && node --check ./src/run-registry.js && node --check ./src/backend-executable.js && node --check ./src/provider-stream.js && node --check ./src/console/index.js && node --check ./src/console/app.js && node --check ./src/console/commands.js && node --check ./src/local-attachments.js && node --check ./src/repository-inventory.js && node --check ./src/session-store.js && node --check ./src/web-origin.js && node --check ./src/workspace-context.js && node --check ./src/orchestrator/index.js && node --check ./src/orchestrator/shared.js && node --check ./src/orchestrator/recovery.js && node --check ./src/orchestrator/risk.js && node --check ./src/orchestrator/contract.js && node --check ./src/orchestrator/instruction.js && node --check ./src/orchestrator/problem-solving.js && node --check ./src/orchestrator/budget.js && node --check ./src/orchestrator/execution-io.js && node --check ./src/orchestrator/presentation.js && node --check ./src/orchestrator/result.js && node --check ./src/orchestrator/retry.js && node --check ./src/orchestrator/evidence.js && node --check ./src/orchestrator/independent-audit.js && node --check ./src/orchestrator/audit.js && node --check ./src/orchestrator/loop.js && node --check ./src/runner.js && node --check ./scripts/fixtures/fake-coding-backend.js && node --check ./scripts/e2e-terminal-evidence.js && node --check ./scripts/audit-gate-e2e.js && node --check ./scripts/retry-circuit-e2e.js && node --check ./scripts/follow-up-charter-e2e.js && node --check ./scripts/task-routing-e2e.js && node --check ./scripts/executor-version-preflight-e2e.js && node --check ./scripts/blocked-recovery-e2e.js && node --check ./scripts/process-localization-e2e.js && node --check ./scripts/hypothesis-retries-e2e.js && node --check ./scripts/budget-enforcement-e2e.js && node --check ./scripts/console-e2e-fixture.js && node --check ./scripts/console-e2e.js && node --check ./scripts/real-provider-console-fixture.js && node --check ./scripts/real-provider-console-e2e.js && node --check ./scripts/fullstack-cli-smoke.js && node --check ./scripts/check-package-contents.js",
     "check:package": "node ./scripts/check-package-contents.js"
   },
   "engines": {

package/src/agent.js

@@ -36,7 +36,19 @@ import {
   referenceLocalAttachmentPaths,
 } from "./local-attachments.js";
 import { discoverWorkspace } from "./workspace-context.js";
-import { resolveBackendExecutable } from "./backend-executable.js";
+import { BACKEND_VERSION_POLICIES } from "./backend-executable.js";
+import {
+  DESKTOP_EXECUTION_LABEL,
+  DESKTOP_EXECUTION_TARGET,
+  desktopExecutorCapability,
+  inspectDesktopExecutor,
+  normalizeDesktopExecutionTarget,
+} from "./desktop-executor.js";
+import { recoveryContractForPreflight } from "./orchestrator/recovery.js";
+import {
+  DEFAULT_RETRY_BUDGET,
+  DEFAULT_TOKEN_BUDGET,
+} from "./orchestrator/budget.js";
 import {
   resolveWebApiBaseUrl,
   sessionRequiresWebAuthorization,
@@ -239,6 +251,7 @@ export async function startAgent({
       }
 
       const url = new URL(req.url || "/", `http://${req.headers.host || "127.0.0.1"}`);
+      const agenticLoopPath = canonicalAgenticLoopPath(url.pathname);
       if (req.method === "GET" && url.pathname === "/v1/health") {
         json(res, 200, {
           ok: true,
@@ -253,7 +266,7 @@ export async function startAgent({
         json(res, 200, await readCapabilities(dependencies));
         return;
       }
-      if (req.method === "POST" && url.pathname === "/v1/coding-loop/preflight") {
+      if (req.method === "POST" && agenticLoopPath === "/v1/agentic-loop/preflight") {
         if (!isSessionValid(session, Date.now(), apiOrigin)) {
           json(res, 401, { error: "simy session expired; run simy again" });
           return;
@@ -268,11 +281,22 @@ export async function startAgent({
           json(res, 400, { error: "backend must be codex or claude" });
           return;
         }
+        let executionTarget;
+        try {
+          executionTarget = normalizeDesktopExecutionTarget(body.execution_target);
+        } catch (error) {
+          json(res, 400, {
+            error: error instanceof Error ? error.message : "execution_target must be desktop",
+            code: "unsupported_execution_target",
+          });
+          return;
+        }
         const backend = body.backend;
         const indexedRepository = await ensureRepositoryIndexed(repository);
         const environment = await inspectCodingLoopEnvironment({
           repository,
           backend,
+          executionTarget,
           localPath:
             typeof body.local_path === "string"
               ? body.local_path
@@ -316,7 +340,7 @@ export async function startAgent({
         void synchronizeAuthorizedSession();
         return;
       }
-      if (req.method === "POST" && url.pathname === "/v1/coding-loop/start") {
+      if (req.method === "POST" && agenticLoopPath === "/v1/agentic-loop/start") {
         if (!isSessionValid(session, Date.now(), apiOrigin)) {
           json(res, 401, { error: "simy session expired; run simy again" });
           return;
@@ -339,9 +363,40 @@ export async function startAgent({
           return;
         }
         if (registry.has(runId)) {
-          json(res, 409, { error: "coding loop run already exists" });
+          json(res, 409, { error: "agentic loop run already exists" });
+          return;
+        }
+        let executionTarget;
+        try {
+          executionTarget = normalizeDesktopExecutionTarget(body.execution_target);
+        } catch (error) {
+          json(res, 400, {
+            error: error instanceof Error ? error.message : "execution_target must be desktop",
+            code: "unsupported_execution_target",
+          });
+          return;
+        }
+        if (body.backend !== "codex" && body.backend !== "claude") {
+          json(res, 400, { error: "backend must be codex or claude" });
           return;
         }
+        if (body.execution_target != null) {
+          const inspection = normalizeBackendInspection(body.backend, availableCapabilities);
+          if (!inspection.compatible) {
+            const summary = backendPreflightSummary(body.backend, inspection);
+            json(res, 409, {
+              error: summary,
+              code: `desktop_executor_${inspection.status}`,
+              execution_target: executionTarget,
+              recovery: recoveryContractForPreflight({
+                key: "backend",
+                summary,
+                details: inspection,
+              }),
+            });
+            return;
+          }
+        }
         let stagedAttachments = [];
         try {
           stagedAttachments = await stageRunAttachments({
@@ -358,6 +413,8 @@ export async function startAgent({
           runId,
           request: {
             backend: body.backend === "claude" ? "claude" : "codex",
+            execution_target: executionTarget,
+            execution_device_id: session?.device_id || null,
             audit_backend:
               body.audit_backend === "claude" || body.audit_backend === "codex"
                 ? body.audit_backend
@@ -370,6 +427,8 @@ export async function startAgent({
                 : indexedRepository?.local_path || null,
             base_branch: typeof body.base_branch === "string" ? body.base_branch : "dev",
             max_attempts: body.max_attempts,
+            retry_budget: body.retry_budget,
+            token_budget: body.token_budget,
             ui_evidence_root:
               typeof body.ui_evidence_root === "string" ? body.ui_evidence_root : "",
             acceptance_criteria: Array.isArray(body.acceptance_criteria)
@@ -391,6 +450,12 @@ export async function startAgent({
               typeof body.design_review_url === "string" ? body.design_review_url : "",
             must_not: Array.isArray(body.must_not) ? body.must_not : [],
             proposal_id: typeof body.proposal_id === "string" ? body.proposal_id : null,
+            charter_context:
+              body.charter_context &&
+              typeof body.charter_context === "object" &&
+              !Array.isArray(body.charter_context)
+                ? body.charter_context
+                : null,
             attachments: stagedAttachments,
           },
           session,
@@ -407,7 +472,7 @@ export async function startAgent({
         return;
       }
 
-      const controlMatch = url.pathname.match(/^\/v1\/coding-loop\/([^/]+)\/control$/);
+      const controlMatch = agenticLoopPath.match(/^\/v1\/agentic-loop\/([^/]+)\/control$/);
       if (req.method === "POST" && controlMatch) {
         if (!isSessionValid(session, Date.now(), apiOrigin)) {
           json(res, 401, { error: "simy session expired; run simy again" });
@@ -421,6 +486,10 @@ export async function startAgent({
         const body = await readJson(req);
         if (body.action === "stop") {
           await stopLocalCodingRun(run);
+          if (run.status !== "stopped" || run.controlState !== "stopped") {
+            json(res, 500, { error: "local executor stop was not confirmed" });
+            return;
+          }
         } else if (body.action === "pause") {
           pauseLocalCodingRun(run);
         } else if (body.action === "resume") {
@@ -440,7 +509,7 @@ export async function startAgent({
         return;
       }
 
-      const guidanceMatch = url.pathname.match(/^\/v1\/coding-loop\/([^/]+)\/guidance$/);
+      const guidanceMatch = agenticLoopPath.match(/^\/v1\/agentic-loop\/([^/]+)\/guidance$/);
       if (req.method === "POST" && guidanceMatch) {
         if (!isSessionValid(session, Date.now(), apiOrigin)) {
           json(res, 401, { error: "simy session expired; run simy again" });
@@ -470,7 +539,7 @@ export async function startAgent({
         return;
       }
 
-      const hilMatch = url.pathname.match(/^\/v1\/coding-loop\/([^/]+)\/hil$/);
+      const hilMatch = agenticLoopPath.match(/^\/v1\/agentic-loop\/([^/]+)\/hil$/);
       if (hilMatch) {
         if (!isSessionValid(session, Date.now(), apiOrigin)) {
           json(res, 401, { error: "simy session expired; run simy again" });
@@ -545,14 +614,14 @@ export async function startAgent({
             repository: selected.repository,
             local_path: selected.local_path,
             root: scan.root,
-            state: "starting",
+            state: "resuming",
           });
           void continuation.catch((error) => reportRepositoryResumeError(error, quiet));
           return;
         }
       }
 
-      const recheckMatch = url.pathname.match(/^\/v1\/coding-loop\/([^/]+)\/recheck$/);
+      const recheckMatch = agenticLoopPath.match(/^\/v1\/agentic-loop\/([^/]+)\/recheck$/);
       if (req.method === "POST" && recheckMatch) {
         const run = registry.get(decodeURIComponent(recheckMatch[1]));
         if (!run) {
@@ -568,7 +637,7 @@ export async function startAgent({
         return;
       }
 
-      const streamMatch = url.pathname.match(/^\/v1\/coding-loop\/([^/]+)\/stream$/);
+      const streamMatch = agenticLoopPath.match(/^\/v1\/agentic-loop\/([^/]+)\/stream$/);
       if (req.method === "GET" && streamMatch) {
         streamRun(res, registry.get(decodeURIComponent(streamMatch[1])));
         return;
@@ -636,6 +705,7 @@ export async function startAgent({
         const requirement = String(input.requirement || "").trim();
         const repository = String(input.repository || "").trim();
         const backend = input.backend === "claude" ? "claude" : "codex";
+        const executionTarget = normalizeDesktopExecutionTarget(input.executionTarget);
         if (!requirement) throw new Error("Describe the coding task first.");
         if (!repository) throw new Error("Set a repository with /repo owner/name.");
         if (availableCapabilities?.backends?.[backend] !== true) {
@@ -648,7 +718,11 @@ export async function startAgent({
           local_path: indexedRepository?.local_path || input.localPath || workspace.localPath,
           base_branch: String(input.baseBranch || "dev"),
           backend,
-          max_attempts: 3,
+          execution_target: executionTarget,
+          execution_device_id: session?.device_id || null,
+          max_attempts: DEFAULT_RETRY_BUDGET + 1,
+          retry_budget: DEFAULT_RETRY_BUDGET,
+          token_budget: DEFAULT_TOKEN_BUDGET,
           acceptance_criteria: [],
           expected_tests: [],
           expected_evidence: [],
@@ -667,7 +741,7 @@ export async function startAgent({
               request,
             });
         const runId = String(remoteRun?.id || "");
-        if (!runId) throw new Error("SIMY Web did not return a coding run id.");
+        if (!runId) throw new Error("SIMY Web did not return an Agentic Loop run id.");
         const run = createRun({ runId, request, session, apiOrigin });
         registry.create(run);
         void startLocalCodingRun(run, runOptions);
@@ -698,6 +772,8 @@ async function createRemoteRun({ apiOrigin, apiBaseUrl, token, request }) {
       backend: request.backend,
       base_branch: request.base_branch,
       max_attempts: request.max_attempts,
+      retry_budget: request.retry_budget,
+      token_budget: request.token_budget,
       acceptance_criteria: request.acceptance_criteria,
       expected_tests: request.expected_tests,
       expected_evidence: request.expected_evidence,
@@ -808,12 +884,31 @@ function localRepositoryHilRequest(run, root, authorizedRoots) {
 
 async function capabilities() {
   const [codex, claude] = await Promise.all([
-    resolveBackendExecutable("codex"),
-    resolveBackendExecutable("claude"),
+    inspectDesktopExecutor("codex"),
+    inspectDesktopExecutor("claude"),
   ]);
   return {
-    backends: { codex: Boolean(codex), claude: Boolean(claude) },
-    features: { repository_scan_approval: true },
+    backends: { codex: codex.compatible, claude: claude.compatible },
+    backend_versions: {
+      codex: publicBackendInspection(codex),
+      claude: publicBackendInspection(claude),
+    },
+    execution_targets: {
+      desktop: {
+        execution_target: DESKTOP_EXECUTION_TARGET,
+        label: DESKTOP_EXECUTION_LABEL,
+        available: codex.compatible || claude.compatible,
+        backends: {
+          codex: desktopExecutorCapability(codex),
+          claude: desktopExecutorCapability(claude),
+        },
+      },
+    },
+    features: {
+      repository_scan_approval: true,
+      executor_version_preflight: true,
+      desktop_executor: true,
+    },
     session_ttl_hours: 48,
   };
 }
@@ -822,13 +917,24 @@ async function readCapabilities(dependencies) {
   return dependencies.capabilities ? dependencies.capabilities() : capabilities();
 }
 
-async function inspectCodingLoopEnvironment({ repository, backend, localPath, dependencies }) {
+async function inspectCodingLoopEnvironment({
+  repository,
+  backend,
+  executionTarget,
+  localPath,
+  dependencies,
+}) {
   const checks = [
     {
       key: "session",
       status: "passed",
       summary: "Local CLI session is connected to this SIMY Web origin.",
     },
+    {
+      key: "execution_target",
+      status: "passed",
+      summary: `This run will execute on ${DESKTOP_EXECUTION_LABEL} through SIMY CLI.`,
+    },
   ];
   let repositoryPath = null;
   try {
@@ -839,32 +945,107 @@ async function inspectCodingLoopEnvironment({ repository, backend, localPath, de
       summary: `Verified ${repository} against the local Git origin.`,
     });
   } catch (error) {
+    const summary =
+      error instanceof Error ? error.message : "Local repository could not be resolved.";
     checks.push({
       key: "repository",
       status: "failed",
-      summary: error instanceof Error ? error.message : "Local repository could not be resolved.",
+      summary,
+      recovery: recoveryContractForPreflight({ key: "repository", summary }),
     });
   }
 
   const available = await readCapabilities(dependencies);
-  const backendAvailable = available?.backends?.[backend] === true;
+  const inspection = normalizeBackendInspection(backend, available);
+  const backendSummary = backendPreflightSummary(backend, inspection);
   checks.push({
     key: "backend",
-    status: backendAvailable ? "passed" : "failed",
-    summary: backendAvailable
-      ? `${backend === "claude" ? "Claude Code" : "Codex"} is available locally.`
-      : `${backend === "claude" ? "Claude Code" : "Codex"} is not available on PATH.`,
+    status: inspection.compatible ? "passed" : "failed",
+    summary: backendSummary,
+    details: {
+      status: inspection.status,
+      installed_version: inspection.installed_version,
+      minimum_version: inspection.minimum_version,
+      update_command: inspection.update_command,
+    },
+    ...(inspection.compatible
+      ? {}
+      : {
+          recovery: recoveryContractForPreflight({
+            key: "backend",
+            summary: backendSummary,
+            details: inspection,
+          }),
+        }),
   });
 
   return {
-    ready: Boolean(repositoryPath && backendAvailable),
+    ready: Boolean(repositoryPath && inspection.compatible),
     repository,
     backend,
+    execution_target: executionTarget,
     local_path: repositoryPath,
     checks,
   };
 }
 
+function publicBackendInspection(inspection) {
+  return {
+    status: inspection.status,
+    available: inspection.available,
+    compatible: inspection.compatible,
+    installed_version: inspection.installed_version,
+    minimum_version: inspection.minimum_version,
+    update_command: inspection.update_command,
+  };
+}
+
+function normalizeBackendInspection(backend, capabilitiesValue) {
+  const policy = BACKEND_VERSION_POLICIES[backend];
+  const detail = capabilitiesValue?.backend_versions?.[backend];
+  if (detail && typeof detail === "object") {
+    return {
+      status: String(detail.status || (detail.compatible ? "compatible" : "missing")),
+      available: detail.available === true,
+      compatible: detail.compatible === true,
+      installed_version:
+        typeof detail.installed_version === "string" ? detail.installed_version : null,
+      minimum_version:
+        typeof detail.minimum_version === "string"
+          ? detail.minimum_version
+          : policy.minimumVersion,
+      update_command:
+        typeof detail.update_command === "string" ? detail.update_command : policy.updateCommand,
+    };
+  }
+  const compatible = capabilitiesValue?.backends?.[backend] === true;
+  return {
+    status: compatible ? "compatible" : "missing",
+    available: compatible,
+    compatible,
+    installed_version: null,
+    minimum_version: policy.minimumVersion,
+    update_command: policy.updateCommand,
+  };
+}
+
+function backendPreflightSummary(backend, inspection) {
+  const label = BACKEND_VERSION_POLICIES[backend].label;
+  if (inspection.status === "compatible" && inspection.installed_version) {
+    return `${label} ${inspection.installed_version} is compatible (requires ${inspection.minimum_version} or newer).`;
+  }
+  if (inspection.status === "outdated") {
+    return `${label} ${inspection.installed_version} is too old. Update to ${inspection.minimum_version} or newer: ${inspection.update_command}`;
+  }
+  if (inspection.status === "unknown_version") {
+    return `${label} is installed, but its version could not be verified. Reinstall or update it: ${inspection.update_command}`;
+  }
+  if (inspection.status === "compatible") {
+    return `${label} is available locally.`;
+  }
+  return `${label} is not available. Install or update it: ${inspection.update_command}`;
+}
+
 async function verifyLaunchChallenge({ apiOrigin, apiBaseUrl, token, runId, challenge }) {
   try {
     const response = await fetch(
@@ -886,6 +1067,10 @@ async function verifyLaunchChallenge({ apiOrigin, apiBaseUrl, token, runId, chal
   }
 }
 
+function canonicalAgenticLoopPath(pathname) {
+  return pathname.replace(/^\/v1\/coding-loop(?=\/|$)/, "/v1/agentic-loop");
+}
+
 function streamRun(res, run) {
   if (!run) {
     json(res, 404, { error: "run not found" });

package/src/backend-executable.js

@@ -2,14 +2,67 @@ import { spawn } from "node:child_process";
 
 const MACOS_CODEX_BINARY = "/Applications/ChatGPT.app/Contents/Resources/codex";
 
-export async function resolveBackendExecutable(
+export const BACKEND_VERSION_POLICIES = Object.freeze({
+  codex: Object.freeze({
+    label: "Codex",
+    minimumVersion: "0.144.0",
+    updateCommand: "npm install -g @openai/codex@latest",
+  }),
+  claude: Object.freeze({
+    label: "Claude Code",
+    minimumVersion: "2.1.200",
+    updateCommand: "claude update",
+  }),
+});
+
+export async function resolveBackendExecutable(backend, options = {}) {
+  const inspection = await inspectBackendExecutable(backend, options);
+  return inspection.available ? inspection.executable : null;
+}
+
+export async function inspectBackendExecutable(
   backend,
   { spawnImpl = spawn, candidates = backendCandidates(backend), timeoutMs = 1_500 } = {},
 ) {
+  const policy = versionPolicy(backend);
   for (const candidate of [...new Set(candidates.filter(Boolean))]) {
-    if (await executableAvailable(candidate, { spawnImpl, timeoutMs })) return candidate;
+    const probe = await probeExecutable(candidate, { spawnImpl, timeoutMs });
+    if (!probe.available) continue;
+    const installedVersion = parseBackendVersion(probe.output);
+    if (!installedVersion) {
+      return {
+        backend,
+        executable: candidate,
+        available: true,
+        compatible: false,
+        status: "unknown_version",
+        installed_version: null,
+        minimum_version: policy.minimumVersion,
+        update_command: policy.updateCommand,
+      };
+    }
+    const compatible = compareVersions(installedVersion, policy.minimumVersion) >= 0;
+    return {
+      backend,
+      executable: candidate,
+      available: true,
+      compatible,
+      status: compatible ? "compatible" : "outdated",
+      installed_version: installedVersion,
+      minimum_version: policy.minimumVersion,
+      update_command: policy.updateCommand,
+    };
   }
-  return null;
+  return {
+    backend,
+    executable: null,
+    available: false,
+    compatible: false,
+    status: "missing",
+    installed_version: null,
+    minimum_version: policy.minimumVersion,
+    update_command: policy.updateCommand,
+  };
 }
 
 export function backendCandidates(backend) {
@@ -23,16 +76,49 @@ export function backendCandidates(backend) {
   ];
 }
 
-function executableAvailable(command, { spawnImpl, timeoutMs }) {
+export function parseBackendVersion(output) {
+  const match = String(output || "").match(/(?:^|\s|v)(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)(?=\s|$|\))/);
+  return match?.[1] ?? null;
+}
+
+export function compareVersions(left, right) {
+  const leftParts = numericVersionParts(left);
+  const rightParts = numericVersionParts(right);
+  for (let index = 0; index < 3; index += 1) {
+    if (leftParts[index] !== rightParts[index]) return leftParts[index] - rightParts[index];
+  }
+  return 0;
+}
+
+function versionPolicy(backend) {
+  return backend === "claude" ? BACKEND_VERSION_POLICIES.claude : BACKEND_VERSION_POLICIES.codex;
+}
+
+function numericVersionParts(value) {
+  const match = String(value || "").match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return [0, 0, 0];
+  return match.slice(1).map(Number);
+}
+
+function probeExecutable(command, { spawnImpl, timeoutMs }) {
   return new Promise((resolve) => {
     let settled = false;
     let timeout;
-    const child = spawnImpl(command, ["--version"], { stdio: "ignore" });
+    let output = "";
+    const child = spawnImpl(command, ["--version"], { stdio: ["ignore", "pipe", "pipe"] });
+    child.stdout?.setEncoding?.("utf8");
+    child.stderr?.setEncoding?.("utf8");
+    child.stdout?.on?.("data", (chunk) => {
+      output += chunk;
+    });
+    child.stderr?.on?.("data", (chunk) => {
+      output += chunk;
+    });
     const finish = (available) => {
       if (settled) return;
       settled = true;
       if (timeout) clearTimeout(timeout);
-      resolve(available);
+      resolve({ available, output: output.trim() });
     };
     timeout = setTimeout(() => {
       child.kill?.("SIGTERM");