impel-cli 0.13.1 → 0.14.0

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
@@ -642,7 +662,7 @@ Invocation uses the clients' native agent behavior:
 
 ```text
 # Claude Code / Claude Desktop Code tab: guaranteed explicit selection
-@agent-research-agent investigate the dependency change
+@research-agent investigate the dependency change
 
 # Claude blocking CLI
 claude --agent research-agent -p "investigate the dependency change"
@@ -715,8 +735,11 @@ Their visible bundle names use the organization display name, for example
 a stable, unique bundle identifier and gateway configuration:
 
 - Impel Claude is an APFS-cloned vendored copy of the official app with its own
-  bundle and helper identities. Its LaunchServices environment sets the
-  vendor-supported `CLAUDE_USER_DATA_DIR` and writes the 3P gateway
+  bundle and helper identities. Its LaunchServices environment sets both the
+  vendor-supported `CLAUDE_USER_DATA_DIR` and Claude Code's
+  `CLAUDE_CONFIG_DIR` to the tenant-private profile. This isolates browser
+  state, sessions, plugins, MCP servers, skills, and native `@` agents from
+  `~/.claude`, while the app writes the 3P gateway
   `configLibrary` below `~/.config/impel/apps/tenants/<org>/claude`. A new
   isolated profile defaults to the Code app while preserving any app selection
   the user makes afterward. A narrowly version-checked compatibility patch
@@ -818,6 +841,18 @@ available: `IMPEL_CODESIGN_ADHOC=1` forces ad-hoc signing, and
 `IMPEL_CODESIGN_IDENTITY=<name>` signs with a specific existing identity (e.g. a
 real `Developer ID Application: …`).
 
+Older Claude profiles already encrypt browser data with the macOS login
+Keychain item named `Claude Safe Storage`. Impel keeps that namespace immutable
+so an update never makes existing cookies or storage unreadable. Because each
+tenant app has a distinct bundle identity, macOS asks once before that app may
+use the legacy item: enter the Mac login password and choose **Always Allow**.
+Choosing **Allow** grants access for only that launch and therefore prompts
+again next time. The stable Impel signature keeps a successful Always Allow
+grant valid across later app updates. Clean profiles instead start with a
+persisted tenant-specific Safe Storage namespace, so they never request access
+to the shared vendor item. Impel does not weaken or silently rewrite Keychain
+access lists.
+
 The Claude 3P config necessarily contains the PAT because that app accepts a
 gateway API key rather than a token-helper command. It is stored in the same
 owner-only Impel config tree as the primary credential. ChatGPT/Codex uses a

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "impel-cli",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "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/apps.js

@@ -83,6 +83,8 @@ const CLAUDE_PLAN_USAGE_GUARD = "if(!Ze().hasOrgPolicyBackend())return;if((r=fr(
 const IMPEL_CLAUDE_PLAN_USAGE_GUARD = `${"if(!wze())return;".padEnd("if(!Ze().hasOrgPolicyBackend())return;".length, " ")}if((r=fr())`;
 const CLAUDE_PLAN_USAGE_REQUEST = 'P.net.fetch(`${ht()}/api/organizations/${o}/usage`,{signal:AbortSignal.timeout(mcr)})';
 const IMPEL_CLAUDE_PLAN_USAGE_REQUEST = 'P.net.fetch("https://gateway.useimpel.com/ui/a/u",{headers:{key:dR(Oe()).apiKey}})'.padEnd(CLAUDE_PLAN_USAGE_REQUEST.length, " ");
+const LEGACY_CLAUDE_SAFE_STORAGE_NAME = "Claude";
+const CLAUDE_SAFE_STORAGE_METADATA = "safe-storage.json";
 
 export const FALLBACK_MODELS = [
   { id: "claude-opus-4-8", provider: "claude", display_name: "Claude Opus 4.8", family: "opus", family_default: true, default: true, context_window: 200000 },
@@ -152,7 +154,7 @@ export const CURRENT_CONFIG_VERSION = 10;
 // — which is what made every `impel update` re-trigger macOS permission
 // prompts. Bump this ONLY when a code change alters the bytes of a built
 // bundle; leave it alone for changes that don't touch bundle contents.
-export const BUNDLE_BUILD_FINGERPRINT = "bundle-2026-07-16.2";
+export const BUNDLE_BUILD_FINGERPRINT = "bundle-2026-07-16.3";
 
 /** Parse the tenant's install manifest, or null when absent/corrupt. */
 export function readTenantManifest(homeDir = os.homedir(), tenantId = null) {
@@ -352,6 +354,130 @@ export function appPaths(homeDir = os.homedir(), tenantId = null, {
   };
 }
 
+function readClaudeSafeStorageMetadata(paths) {
+  const metadataPath = path.join(paths.claude.root, CLAUDE_SAFE_STORAGE_METADATA);
+  try {
+    const metadata = JSON.parse(fs.readFileSync(metadataPath, "utf8"));
+    if (
+      metadata?.schemaVersion !== 1
+      || typeof metadata.appName !== "string"
+      || !metadata.appName.trim()
+      || metadata.appName.length > 256
+    ) {
+      throw new Error("invalid contents");
+    }
+    return metadata;
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw new Error(`Claude Safe Storage metadata is invalid: ${metadataPath}`);
+  }
+}
+
+/**
+ * Electron keys macOS Safe Storage by app.name. Existing profiles already have
+ * encrypted data under `Claude Safe Storage`, so changing their name would make
+ * that data unreadable. New profiles can safely start with an immutable,
+ * tenant-specific namespace and never touch the vendor/shared Keychain item.
+ */
+export function ensureClaudeSafeStorageName(paths, tenantId = null) {
+  const existing = readClaudeSafeStorageMetadata(paths);
+  if (existing) return existing.appName;
+  const hasExistingProfile = fs.existsSync(paths.claude.userData)
+    && fs.readdirSync(paths.claude.userData).length > 0;
+  const appName = hasExistingProfile
+    ? LEGACY_CLAUDE_SAFE_STORAGE_NAME
+    : `Impel Claude${tenantId ? ` [${normalizeTenantId(tenantId)}]` : ""}`;
+  writeAtomic(path.join(paths.claude.root, CLAUDE_SAFE_STORAGE_METADATA), `${JSON.stringify({
+    schemaVersion: 1,
+    appName,
+    mode: hasExistingProfile ? "legacy" : "tenant",
+  }, null, 2)}\n`, 0o600);
+  return appName;
+}
+
+const CLAUDE_SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+
+function managedClaudeDesktopSessionIds(userData) {
+  const root = path.join(userData, "claude-code-sessions");
+  if (!fs.existsSync(root) || fs.lstatSync(root).isSymbolicLink()) return new Set();
+  const ids = new Set();
+  const pending = [root];
+  while (pending.length > 0) {
+    const directory = pending.pop();
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const candidate = path.join(directory, entry.name);
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) {
+        pending.push(candidate);
+        continue;
+      }
+      if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+      try {
+        const metadata = JSON.parse(fs.readFileSync(candidate, "utf8"));
+        if (CLAUDE_SESSION_ID_RE.test(metadata?.cliSessionId || "")) ids.add(metadata.cliSessionId);
+      } catch {
+        // A corrupt historical session remains in place; other sessions can
+        // still be migrated safely.
+      }
+    }
+  }
+  return ids;
+}
+
+/**
+ * Before v0.13.2 the desktop bundle isolated Electron state but omitted
+ * CLAUDE_CONFIG_DIR, so its embedded Claude Code transcripts fell through to
+ * ~/.claude. Copy only transcripts referenced by this app profile's own
+ * session metadata into the private config root. Native history is never
+ * removed or rewritten, and unrelated session IDs are ignored.
+ */
+export function migrateLegacyClaudeAppSessions(userData, homeDir = os.homedir()) {
+  const sessionIds = managedClaudeDesktopSessionIds(userData);
+  if (sessionIds.size === 0) return 0;
+  const nativeProjects = path.join(homeDir, ".claude", "projects");
+  const privateProjects = path.join(userData, "projects");
+  if (!fs.existsSync(nativeProjects) || fs.lstatSync(nativeProjects).isSymbolicLink()) return 0;
+  if (fs.existsSync(privateProjects) && fs.lstatSync(privateProjects).isSymbolicLink()) {
+    throw new Error(`refusing to migrate Claude sessions into symlinked profile path ${privateProjects}`);
+  }
+
+  let copied = 0;
+  for (const project of fs.readdirSync(nativeProjects, { withFileTypes: true })) {
+    if (!project.isDirectory() || project.isSymbolicLink()) continue;
+    const sourceDirectory = path.join(nativeProjects, project.name);
+    const destinationDirectory = path.join(privateProjects, project.name);
+    if (fs.existsSync(destinationDirectory) && fs.lstatSync(destinationDirectory).isSymbolicLink()) {
+      throw new Error(`refusing to migrate Claude sessions into symlinked project path ${destinationDirectory}`);
+    }
+    for (const entry of fs.readdirSync(sourceDirectory, { withFileTypes: true })) {
+      if (!entry.isFile() || entry.isSymbolicLink() || !entry.name.endsWith(".jsonl")) continue;
+      const sessionId = entry.name.slice(0, -".jsonl".length);
+      if (!sessionIds.has(sessionId)) continue;
+      const source = path.join(sourceDirectory, entry.name);
+      const destination = path.join(destinationDirectory, entry.name);
+      if (fs.existsSync(destination) && fs.lstatSync(destination).isSymbolicLink()) {
+        throw new Error(`refusing to overwrite symlinked Claude session transcript ${destination}`);
+      }
+      const sourceStat = fs.statSync(source);
+      if (fs.existsSync(destination) && fs.statSync(destination).mtimeMs >= sourceStat.mtimeMs) continue;
+      fs.mkdirSync(destinationDirectory, { recursive: true, mode: 0o700 });
+      fs.chmodSync(destinationDirectory, 0o700);
+      const temporary = `${destination}.tmp-${process.pid}`;
+      try {
+        fs.copyFileSync(source, temporary);
+        fs.chmodSync(temporary, 0o600);
+        fs.renameSync(temporary, destination);
+        fs.utimesSync(destination, sourceStat.atime, sourceStat.mtime);
+        fs.chmodSync(destination, 0o600);
+        copied += 1;
+      } finally {
+        fs.rmSync(temporary, { force: true });
+      }
+    }
+  }
+  return copied;
+}
+
 export async function fetchGatewayModels(config, fetchImpl = fetch) {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), 20000);
@@ -395,6 +521,9 @@ export function installManagedAppFiles({
     claudeUserData,
     tenantName: config.tenantName,
   });
+  const claudeSafeStorageName = targets.includes("claude")
+    ? ensureClaudeSafeStorageName(paths, config.tenantId)
+    : null;
   if (targets.includes("chatgpt")) secureAllManagedCodexHomes({ appsRoot: paths.root });
   fs.mkdirSync(paths.tenantRoot, { recursive: true, mode: 0o700 });
   if (writeTokenHelperFile) writeTokenHelper(paths.tokenHelper, config.tenantId);
@@ -409,6 +538,7 @@ export function installManagedAppFiles({
   const installed = [];
   for (const target of targets) {
     if (target === "claude") {
+      migrateLegacyClaudeAppSessions(paths.claude.userData, homeDir);
       writeClaudeDefaultApp(paths);
       writeClaudeConfig(paths, config, models);
     }
@@ -421,14 +551,23 @@ export function installManagedAppFiles({
         assertPinnedVendorAppVersion(target, resolvedVendorPaths[target]);
       }
       if (target === "chatgpt") writeVendoredChatGPTBundle(paths, resolvedVendorPaths.chatgpt, config.gatewayUrl);
-      else writeVendoredClaudeBundle(paths, resolvedVendorPaths.claude, config.gatewayUrl);
+      else writeVendoredClaudeBundle(
+        paths,
+        resolvedVendorPaths.claude,
+        config.gatewayUrl,
+        claudeSafeStorageName,
+      );
       if (config.tenantId) {
         // A successful tenant-specific rebuild supersedes the old global
         // launcher. Other tenant launchers have distinct names and survive.
         fs.rmSync(appPaths(homeDir)[target].launcher, { recursive: true, force: true });
       }
     }
-    installed.push({ target, launcher: paths[target].launcher });
+    installed.push({
+      target,
+      launcher: paths[target].launcher,
+      ...(target === "claude" ? { safeStorageName: claudeSafeStorageName } : {}),
+    });
   }
 
   writeAtomic(path.join(paths.tenantRoot, "manifest.json"), JSON.stringify({
@@ -992,7 +1131,7 @@ exec ${node} ${cli} token${tenantArgs}
   writeAtomic(target, script, 0o700);
 }
 
-function writeVendoredClaudeBundle(paths, vendorPath, gatewayUrl) {
+function writeVendoredClaudeBundle(paths, vendorPath, gatewayUrl, safeStorageName) {
   if (!vendorPath) throw new Error("Claude vendor app is unavailable");
   const executableName = APP_DEFINITIONS.claude.executableNames.find((name) => (
     fs.existsSync(path.join(vendorPath, "Contents", "MacOS", name))
@@ -1026,6 +1165,7 @@ function writeVendoredClaudeBundle(paths, vendorPath, gatewayUrl) {
       );
       planUsageRequestPatchCount = patchClaudePlanUsageRequest(asarPath);
     }
+    const safeStorageNamePatchCount = patchClaudeSafeStorageName(asarPath);
     const newAsarHash = asarHeaderHash(asarPath);
 
     updateBundleIdentity(plistPath, {
@@ -1035,7 +1175,15 @@ function writeVendoredClaudeBundle(paths, vendorPath, gatewayUrl) {
       name: paths.claude.displayName,
     });
     updateAsarIntegrityPlist(plistPath, oldAsarHash, newAsarHash);
+    // Claude Desktop separates its Electron profile from Claude Code's config
+    // root. Keep both on the tenant-private path: CLAUDE_USER_DATA_DIR isolates
+    // browser/app state, while CLAUDE_CONFIG_DIR controls sessions, plugins,
+    // MCP servers, skills, and native `@` agents used by the embedded runtime.
+    // Without the latter, the app silently falls back to ~/.claude and can
+    // expose an unrelated tenant's agents or secret-bearing MCP configuration.
     setPlistEnvironmentString(plistPath, "CLAUDE_USER_DATA_DIR", paths.claude.userData);
+    setPlistEnvironmentString(plistPath, "CLAUDE_CONFIG_DIR", paths.claude.userData);
+    setPlistEnvironmentString(plistPath, "IMPEL_CN", safeStorageName);
     rebrandElectronHelpers(staging, {
       fromName: "Claude",
       toName: paths.claude.displayName,
@@ -1054,10 +1202,13 @@ function writeVendoredClaudeBundle(paths, vendorPath, gatewayUrl) {
       bundleIdentifier: paths.claude.bundleIdentifier,
       displayName: paths.claude.displayName,
       profileRoot: paths.claude.userData,
+      configRoot: paths.claude.userData,
+      safeStorageName,
       launchMode: "LSEnvironment",
       patches: {
         aggregatePlanUsageGuard: planUsageGuardPatchCount,
         aggregatePlanUsageRequest: planUsageRequestPatchCount,
+        safeStorageName: safeStorageNamePatchCount,
       },
       asarHeaderSha256: newAsarHash,
     }, null, 2) + "\n", 0o644);
@@ -1239,6 +1390,24 @@ function patchClaudePlanUsageRequest(asarPath) {
   return applyFixedWidthAsarPatches(asarPath, archive, patches, "Claude plan-usage gateway request");
 }
 
+function patchClaudeSafeStorageName(asarPath) {
+  const archive = fs.readFileSync(asarPath);
+  const source = archive.toString("latin1");
+  const startupPattern = /([A-Za-z_$][\w$]*)\.app\.isPackaged\|\|\1\.app\.setName\("Claude"\)/gu;
+  const patches = [...source.matchAll(startupPattern)].map((match) => {
+    const original = match[0];
+    const replacement = `${match[1]}.app.setName(process.env.IMPEL_CN)`;
+    if (replacement.length > original.length) {
+      throw new Error("Claude Safe Storage app-name replacement no longer fits the vendor ASAR contract");
+    }
+    return { offset: match.index, original, replacement: replacement.padEnd(original.length, " ") };
+  });
+  if (patches.length !== 1) {
+    throw new Error(`Claude Safe Storage app-name patch expected 1 match, found ${patches.length}`);
+  }
+  return applyFixedWidthAsarPatches(asarPath, archive, patches, "Claude Safe Storage app name");
+}
+
 function patchFastModeAuthGate(asarPath) {
   const archive = fs.readFileSync(asarPath);
   const source = archive.toString("latin1");

package/src/commands/apps.js

@@ -56,6 +56,8 @@ import {
   windowsClaudeUserData,
 } from "../windowsApps.js";
 
+const CLAUDE_KEYCHAIN_NOTICE = "Claude Keychain: enter your Mac login password and choose Always Allow on the first prompt for this tenant; Allow is temporary.";
+
 // Each isolated desktop app maps to a client CLI + the env override that points
 // that CLI at the app's private profile, so skill syncing lands in the app's
 // installation rather than a global one.
@@ -626,6 +628,11 @@ export async function cmdApps(argv, overrides = {}) {
     const verb = action === "install" ? "Installed" : "Updated";
     io.log(`${verb} ${item.launcher}${rebuilt.has(item.target) ? "" : " (bundle already current)"}`);
   }
+  if (installed.some((item) => (
+    item.target === "claude"
+    && rebuilt.has(item.target)
+    && item.safeStorageName === "Claude"
+  ))) io.log(CLAUDE_KEYCHAIN_NOTICE);
   console.log(`Models: ${catalog.models.length} from ${catalog.source}. Normal ~/.claude and ~/.codex profiles were not changed.`);
 
   // Best-effort: sync the Bifrost shared skills into each installed isolated app
@@ -745,6 +752,11 @@ export async function provisionAndOpenManagedApps({
       io.log(`Installed and configured ${item.launcher} for tenant ${config.tenantId}.`);
     }
   }
+  if (installed.some((item) => (
+    item.target === "claude"
+    && staleBundleTargets.includes(item.target)
+    && item.safeStorageName === "Claude"
+  ))) io.log(CLAUDE_KEYCHAIN_NOTICE);
 
   // Match explicit install setup without penalizing repeat opens: this helper
   // only runs when the zero-network fast path has detected drift or first use.

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) };
 }

package/src/windowsApps.js

@@ -329,7 +329,7 @@ export function removeManagedWindowsChatGPTApp(appsRoot) {
   fs.rmSync(windowsChatGPTCacheRoot(appsRoot), { recursive: true, force: true });
 }
 
-/** Launch the signed vendor app with only its profile root redirected to Impel. */
+/** Launch the signed vendor app with all mutable Claude state redirected to Impel. */
 export function launchWindowsClaudeApp(binary, userData, dependencies = {}) {
   const io = {
     environment: process.env,
@@ -341,11 +341,17 @@ export function launchWindowsClaudeApp(binary, userData, dependencies = {}) {
   const environment = { ...io.environment };
   // These developer-only overrides require a signed CDP token and must never
   // bleed from an unrelated native Claude session into the managed app.
-  const managedKeys = new Set(["CLAUDE_USER_DATA_DIR", "CLAUDE_CDP_AUTH", "CLAUDE_AI_URL"]);
+  const managedKeys = new Set([
+    "CLAUDE_USER_DATA_DIR",
+    "CLAUDE_CONFIG_DIR",
+    "CLAUDE_CDP_AUTH",
+    "CLAUDE_AI_URL",
+  ]);
   for (const key of Object.keys(environment)) {
     if (managedKeys.has(key.toUpperCase())) delete environment[key];
   }
   environment.CLAUDE_USER_DATA_DIR = userData;
+  environment.CLAUDE_CONFIG_DIR = userData;
 
   return new Promise((resolve, reject) => {
     const child = io.spawnProcess(binary, [], {