impel-cli 0.7.0

package/src/args.js

@@ -0,0 +1,36 @@
+// Tiny dependency-free flag parser. Supports `--flag value` and `--flag=value`.
+// `spec` maps flag name -> { type: "string" | "boolean" }.
+
+export function parseFlags(argv, spec = {}) {
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--") {
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
+    if (!arg.startsWith("--")) {
+      positionals.push(arg);
+      continue;
+    }
+    const eqIdx = arg.indexOf("=");
+    let name;
+    let value;
+    if (eqIdx !== -1) {
+      name = arg.slice(2, eqIdx);
+      value = arg.slice(eqIdx + 1);
+    } else {
+      name = arg.slice(2);
+      const isBoolean = spec[name]?.type === "boolean";
+      if (isBoolean) {
+        value = true;
+      } else {
+        value = argv[i + 1];
+        i += 1;
+      }
+    }
+    flags[name] = value;
+  }
+  return { flags, positionals };
+}

package/src/claudeSetup.js

@@ -0,0 +1,207 @@
+// Applies / reverts / detects the Impel-gateway config in ~/.claude/settings.json.
+//
+// Gateway mode adds exactly two keys — `apiKeyHelper: "impel token"` and
+// `env.ANTHROPIC_BASE_URL: "<gateway>/anthropic"` — and nothing else. Reverting
+// removes ONLY those two (and only when they still point at Impel), restoring
+// any prior values that were backed up when gateway mode was turned on.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { IMPEL_MANAGED_MCP_ENV, impelMcpInvocation } from "./selfInvocation.js";
+
+export const CLAUDE_DIR = path.join(os.homedir(), ".claude");
+export const CLAUDE_SETTINGS_PATH = path.join(CLAUDE_DIR, "settings.json");
+export const CLAUDE_USER_CONFIG_PATH = path.join(os.homedir(), ".claude.json");
+
+export const IMPEL_API_KEY_HELPER = "impel token";
+export const IMPEL_MCP_SERVER_NAME = "impel";
+const LEGACY_IMPEL_MCP_SERVER = { type: "stdio", command: "impel", args: ["mcp"] };
+
+function impelMcpServer() {
+  return impelMcpInvocation();
+}
+
+/** The ANTHROPIC_BASE_URL value Impel sets for a given gateway. */
+export function impelClaudeBaseUrl(gatewayUrl) {
+  return `${gatewayUrl}/anthropic`;
+}
+
+/** Experimental Anthropic-compatible route that can dispatch both providers. */
+export function impelCrossAppClaudeBaseUrl(gatewayUrl) {
+  return `${gatewayUrl}/experimental/anthropic`;
+}
+
+export function isImpelApiKeyHelper(value) {
+  return value === IMPEL_API_KEY_HELPER;
+}
+
+export function isImpelClaudeBaseUrl(value, gatewayUrl) {
+  return value != null && value === impelClaudeBaseUrl(gatewayUrl);
+}
+
+function readSettings() {
+  if (!fs.existsSync(CLAUDE_SETTINGS_PATH)) return { settings: {}, exists: false };
+  const raw = fs.readFileSync(CLAUDE_SETTINGS_PATH, "utf8").trim();
+  if (!raw) return { settings: {}, exists: true };
+  try {
+    return { settings: JSON.parse(raw), exists: true };
+  } catch {
+    throw new Error(
+      `${CLAUDE_SETTINGS_PATH} exists but isn't valid JSON. Fix or back it up, then re-run.`
+    );
+  }
+}
+
+function writeSettings(settings) {
+  fs.mkdirSync(CLAUDE_DIR, { recursive: true });
+  fs.writeFileSync(CLAUDE_SETTINGS_PATH, JSON.stringify(settings, null, 2) + "\n");
+}
+
+function readUserConfig() {
+  if (!fs.existsSync(CLAUDE_USER_CONFIG_PATH)) return { config: {}, exists: false };
+  const raw = fs.readFileSync(CLAUDE_USER_CONFIG_PATH, "utf8").trim();
+  if (!raw) return { config: {}, exists: true };
+  try {
+    return { config: JSON.parse(raw), exists: true };
+  } catch {
+    throw new Error(
+      `${CLAUDE_USER_CONFIG_PATH} exists but isn't valid JSON. Fix or back it up, then re-run.`
+    );
+  }
+}
+
+function writeUserConfig(config) {
+  fs.writeFileSync(CLAUDE_USER_CONFIG_PATH, JSON.stringify(config, null, 2) + "\n", {
+    mode: 0o600,
+  });
+}
+
+function isImpelMcpServer(value) {
+  if (!value || !Array.isArray(value.args)) return false;
+  const current = impelMcpServer();
+  return (
+    (value.command === current.command &&
+      value.args.length === current.args.length &&
+      value.args.every((argument, index) => argument === current.args[index])) ||
+    (value.type === "stdio" &&
+      value.env?.[IMPEL_MANAGED_MCP_ENV] === "1" &&
+      value.args.at(-1) === "mcp") ||
+    (value.command === LEGACY_IMPEL_MCP_SERVER.command &&
+      value.args.length === 1 &&
+      value.args[0] === "mcp")
+  );
+}
+
+/**
+ * Detects whether Claude Code is currently routed through Impel.
+ * Gateway mode = our apiKeyHelper OR our base URL is present.
+ */
+export function detectClaudeMode(gatewayUrl) {
+  const { settings, exists } = readSettings();
+  const apiKeyHelper = settings.apiKeyHelper;
+  const baseUrl = settings.env?.ANTHROPIC_BASE_URL;
+  const isGateway =
+    isImpelApiKeyHelper(apiKeyHelper) || isImpelClaudeBaseUrl(baseUrl, gatewayUrl);
+  return { mode: isGateway ? "gateway" : "account", exists, apiKeyHelper, baseUrl };
+}
+
+/**
+ * Turns ON gateway mode. Returns the prior values so the caller can back them
+ * up. Merges — every other key in settings.json is left untouched.
+ */
+export function applyClaudeGateway(gatewayUrl) {
+  const { settings } = readSettings();
+  const { config: userConfig } = readUserConfig();
+  const priorMcpServer = userConfig.mcpServers?.[IMPEL_MCP_SERVER_NAME];
+  if (priorMcpServer && !isImpelMcpServer(priorMcpServer)) {
+    throw new Error(
+      `${CLAUDE_USER_CONFIG_PATH} already has an mcpServers.${IMPEL_MCP_SERVER_NAME} entry that wasn't written by impel-cli. Remove or rename it, then re-run.`
+    );
+  }
+
+  const priorApiKeyHelper = settings.apiKeyHelper;
+  const priorBaseUrl = settings.env?.ANTHROPIC_BASE_URL;
+
+  settings.apiKeyHelper = IMPEL_API_KEY_HELPER;
+  settings.env = {
+    ...(settings.env || {}),
+    ANTHROPIC_BASE_URL: impelClaudeBaseUrl(gatewayUrl),
+  };
+
+  writeSettings(settings);
+  userConfig.mcpServers = {
+    ...(userConfig.mcpServers || {}),
+    [IMPEL_MCP_SERVER_NAME]: impelMcpServer(),
+  };
+  writeUserConfig(userConfig);
+
+  return {
+    path: CLAUDE_SETTINGS_PATH,
+    apiKeyHelper: settings.apiKeyHelper,
+    baseUrl: settings.env.ANTHROPIC_BASE_URL,
+    priorApiKeyHelper,
+    priorBaseUrl,
+  };
+}
+
+/**
+ * Turns OFF gateway mode: removes ONLY Impel's apiKeyHelper / base URL (never a
+ * user's own), then restores any backed-up prior values. `backup` may contain
+ * `apiKeyHelper` and/or `ANTHROPIC_BASE_URL` (null = "there was nothing here").
+ */
+export function revertClaudeGateway(gatewayUrl, backup = {}) {
+  const { settings, exists } = readSettings();
+  const { config: userConfig, exists: userConfigExists } = readUserConfig();
+
+  let changed = false;
+  let removedHelper = false;
+  let removedBaseUrl = false;
+  let removedMcpServer = false;
+
+  if (isImpelApiKeyHelper(settings.apiKeyHelper)) {
+    removedHelper = true;
+    if (backup.apiKeyHelper != null) settings.apiKeyHelper = backup.apiKeyHelper;
+    else delete settings.apiKeyHelper;
+    changed = true;
+  }
+
+  const currentBaseUrl = settings.env?.ANTHROPIC_BASE_URL;
+  if (isImpelClaudeBaseUrl(currentBaseUrl, gatewayUrl)) {
+    removedBaseUrl = true;
+    if (backup.ANTHROPIC_BASE_URL != null) {
+      settings.env.ANTHROPIC_BASE_URL = backup.ANTHROPIC_BASE_URL;
+    } else {
+      delete settings.env.ANTHROPIC_BASE_URL;
+      if (settings.env && Object.keys(settings.env).length === 0) delete settings.env;
+    }
+    changed = true;
+  }
+
+  if (changed) writeSettings(settings);
+
+  if (isImpelMcpServer(userConfig.mcpServers?.[IMPEL_MCP_SERVER_NAME])) {
+    removedMcpServer = true;
+    if (backup.mcpServer != null) {
+      userConfig.mcpServers[IMPEL_MCP_SERVER_NAME] = backup.mcpServer;
+    } else {
+      delete userConfig.mcpServers[IMPEL_MCP_SERVER_NAME];
+      if (Object.keys(userConfig.mcpServers).length === 0) {
+        delete userConfig.mcpServers;
+      }
+    }
+    writeUserConfig(userConfig);
+  }
+
+  return {
+    path: CLAUDE_SETTINGS_PATH,
+    exists: exists || userConfigExists,
+    changed: changed || removedMcpServer,
+    removedHelper,
+    removedBaseUrl,
+    removedMcpServer,
+    restoredApiKeyHelper: removedHelper && backup.apiKeyHelper != null ? backup.apiKeyHelper : null,
+    restoredBaseUrl: removedBaseUrl && backup.ANTHROPIC_BASE_URL != null ? backup.ANTHROPIC_BASE_URL : null,
+  };
+}

