impel-cli 0.20.56 → 0.20.57

package/src/commands/models.js

@@ -0,0 +1,160 @@
+// `impel models sync|list` — the explicit surface over the CLI Codex model
+// catalog layering (D13). `sync` fetches the tenant's gateway catalog and
+// rewrites the isolated `impel codex` models.json (with provenance in
+// models-manifest.json); `list` is near-free diagnostics over the same files:
+// what the picker will show next launch, where it came from (gateway sync or
+// the offline floor), and how stale it is. Launches never depend on this
+// command — the same sync runs launch-layered, TTL-gated, and from the token
+// heartbeat; this is the direct repair/inspection path.
+
+import { parseFlags } from "../args.js";
+import {
+  crossAppModelsEnabled,
+  loadConfig,
+  normalizeGatewayUrl,
+  redactSecretText,
+  resolveDefaultGateway,
+} from "../config.js";
+import { codexCatalogStatus, syncCodexModels } from "../modelSync.js";
+import { MODEL_SYNC_TTL_MS } from "../modelsManifest.js";
+import { ensureTenantSelection, normalizeTenantId, tenantCredential } from "../tenants.js";
+import { RUNTIME_BRAND } from "../runtimeBrand.js";
+
+const HELP = `impel models - inspect or refresh the isolated Codex model catalog
+
+Usage:
+  impel models list [--tenant <org>] [--json]
+  impel models sync [--tenant <org>] [--stale-only]
+
+list shows the catalog \`impel codex\` will load next launch: each model, and
+whether the file is the last gateway sync (with its age) or the built-in
+offline floor. sync fetches the tenant's live gateway catalog and rewrites the
+catalog atomically; --stale-only exits without fetching while the last sync is
+inside its ${MODEL_SYNC_TTL_MS / (60 * 60 * 1000)}h window. Launches never block on this: they layer the same
+sync after the offline floor write and keep the last good catalog on failure.
+`;
+
+function formatAge(ageMs) {
+  const minutes = Math.floor(ageMs / 60_000);
+  if (minutes < 1) return "just now";
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 48) return `${hours}h ago`;
+  return `${Math.floor(hours / 24)}d ago`;
+}
+
+export function describeCatalogStatus(status) {
+  if (status.catalogError === "missing") {
+    return `not initialized (run \`${RUNTIME_BRAND.cli.command} setup\` or \`${RUNTIME_BRAND.cli.command} codex\` first)`;
+  }
+  if (status.catalogError) return "unreadable (rerun the launcher to regenerate it)";
+  if (status.source === "floor") {
+    return `offline floor (never synced; run \`${RUNTIME_BRAND.cli.command} models sync\`)`;
+  }
+  const age = status.ageMs === null ? "unknown age" : formatAge(status.ageMs);
+  const version = status.manifest?.catalogVersion == null ? "" : `, catalog v${status.manifest.catalogVersion}`;
+  return `gateway sync ${age}${version}, ${status.fresh ? "fresh" : "stale"}`;
+}
+
+export async function cmdModels(argv, overrides = {}) {
+  const [action, ...rest] = argv;
+  if (action === undefined || ["help", "--help", "-h"].includes(action)) {
+    console.log(HELP);
+    return;
+  }
+  if (!["sync", "list"].includes(action)) {
+    console.error(`impel models: unknown action "${action}". Use \`sync\` or \`list\`.`);
+    process.exitCode = 1;
+    return;
+  }
+  const { flags, positionals } = parseFlags(rest, {
+    tenant: { type: "string" },
+    "stale-only": { type: "boolean" },
+    json: { type: "boolean" },
+  });
+  if (positionals.length > 0) {
+    console.error(`impel models: unexpected argument "${positionals[0]}"`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const io = {
+    loadConfig,
+    ensureTenantSelection,
+    syncModels: syncCodexModels,
+    catalogStatus: codexCatalogStatus,
+    log: (message) => console.log(message),
+    ...overrides,
+  };
+  const config = io.loadConfig();
+  if (!config?.pat) {
+    console.error(`impel models: not authenticated. Run \`${RUNTIME_BRAND.cli.command} setup\` (or \`${RUNTIME_BRAND.cli.command} auth\`) first.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const tenantId = flags.tenant
+      ? normalizeTenantId(flags.tenant)
+      : (await io.ensureTenantSelection(config)).tenantId;
+    const gatewayUrl = normalizeGatewayUrl(config.gatewayUrl || resolveDefaultGateway());
+    const crossAppModels = crossAppModelsEnabled(config);
+
+    if (action === "sync") {
+      const result = await io.syncModels({
+        gatewayUrl,
+        credential: tenantCredential(config.pat, tenantId),
+        tenantId,
+        crossAppModels,
+        staleOnly: Boolean(flags["stale-only"]),
+      });
+      if (result.skipped && result.reason === "uninitialized") {
+        console.error(
+          `impel models: the isolated Codex profile for tenant "${tenantId}" is not initialized. `
+          + `Run \`${RUNTIME_BRAND.cli.command} setup\` (or \`${RUNTIME_BRAND.cli.command} codex\`) first.`,
+        );
+        process.exitCode = 1;
+        return;
+      }
+      if (result.skipped) {
+        io.log(`Models: catalog for tenant ${tenantId} is fresh; nothing to sync.`);
+        return;
+      }
+      io.log(
+        `Models: synced ${result.models} model${result.models === 1 ? "" : "s"} for tenant ${tenantId}`
+        + `${result.catalogVersion == null ? "" : ` (catalog v${result.catalogVersion})`}. `
+        + "The picker updates on the next launch.",
+      );
+      return;
+    }
+
+    const status = io.catalogStatus(tenantId, { gatewayUrl, crossAppModels });
+    if (flags.json) {
+      io.log(JSON.stringify({
+        tenantId: status.tenantId,
+        catalogPath: status.catalogPath,
+        source: status.catalogError ? null : status.source,
+        catalogError: status.catalogError,
+        syncedAt: status.syncedAt,
+        catalogVersion: status.manifest?.catalogVersion ?? null,
+        fresh: status.fresh,
+        crossAppModels,
+        models: status.models.map((model) => model.slug),
+      }, null, 2));
+      return;
+    }
+    io.log(`Tenant:  ${tenantId}`);
+    io.log(`Catalog: ${status.catalogPath}`);
+    io.log(`Status:  ${describeCatalogStatus(status)}`);
+    if (crossAppModels) io.log("Experiments: cross-app models enabled");
+    if (status.models.length > 0) {
+      io.log(`Models (${status.models.length}):`);
+      for (const model of status.models) {
+        io.log(`  ${model.slug}${model.display_name && model.display_name !== model.slug ? ` — ${model.display_name}` : ""}`);
+      }
+    }
+  } catch (error) {
+    console.error(`impel models: ${redactSecretText(error?.message || error)}`);
+    process.exitCode = 1;
+  }
+}

