impel-cli 0.13.2 → 0.14.1

package/README.md

@@ -25,6 +25,26 @@ of the protected Store directory and launches it with tenant-specific Codex and
 browser profiles. Each approach keeps the user's normal app profile and
 signed-in account untouched.
 
+## Gateway-only vendor package
+
+White-labelled gateway launchers import the deliberately narrow
+`impel-cli/gateway` subpath. It exports only `createGatewayCli`; the resulting
+CLI accepts `setup`, `auth`, `claude`, `codex`, `status`, `token`, help, and
+version. Tasks, tenants, PAT minting, apps, agents, skills, MCP, updates, and
+other Impel control-plane commands are not part of this package surface.
+
+```js
+import { createGatewayCli } from "impel-cli/gateway";
+
+const cli = createGatewayCli({ brand, entrypoint, version });
+const exitCode = await cli.main(process.argv.slice(2));
+if (exitCode) process.exitCode = exitCode;
+```
+
+The caller supplies a validated branding document, its own executable path,
+and its package version. Gateway profile behavior and the command allowlist
+remain in `impel-cli`, so vendor CLIs do not copy or fork those implementations.
+
 ## Start here
 
 You do not need GitHub access to install Impel. You need an Impel account and a
@@ -610,8 +630,8 @@ every managed profile. This catalog is separate from automatic specialists: it
 may include truthfully declared write-capable agents, but those agents require
 explicit user selection before the server will start a run.
 
-- Claude Code: `<CLAUDE_CONFIG_DIR>/agents/impel-managed/*.md`
-- Codex / ChatGPT Codex mode: `<CODEX_HOME>/agents/impel-managed/*.toml`
+- Claude Code / Claude Desktop: `<CLAUDE_CONFIG_DIR>/agents/<agent-name>.md`
+- Codex / ChatGPT Codex mode: `<CODEX_HOME>/agents/impel-<tenant>-<agent-id>.toml`
 
 Each generated agent is bound to one exact `agentId` and
 `scopeParam`. It verifies that the exact agent is still available, starts one
@@ -623,8 +643,8 @@ when invoked.
 
 Visible agent names come from the registry title. Codex keeps that title as the
 custom-agent name; Claude uses the lowercase, hyphenated form required by its
-native agent schema. The generated filenames remain stable tenant-and-agent
-identifiers so title changes update in place without colliding with user files.
+native agent schema and Desktop's `@` picker requires the Markdown filename to
+match that name. Codex filenames remain stable tenant-and-agent identifiers.
 Duplicate or built-in-reserved titles receive a deterministic disambiguator.
 
 The sync writes atomically and records a manifest beside the generated files.

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "impel-cli",
-  "version": "0.13.2",
+  "version": "0.14.1",
   "description": "Configure Claude Code and Codex CLI to talk to Impel's gateway, authenticated by an Impel Personal Access Token",
   "type": "module",
   "bin": {
     "impel": "bin/impel.js"
   },
