impel-cli 0.15.3 → 0.16.1

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.3",
+  "version": "0.16.1",
   "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/apps.js

@@ -10,6 +10,7 @@ import {
   secureManagedCodexHome,
 } from "./codexSecurity.js";
 import { normalizeTenantId } from "./tenants.js";
+import { impelCliInvocation } from "./selfInvocation.js";
 import { crossAppModelsEnabled, redactSecretText } from "./config.js";
 import { ADHOC_IDENTITY, codesignIdentityArgs, desiredSigningMode, resolveSigningIdentity } from "./codesign.js";
 
@@ -925,9 +926,16 @@ function writeChatGPTConfig(paths, config, models, vendorCodexModels, invocation
   };
   writeAtomic(paths.chatgpt.catalog, JSON.stringify(catalog, null, 2) + "\n", 0o600);
   const auth = invocations?.auth || { command: paths.tokenHelper, args: null };
+  // Finder/Dock-launched apps inherit a minimal PATH without npm/nvm bin
+  // directories, so a PATH-relative "impel" never spawns there. Bake the
+  // absolute node + CLI invocation; the launch-time `app refresh` rewrites
+  // this config whenever those paths change.
+  const mcpInvocation = impelCliInvocation(
+    config.tenantId ? ["mcp", "--tenant", config.tenantId] : ["mcp"]
+  );
   const mcp = invocations?.mcp || {
-    command: "impel",
-    args: config.tenantId ? ["mcp", "--tenant", config.tenantId] : ["mcp"],
+    command: mcpInvocation.command,
+    args: [...mcpInvocation.args],
   };
 
   const managedToml = [
@@ -1153,20 +1161,63 @@ function readTopLevelTomlString(toml, key) {
   }
 }
 
+/**
+ * Rewrite one tenant's app token helper with the current node/CLI paths.
+ * Cheap and Impel-owned, so install recovery can use it to heal helpers whose
+ * baked interpreter or checkout paths went stale.
+ */
+export function rewriteTenantTokenHelper(tenantId, homeDir = os.homedir()) {
+  const paths = appPaths(homeDir, tenantId);
+  if (!fs.existsSync(path.dirname(paths.tokenHelper))) return false;
+  writeTokenHelper(paths.tokenHelper, tenantId);
+  return true;
+}
+
 function writeTokenHelper(target, tenantId) {
   const cliPath = fileURLToPath(new URL("../bin/impel.js", import.meta.url));
   const node = shellQuote(process.execPath);
   const cli = shellQuote(cliPath);
   const tenantArgs = tenantId ? ` --tenant ${shellQuote(tenantId)}` : "";
-  const refreshTenantArgs = tenantId ? ` --tenant ${shellQuote(tenantId)}` : "";
   // The apps invoke this helper whenever they need auth, which makes it the
   // one hook that fires on Finder/Dock launches too. Piggyback a detached,
   // TTL-gated config/catalog/skills refresh (`app refresh --stale-only`) so
   // the managed apps keep themselves current without touching stdout — the
   // caller consumes stdout as the token.
+  //
+  // The baked interpreter/CLI paths are only first choices: an nvm upgrade or
+  // a moved checkout deletes them, and a helper that hardcodes them strands
+  // every managed app with no auth (observed as "provider auth command exited
+  // with status 1" outages). Resolve again at call time before giving up, and
+  // prefer the global npm install next to whichever node is found so the
+  // refresh keeps rewriting this helper with current paths.
   const script = `#!/bin/sh
-(${node} ${cli} app refresh --stale-only${refreshTenantArgs} </dev/null >/dev/null 2>&1 &)
-exec ${node} ${cli} token${tenantArgs}
+# Managed by impel-cli; regenerated by \`impel app refresh\`.
+NODE=${node}
+CLI=${cli}
+if ! [ -x "$NODE" ]; then
+  NODE="$(command -v node 2>/dev/null || true)"
+fi
+if ! [ -x "$NODE" ]; then
+  for candidate in /opt/homebrew/bin/node /usr/local/bin/node "$HOME"/.nvm/versions/node/*/bin/node; do
+    if [ -x "$candidate" ]; then NODE="$candidate"; fi
+  done
+fi
+if ! [ -x "$NODE" ]; then
+  echo 'impel token helper: no usable node runtime found; re-run \`impel setup\`' >&2
+  exit 1
+fi
+if ! [ -f "$CLI" ]; then
+  CLI="$(dirname "$NODE")/../lib/node_modules/impel-cli/bin/impel.js"
+fi
+if ! [ -f "$CLI" ]; then
+  CLI="$(command -v impel 2>/dev/null || true)"
+fi
+if [ -z "$CLI" ] || ! [ -f "$CLI" ]; then
+  echo 'impel token helper: impel-cli not found; re-run \`impel setup\`' >&2
+  exit 1
+fi
+("$NODE" "$CLI" app refresh --stale-only${tenantArgs} </dev/null >/dev/null 2>&1 &)
+exec "$NODE" "$CLI" token${tenantArgs}
 `;
   writeAtomic(target, script, 0o700);
 }

package/src/commands/setup.js

@@ -5,6 +5,7 @@
 
 import { parseFlags } from "../args.js";
 import {
+  crossAppModelsEnabled,
   loadConfig,
   saveConfig,
   normalizeGatewayUrl,
@@ -14,10 +15,12 @@ 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 { rewriteTenantTokenHelper } from "../apps.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 +413,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 +479,24 @@ 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);
+              // Also refresh the app token helper: a stale baked node/CLI
+              // path there breaks every managed app's auth.
+              rewriteTenantTokenHelper(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 +507,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 +523,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"
   );
 }
@@ -37,8 +36,11 @@ export function saveInstallRecoveryCheckpoint(
 ) {
   fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
   const temporary = `${filePath}.tmp-${process.pid}`;
+  fs.rmSync(temporary, { force: true });
+  // "wx" refuses to follow a pre-planted symlink at the predictable temp path.
   fs.writeFileSync(temporary, `${JSON.stringify(checkpoint, null, 2)}\n`, {
     mode: 0o600,
+    flag: "wx",
   });
   fs.renameSync(temporary, filePath);
   try {