impel-cli 0.14.2 → 0.15.0

package/README.md

@@ -110,8 +110,19 @@ impel update               # install the latest Impel CLI later
 
 `impel setup` keeps your normal Claude and Codex profiles separate. On Mac and
 Windows it also prepares the supported isolated desktop experiences. On Windows,
-it installs missing official vendor command-line tools when needed. On Linux,
-it prepares the isolated command-line workflow.
+it installs missing official vendor command-line tools with the vendors'
+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 can only
+return a reviewed action ID; the CLI rejects free-form commands and asks before
+every mutation. 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 something does not work
 
@@ -133,11 +144,13 @@ access, scopes, and organization membership for every protected action.
 
 ```
 impel setup [--pat <pat>] [--tenant <org>] [--skip-apps] [--skip-clis]
+            [--repair|--no-recovery]
                                              Guided setup: token, tenant, platform clients, verify
                                              (closes running Claude/ChatGPT apps, updates the vendor
                                               apps, then installs the vendored Impel apps on macOS;
-                                              installs missing vendor CLIs on Windows)
-impel update [--check] [--skip-apps]         Update EVERYTHING: reinstall the CLI from npm, then
+                                              runs official native vendor CLI installers on Windows)
+impel update [--check] [--skip-apps] [--repair|--no-recovery]
+                                             Update EVERYTHING: reinstall the CLI from npm, then
                                              cascade to `app update all`, `skills sync all`, and
                                              `agents sync all`
 impel auth [--pat <pat>] [--gateway <url>] [--app <url>]
@@ -472,26 +485,36 @@ and pre-tenancy Impel CLI profiles, so switching organizations cannot strand an
 older snapshot. These safeguards apply only to Impel-owned `CODEX_HOME`
 directories; native `~/.codex` remains untouched.
 
-On Windows, `impel setup` ensures the official `@anthropic-ai/claude-code` and
-`@openai/codex` packages are available, installing only the missing package(s)
-with the same npm installation that supplies Impel. Use `--skip-clis` to prepare
-the profiles without installing missing vendor CLIs. The launchers and skill
-sync resolve native executables through `PATH`/`PATHEXT`, including global npm
-`.cmd` and `.bat` shims. Windows environment references such as `%NVM_SYMLINK%`
-are expanded during lookup, and the standard npm-global, Claude native-installer,
-and Codex standalone-installer directories are checked even when the parent
-PowerShell PATH is stale. Arguments are forwarded through an explicitly escaped
-`cmd.exe` invocation without Node shell mode; NULs and line breaks, which cannot
-be represented safely through a batch shim, are rejected before anything is
-launched. Managed Codex auth and MCP subprocesses bypass batch shims entirely by
-calling Node directly.
-
-If npm itself fails during setup, the wizard prints the native spawn error and
-the exact vendor-package command to retry in PowerShell. If npm succeeds but the
-new commands remain undiscoverable, close and reopen PowerShell; then use
-`npm prefix --global` to identify the directory that must be on the user PATH.
-Setup exits non-zero and says it is incomplete until both launchers are ready—it
-does not print a success banner after a failed installation.
+On Windows, `impel setup` installs only missing command-line tools through the
+vendors' current native PowerShell installers. Claude Code's npm installation is
+deprecated and its current package requires Node.js 22, while Impel itself still
+supports Node.js 18 or newer. The native path keeps that valid Impel setup
+working. Codex's installer is run non-interactively. Both installers download
+platform-specific native releases and verify their published SHA-256 checksums.
+Use `--skip-clis` to prepare the profiles without installing missing vendor
+CLIs. Each tool is installed independently, so a failure from one vendor does
+not prevent the other tool from being installed and configured.
+
+The launchers and skill sync still resolve executables through `PATH`/`PATHEXT`,
+including existing global npm `.cmd` and `.bat` shims. Windows environment
+references such as `%NVM_SYMLINK%` are expanded during lookup, and the standard
+npm-global, Claude native-installer, Codex standalone-installer, and Windows
+PowerShell directories are checked even when the parent PowerShell PATH is
+stale. Candidates must also pass a bounded `--version` probe, so a stale or
+half-removed npm shim cannot hide a healthy native install later in the search
+path. Existing batch-shim arguments are forwarded through an explicitly
+escaped `cmd.exe` invocation without Node shell mode; NULs and line breaks,
+which cannot be represented safely through a batch shim, are rejected before
+anything is launched. Managed Codex auth and MCP subprocesses bypass batch
+shims entirely by calling Node directly.
+
+If a native installer fails, the wizard identifies the affected tool, preserves
+the other tool's successful install, and prints that vendor's exact official
+PowerShell command to retry. If an installer exits successfully but its command
+cannot be verified, close and reopen PowerShell, retry the printed command, and
+run `impel setup` again. Setup exits non-zero and says it is incomplete until
+both launchers are ready—it does not print a success banner after a failed
+installation.
 
 Windows receives the complete CLI workflow: setup/auth, tenant selection,
 isolated Claude and Codex launches, native profile switching, tasks, skills,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.14.2",
+  "version": "0.15.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/cli.js

@@ -23,7 +23,8 @@ const HELP = `impel — the Impel gateway CLI: isolated Claude Code, Codex, and
 Get started:
   impel setup                                 Guided end-to-end onboarding: token, tenant,
                                               platform clients, gateway verification