+  "exports": {
+    "./gateway": "./src/gateway/index.js"
+  },
   "files": [
     "bin",
     "src",

package/src/agents.js

@@ -398,10 +398,16 @@ export function renderManagedAgents(client, tenantId, agents, invocation = impel
   return agents.map((agent, index) => {
     const name = names[index];
     const extension = client === "claude" ? ".md" : ".toml";
+    // Claude Desktop decides whether an SDK-reported agent is user-defined by
+    // comparing its reported name with the Markdown filename (without .md).
+    // A stable tenant/agent filename causes Desktop to classify the agent as a
+    // builtin and remove it from the @ mention picker. Claude names are already
+    // collision-safe, filesystem-safe identifiers, so use them as filenames.
+    const fileStem = client === "claude" ? name : fileStems[index];
     const contents = client === "claude"
       ? renderClaudeAgent({ tenantId: normalizedTenant, agent, name, invocation })
       : renderCodexAgent({ tenantId: normalizedTenant, agent, name, invocation });
-    return { agentId: agent.agentId, name, fileName: `${fileStems[index]}${extension}`, contents };
+    return { agentId: agent.agentId, name, fileName: `${fileStem}${extension}`, contents };
   });
 }
 
@@ -432,7 +438,7 @@ function readManifest(manifestPath) {
 
 function profileIsFresh(profile, tenantId, now, ttlMs) {
   const manifest = readManifest(path.join(profile.root, "agents", MANAGED_AGENT_DIRECTORY, MANAGED_AGENT_MANIFEST));
-  if (!manifest || manifest.version !== 2 || manifest.tenantId !== tenantId) return false;
+  if (!manifest || manifest.version !== 3 || manifest.tenantId !== tenantId) return false;
   const syncedAt = Date.parse(manifest.syncedAt || "");
   if (!Number.isFinite(syncedAt) || now - syncedAt >= ttlMs) return false;
   return manifest.files.every((fileName) =>
@@ -455,7 +461,7 @@ export function syncAgentProfile({ client, root, label, tenantId, agents, now =
   const prior = readManifest(manifestPath);
   const rendered = renderManagedAgents(client, tenantId, agents);
   const priorFiles = new Set(prior?.files || []);
-  const priorUsesDiscoveryRoot = prior?.version === 2;
+  const priorUsesDiscoveryRoot = prior?.version === 2 || prior?.version === 3;
 
   // Native clients discover standalone definitions directly under `agents/`.
   // Preflight every destination before writing so an unmanaged file with the
@@ -497,7 +503,7 @@ export function syncAgentProfile({ client, root, label, tenantId, agents, now =
     }
   }
   atomicPrivateWrite(manifestPath, `${JSON.stringify({
-    version: 2,
+    version: 3,
     tenantId,
     client,
     syncedAt: new Date(now).toISOString(),

package/src/gateway/index.js

@@ -0,0 +1,454 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+
+import { nativeCommandInvocation } from "../nativeProcess.js";
+
+const SAFE_ID = /^[a-z][a-z0-9-]{2,31}$/u;
+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 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;
+
+function validateText(name, value, max = 128) {
+  if (typeof value !== "string" || value.trim() !== value || !value || value.length > max || CONTROL_TEST_RE.test(value)) {
+    throw new Error(`gateway CLI ${name} is invalid`);
+  }
+  return value;
+}
+
+function validateRoute(name, value) {
+  if (typeof value !== "string" || !SAFE_ROUTE.test(value) || value.includes("//")) {
+    throw new Error(`gateway CLI ${name} is invalid`);
+  }
+  return value;
+}
+
+function validateBrand(input) {
+  if (!input || Array.isArray(input) || typeof input !== "object" || input.schemaVersion !== 1) {
+    throw new Error("gateway CLI brand schemaVersion must be 1");
+  }
+  const productID = String(input.product?.id || "");
+  const command = String(input.cli?.command || "");
+  const configNamespace = String(input.cli?.configNamespace || "");
+  const providerID = String(input.cli?.providerId || "");
+  const managedMarker = String(input.cli?.managedMarker || "");
+  const environmentPrefix = String(input.cli?.environmentPrefix || command.toUpperCase().replace(/-/gu, "_"));
+  const patPrefix = String(input.auth?.patPrefix || "");
+  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");
+  if (!SAFE_NAMESPACE.test(providerID)) throw new Error("gateway CLI providerId is invalid");
+  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");
+
+  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 }),
+    gateway: Object.freeze({
+      defaultOrigin,
+      healthPath: validateRoute("healthPath", input.gateway?.healthPath),
+      modelsPath: validateRoute("modelsPath", input.gateway?.modelsPath),
+      anthropicBasePath: validateRoute("anthropicBasePath", input.gateway?.anthropicBasePath),
+      codexCliBasePath: validateRoute("codexCliBasePath", input.gateway?.codexCliBasePath),
+    }),
+  });
+}
+
+function parseFlags(argv, spec = {}) {
+  const flags = {};
+  const positionals = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--") {
+      positionals.push(...argv.slice(index + 1));
+      break;
+    }
+    if (!argument.startsWith("--")) {
+      positionals.push(argument);
+      continue;
+    }
+    const equalsIndex = argument.indexOf("=");
+    const name = argument.slice(2, equalsIndex === -1 ? undefined : equalsIndex);
+    if (!Object.hasOwn(spec, name)) throw new Error(`unknown flag --${name}`);
+    let value;
+    if (equalsIndex !== -1) {
+      value = argument.slice(equalsIndex + 1);
+    } else if (spec[name].type === "boolean") {
+      value = true;
+    } else {
+      value = argv[index + 1];
+      index += 1;
+    }
+    if (spec[name].type === "string" && (value === undefined || value === "")) {
+      throw new Error(`--${name} requires a value`);
+    }
+    flags[name] = value;
+  }
+  return { flags, positionals };
+}
+
+function normalizeGatewayUrl(value) {
+  const normalized = String(value || "").trim().replace(/\/+$/u, "");
+  if (!normalized) throw new Error("a gateway URL is required");
+  const parsed = new URL(normalized);
+  const localHTTP = parsed.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname);
+  if (parsed.protocol !== "https:" && !localHTTP) {
+    throw new Error("gateway URL must use HTTPS (HTTP is allowed only for local testing)");
+  }
+  if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+    throw new Error("gateway URL must not contain credentials, query, or fragment");
+  }
+  return parsed.toString().replace(/\/+$/u, "");
+}
+
+function joinRoute(origin, route) {
+  return `${origin}${route.startsWith("/") ? route : `/${route}`}`;
+}
+
+/**
+ * Create a deliberately small, branded gateway launcher. This is the only
+ * public library surface intended for white-labelled vendor CLIs.
+ */
+export function createGatewayCli(options) {
+  const brand = validateBrand(options?.brand);
+  const entrypoint = String(options?.entrypoint || "");
+  const version = String(options?.version || "");
+  if (!entrypoint || !path.isAbsolute(entrypoint)) throw new Error("gateway CLI entrypoint must be an absolute path");
+  if (!/^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/u.test(version)) throw new Error("gateway CLI version is invalid");
+
+  const environment = options.environment || process.env;
+  const input = options.input || process.stdin;
+  const output = options.output || process.stdout;
+  const environmentName = (suffix) => `${brand.cli.environmentPrefix}_${suffix}`;
+  const configDirectory = environment[environmentName("CONFIG_DIR")] || path.join(os.homedir(), ".config", brand.cli.configNamespace);
+  const configPath = path.join(configDirectory, "config.json");
+  const profileRoot = path.join(configDirectory, "cli");
+  const gatewayRoutes = Object.freeze({
+    health(origin) { return joinRoute(origin, brand.gateway.healthPath); },
+    models(origin) { return joinRoute(origin, brand.gateway.modelsPath); },
+    anthropic(origin) { return joinRoute(origin, brand.gateway.anthropicBasePath); },
+    codex(origin) { return joinRoute(origin, brand.gateway.codexCliBasePath); },
+  });
+  const print = (line = "") => output.write(`${line}\n`);
+
+  function ensurePrivateDirectory(directory) {
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`${directory} must be a real private directory`);
+    try { fs.chmodSync(directory, 0o700); } catch {}
+  }
+
+  function writePrivateFile(filePath, contents) {
+    ensurePrivateDirectory(path.dirname(filePath));
+    const temporary = `${filePath}.tmp-${process.pid}`;
+    try {
+      fs.writeFileSync(temporary, contents, { encoding: "utf8", mode: 0o600, flag: "wx" });
+      fs.renameSync(temporary, filePath);
+      try { fs.chmodSync(filePath, 0o600); } catch {}
+    } finally {
+      try { fs.rmSync(temporary, { force: true }); } catch {}
+    }
+  }
+
+  function loadConfig() {
+    let raw;
+    try { raw = fs.readFileSync(configPath, "utf8"); }
+    catch (error) { if (error?.code === "ENOENT") return null; throw error; }
+    let value;
+    try { value = JSON.parse(raw); }
+    catch { throw new Error(`${configPath} is not valid JSON; fix or remove it`); }
+    if (!value || Array.isArray(value) || typeof value !== "object") throw new Error(`${configPath} must contain a JSON object`);
+    if (value.gatewayUrl) value.gatewayUrl = normalizeGatewayUrl(value.gatewayUrl);
+    return value;
+  }
+
+  function saveConfig(config) {
+    writePrivateFile(configPath, `${JSON.stringify(config, null, 2)}\n`);
+  }
+
+  function maskSecret(value) {
+    const secret = String(value || "");
+    if (!secret) return "(none)";
+    if (secret.length <= 12) return "*".repeat(secret.length);
+    return `${secret.slice(0, brand.auth.patPrefix.length + 4)}...${secret.slice(-4)}`;
+  }
+
+  function redactSecretText(value) {
+    const escapedPrefix = brand.auth.patPrefix.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+    const tokenPattern = new RegExp(`${escapedPrefix}[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)?`, "gu");
+    return String(value ?? "")
+      .replace(tokenPattern, "[REDACTED GATEWAY CREDENTIAL]")
+      .replace(ANSI_ESCAPE_RE, "")
+      .replace(CONTROL_RE, " ");
+  }
+
+  function resolveGateway(existing) {
+    const value = environment[environmentName("GATEWAY_URL")] || existing?.gatewayUrl || brand.gateway.defaultOrigin;
+    if (!value) {
+      throw new Error(`a gateway URL is required (pass --gateway or set ${environmentName("GATEWAY_URL")})`);
+    }
+    return normalizeGatewayUrl(value);
+  }
+
+  function promptSecret(question) {
+    return new Promise((resolve) => {
+      const rl = readline.createInterface({ input, output, terminal: input.isTTY });
+      if (input.isTTY) {
+        const originalWrite = rl._writeToOutput?.bind(rl);
+        if (originalWrite) {
+          rl._writeToOutput = (text) => originalWrite(text === question ? text : "*".repeat(text.length));
+        }
+      }
+      rl.question(question, (answer) => {
+        rl.close();
+        output.write("\n");
+        resolve(answer.trim());
+      });
+    });
+  }
+
+  async function resolveAuthConfig(argv) {
+    const { flags } = parseFlags(argv, { gateway: { type: "string" } });
+    const existing = loadConfig();
+    const suppliedPAT = environment[environmentName("PAT")];
+    const pat = String(suppliedPAT || await promptSecret(`${brand.product.displayName} Personal Access Token: `)).trim();
+    if (!pat.startsWith(brand.auth.patPrefix) || /[\u0000-\u0020\u007f]/u.test(pat)) {
+      throw new Error(`PAT must start with ${brand.auth.patPrefix} and contain no whitespace`);
+    }
+    const gatewayUrl = flags.gateway ? normalizeGatewayUrl(flags.gateway) : resolveGateway(existing);
+    return { schemaVersion: 1, pat, gatewayUrl, updatedAt: new Date().toISOString() };
+  }
+
+  function persistAuthConfig(config, { quiet = false } = {}) {
+    saveConfig(config);
+    if (!quiet) {
+      print(`Stored ${brand.product.displayName} credentials in the private ${brand.cli.command} config.`);
+      print(`  gateway: ${config.gatewayUrl}`);
+      print(`  PAT:     ${maskSecret(config.pat)}`);
+    }
+  }
+
+  async function checkGateway(gatewayUrl, pat) {
+    const requestOptions = { signal: AbortSignal.timeout(5000) };
+    const health = await fetch(gatewayRoutes.health(gatewayUrl), requestOptions);
+    if (!health.ok) throw new Error(`gateway health returned HTTP ${health.status}`);
+    const models = await fetch(gatewayRoutes.models(gatewayUrl), {
+      ...requestOptions,
+      headers: { authorization: `Bearer ${pat}` },
+    });
+    if (!models.ok) throw new Error(`gateway authentication returned HTTP ${models.status}`);
+    const body = await models.json();
+    return { modelCount: Array.isArray(body?.data) ? body.data.length : null };
+  }
+
+  function readJsonObject(filePath) {
+    if (!fs.existsSync(filePath)) return {};
+    try {
+      const value = JSON.parse(fs.readFileSync(filePath, "utf8"));
+      if (!value || Array.isArray(value) || typeof value !== "object") throw new Error();
+      return value;
+    } catch { throw new Error(`${filePath} must contain a JSON object`); }
+  }
+
+  function cliInvocation(args = []) {
+    return { command: process.execPath, args: [entrypoint, ...args] };
+  }
+
+  function ensureClaudeProfile(gatewayUrl) {
+    const configDir = path.join(profileRoot, "claude");
+    const settingsPath = path.join(configDir, "settings.json");
+    const settings = readJsonObject(settingsPath);
+    settings.env = {
+      ...(settings.env && typeof settings.env === "object" && !Array.isArray(settings.env) ? settings.env : {}),
+      ANTHROPIC_BASE_URL: gatewayRoutes.anthropic(gatewayUrl),
+    };
+    delete settings.env.ANTHROPIC_API_KEY;
+    delete settings.env.ANTHROPIC_AUTH_TOKEN;
+    writePrivateFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+    return { configDir, settingsPath };
+  }
+
+  const startMark = `# >>> ${brand.cli.managedMarker} profile >>>`;
+  const endMark = `# <<< ${brand.cli.managedMarker} profile <<<`;
+
+  function stripManagedBlock(text, filePath) {
+    const start = text.indexOf(startMark);
+    if (start === -1) return text;
+    const end = text.indexOf(endMark, start);
+    if (end === -1) throw new Error(`${filePath} has an incomplete managed block`);
+    return text.slice(0, start) + text.slice(end + endMark.length);
+  }
+
+  function codexManagedBlock(gatewayUrl) {
+    const auth = cliInvocation(["token"]);
+    return [
+      startMark,
+      `# Generated by the ${brand.product.displayName} CLI. Settings outside this block are preserved.`,
+      `[model_providers.${brand.cli.providerId}]`,
+      `name = ${JSON.stringify(`${brand.product.displayName} Gateway`)}`,
+      `base_url = ${JSON.stringify(gatewayRoutes.codex(gatewayUrl))}`,
+      'wire_api = "responses"',
+      "",
+      `[model_providers.${brand.cli.providerId}.auth]`,
+      `command = ${JSON.stringify(auth.command)}`,
+      `args = [${auth.args.map((argument) => JSON.stringify(argument)).join(", ")}]`,
+      "timeout_ms = 5000",
+      "refresh_interval_ms = 300000",
+      "",
+      "[features]",
+      "shell_snapshot = false",
+      endMark,
+    ].join("\n");
+  }
+
+  function ensureCodexProfile(gatewayUrl) {
+    const codexHome = path.join(profileRoot, "codex");
+    const filePath = path.join(codexHome, "config.toml");
+    const original = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : "";
+    const outside = stripManagedBlock(original, filePath).trim();
+    const provider = brand.cli.providerId.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+    if (new RegExp(`^\\s*\\[model_providers\\.${provider}(?:\\.|\\])`, "mu").test(outside)) {
+      throw new Error(`${filePath} contains a ${brand.cli.providerId} provider outside the managed block`);
+    }
+    if (/^\s*\[features\]\s*$/mu.test(outside) || /^\s*features\.shell_snapshot\s*=/mu.test(outside)) {
+      throw new Error(`${filePath} defines features outside the managed block; move them into another isolated profile`);
+    }
+    const withoutProvider = outside.replace(/^\s*model_provider\s*=.*$/mu, "").trim();
+    const next = [`model_provider = ${JSON.stringify(brand.cli.providerId)}`, codexManagedBlock(gatewayUrl), withoutProvider]
+      .filter(Boolean).join("\n\n").concat("\n");
+    writePrivateFile(filePath, next);
+    return { codexHome, filePath };
+  }
+
+  async function cmdAuth(argv, { quiet = false } = {}) {
+    const config = await resolveAuthConfig(argv);
+    persistAuthConfig(config, { quiet });
+    return 0;
+  }
+
+  async function cmdSetup(argv) {
+    const config = await resolveAuthConfig(argv);
+    const result = await checkGateway(config.gatewayUrl, config.pat);
+    ensureClaudeProfile(config.gatewayUrl);
+    ensureCodexProfile(config.gatewayUrl);
+    persistAuthConfig(config, { quiet: true });
+    print(`${brand.product.displayName} gateway setup is ready.`);
+    print(`  gateway: ${config.gatewayUrl}`);
+    if (result.modelCount !== null) print(`  models:  ${result.modelCount}`);
+    print(`  launch:  ${brand.cli.command} claude  |  ${brand.cli.command} codex`);
+    return 0;
+  }
+
+  async function cmdStatus() {
+    const config = loadConfig();
+    if (!config?.pat || !config?.gatewayUrl) throw new Error(`not configured; run \`${brand.cli.command} setup\``);
+    print(`Gateway: ${config.gatewayUrl}`);
+    print(`PAT:     ${maskSecret(config.pat)}`);
+    print(`Profiles: ${profileRoot}`);
+    try {
+      const result = await checkGateway(config.gatewayUrl, config.pat);
+      print(`Status:  ready${result.modelCount === null ? "" : ` (${result.modelCount} models)`}`);
+    } catch (error) {
+      throw new Error(redactSecretText(error?.message || error));
+    }
+    return 0;
+  }
+
+  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`);
+    return 0;
+  }
+
+  function cleanLaunchEnvironment() {
+    const childEnvironment = { ...environment };
+    for (const name of [
+      environmentName("PAT"),
+      "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_BASE_URL", "ANTHROPIC_CUSTOM_HEADERS",
+      "OPENAI_API_KEY", "OPENAI_BASE_URL", "CODEX_API_KEY",
+    ]) delete childEnvironment[name];
+    return childEnvironment;
+  }
+
+  function runNative(tool, argv, childEnvironment) {
+    return new Promise((resolve, reject) => {
+      const invocation = nativeCommandInvocation(
+        tool,
+        argv,
+        childEnvironment,
+        process.platform,
+        brand.cli.environmentPrefix,
+      );
+      const child = spawn(invocation.command, invocation.args, {
+        env: childEnvironment,
+        stdio: "inherit",
+        windowsVerbatimArguments: invocation.windowsVerbatimArguments,
+      });
+      child.once("error", reject);
+      child.once("exit", (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+    });
+  }
+
+  async function cmdLaunch(tool, argv) {
+    const config = loadConfig();
+    if (!config?.pat || !config?.gatewayUrl) throw new Error(`not configured; run \`${brand.cli.command} setup\``);
+    const childEnvironment = cleanLaunchEnvironment();
+    if (tool === "claude") {
+      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;
+    } else if (tool === "codex") {
+      const profile = ensureCodexProfile(config.gatewayUrl);
+      childEnvironment.CODEX_HOME = profile.codexHome;
+    } else {
+      throw new Error(`unsupported launcher ${tool}`);
+    }
+    return runNative(tool, argv, childEnvironment);
+  }
+
+  const help = `${brand.cli.command} — ${brand.product.displayName} gateway CLI
+
+  ${brand.cli.command} setup --gateway <url>                 Configure, verify, and create isolated profiles
+  ${brand.cli.command} auth --gateway <url>                  Store the PAT and gateway URL privately
+  ${brand.cli.command} claude [args...]                      Launch isolated Claude Code
+  ${brand.cli.command} codex [args...]                       Launch isolated Codex
+  ${brand.cli.command} status                                Verify gateway authentication and model catalog
+  ${brand.cli.command} token                                 Auth-helper output; prints only the PAT
+  ${brand.cli.command} help
+  ${brand.cli.command} --version
+
+Environment:
+  ${environmentName("PAT")}          PAT for non-interactive setup/auth; keep it out of command arguments
+  ${environmentName("GATEWAY_URL")}  Default gateway URL
+  ${environmentName("CLAUDE_BIN")}   Optional Claude executable override
+  ${environmentName("CODEX_BIN")}    Optional Codex executable override
+`;
+
+  async function main(argv) {
+    const [command, ...rest] = argv;
+    switch (command) {
+      case undefined: case "help": case "--help": case "-h": print(help); return 0;
+      case "--version": case "-v": print(version); return 0;
+      case "setup": return cmdSetup(rest);
+      case "auth": return cmdAuth(rest);
+      case "token": return cmdToken();
+      case "status": return cmdStatus();
+      case "claude": case "codex": return cmdLaunch(command, rest);
+      default: throw new Error(`unknown command ${JSON.stringify(command)}; run \`${brand.cli.command} help\``);
+    }
+  }
+
+  return Object.freeze({ main });
+}

package/src/nativeProcess.js

@@ -51,10 +51,10 @@ function binaryCandidates(directory, tool, environment, platform) {
   return windowsPathExtensions(environment).map((extension) => `${base}${extension}`);
 }
 
-function overrideName(tool) {
-  if (tool === "claude") return "IMPEL_CLAUDE_BIN";
-  if (tool === "codex") return "IMPEL_CODEX_BIN";
-  if (tool === "npm") return "IMPEL_NPM_BIN";
+function overrideName(tool, environmentPrefix = "IMPEL") {
+  if (tool === "claude") return `${environmentPrefix}_CLAUDE_BIN`;
+  if (tool === "codex") return `${environmentPrefix}_CODEX_BIN`;
+  if (tool === "npm") return `${environmentPrefix}_NPM_BIN`;
   return null;
 }
 
@@ -116,8 +116,13 @@ function commonCandidates(tool, environment, platform) {
 }
 
 /** Resolve a real executable/shim if one is installed, otherwise return null. */
-export function findNativeBinary(tool, environment = process.env, platform = process.platform) {
-  const override = overrideName(tool);
+export function findNativeBinary(
+  tool,
+  environment = process.env,
+  platform = process.platform,
+  environmentPrefix = "IMPEL",
+) {
+  const override = overrideName(tool, environmentPrefix);
   const overriddenBinary = override ? environmentValue(environment, override) : null;
   if (overriddenBinary) return isExecutable(overriddenBinary, platform) ? overriddenBinary : null;
 
@@ -136,10 +141,15 @@ export function findNativeBinary(tool, environment = process.env, platform = pro
 }
 
 /** Resolve an executable for launch, preserving explicit overrides and useful ENOENT errors. */
-export function resolveNativeBinary(tool, environment = process.env, platform = process.platform) {
-  const override = overrideName(tool);
+export function resolveNativeBinary(
+  tool,
+  environment = process.env,
+  platform = process.platform,
+  environmentPrefix = "IMPEL",
+) {
+  const override = overrideName(tool, environmentPrefix);
   const overriddenBinary = override ? environmentValue(environment, override) : null;
-  return overriddenBinary || findNativeBinary(tool, environment, platform) || tool;
+  return overriddenBinary || findNativeBinary(tool, environment, platform, environmentPrefix) || tool;
 }
 
 // Windows cannot execute npm's .cmd/.bat shims directly. This is the escaping
@@ -186,7 +196,13 @@ export function nativeSpawnInvocation(binary, argv, environment = process.env, p
 }
 
 /** Resolve a PATH command and produce a spawn-safe invocation for this platform. */
-export function nativeCommandInvocation(tool, argv, environment = process.env, platform = process.platform) {
-  const binary = resolveNativeBinary(tool, environment, platform);
+export function nativeCommandInvocation(
+  tool,
+  argv,
+  environment = process.env,
+  platform = process.platform,
+  environmentPrefix = "IMPEL",
+) {
+  const binary = resolveNativeBinary(tool, environment, platform, environmentPrefix);
   return { binary, ...nativeSpawnInvocation(binary, argv, environment, platform) };
 }