package/src/commands/sessions.js

@@ -14,9 +14,17 @@ import {
   sessionOutboxStatus,
   touchSessionFlushLock,
 } from "../sessionCollector.js";
-import { loadConfig, redactSecretText } from "../config.js";
+import {
+  crossAppModelsEnabled,
+  loadConfig,
+  normalizeGatewayUrl,
+  redactSecretText,
+  resolveDefaultGateway,
+} from "../config.js";
+import { tenantCliProfilePaths } from "../cliProfiles.js";
+import { cliCodexCatalogStale } from "../modelSync.js";
 import { impelCliInvocation } from "../selfInvocation.js";
-import { spawnDetachedAppRefresh } from "../updates.js";
+import { spawnDetachedAppRefresh, spawnDetachedModelSync } from "../updates.js";
 import { brandedEnvironmentName, RUNTIME_BRAND } from "../runtimeBrand.js";
 
 const MANAGED_SESSION_HOOK_FLAG = `${RUNTIME_BRAND.cli.command}-managed-session-hook-v1`;
@@ -71,6 +79,45 @@ export function maybeRepairManagedApps(tenantId, {
   return true;
 }
 
+/**
+ * The model-catalog half of the token-helper heartbeat: when the isolated CLI
+ * Codex catalog for this tenant exists but is past its sync TTL (or its
+ * manifest no longer matches the file), kick one detached
+ * `models sync --stale-only`. Same shape as maybeRepairManagedApps — the
+ * vendor apps and Codex's auth command invoke `impel token` every ~5 minutes,
+ * so this is the channel that keeps catalogs converging on machines where
+ * nobody relaunches. The heartbeat lock stops repeated token calls from
+ * stacking sync children while the gateway is unreachable.
+ */
+export function maybeSyncCliModels(tenantId, {
+  config = null,
+  catalogStale = cliCodexCatalogStale,
+  lockIsFresh = sessionFlushLockIsFresh,
+  touchLock = touchSessionFlushLock,
+  spawnModelSync = spawnDetachedModelSync,
+} = {}) {
+  if (!tenantId) return false;
+  let stored = config;
+  if (stored === null) {
+    try {
+      stored = loadConfig();
+    } catch {
+      return false;
+    }
+  }
+  if (!stored?.pat) return false;
+  const gatewayUrl = normalizeGatewayUrl(stored.gatewayUrl || resolveDefaultGateway());
+  if (!catalogStale(tenantId, {
+    gatewayUrl,
+    crossAppModels: crossAppModelsEnabled(stored),
+  })) return false;
+  const lock = path.join(tenantCliProfilePaths(tenantId).codexHome, "models-sync-heartbeat");
+  if (lockIsFresh(lock, 60_000)) return false;
+  touchLock(lock);
+  spawnModelSync(tenantId);
+  return true;
+}
+
 /**
  * The codex session-hook entry point: same repair, scoped to ChatGPT/Codex
  * drift exactly as before the helper was generalized (the codex hook fires on
@@ -127,7 +174,13 @@ export async function cmdSessions(argv) {
         config,
         flush: false,
       });
-      if (flags.provider === "codex") maybeRepairManagedCodexApp(flags.tenant);
+      if (flags.provider === "codex") {
+        maybeRepairManagedCodexApp(flags.tenant);
+        // Same guaranteed-to-run channel, second artifact: keep the isolated
+        // CLI Codex model catalog converging from codex session events too
+        // (TTL + heartbeat-locked, detached `models sync --stale-only`).
+        maybeSyncCliModels(flags.tenant);
+      }
       // The Claude mirror of the codex repair above: Claude Desktop rewrites
       // its co-owned profile files too, and its session hooks are the only
       // Impel code guaranteed to still run afterward.

package/src/commands/setup.js

@@ -344,6 +344,7 @@ export async function cmdSetup(argv, overrides = {}) {
         tenantId: selected.id,
         platform: io.platform,
         skipInstall: true,
+        crossAppModels: config.experimental?.crossAppModels === true,
       });
       let prepared = inspected;
       if (inspected.missingAfter.length && !inspectOnly && !flags["skip-clis"]) {
@@ -376,6 +377,7 @@ export async function cmdSetup(argv, overrides = {}) {
             platform: io.platform,
             skipInstall: false,
             installTools,
+            crossAppModels: config.experimental?.crossAppModels === true,
           });
         }
       }

package/src/commands/token.js

@@ -1,7 +1,7 @@
 import { loadConfig } from "../config.js";
 import { parseFlags } from "../args.js";
 import { ensureTenantSelection, normalizeTenantId, tenantCredential } from "../tenants.js";
-import { maybeRepairManagedApps } from "./sessions.js";
+import { maybeRepairManagedApps, maybeSyncCliModels } from "./sessions.js";
 import { RUNTIME_BRAND } from "../runtimeBrand.js";
 
 // This is the `apiKeyHelper` / auth-command contract: stdout (and only
@@ -12,6 +12,7 @@ export async function cmdToken(argv = [], overrides = {}) {
     loadConfig,
     ensureTenantSelection,
     repairManagedApps: maybeRepairManagedApps,
+    syncCliModels: maybeSyncCliModels,
     ...overrides,
   };
   const { flags } = parseFlags(argv, { tenant: { type: "string" } });
@@ -39,6 +40,15 @@ export async function cmdToken(argv = [], overrides = {}) {
     } catch {
       // Opportunistic only; the token contract is already fulfilled.
     }
+    // Same heartbeat, second surface: Codex invokes this helper every ~5
+    // minutes, so it is also where a stale isolated-CLI model catalog gets
+    // its detached `models sync --stale-only` (D13). Identical contract:
+    // after the token bytes, never stdout, never the exit code.
+    try {
+      io.syncCliModels(tenantId, { config });
+    } catch {
+      // Opportunistic only; the token contract is already fulfilled.
+    }
   } catch (error) {
     process.stderr.write(`${RUNTIME_BRAND.cli.command}: ${error.message}\n`);
     process.exitCode = 1;

package/src/extension/index.js

@@ -12,6 +12,7 @@ const ALIASES = Object.freeze({
   tenants: "tenant",
   org: "tenant",
   skill: "skills",
+  model: "models",
   agent: "agents",
   upgrade: "update",
   on: "use",
@@ -39,6 +40,7 @@ function help(version) {
   if (enabled.has("mcp")) lines.push(`  ${command} mcp                           Run the authenticated MCP transport`);
   if (enabled.has("sessions")) lines.push(`  ${command} sessions ...                  Run managed session lifecycle hooks`);
   if (enabled.has("skills")) lines.push(`  ${command} skills sync [...]             Sync gateway skills into managed clients`);
+  if (enabled.has("models")) lines.push(`  ${command} models list|sync              Inspect or refresh the isolated Codex model catalog`);
   if (enabled.has("agents")) lines.push(`  ${command} agents sync [...]             Sync tenant agents into managed clients`);
   if (enabled.has("status")) lines.push(`  ${command} status                        Show local readiness`);
   if (enabled.has("doctor")) lines.push(`  ${command} doctor [...]                  Run gateway and provider diagnostics`);

package/src/gatewayModels.js

@@ -0,0 +1,58 @@
+// The authenticated tenant model catalog fetch (GET /v1/models), shared by
+// the desktop app writers in apps.js and the CLI catalog sync in
+// modelSync.js. Leaf module (no imports): the model-catalog side of the CLI
+// must be loadable without pulling in the desktop bundle machinery, so this
+// cannot live in apps.js. apps.js re-exports it for existing importers.
+
+function isGatewayModel(model) {
+  return model && typeof model.id === "string" && (model.provider === "claude" || model.provider === "codex");
+}
+
+/**
+ * A tenant whose subscription genuinely has no Claude/Codex seats returns an
+ * explicitly marked empty catalog. Only lifecycle reconciliation may treat
+ * that as valid emptiness (allowEmpty) — every other caller keeps failing
+ * closed so a gateway outage can never masquerade as "no models".
+ */
+function isExplicitNoSeatCatalog(payload) {
+  const statuses = payload?.provider_status;
+  return Boolean(statuses
+    && typeof statuses === "object"
+    && !Array.isArray(statuses)
+    && ["claude", "codex"].every((provider) => (
+      statuses[provider]?.state === "no_seat"
+      && statuses[provider]?.routable === false
+    )));
+}
+
+export async function fetchGatewayModels(config, fetchImpl = fetch, { allowEmpty = false } = {}) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 20000);
+  try {
+    const response = await fetchImpl(`${config.gatewayUrl}/v1/models`, {
+      headers: { authorization: `Bearer ${config.pat}` },
+      signal: controller.signal,
+    });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    const payload = await response.json();
+    if (config.tenantId && payload?.org_id !== config.tenantId) {
+      throw new Error("gateway model catalog tenant did not match the selected tenant");
+    }
+    if (config.productAccess && payload?.product_access !== config.productAccess) {
+      throw new Error("gateway model catalog product access did not match the live entitlement");
+    }
+    if (!Array.isArray(payload?.data)) throw new Error("response has no model data array");
+    // The envelope is additive at schema version 3: overlay-aware gateways
+    // also send entitlement_available and org_defaults beside the filtered
+    // data[], whose per-model default/family_default flags are already
+    // rewritten to the tenant's effective defaults. Clients trust the served
+    // flags as-is and tolerate unknown envelope fields.
+    const models = payload.data.filter(isGatewayModel);
+    if (models.length === 0 && !(allowEmpty && isExplicitNoSeatCatalog(payload))) {
+      throw new Error("gateway returned no supported models");
+    }
+    return { models, source: "gateway", version: payload.version ?? null };
+  } finally {
+    clearTimeout(timeout);
+  }
+}

