impel-cli 0.20.55 → 0.20.57

package/src/commands/doctor.js

@@ -1,11 +1,12 @@
 import { parseFlags } from "../args.js";
-import { loadConfig, normalizeGatewayUrl, resolveDefaultGateway } from "../config.js";
+import { crossAppModelsEnabled, loadConfig, normalizeGatewayUrl, resolveDefaultGateway } from "../config.js";
 import {
   DEFAULT_TTFT_BUDGET_MS,
   DOCTOR_PROVIDERS,
   probeTenant,
   recordSucceeded,
 } from "../doctor.js";
+import { codexCatalogStatus } from "../modelSync.js";
 import {
   assertProviderScopes,
   fetchTenants,
@@ -85,12 +86,43 @@ function doctorGatewayUrl(value) {
   return parsed.origin;
 }
 
+/**
+ * Local, offline staleness of the isolated `impel codex` model catalog
+ * (models.json + models-manifest.json). Reported beside the live gateway
+ * catalog probe so a device stuck on the offline floor or a months-old sync
+ * is visible from the same diagnosis surface that proves the gateway works.
+ */
+function cliModelCatalogReport(tenantId, { gatewayUrl, crossAppModels }) {
+  try {
+    const status = codexCatalogStatus(tenantId, { gatewayUrl, crossAppModels });
+    return {
+      state: status.catalogError ?? (status.source === "floor" ? "floor" : "synced"),
+      syncedAt: status.syncedAt,
+      catalogVersion: status.manifest?.catalogVersion ?? null,
+      fresh: status.fresh,
+      models: status.models.length,
+    };
+  } catch (error) {
+    return { state: "error", error: String(error?.message || error), fresh: false, models: 0 };
+  }
+}
+
+function cliModelCatalogLine(local) {
+  if (local.state === "missing") return "not initialized (run `impel codex` once)";
+  if (local.state === "floor") return "offline floor (never synced; run `impel models sync`)";
+  if (local.state === "synced") {
+    return `gateway sync ${local.syncedAt ?? "unknown"} (${local.fresh ? "fresh" : "stale"}, ${local.models} models)`;
+  }
+  return `${local.state}${local.error ? ` (${local.error})` : ""}`;
+}
+
 function printHuman(report) {
   for (const tenant of report.tenants) {
     console.log(`Tenant:  ${tenant.tenantId}`);
     console.log(`Access:  ${productAccessLabel(tenant.productAccess)}`);
     console.log(`Catalog: ${tenant.catalog.status ?? "network error"} (${tenant.catalog.models} ready models, ${tenant.catalog.durationMs ?? "?"}ms)`);
     if (tenant.catalog.error) console.log(`  ERROR ${tenant.catalog.error}`);
+    if (tenant.cliModelCatalog) console.log(`CLI models: ${cliModelCatalogLine(tenant.cliModelCatalog)}`);
     for (const record of tenant.records) {
       const ok = recordSucceeded(record);
       const latency = record.ttftMs === null ? "TTFT n/a" : `TTFT ${record.ttftMs}ms, total ${record.totalMs}ms`;
@@ -194,7 +226,7 @@ export async function cmdDoctor(argv) {
 
   const tenantReports = [];
   for (const tenant of tenants) {
-    tenantReports.push(await probeTenant({
+    const tenantReport = await probeTenant({
       config: doctorConfig,
       tenantId: tenant.id,
       productAccess: listing.productAccess,
@@ -203,7 +235,13 @@ export async function cmdDoctor(argv) {
       timeoutMs,
       ttftBudgets,
       strictLatency: Boolean(flags["strict-latency"]),
-    }));
+    });
+    // Offline and advisory: catalog staleness never flips the probe verdict.
+    tenantReport.cliModelCatalog = cliModelCatalogReport(tenant.id, {
+      gatewayUrl,
+      crossAppModels: crossAppModelsEnabled(config),
+    });
+    tenantReports.push(tenantReport);
   }
   const report = {
     generatedAt: new Date().toISOString(),

package/src/commands/launch.js

@@ -20,10 +20,11 @@ import {
   saveConfig,
 } from "../config.js";
 import { impelClaudeBaseUrl, impelCrossAppClaudeBaseUrl } from "../claudeSetup.js";
+import { syncCodexModelsSafe } from "../modelSync.js";
 import { parentVerbatimRelayAppendix } from "../verbatimRelay.js";
 import { withGitEnvironment } from "../skills.js";
 import { assertProviderScopes, ensureTenantSelection, tenantCredential } from "../tenants.js";
-import { maybePrintUpdateNotice } from "../updates.js";
+import { installedVersion, maybePrintUpdateNotice } from "../updates.js";
 import { nativeSpawnInvocation } from "../nativeProcess.js";
 import { IMPEL_NATIVE_BENCHMARK_ENV } from "../selfInvocation.js";
 import { resolveReviewedVendorCliBinary } from "../vendorCliBinaries.js";
@@ -392,7 +393,13 @@ async function assertLiveProviderReadiness({ config, gatewayUrl, credential, ten
   if (!readiness.reachable) {
     throw new Error(`could not verify live ${label} availability for tenant "${tenantId}" (${readiness.error || "gateway unreachable"})`);
   }
-  if (readiness.rejected) throw new Error(`gateway credential was rejected (HTTP ${readiness.status})`);
+  if (readiness.rejected) {
+    throw new Error(
+      `gateway credential was rejected (HTTP ${readiness.status}). `
+      + `Your access to tenant "${tenantId}" may have changed; rerun \`${RUNTIME_BRAND.cli.command} setup\` `
+      + "to refresh it, or ask a workspace administrator to confirm your gateway seat.",
+    );
+  }
   if (!readiness.healthy) {
     throw new Error(`could not verify live ${label} availability for tenant "${tenantId}" (${readiness.error || `HTTP ${readiness.status}`})`);
   }
@@ -408,9 +415,13 @@ function runNativeCli(tool, argv, environment) {
   const binary = resolveReviewedVendorCliBinary(tool, environment);
   if (!binary) {
     const version = PINNED_VENDOR_CLI_VERSIONS[tool];
+    const repair = process.platform === "win32"
+      ? `${RUNTIME_BRAND.cli.command}.cmd update`
+      : `${RUNTIME_BRAND.cli.command} update`;
     console.error(
       `impel ${tool}: reviewed ${tool === "claude" ? "Claude Code" : "Codex"} CLI `
-      + `v${version} is not installed. Run \`impel update\` to repair it.`,
+      + `v${version} is not installed (an unreviewed or auto-updated build is not launched `
+      + `against the gateway). Run \`${repair}\` to repair it.`,
     );
     return Promise.resolve(127);
   }
@@ -491,7 +502,7 @@ export async function cmdLaunch(tool, argv) {
   if (RUNTIME_BRAND.cli.packageName === "impel-cli") maybePrintUpdateNotice();
 
   const gatewayUrl = normalizeGatewayUrl(config.gatewayUrl || resolveDefaultGateway());
-  const crossAppModels = tool === "claude" && crossAppModelsEnabled(config);
+  const crossAppModels = crossAppModelsEnabled(config);
   let tenantId;
   try {
     // PAT scopes are immutable. Refresh legacy configs once, then use the
@@ -547,8 +558,15 @@ export async function cmdLaunch(tool, argv) {
     // Impel PATs are bearer tokens, so keep the token process-scoped instead of
     // writing it into Claude's isolated profile.
     environment.ANTHROPIC_AUTH_TOKEN = gatewayCredential;
+    // Version attribution for gateway logs: a 403 in production is currently
+    // impossible to correlate to a CLI/vendor build. Appended so a user's own
+    // custom headers survive.
+    const versionHeader = `X-Impel-Cli-Version: ${RUNTIME_BRAND.cli.packageName}/${installedVersion() || "unknown"}`;
+    environment.ANTHROPIC_CUSTOM_HEADERS = environment.ANTHROPIC_CUSTOM_HEADERS
+      ? `${environment.ANTHROPIC_CUSTOM_HEADERS}\n${versionHeader}`
+      : versionHeader;
   } else if (tool === "codex") {
-    const profile = ensureImpelCodexProfile(gatewayUrl, tenantId);
+    const profile = ensureImpelCodexProfile(gatewayUrl, tenantId, { crossAppModels });
     agentProfile = {
       client: "codex",
       root: profile.codexHome,
@@ -558,6 +576,19 @@ export async function cmdLaunch(tool, argv) {
     deleteEnvironmentKeys(environment, CODEX_DIRECT_AUTH_ENV);
     environment.CODEX_HOME = profile.codexHome;
     environment[CODEX_GATEWAY_TOKEN_ENV] = gatewayCredential;
+    // Launch layering (D13): the synchronous writer above guaranteed a valid
+    // catalog (offline floor, or the intact last sync). Refresh it from the
+    // gateway at most every six hours; a network/catalog failure keeps the
+    // last good file and never blocks this launch. Codex reads
+    // model_catalog_json at startup, so a fresh sync lands next launch.
+    await syncCodexModelsSafe({
+      gatewayUrl,
+      credential: gatewayCredential,
+      tenantId,
+      crossAppModels,
+      staleOnly: true,
+      logger: agentSyncLogger(nativeArgv),
+    });
   } else {
     throw new Error(`unsupported CLI launcher: ${tool}`);
   }

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/commands/update.js

@@ -11,6 +11,10 @@ import { nativeCommandInvocation } from "../nativeProcess.js";
 import { withProgress } from "../progress.js";
 import { runInstallRecovery } from "../installRecovery/engine.js";
 import { reportInstallFailure } from "../autoReport.js";
+import {
+  convergenceSummaryDiagnostics,
+  readRecentConvergenceSummary,
+} from "../convergenceSummary.js";
 import { brandedEnvironmentName, brandedText, RUNTIME_BRAND } from "../runtimeBrand.js";
 import { IMPEL_CLI_ENTRYPOINT } from "../selfInvocation.js";
 import {
@@ -512,12 +516,11 @@ export async function cmdUpdate(argv, overrides = {}) {
     console.error("impel update: tenant convergence failed; rerun `impel update` after addressing the reported issue.");
     // The child is `impel _converge`, which files no report of its own — and
     // this parent only sees its exit status, because the child inherits stdio
-    // so its progress reaches the terminal live. So this report carries what
-    // the parent does know: that it was an update cascade, and which flags
-    // shaped the run it failed under. Which tenants failed is visible on the
-    // user's screen but not in the report; closing that gap needs a channel
-    // between the two processes, which R2 (one report per invocation) says must
-    // not simply be a second report from the child.
+    // so its progress reaches the terminal live. The child does leave a
+    // machine-readable summary on disk, though, so the single report R2
+    // allows can carry which tenants failed and why instead of only the
+    // flags that shaped the run.
+    const summary = (io.readConvergenceSummary || readRecentConvergenceSummary)();
     await reportUpdateFailure({
       scope: "shared",
       platform: io.platform,
@@ -528,6 +531,7 @@ export async function cmdUpdate(argv, overrides = {}) {
         skipApps: String(Boolean(flags["skip-apps"])),
         skipClis: String(Boolean(flags["skip-clis"])),
         cascadedEntrypoint: String(Boolean(cascadeEntrypoint)),
+        ...convergenceSummaryDiagnostics(summary),
       },
     });
     process.exitCode = 1;

package/src/convergenceSummary.js

@@ -0,0 +1,84 @@
+// The `impel update` parent spawns `impel _converge` with inherited stdio and
+// only sees its exit status, and R2 allows one report per invocation — so the
+// auto-filed "Tenant convergence failed" report has carried no tenant detail
+// at all. The child instead leaves a machine-readable summary on disk that the
+// parent folds into the diagnostics of the report it was already filing.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { CONFIG_DIR, redactSecretText } from "./config.js";
+import { renameWithWindowsRetry } from "./windowsFs.js";
+
+export const CONVERGENCE_SUMMARY_PATH = path.join(CONFIG_DIR, "reports", ".last-convergence.json");
+
+// Wide enough to survive install-recovery sessions between the child's write
+// and the parent's read; narrow enough that yesterday's failure never
+// masquerades as today's.
+export const CONVERGENCE_SUMMARY_FRESHNESS_MS = 15 * 60 * 1_000;
+
+const MAX_FAILED_TENANTS = 12;
+const MAX_ERRORS_PER_TENANT = 4;
+const MAX_ERROR_LENGTH = 300;
+
+/** Best-effort: losing the summary only costs report detail, never the run. */
+export function writeConvergenceSummary({ passed, sharedFailure = null, failedTenants = [] }, {
+  summaryPath = CONVERGENCE_SUMMARY_PATH,
+  now = Date.now(),
+} = {}) {
+  try {
+    const summary = {
+      writtenAt: new Date(now).toISOString(),
+      passed: Boolean(passed),
+      sharedFailure: sharedFailure ? redactSecretText(String(sharedFailure)).slice(0, 2_000) : null,
+      failedTenants: failedTenants.slice(0, MAX_FAILED_TENANTS).map((tenant) => ({
+        tenantId: String(tenant.tenantId || "").slice(0, 128),
+        errors: (tenant.errors || [])
+          .slice(0, MAX_ERRORS_PER_TENANT)
+          .map((error) => redactSecretText(String(error)).slice(0, MAX_ERROR_LENGTH)),
+      })),
+    };
+    fs.mkdirSync(path.dirname(summaryPath), { recursive: true, mode: 0o700 });
+    const temporaryPath = `${summaryPath}.tmp-${process.pid}`;
+    fs.writeFileSync(temporaryPath, `${JSON.stringify(summary)}\n`, { mode: 0o600 });
+    renameWithWindowsRetry(temporaryPath, summaryPath);
+  } catch {
+    // Deliberately silent: the summary is diagnostics for a report about a
+    // failure that has already been announced on the user's terminal.
+  }
+}
+
+/** Returns the parsed summary only while it is plausibly from this cascade. */
+export function readRecentConvergenceSummary({
+  summaryPath = CONVERGENCE_SUMMARY_PATH,
+  now = Date.now(),
+} = {}) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(summaryPath, "utf8"));
+    const writtenAt = Date.parse(parsed?.writtenAt || "");
+    if (!Number.isFinite(writtenAt)) return null;
+    if (writtenAt > now + 60_000 || now - writtenAt > CONVERGENCE_SUMMARY_FRESHNESS_MS) return null;
+    if (typeof parsed.passed !== "boolean" || !Array.isArray(parsed.failedTenants)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/** Flatten a summary into the bounded string map the report envelope accepts. */
+export function convergenceSummaryDiagnostics(summary) {
+  if (!summary || summary.passed) return {};
+  const failed = summary.failedTenants.filter((tenant) => tenant?.tenantId);
+  return {
+    ...(summary.sharedFailure ? { sharedFailure: summary.sharedFailure } : {}),
+    ...(failed.length
+      ? {
+        failedTenantIds: failed.map((tenant) => tenant.tenantId).join(","),
+        failedTenantErrors: failed
+          .map((tenant) => `${tenant.tenantId}: ${(tenant.errors || []).join("; ")}`)
+          .join(" | ")
+          .slice(0, 1_800),
+      }
+      : {}),
+  };
+}

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