package/src/cli.js

@@ -0,0 +1,184 @@
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { cmdAuth } from "./commands/auth.js";
+import { cmdToken } from "./commands/token.js";
+import { cmdUse } from "./commands/use.js";
+import { cmdStatus } from "./commands/status.js";
+import { cmdTasks } from "./commands/tasks.js";
+import { cmdApps } from "./commands/apps.js";
+import { cmdMcp } from "./commands/mcp.js";
+import { cmdLaunch } from "./commands/launch.js";
+import { cmdSkills } from "./commands/skills.js";
+import { cmdTenant } from "./commands/tenant.js";
+import { cmdDoctor } from "./commands/doctor.js";
+import { cmdSetup } from "./commands/setup.js";
+import { cmdUpdate } from "./commands/update.js";
+import { cmdExperimental } from "./commands/experimental.js";
+
+const HELP = `impel — the Impel gateway CLI: isolated Claude Code, Codex, and desktop apps
+
+Get started:
+  impel setup                                 Guided end-to-end onboarding: token, tenant,
+                                              platform clients, gateway verification
+                                              (--pat <pat> --tenant <org> --skip-apps/--skip-clis)
+  impel update                                Update everything: the CLI itself, then the
+                                              Impel apps and skills (--check, --skip-apps)
+
+Run:
+  impel claude [args...]                      Launch Claude Code with an isolated Impel profile
+  impel codex [args...]                       Launch Codex with an isolated Impel profile
+  impel app open [claude|chatgpt|codex|all]   Open the isolated Impel desktop app(s)
+  impel status                                Tenant, PAT, per-tool mode, gateway reachability
+  impel doctor [--tenant <org>|--all-tenants] Synthetic provider, routing, and latency checks
+
+Manage:
+  impel auth [--pat <pat>]                    Store your PAT + URLs (--gateway/--app <url>)
+  impel tenant list|current|use <org>         List or select the active organization
+  impel tasks list|get|create|update|delete   CRUD Impel tickets (aliases: task, ticket[s])
+  impel token [--tenant <org>]                Print the selected-tenant bearer
+  impel mcp                                   Run the local Impel MCP stdio bridge
+  impel skills sync [claude|codex|all]        Sync shared skills into managed clients
+
+Desktop apps (macOS and Windows):
+  impel app install [claude|chatgpt|codex|all] Install the isolated Impel desktop app/profile
+  impel app update [claude|chatgpt|codex|all]  Update vendor apps and managed profiles
+  impel app refresh [claude|chatgpt|codex|all] Configs/catalog/skills only; safe while apps run
+  impel app status [claude|chatgpt|codex|all]  Show isolated app and vendor versions
+  impel app uninstall [target] [--keep-data]  Remove only Impel-managed apps/data
+
+Native profile switching (advanced; setup never touches native tools):
+  impel use gateway [claude|codex|all]        Route native Claude Code/Codex through the gateway
+  impel use account [claude|codex|all]        Revert to your own Anthropic/OpenAI login
+  impel on / impel off                        Aliases for the two commands above
+
+  impel help                                  Show this help
+  impel --version                             Show the installed version
+
+Env:
+  IMPEL_GATEWAY_URL   Default gateway URL when --gateway isn't passed.
+  IMPEL_APP_URL       Default app/control-plane URL for setup, auth, and tasks.
+  IMPEL_SKIP_UPDATE_CHECK=1   Silence launch-time update notices.
+
+Config file:
+  ~/.config/impel/config.json (mode 0600)
+`;
+
+function printVersion() {
+  const pkgPath = fileURLToPath(new URL("../package.json", import.meta.url));
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  console.log(pkg.version);
+}
+
+// Accepts "claude" | "codex" | "all" | undefined; returns a normalized target
+// or null if the token isn't a valid target. `codex-cli`/`codex-app` normalize
+// to `codex` (they share the same config file).
+function normalizeTarget(token) {
+  if (token === undefined) return "all";
+  if (["claude", "codex", "all"].includes(token)) return token;
+  if (token === "codex-cli" || token === "codex-app") return "codex";
+  return null;
+}
+
+export async function main(argv) {
+  const [cmd, ...rest] = argv;
+
+  switch (cmd) {
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      console.log(HELP);
+      return;
+
+    case "--version":
+    case "-v":
+      printVersion();
+      return;
+
+    case "auth":
+      return cmdAuth(rest);
+
+    case "token":
+      return cmdToken(rest);
+
+    case "mcp":
+      return cmdMcp(rest);
+
+    case "claude":
+    case "codex":
+      return cmdLaunch(cmd, rest);
+
+    case "status":
+      return cmdStatus();
+
+    case "doctor":
+      return cmdDoctor(rest);
+
+    case "tasks":
+    case "task":
+    case "tickets":
+    case "ticket":
+      return cmdTasks(rest);
+
+    case "tenant":
+    case "tenants":
+    case "org":
+      return cmdTenant(rest);
+
+    case "app":
+    case "apps":
+      return cmdApps(rest);
+
+    case "skills":
+    case "skill":
+      return cmdSkills(rest);
+
+    case "on":
+      return runUse("gateway", rest[0]);
+
+    case "off":
+      return runUse("account", rest[0]);
+
+    case "use": {
+      const [mode, targetToken] = rest;
+      if (mode !== "gateway" && mode !== "account") {
+        console.error(`impel use: expected \`gateway\` or \`account\`, got "${mode ?? ""}".`);
+        console.error("  Try `impel use gateway` (alias `impel on`) or `impel use account` (alias `impel off`).");
+        process.exitCode = 1;
+        return;
+      }
+      return runUse(mode, targetToken);
+    }
+
+    case "setup":
+      // The old per-tool aliases (setup claude|codex-cli|codex-app) flipped
+      // native configs; that swap is no longer part of setup. cmdSetup rejects
+      // positional targets with a pointer to `impel use gateway`.
+      return cmdSetup(rest);
+
+    case "update":
+    case "upgrade":
+      return cmdUpdate(rest);
+
+    // Intentionally omitted from the public help while the contract is gated
+    // server-side and limited to Impel-managed desktop apps.
+    case "experimental":
+      return cmdExperimental(rest);
+
+    default:
+      console.error(`impel: unknown command "${cmd}"\n`);
+      console.log(HELP);
+      process.exitCode = 1;
+  }
+}
+
+function runUse(mode, targetToken) {
+  const target = normalizeTarget(targetToken);
+  if (target === null) {
+    console.error(`impel: unknown target "${targetToken}". Use \`claude\`, \`codex\`, or \`all\`.`);
+    process.exitCode = 1;
+    return;
+  }
+  return cmdUse({ mode, target });
+}