package/src/macSetup.js

@@ -178,6 +178,7 @@ export async function prepareMacClis({
   skipInstall = false,
   inspectOnly = false,
   installTools = ["claude", "codex"],
+  crossAppModels = false,
 } = {}, dependencies = {}) {
   const io = {
     environment: process.env,
@@ -244,8 +245,8 @@ export async function prepareMacClis({
   const binaries = installAttempted
     ? detectMacClis(io.find, io.environment, io.verify)
     : before;
-  const claudeProfile = io.ensureClaudeProfile(gatewayUrl, tenantId);
-  const codexProfile = io.ensureCodexProfile(gatewayUrl, tenantId);
+  const claudeProfile = io.ensureClaudeProfile(gatewayUrl, tenantId, { crossAppModels });
+  const codexProfile = io.ensureCodexProfile(gatewayUrl, tenantId, { crossAppModels });
   if (binaries.claude) {
     await io.syncSkills({
       client: "claude",

package/src/managedProfileVersion.js

@@ -9,4 +9,9 @@
 // v44 disables the vendor background auto-updater in managed Claude CLI
 // profiles so a session on the reviewed release cannot move the shared
 // launcher past the pin (the Windows drift behind the gateway lockouts).
-export const CURRENT_CONFIG_VERSION = 44;
+// v45 layers `impel models sync` over the isolated CLI Codex catalog: the
+// profile writer keeps a manifest-verified synced catalog instead of always
+// reasserting the FALLBACK_MODELS floor, records provenance in
+// models-manifest.json, and (with cross-app models enabled) routes the CLI
+// provider through the experimental OpenAI-compatible gateway path.
+export const CURRENT_CONFIG_VERSION = 45;

package/src/modelCatalog.js

@@ -4,6 +4,7 @@
 // tenant profiles in cliProfiles.js can consume it without an import cycle —
 // the 0.20.39 regression happened precisely because the CLI carried its own
 // hand-frozen copy of this data.
+import { redactSecretText } from "./config.js";
 import { RUNTIME_BRAND } from "./runtimeBrand.js";
 
 const STANDARD_REASONING_LEVELS = [
@@ -65,6 +66,7 @@ export function codexCatalogEntry(model, index, vendorModel) {
     multi_agent_version: null,
   };
   const entry = vendorModel ? { ...generated, ...vendorModel } : generated;
+  const serviceTiers = Array.isArray(model.service_tiers) ? model.service_tiers : (entry.service_tiers || []);
   return {
     ...entry,
     slug: model.id,
@@ -74,7 +76,16 @@ export function codexCatalogEntry(model, index, vendorModel) {
     supported_reasoning_levels: Array.isArray(model.supported_reasoning_levels)
       ? model.supported_reasoning_levels
       : entry.supported_reasoning_levels,
-    service_tiers: Array.isArray(model.service_tiers) ? model.service_tiers : (entry.service_tiers || []),
+    service_tiers: serviceTiers,
+    // The vendor catalog always pairs the priority ("Fast") service tier with
+    // additional_speed_tiers: ["fast"], and the pinned Codex runtime
+    // serializes both to the renderer. Reconstruct the pair from the final
+    // service tiers (vendor enrichment may still carry its own value) so the
+    // Fast surface matches vendor shape — the impel-apps writer has always
+    // done this and the two projections must not drift (D15).
+    additional_speed_tiers: Array.isArray(vendorModel?.additional_speed_tiers)
+      ? vendorModel.additional_speed_tiers
+      : (serviceTiers.some((tier) => tier?.id === "priority") ? ["fast"] : []),
     visibility: "list",
     supported_in_api: true,
     priority: Number.isInteger(model.priority) ? model.priority : (entry.priority || index + 1),
@@ -86,6 +97,76 @@ export function codexCatalogEntry(model, index, vendorModel) {
   };
 }
 
+/**
+ * Project a gateway Claude model into the Codex picker. Fail-closed: every
+ * capability field must arrive verified in client_capabilities.codex, or the
+ * model is omitted (never guessed). Lives in this leaf (not apps.js) so the
+ * CLI catalog sync and the desktop writers share one projection; apps.js
+ * re-exports it for existing importers.
+ */
+export function foreignClaudeCodexCatalogEntry(model, index) {
+  const capability = model.client_capabilities?.codex;
+  const levels = capability?.supported_reasoning_levels;
+  const tiers = capability?.service_tiers;
+  const modalities = capability?.input_modalities;
+  const valid = capability && typeof capability === "object"
+    && Number.isInteger(capability.context_window) && capability.context_window > 0
+    && Number.isInteger(capability.max_context_window) && capability.max_context_window >= capability.context_window
+    && Array.isArray(levels) && levels.every((level) => (
+      level && typeof level.effort === "string" && typeof level.description === "string"
+    ))
+    && Array.isArray(tiers) && tiers.every((tier) => (
+      tier && typeof tier.id === "string" && typeof tier.name === "string" && typeof tier.description === "string"
+    ))
+    && Array.isArray(modalities) && modalities.every((value) => typeof value === "string")
+    && ["supports_parallel_tool_calls", "supports_reasoning_summaries", "supports_verbosity", "supports_search_tool", "supports_image_detail_original"]
+      .every((key) => typeof capability[key] === "boolean")
+    && (capability.default_reasoning_level == null
+      || capability.default_reasoning_level === ""
+      || levels.some((level) => level.effort === capability.default_reasoning_level))
+    && (capability.apply_patch_tool_type == null || typeof capability.apply_patch_tool_type === "string")
+    && (capability.web_search_tool_type == null || typeof capability.web_search_tool_type === "string");
+  if (!valid) {
+    console.warn(`impel: omitting model ${redactSecretText(model.id)} from Impel ChatGPT: missing verified Codex capabilities`);
+    return null;
+  }
+  return {
+    slug: model.id,
+    display_name: model.display_name || model.id,
+    description: model.description || `Claude model available through the Impel gateway (${model.id}).`,
+    ...(capability.default_reasoning_level ? { default_reasoning_level: capability.default_reasoning_level } : {}),
+    supported_reasoning_levels: levels,
+    service_tiers: tiers,
+    // Same vendor-shape pairing rule as codexCatalogEntry: a priority tier
+    // always travels with the "fast" speed tier.
+    additional_speed_tiers: tiers.some((tier) => tier?.id === "priority") ? ["fast"] : [],
+    shell_type: "shell_command",
+    visibility: "list",
+    supported_in_api: true,
+    priority: Number.isInteger(model.priority) ? model.priority : index + 1,
+    base_instructions: "You are an AI coding agent. Follow repository instructions, collaborate with the user, make scoped changes, and verify your work.",
+    include_skills_usage_instructions: false,
+    supports_reasoning_summaries: capability.supports_reasoning_summaries,
+    support_verbosity: capability.supports_verbosity,
+    ...(capability.supports_reasoning_summaries ? { default_reasoning_summary: "none" } : {}),
+    ...(capability.supports_verbosity ? { default_verbosity: "low" } : {}),
+    ...(capability.apply_patch_tool_type ? { apply_patch_tool_type: capability.apply_patch_tool_type } : {}),
+    ...(capability.web_search_tool_type ? { web_search_tool_type: capability.web_search_tool_type } : {}),
+    truncation_policy: { mode: "tokens", limit: 10000 },
+    context_window: capability.context_window,
+    max_context_window: capability.max_context_window,
+    effective_context_window_percent: 95,
+    experimental_supported_tools: [],
+    input_modalities: modalities,
+    supports_parallel_tool_calls: capability.supports_parallel_tool_calls,
+    supports_image_detail_original: capability.supports_image_detail_original,
+    supports_search_tool: capability.supports_search_tool,
+    use_responses_lite: false,
+    tool_mode: null,
+    multi_agent_version: null,
+  };
+}
+
 /**
  * The managed CLI Codex catalog, projected from the same model registry the
  * desktop app uses so reasoning efforts, service tiers, and tool modes can
@@ -101,3 +182,30 @@ export function managedCodexCliCatalog(now = new Date()) {
       .map((model, index) => codexCatalogEntry(model, index)),
   };
 }
+
+/**
+ * The same catalog document, projected from live gateway models instead of
+ * the FALLBACK_MODELS floor (`impel models sync`). The gateway payload never
+ * flows through: every entry is reconstructed by codexCatalogEntry /
+ * foreignClaudeCodexCatalogEntry from validated fields, exactly like the
+ * desktop writer (D15). Claude models join the picker only when crossAppModels
+ * is enabled AND each carries verified client_capabilities.codex (fail-closed
+ * in the foreign projection). Returns null when nothing projects — an empty
+ * catalog must never replace the floor.
+ */
+export function gatewayCodexCliCatalog(models, { crossAppModels = false, now = new Date() } = {}) {
+  const ordered = crossAppModels
+    ? [...models.filter((model) => model.provider === "codex"), ...models.filter((model) => model.provider === "claude")]
+    : models.filter((model) => model.provider === "codex");
+  const codexModels = ordered
+    .map((model, index) => model.provider === "codex"
+      ? codexCatalogEntry(model, index)
+      : foreignClaudeCodexCatalogEntry(model, index))
+    .filter(Boolean);
+  if (codexModels.length === 0) return null;
+  return {
+    fetched_at: now.toISOString(),
+    client_version: `${RUNTIME_BRAND.cli.command}-managed-2`,
+    models: codexModels,
+  };
+}