impel-cli 0.15.2 → 0.16.0

package/README.md

@@ -115,15 +115,19 @@ checksum-verifying native installers, so Claude Code does not inherit its newer
 Node.js requirement from the deprecated npm package. On Linux, it prepares the
 isolated command-line workflow.
 
-If setup or the CLI self-update fails, Impel first runs a deterministic local
-check. In an interactive terminal it then offers assisted recovery; use
-`impel setup --repair` (or `impel update --repair`) to opt in explicitly. Before
-upload, the CLI prints the exact sanitized payload. The hosted agent returns a
-reviewed action ID, and the CLI runs its allowlisted command locally; free-form
-model commands are rejected and every mutation requires confirmation. Sessions
-expire after 15 minutes, mutation capabilities are
-single-use, and a private checkpoint lets `--repair` resume an interrupted run.
-Use `--no-recovery` or `IMPEL_DISABLE_INSTALL_RECOVERY=1` to keep recovery off.
+If setup or the CLI self-update fails, Impel first runs deterministic local
+repairs for known failure fingerprints — offline, with no upload. If the
+failure persists, an interactive terminal offers assisted recovery (use
+`impel setup --repair` or `impel update --repair` to opt in explicitly): a
+bounded local loop where a gateway-hosted model selects typed diagnostic and
+repair tools and the CLI validates, approves, and executes them on this
+machine. Before the first upload, the CLI prints the exact sanitized payload.
+Free-form model commands are impossible by construction; repairs limited to
+Impel-owned files need one approval per session, while vendor installers and
+PATH edits always confirm individually. Recovery only reports success after
+the failed steps re-pass their local health checks, and it stops after 12
+model turns or 10 minutes. Use `--no-recovery` or
+`IMPEL_DISABLE_INSTALL_RECOVERY=1` to keep recovery off.
 
 ### If something does not work
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.15.2",
+  "version": "0.16.0",
   "description": "Configure Claude Code and Codex CLI to talk to Impel's gateway, authenticated by an Impel Personal Access Token",
   "type": "module",
   "bin": {

package/src/agents.js

@@ -29,6 +29,7 @@ const NATIVE_AGENT_TOOL_NAMES = [
 const SAFE_AGENT_ID_RE = /^[A-Za-z0-9_.:-]{1,160}$/u;
 const SAFE_SCOPE_PARAM_RE = /^[A-Za-z0-9_.:-]{1,160}$/u;
 const MAX_CATALOG_ITEMS = 500;
+const RETRYABLE_AGENT_CATALOG_ERROR = /request timed out|fetch failed|ECONNRESET|ETIMEDOUT|EAI_AGAIN|network error/iu;
 const RESERVED_AGENT_NAMES = Object.freeze({
   claude: new Set(["explore", "general-purpose", "plan"]),
   codex: new Set(["default", "explorer", "worker"]),
@@ -540,7 +541,14 @@ export async function syncAgentProfiles({
     .map((profile) => ({ ...profile, skipped: true, reason: "fresh" }));
   if (pending.length === 0) return skipped;
 
-  const catalog = await fetchCatalog({ gatewayUrl, credential, tenantId: normalizedTenant });
+  let catalog;
+  try {
+    catalog = await fetchCatalog({ gatewayUrl, credential, tenantId: normalizedTenant });
+  } catch (error) {
+    if (!RETRYABLE_AGENT_CATALOG_ERROR.test(String(error?.message || error))) throw error;
+    logger.log("Agents: catalog request failed transiently; retrying once…");
+    catalog = await fetchCatalog({ gatewayUrl, credential, tenantId: normalizedTenant });
+  }
   const results = [];
   for (const profile of pending) {
     const result = syncAgentProfile({

package/src/commands/setup.js

@@ -5,6 +5,7 @@
 
 import { parseFlags } from "../args.js";
 import {
+  crossAppModelsEnabled,
   loadConfig,
   saveConfig,
   normalizeGatewayUrl,
@@ -14,10 +15,11 @@ import {
   redactSecretText,
 } from "../config.js";
 import { promptSecret, promptText } from "../prompt.js";
+import { ensureImpelClaudeProfile, ensureImpelCodexProfile } from "../cliProfiles.js";
 import { fetchTenants, normalizeTenantId, tenantCredential } from "../tenants.js";
 import { cmdApps } from "./apps.js";
 import { prepareWindowsClis, windowsCliInstallCommands } from "../windowsSetup.js";
-import { runInstallRecovery } from "../installRecovery/loop.js";
+import { runInstallRecovery } from "../installRecovery/engine.js";
 
 const HELP = `impel setup - guided end-to-end gateway setup
 
@@ -410,14 +412,63 @@ export async function cmdSetup(argv, overrides = {}) {
         ])
       ),
     };
+
+    // Recovery ends as "fixed" only when every goal derived from the failed
+    // steps passes a fresh local check. App installs have no cheap external
+    // probe, so that goal tracks the most recent reviewed install result.
+    const appInstallState = { ok: false };
+    const installVendorApp = async (target) => {
+      const installed = await io.installApps(["install", target]);
+      appInstallState.ok = installed !== false;
+      return installed;
+    };
+    const goals = [];
+    if (io.platform === "win32" && setupFailures.some((failure) => /vendor_cli|windows_clis/iu.test(failure.step))) {
+      goals.push({
+        id: "windows-clis",
+        description: "Claude Code and Codex are installed and pass their version checks",
+        run: async () => {
+          const checked = await io.prepareWindowsClis({
+            gatewayUrl,
+            tenantId: tenant.id,
+            skipInstall: true,
+          });
+          return checked.missingAfter.length === 0
+            ? true
+            : { ok: false, detail: `still missing: ${checked.missingAfter.join(", ")}` };
+        },
+      });
+    }
+    if (setupFailures.some((failure) => /vendor_app/iu.test(failure.step))) {
+      goals.push({
+        id: "desktop-apps",
+        description: "The Impel desktop app profiles installed cleanly",
+        run: () => appInstallState.ok === true,
+      });
+    }
+    if (setupFailures.some((failure) => failure.step === "verify.gateway")) {
+      goals.push({
+        id: "gateway",
+        description: "The gateway accepts the stored credential",
+        run: async () => {
+          const checked = await io.probe(gatewayUrl, pat, tenant.id);
+          return checked.reachable && !checked.rejected
+            ? true
+            : { ok: false, detail: checked.error || `HTTP ${checked.status}` };
+        },
+      });
+    }
+
     try {
       const recovery = await io.recoverInstall(
         {
           failure: aggregateFailure,
           config,
+          goals,
           explicit: Boolean(flags.repair),
           noRecovery: Boolean(flags["no-recovery"]),
           actionContext: {
+            tenantId: tenant.id,
             probeGateway: () => io.probe(gatewayUrl, pat, tenant.id),
             installVendorClis: (tool) =>
               io.prepareWindowsClis({
@@ -427,15 +478,21 @@ export async function cmdSetup(argv, overrides = {}) {
                 installTools: [tool],
               }),
             repairProfiles: async () => {
-              if (io.platform !== "win32") return false;
-              const result = await io.prepareWindowsClis({
-                gatewayUrl,
-                tenantId: tenant.id,
-                skipInstall: true,
+              if (io.platform === "win32") {
+                const result = await io.prepareWindowsClis({
+                  gatewayUrl,
+                  tenantId: tenant.id,
+                  skipInstall: true,
+                });
+                return result.missingAfter.length === 0;
+              }
+              ensureImpelClaudeProfile(gatewayUrl, tenant.id, {
+                crossAppModels: crossAppModelsEnabled(config),
               });
-              return result.missingAfter.length === 0;
+              ensureImpelCodexProfile(gatewayUrl, tenant.id);
+              return true;
             },
-            installVendorApp: (target) => io.installApps(["install", target]),
+            installVendorApp,
             retryStep: async (step) => {
               if (/vendor_cli|windows_clis/iu.test(step || "")) {
                 const result = await io.prepareWindowsClis({
@@ -446,7 +503,7 @@ export async function cmdSetup(argv, overrides = {}) {
                 return result.missingAfter.length === 0;
               }
               if (/vendor_app/iu.test(step || "")) {
-                return (await io.installApps(["install", "all"])) !== false;
+                return (await installVendorApp("all")) !== false;
               }
               if (/gateway/iu.test(step || "")) {
                 const result = await io.probe(gatewayUrl, pat, tenant.id);
@@ -462,23 +519,11 @@ export async function cmdSetup(argv, overrides = {}) {
           ...(overrides.recoveryOverrides || {}),
         }
       );
+      // "fixed" is only reported after every goal passed a fresh local check
+      // inside the engine, so no separate re-verification is needed here.
       if (recovery.fixed) {
-        if (io.platform === "win32" && setupFailures.some((failure) => /vendor_cli|windows_clis/iu.test(failure.step))) {
-          const checked = await io.prepareWindowsClis({
-            gatewayUrl,
-            tenantId: tenant.id,
-            skipInstall: true,
-          });
-          platformSetupFailed = checked.missingAfter.length > 0;
-        } else {
-          platformSetupFailed = false;
-        }
-        if (setupFailures.some((failure) => failure.step === "verify.gateway")) {
-          const checked = await io.probe(gatewayUrl, pat, tenant.id);
-          verificationFailed = !checked.reachable || checked.rejected;
-        } else {
-          verificationFailed = false;
-        }
+        platformSetupFailed = false;
+        verificationFailed = false;
       }
     } catch (error) {
       console.warn(`Install recovery could not start (${redactSecretText(error?.message || error)}).`);

package/src/commands/update.js

@@ -16,7 +16,7 @@ import { nativeCommandInvocation } from "../nativeProcess.js";
 import { windowsClaudeUserData } from "../windowsApps.js";
 import { withProgress } from "../progress.js";
 import { installedAppTenantIds } from "./apps.js";
-import { runInstallRecovery } from "../installRecovery/loop.js";
+import { runInstallRecovery } from "../installRecovery/engine.js";
 import {
   fetchRemoteVersion,
   installedVersion,
@@ -220,7 +220,10 @@ export async function cmdUpdate(argv, overrides = {}) {
       }
       const config = io.loadConfig();
       let recovered = false;
-      if (config?.pat && config?.tenantId && config?.appUrl) {
+      if (config?.pat && config?.tenantId) {
+        // The goal tracks the most recent reviewed retry of the npm install:
+        // recovery may only end "fixed" once that retry actually succeeded.
+        const updateState = { ok: false };
         try {
           const recovery = await io.recoverInstall(
             {
@@ -232,11 +235,31 @@ export async function cmdUpdate(argv, overrides = {}) {
                 message: "The npm-verified global impel-cli update failed.",
               },
               config,
+              goals: [
+                {
+                  id: "cli-update",
+                  description: "The global impel-cli npm update completed successfully",
+                  run: () => updateState.ok === true,
+                },
+              ],
               explicit: Boolean(flags.repair),
               noRecovery: Boolean(flags["no-recovery"]),
               actionContext: {
-                retryStep: async () =>
-                  io.selfUpdate(updateInstallSpec()) === true,
+                tenantId: config.tenantId,
+                probeGateway: async () => {
+                  try {
+                    const response = await fetch(`${config.gatewayUrl}/health`, {
+                      signal: AbortSignal.timeout(5000),
+                    });
+                    return { reachable: true, status: response.status, rejected: false };
+                  } catch (error) {
+                    return { reachable: false, error: redactSecretText(error?.message || error) };
+                  }
+                },
+                retryStep: async () => {
+                  updateState.ok = io.selfUpdate(updateInstallSpec()) === true;
+                  return updateState.ok;
+                },
               },
             },
             overrides.recoveryOverrides || {}

package/src/installRecovery/checkpoint.js

@@ -11,10 +11,9 @@ export const INSTALL_RECOVERY_CHECKPOINT_PATH = path.join(
 function validCheckpoint(value) {
   return Boolean(
     value &&
-      value.protocolVersion === 1 &&
-      typeof value.sessionId === "string" &&
-      typeof value.recoveryToken === "string" &&
+      value.protocolVersion === 2 &&
       typeof value.fingerprint === "string" &&
+      typeof value.status === "string" &&
       typeof value.expiresAt === "number"
   );
 }