-                                              (--pat <pat> --tenant <org> --skip-apps/--skip-clis)
+                                              (--pat <pat> --tenant <org> --skip-apps/--skip-clis
+                                               --repair/--no-recovery)
   impel update                                Update everything: the CLI itself, then the
                                               Impel apps, skills, and agents (--check, --skip-apps)
 
@@ -69,6 +70,7 @@ Env:
   IMPEL_APP_URL       Default app/control-plane URL for setup, auth, PATs, and tasks.
   IMPEL_SKIP_UPDATE_CHECK=1   Silence launch-time update notices.
   IMPEL_SKIP_AGENT_SYNC=1     Keep the last native-agent catalog without refreshing it.
+  IMPEL_DISABLE_INSTALL_RECOVERY=1   Disable local and hosted install recovery.
 
 Config file:
   ~/.config/impel/config.json (mode 0600)

package/src/commands/setup.js

@@ -16,7 +16,8 @@ import {
 import { promptSecret, promptText } from "../prompt.js";
 import { fetchTenants, normalizeTenantId, tenantCredential } from "../tenants.js";
 import { cmdApps } from "./apps.js";
-import { prepareWindowsClis, windowsCliInstallCommand } from "../windowsSetup.js";
+import { prepareWindowsClis, windowsCliInstallCommands } from "../windowsSetup.js";
+import { runInstallRecovery } from "../installRecovery/loop.js";
 
 const HELP = `impel setup - guided end-to-end gateway setup
 
@@ -34,6 +35,8 @@ Usage:
   impel setup --tenant <org>        Preselect the organization
   impel setup --skip-apps           Skip the desktop-app installation step
   impel setup --skip-clis           On Windows, don't install missing vendor CLIs
+  impel setup --repair              Explicitly opt into sanitized assisted recovery on failure
+  impel setup --no-recovery         Disable local and hosted recovery for this run
 `;
 
 /**
@@ -104,6 +107,7 @@ export async function cmdSetup(argv, overrides = {}) {
     installApps: cmdApps,
     prepareWindowsClis,
     probe: probeGateway,
+    recoverInstall: runInstallRecovery,
     isTTY: process.stdin.isTTY,
     platform: process.platform,
     ...overrides,
@@ -115,6 +119,8 @@ export async function cmdSetup(argv, overrides = {}) {
     app: { type: "string" },
     "skip-apps": { type: "boolean" },
     "skip-clis": { type: "boolean" },
+    repair: { type: "boolean" },
+    "no-recovery": { type: "boolean" },
     help: { type: "boolean" },
   });
   if (flags.help) {
@@ -174,6 +180,15 @@ export async function cmdSetup(argv, overrides = {}) {
   console.log(`    ✓ stored in ~/.config/impel/config.json (mode 0600)`);
   console.log("");
 
+  const setupFailures = [];
+  const recordSetupFailure = (failure) => {
+    setupFailures.push({
+      platform: io.platform,
+      architecture: process.arch,
+      ...failure,
+    });
+  };
+
   // ── Step 2: organization ─────────────────────────────────────────────────
   // A successful tenant fetch also proves the token: the app verifies it
   // against impel-identity before answering.
@@ -249,23 +264,42 @@ export async function cmdSetup(argv, overrides = {}) {
       }
       if (result.missingAfter.length > 0 && !flags["skip-clis"]) {
         platformSetupFailed = true;
-        if (result.installSucceeded === false) {
-          const failure = result.installFailure;
-          const detail = failure?.message
-            ? `: ${redactSecretText(failure.message)}`
-            : Number.isInteger(failure?.status)
-              ? ` (exit code ${failure.status})`
-              : failure?.signal
-                ? ` (signal ${failure.signal})`
-                : "";
-          console.error(`    npm could not install the missing vendor CLIs${detail}.`);
-          console.error("    Retry this command in the same PowerShell window:");
-          console.error(`      ${result.installCommand || windowsCliInstallCommand(result.missingAfter)}`);
-        } else {
-          console.error("    npm completed, but the installed commands are not discoverable.");
-          console.error("    Close and reopen PowerShell, then re-run `impel setup`.");
-          console.error("    If they are still missing, run `npm prefix --global` and add that directory to your user PATH.");
+        const fallbackCommands = windowsCliInstallCommands(result.missingAfter);
+        for (const tool of result.missingAfter) {
+          const label = tool === "claude" ? "Claude Code" : "Codex";
+          const installation = result.installations?.[tool];
+          const failure = installation?.failure;
+          if (installation?.succeeded === false || (!installation && result.installSucceeded === false)) {
+            const detail = failure?.message
+              ? `: ${redactSecretText(failure.message)}`
+              : Number.isInteger(failure?.status)
+                ? ` (exit code ${failure.status})`
+                : failure?.signal
+                  ? ` (signal ${failure.signal})`
+                  : "";
+            console.error(`    ${label}'s native installer failed${detail}.`);
+            recordSetupFailure({
+              step: `install.vendor_cli.${tool}`,
+              command: installation?.command || result.installCommands?.[tool] || fallbackCommands[tool],
+              exitCode: failure?.status,
+              signal: failure?.signal,
+              errorCode: failure?.code,
+              message: failure?.message
+                ? `${label}'s native installer failed: ${failure.message}`
+                : `${label}'s native installer did not reach a verified state.`,
+            });
+          } else {
+            console.error(`    ${label}'s native installer completed, but Impel could not verify the command.`);
+            recordSetupFailure({
+              step: `verify.vendor_cli.${tool}`,
+              command: installation?.command || result.installCommands?.[tool] || fallbackCommands[tool],
+              message: `${label}'s installer completed but the command was not discoverable or did not pass its version check.`,
+            });
+          }
+          console.error("    Retry its official installer in the same PowerShell window:");
+          console.error(`      ${installation?.command || result.installCommands?.[tool] || fallbackCommands[tool]}`);
         }
+        console.error("    Then close and reopen PowerShell and re-run `impel setup`.");
       } else if (result.missingAfter.length > 0) {
         console.log("    Vendor CLI installation was skipped; install it before using the matching launcher.");
       } else {
@@ -275,6 +309,11 @@ export async function cmdSetup(argv, overrides = {}) {
       platformSetupFailed = true;
       console.error(`    ✗ Windows CLI setup failed (${redactSecretText(error?.message || error)})`);
       console.error("    Fix the issue, then re-run `impel setup`.");
+      recordSetupFailure({
+        step: "setup.windows_clis",
+        errorCode: error?.code,
+        message: `Windows CLI setup failed: ${error?.message || error}`,
+      });
     }
     if (flags["skip-apps"]) {
       console.log("    Windows desktop apps: skipped (--skip-apps).");
@@ -285,6 +324,10 @@ export async function cmdSetup(argv, overrides = {}) {
         if (installed === false) {
           platformSetupFailed = true;
           console.error("    ✗ Windows desktop app setup failed; fix the issue above, then re-run `impel app install all`.");
+          recordSetupFailure({
+            step: "install.vendor_app.all",
+            message: "Windows desktop app setup returned an unsuccessful result.",
+          });
         } else {
           console.log("    ✓ Impel Claude and Impel ChatGPT profiles are ready");
         }
@@ -292,6 +335,11 @@ export async function cmdSetup(argv, overrides = {}) {
         platformSetupFailed = true;
         console.error(`    ✗ Windows desktop app setup failed (${redactSecretText(error?.message || error)})`);
         console.error("    Fix the issue, then re-run `impel app install all`.");
+        recordSetupFailure({
+          step: "install.vendor_app.all",
+          errorCode: error?.code,
+          message: `Windows desktop app setup failed: ${error?.message || error}`,
+        });
       }
     }
   } else if (flags["skip-apps"]) {
@@ -313,6 +361,11 @@ export async function cmdSetup(argv, overrides = {}) {
         `    ✗ app installation failed (${redactSecretText(error?.message || error)})`
       );
       console.error("    Fix the issue, then re-run `impel app install`.");
+      recordSetupFailure({
+        step: "install.vendor_app.all",
+        errorCode: error?.code,
+        message: `Desktop app installation failed: ${error?.message || error}`,
+      });
     }
   }
   console.log("");
@@ -326,15 +379,113 @@ export async function cmdSetup(argv, overrides = {}) {
     verificationFailed = true;
     console.log(`4/4 Verify: ✗ gateway reachable but it rejected the token (HTTP ${probe.status}).`);
     console.log("    Mint a fresh token and re-run `impel setup`.");
-    process.exitCode = 1;
+    recordSetupFailure({
+      step: "verify.gateway",
+      exitCode: probe.status,
+      message: `The gateway rejected the configured credential with HTTP ${probe.status}.`,
+    });
   } else {
     verificationFailed = true;
     console.log(`4/4 Verify: ✗ gateway unreachable (${probe.error}).`);
     console.log("    Check your network, then run `impel status` to retry.");
-    process.exitCode = 1;
+    recordSetupFailure({
+      step: "verify.gateway",
+      message: `The gateway could not be reached: ${probe.error}.`,
+    });
+  }
+
+  if (platformSetupFailed || verificationFailed) {
+    const aggregateFailure = {
+      platform: io.platform,
+      architecture: process.arch,
+      step: setupFailures.length === 1 ? setupFailures[0].step : "setup.multiple",
+      message:
+        setupFailures.length === 1
+          ? setupFailures[0].message
+          : `${setupFailures.length} setup checks failed.`,
+      diagnostics: Object.fromEntries(
+        setupFailures.slice(0, 20).map((failure, index) => [
+          `failure${index + 1}`,
+          `${failure.step}: ${failure.message}`,
+        ])
+      ),
+    };
+    try {
+      const recovery = await io.recoverInstall(
+        {
+          failure: aggregateFailure,
+          config,
+          explicit: Boolean(flags.repair),
+          noRecovery: Boolean(flags["no-recovery"]),
+          actionContext: {
+            probeGateway: () => io.probe(gatewayUrl, pat, tenant.id),
+            installVendorClis: (tool) =>
+              io.prepareWindowsClis({
+                gatewayUrl,
+                tenantId: tenant.id,
+                skipInstall: false,
+                installTools: [tool],
+              }),
+            repairProfiles: async () => {
+              if (io.platform !== "win32") return false;
+              const result = await io.prepareWindowsClis({
+                gatewayUrl,
+                tenantId: tenant.id,
+                skipInstall: true,
+              });
+              return result.missingAfter.length === 0;
+            },
+            installVendorApp: (target) => io.installApps(["install", target]),
+            retryStep: async (step) => {
+              if (/vendor_cli|windows_clis/iu.test(step || "")) {
+                const result = await io.prepareWindowsClis({
+                  gatewayUrl,
+                  tenantId: tenant.id,
+                  skipInstall: false,
+                });
+                return result.missingAfter.length === 0;
+              }
+              if (/vendor_app/iu.test(step || "")) {
+                return (await io.installApps(["install", "all"])) !== false;
+              }
+              if (/gateway/iu.test(step || "")) {
+                const result = await io.probe(gatewayUrl, pat, tenant.id);
+                return Boolean(result.reachable && !result.rejected);
+              }
+              return false;
+            },
+          },
+        },
+        {
+          isTTY: io.isTTY,
+          promptText: io.promptText,
+          ...(overrides.recoveryOverrides || {}),
+        }
+      );
+      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;
+        }
+      }
+    } catch (error) {
+      console.warn(`Install recovery could not start (${redactSecretText(error?.message || error)}).`);
+    }
   }
 
-  if (platformSetupFailed) process.exitCode = 1;
+  if (platformSetupFailed || verificationFailed) process.exitCode = 1;
 
   console.log("");
   if (platformSetupFailed || verificationFailed) {

package/src/commands/update.js

@@ -16,6 +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 {
   fetchRemoteVersion,
   installedVersion,
@@ -38,6 +39,8 @@ Usage:
   impel update              Update the CLI, then cascade to apps, skills, and agents
   impel update --check      Report whether an update is available; change nothing
   impel update --skip-apps  Skip the desktop-app step of the cascade
+  impel update --repair     Explicitly opt into sanitized assisted recovery on failure
+  impel update --no-recovery  Disable local and hosted recovery for this run
 `;
 
 function reportProcessFailure(stage, result) {
@@ -166,12 +169,16 @@ export async function cmdUpdate(argv, overrides = {}) {
     appsInstalled: anyAppInstalled,
     platform: process.platform,
     progress: withProgress,
+    recoverInstall: runInstallRecovery,
+    loadConfig,
     ...overrides,
   };
   const { flags } = parseFlags(argv, {
     check: { type: "boolean" },
     "skip-apps": { type: "boolean" },
     "refresh-cache": { type: "boolean" },
+    repair: { type: "boolean" },
+    "no-recovery": { type: "boolean" },
     help: { type: "boolean" },
   });
   if (flags.help) {
@@ -211,8 +218,39 @@ export async function cmdUpdate(argv, overrides = {}) {
         console.error("  Verify `npm --version` in PowerShell, then retry `impel update`.");
         console.error("  Manual recovery: `npm install --global impel-cli@latest`.");
       }
-      process.exitCode = 1;
-      return;
+      const config = io.loadConfig();
+      let recovered = false;
+      if (config?.pat && config?.tenantId && config?.appUrl) {
+        try {
+          const recovery = await io.recoverInstall(
+            {
+              failure: {
+                platform: io.platform,
+                architecture: process.arch,
+                step: "install.impel_cli",
+                command: "npm install --global impel-cli@latest",
+                message: "The npm-verified global impel-cli update failed.",
+              },
+              config,
+              explicit: Boolean(flags.repair),
+              noRecovery: Boolean(flags["no-recovery"]),
+              actionContext: {
+                retryStep: async () =>
+                  io.selfUpdate(updateInstallSpec()) === true,
+              },
+            },
+            overrides.recoveryOverrides || {}
+          );
+          recovered = recovery.fixed;
+        } catch (error) {
+          console.warn(`impel update: assisted recovery could not start (${redactSecretText(error?.message || error)}).`);
+        }
+      }
+      if (!recovered) {
+        process.exitCode = 1;
+        return;
+      }
+      console.log("CLI: recovery verified the update path.");
     }
     console.log(`CLI: updated${remote ? ` to v${remote}` : ""}.`);
   }

package/src/gateway/index.js

@@ -11,6 +11,7 @@ const SAFE_NAMESPACE = /^[a-z][a-z0-9_-]{1,31}$/u;
 const SAFE_PREFIX = /^[a-z][a-z0-9_]{2,31}_$/u;
 const SAFE_ENVIRONMENT_PREFIX = /^[A-Z][A-Z0-9_]{1,31}$/u;
 const SAFE_ROUTE = /^\/[A-Za-z0-9._~!$&'()*+,;=:@%/-]*$/u;
+const SAFE_TENANT_ID = /^[A-Za-z0-9_.-]{1,128}$/u;
 const ANSI_ESCAPE_RE = /\u001B(?:\][^\u0007\u001B]*(?:\u0007|\u001B\\)|\[[0-?]*[ -/]*[@-~]|[@-_])/gu;
 const CONTROL_TEST_RE = /[\u0000-\u001F\u007F-\u009F]/u;
 const CONTROL_RE = /[\u0000-\u001F\u007F-\u009F]/gu;
@@ -29,6 +30,15 @@ function validateRoute(name, value) {
   return value;
 }
 
+function validateTenantID(value) {
+  if (value == null) return null;
+  const tenantID = String(value || "").trim();
+  if (!SAFE_TENANT_ID.test(tenantID) || tenantID === "." || tenantID === ".." || CONTROL_TEST_RE.test(tenantID)) {
+    throw new Error("gateway CLI tenant.defaultId is invalid");
+  }
+  return tenantID;
+}
+
 function validateBrand(input) {
   if (!input || Array.isArray(input) || typeof input !== "object" || input.schemaVersion !== 1) {
     throw new Error("gateway CLI brand schemaVersion must be 1");
@@ -40,6 +50,8 @@ function validateBrand(input) {
   const managedMarker = String(input.cli?.managedMarker || "");
   const environmentPrefix = String(input.cli?.environmentPrefix || command.toUpperCase().replace(/-/gu, "_"));
   const patPrefix = String(input.auth?.patPrefix || "");
+  const tenantPrefix = input.auth?.tenantPrefix == null ? null : String(input.auth.tenantPrefix);
+  const defaultTenantID = validateTenantID(input.tenant?.defaultId);
   if (!SAFE_ID.test(productID)) throw new Error("gateway CLI product.id is invalid");
   if (!SAFE_ID.test(command)) throw new Error("gateway CLI command is invalid");
   if (!SAFE_NAMESPACE.test(configNamespace)) throw new Error("gateway CLI configNamespace is invalid");
@@ -47,13 +59,16 @@ function validateBrand(input) {
   if (!SAFE_NAMESPACE.test(managedMarker)) throw new Error("gateway CLI managedMarker is invalid");
   if (!SAFE_ENVIRONMENT_PREFIX.test(environmentPrefix)) throw new Error("gateway CLI environmentPrefix is invalid");
   if (!SAFE_PREFIX.test(patPrefix)) throw new Error("gateway CLI PAT prefix is invalid");
+  if (tenantPrefix != null && !SAFE_PREFIX.test(tenantPrefix)) throw new Error("gateway CLI tenant prefix is invalid");
+  if (defaultTenantID && !tenantPrefix) throw new Error("gateway CLI tenant prefix is required when tenant.defaultId is set");
 
   const defaultOrigin = input.gateway?.defaultOrigin == null ? null : normalizeGatewayUrl(input.gateway.defaultOrigin);
   return Object.freeze({
     schemaVersion: 1,
     product: Object.freeze({ id: productID, displayName: validateText("product.displayName", input.product?.displayName) }),
     cli: Object.freeze({ command, configNamespace, providerId: providerID, managedMarker, environmentPrefix }),
-    auth: Object.freeze({ patPrefix }),
+    auth: Object.freeze({ patPrefix, tenantPrefix }),
+    tenant: Object.freeze({ defaultId: defaultTenantID }),
     gateway: Object.freeze({
       defaultOrigin,
       healthPath: validateRoute("healthPath", input.gateway?.healthPath),
@@ -183,9 +198,21 @@ export function createGatewayCli(options) {
     return `${secret.slice(0, brand.auth.patPrefix.length + 4)}...${secret.slice(-4)}`;
   }
 
+  function bearerCredential(pat) {
+    if (!brand.tenant.defaultId) return pat;
+    const encodedTenant = Buffer.from(brand.tenant.defaultId, "utf8").toString("base64url");
+    return `${brand.auth.tenantPrefix}${encodedTenant}.${pat}`;
+  }
+
   function redactSecretText(value) {
     const escapedPrefix = brand.auth.patPrefix.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
-    const tokenPattern = new RegExp(`${escapedPrefix}[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)?`, "gu");
+    const escapedTenantPrefix = brand.auth.tenantPrefix?.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+    const tokenPattern = new RegExp(
+      escapedTenantPrefix
+        ? `(?:${escapedTenantPrefix}[A-Za-z0-9_-]+\\.)?${escapedPrefix}[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)?`
+        : `${escapedPrefix}[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)?`,
+      "gu",
+    );
     return String(value ?? "")
       .replace(tokenPattern, "[REDACTED GATEWAY CREDENTIAL]")
       .replace(ANSI_ESCAPE_RE, "")
@@ -244,7 +271,7 @@ export function createGatewayCli(options) {
     if (!health.ok) throw new Error(`gateway health returned HTTP ${health.status}`);
     const models = await fetch(gatewayRoutes.models(gatewayUrl), {
       ...requestOptions,
-      headers: { authorization: `Bearer ${pat}` },
+      headers: { authorization: `Bearer ${bearerCredential(pat)}` },
     });
     if (!models.ok) throw new Error(`gateway authentication returned HTTP ${models.status}`);
     const body = await models.json();
@@ -353,6 +380,7 @@ export function createGatewayCli(options) {
     const config = loadConfig();
     if (!config?.pat || !config?.gatewayUrl) throw new Error(`not configured; run \`${brand.cli.command} setup\``);
     print(`Gateway: ${config.gatewayUrl}`);
+    if (brand.tenant.defaultId) print(`Tenant:  ${brand.tenant.defaultId}`);
     print(`PAT:     ${maskSecret(config.pat)}`);
     print(`Profiles: ${profileRoot}`);
     try {
@@ -367,7 +395,7 @@ export function createGatewayCli(options) {
   async function cmdToken() {
     const config = loadConfig();
     if (!config?.pat) throw new Error(`not authenticated; run \`${brand.cli.command} setup\` or \`${brand.cli.command} auth\``);
-    output.write(`${config.pat}\n`);
+    output.write(`${bearerCredential(config.pat)}\n`);
     return 0;
   }
 
@@ -408,7 +436,7 @@ export function createGatewayCli(options) {
       const profile = ensureClaudeProfile(config.gatewayUrl);
       childEnvironment.CLAUDE_CONFIG_DIR = profile.configDir;
       childEnvironment.ANTHROPIC_BASE_URL = gatewayRoutes.anthropic(config.gatewayUrl);
-      childEnvironment.ANTHROPIC_AUTH_TOKEN = config.pat;
+      childEnvironment.ANTHROPIC_AUTH_TOKEN = bearerCredential(config.pat);
     } else if (tool === "codex") {
       const profile = ensureCodexProfile(config.gatewayUrl);
       childEnvironment.CODEX_HOME = profile.codexHome;