package/src/cliProfiles.js

@@ -0,0 +1,216 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { impelClaudeBaseUrl, impelCrossAppClaudeBaseUrl } from "./claudeSetup.js";
+import { impelCodexBaseUrl } from "./codexSetup.js";
+import {
+  hardenManagedCodexToml,
+  secureAllManagedCodexHomes,
+  secureManagedCodexHome,
+} from "./codexSecurity.js";
+import { CONFIG_DIR } from "./config.js";
+import { normalizeTenantId } from "./tenants.js";
+import { impelCliInvocation, impelMcpInvocation } from "./selfInvocation.js";
+
+export const IMPEL_CLI_PROFILES_DIR = path.join(CONFIG_DIR, "cli");
+
+export function tenantCliProfilePaths(tenantId) {
+  const root = path.join(IMPEL_CLI_PROFILES_DIR, "tenants", normalizeTenantId(tenantId));
+  return {
+    root,
+    claudeConfigDir: path.join(root, "claude"),
+    codexHome: path.join(root, "codex"),
+  };
+}
+
+const CODEX_START_MARK = "# >>> impel-cli isolated profile block >>>";
+const CODEX_END_MARK = "# <<< impel-cli isolated profile block <<<";
+const CODEX_PROVIDER_LINE_RE = /^model_provider[ \t]*=[ \t]*"([^"]*)"[ \t]*$/m;
+const IMPEL_SPECIALIST_CODEX_APPROVAL_TOOLS = [
+  "impel_specialists-list_specialist_runs",
+  "impel_specialists-list_specialists",
+  "impel_specialists-read_specialist_run",
+  "impel_specialists-start_specialist_run",
+];
+
+// API-backed Claude profiles need the Fable family registered explicitly for
+// it to appear in /model. Opus remains the initial selection; later choices
+// made by the user remain authoritative.
+export const IMPEL_DEFAULT_CLAUDE_MODEL = "opus[1m]";
+export const IMPEL_FABLE_MODEL = "claude-fable-5";
+
+function ensurePrivateDirectory(directory) {
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  try {
+    fs.chmodSync(directory, 0o700);
+  } catch {
+    // Best effort on platforms where chmod is unavailable.
+  }
+}
+
+function writePrivateFile(filePath, contents) {
+  ensurePrivateDirectory(path.dirname(filePath));
+  const temporaryPath = `${filePath}.tmp-${process.pid}`;
+  try {
+    fs.writeFileSync(temporaryPath, contents, { mode: 0o600 });
+    fs.renameSync(temporaryPath, filePath);
+    try {
+      fs.chmodSync(filePath, 0o600);
+    } catch {
+      // Best effort on platforms where chmod is unavailable.
+    }
+  } finally {
+    try {
+      fs.rmSync(temporaryPath, { force: true });
+    } catch {
+      // The rename already removed the temporary file in the normal case.
+    }
+  }
+}
+
+function readJsonObject(filePath) {
+  if (!fs.existsSync(filePath)) return {};
+  const raw = fs.readFileSync(filePath, "utf8").trim();
+  if (!raw) return {};
+  try {
+    const value = JSON.parse(raw);
+    if (!value || Array.isArray(value) || typeof value !== "object") throw new Error();
+    return value;
+  } catch {
+    throw new Error(`${filePath} exists but isn't a valid JSON object. Fix or remove it, then re-run.`);
+  }
+}
+
+export function ensureImpelClaudeProfile(gatewayUrl, tenantId, { crossAppModels = false } = {}) {
+  const configDir = tenantCliProfilePaths(tenantId).claudeConfigDir;
+  ensurePrivateDirectory(configDir);
+  const settingsPath = path.join(configDir, "settings.json");
+  const userConfigPath = path.join(configDir, ".claude.json");
+  const settings = readJsonObject(settingsPath);
+  const userConfig = readJsonObject(userConfigPath);
+
+  // The isolated launcher supplies the Impel PAT only to the child process.
+  // Remove older launcher-generated helpers so Claude does not validate the
+  // bearer token as an Anthropic-shaped API key before sending it upstream.
+  if (settings.apiKeyHelper === "impel token") delete settings.apiKeyHelper;
+  if (typeof settings.model !== "string" || !settings.model.trim()) {
+    settings.model = IMPEL_DEFAULT_CLAUDE_MODEL;
+  }
+  const managedEnvironment = {
+    ...(settings.env && typeof settings.env === "object" && !Array.isArray(settings.env)
+      ? settings.env
+      : {}),
+    ANTHROPIC_BASE_URL: crossAppModels
+      ? impelCrossAppClaudeBaseUrl(gatewayUrl)
+      : impelClaudeBaseUrl(gatewayUrl),
+    ANTHROPIC_DEFAULT_FABLE_MODEL: IMPEL_FABLE_MODEL,
+    ANTHROPIC_DEFAULT_FABLE_MODEL_NAME: "Fable",
+    ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION:
+      "Fable 5 · Most capable for your hardest and longest-running tasks",
+  };
+  if (crossAppModels) {
+    // Claude Code 2.1.129+ queries <ANTHROPIC_BASE_URL>/v1/models and adds
+    // gateway-discovered entries to /model. The experimental gateway returns
+    // reversible anthropic.* aliases for GPT IDs because Claude Code filters
+    // discovered IDs that do not begin with "claude" or "anthropic".
+    managedEnvironment.CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY = "1";
+  } else {
+    delete managedEnvironment.CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY;
+  }
+  settings.env = managedEnvironment;
+  userConfig.mcpServers = {
+    ...(userConfig.mcpServers &&
+    typeof userConfig.mcpServers === "object" &&
+    !Array.isArray(userConfig.mcpServers)
+      ? userConfig.mcpServers
+      : {}),
+    impel: impelMcpInvocation(["--tenant", tenantId]),
+  };
+
+  writePrivateFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+  writePrivateFile(userConfigPath, `${JSON.stringify(userConfig, null, 2)}\n`);
+
+  return { configDir, settingsPath, userConfigPath };
+}
+
+function stripCodexManagedBlock(text, configPath) {
+  const start = text.indexOf(CODEX_START_MARK);
+  if (start === -1) return text;
+  const end = text.indexOf(CODEX_END_MARK, start);
+  if (end === -1) {
+    throw new Error(
+      `${configPath} has an incomplete Impel profile block. Fix or remove it, then re-run.`
+    );
+  }
+  return text.slice(0, start) + text.slice(end + CODEX_END_MARK.length);
+}
+
+function splitTomlPreamble(text) {
+  const table = text.match(/^\s*\[/m);
+  if (!table) return { preamble: text, rest: "" };
+  return { preamble: text.slice(0, table.index), rest: text.slice(table.index) };
+}
+
+function codexManagedBlock(gatewayUrl, tenantId) {
+  const auth = impelCliInvocation(["token", "--tenant", tenantId]);
+  const mcp = impelCliInvocation(["mcp", "--tenant", tenantId]);
+  const lines = [
+    CODEX_START_MARK,
+    "# Generated for `impel codex`. Other profile settings outside this block are preserved.",
+    "[model_providers.impel]",
+    'name = "Impel Gateway"',
+    `base_url = ${JSON.stringify(impelCodexBaseUrl(gatewayUrl))}`,
+    'wire_api = "responses"',
+    "",
+    "[model_providers.impel.auth]",
+    `command = ${JSON.stringify(auth.command)}`,
+    `args = [${auth.args.map((argument) => JSON.stringify(argument)).join(", ")}]`,
+    "timeout_ms = 5000",
+    "refresh_interval_ms = 300000",
+    "",
+    "[mcp_servers.impel]",
+    `command = ${JSON.stringify(mcp.command)}`,
+    `args = [${mcp.args.map((argument) => JSON.stringify(argument)).join(", ")}]`,
+    "",
+  ];
+  for (const tool of IMPEL_SPECIALIST_CODEX_APPROVAL_TOOLS) {
+    lines.push(
+      `[mcp_servers.impel.tools.${JSON.stringify(tool)}]`,
+      'approval_mode = "approve"',
+      "",
+    );
+  }
+  lines.push(CODEX_END_MARK);
+  return lines.join("\n");
+}
+
+export function ensureImpelCodexProfile(gatewayUrl, tenantId) {
+  secureAllManagedCodexHomes({ cliRoot: IMPEL_CLI_PROFILES_DIR });
+  const codexHome = tenantCliProfilePaths(tenantId).codexHome;
+  secureManagedCodexHome(codexHome);
+  const configPath = path.join(codexHome, "config.toml");
+  const original = fs.existsSync(configPath) ? fs.readFileSync(configPath, "utf8") : "";
+  const withoutManagedBlock = stripCodexManagedBlock(original, configPath);
+
+  if (/^(\[model_providers\.impel(?:\.|\])|\[mcp_servers\.impel\])/m.test(withoutManagedBlock)) {
+    throw new Error(
+      `${configPath} contains an Impel provider or MCP table outside the managed profile block. ` +
+        "Remove or rename that table, then re-run."
+    );
+  }
+
+  const { preamble, rest } = splitTomlPreamble(withoutManagedBlock);
+  const providerLine = 'model_provider = "impel"';
+  const nextPreamble = CODEX_PROVIDER_LINE_RE.test(preamble)
+    ? preamble.replace(CODEX_PROVIDER_LINE_RE, providerLine)
+    : `${preamble.trimEnd()}${preamble.trim() ? "\n" : ""}${providerLine}\n`;
+  const restText = rest.trim();
+  const next = [nextPreamble.trimEnd(), codexManagedBlock(gatewayUrl, tenantId), restText]
+    .filter(Boolean)
+    .join("\n\n")
+    .concat("\n");
+
+  writePrivateFile(configPath, hardenManagedCodexToml(next, configPath));
+  secureManagedCodexHome(codexHome);
+  return { codexHome, configPath };
+}