@desplega.ai/agent-swarm 2.7.6 → 2.7.7

package/src/pages/version.ts

@@ -35,6 +35,9 @@ export async function snapshotPage(
     passwordHash: page.passwordHash,
     body: page.body,
     needsCredentials: page.needsCredentials,
+    theme: page.theme,
+    themeTokens: page.themeTokens,
+    designVersion: page.designVersion,
   };
 
   return createPageVersion({

package/src/providers/amp-adapter.ts

@@ -45,7 +45,7 @@ import type {
  * default; the image installs exactly this version and the per-task settings
  * set `amp.updates.mode: "disabled"`. Bump it deliberately, with a live run.
  */
-export const AMP_PACKAGE = "@ampcode/cli@0.0.1793363705-g5c9ae5";
+export const AMP_PACKAGE = "@ampcode/cli@0.0.1793450357-gd44904";
 
 /** MCP server name. Amp exposes its tools as `agent_swarm` / `store_progress` (dashes become underscores). */
 const AMP_MCP_SERVER_NAME = "agent-swarm";

package/src/providers/codex-adapter.ts

@@ -2053,6 +2053,7 @@ export async function createInProcessCodexSession(
     const appServerFactory = opts.appServerFactory ?? ((options) => new CodexAppServer(options));
     const client = appServerFactory({
       ...(codexPathOverride ? { codexPath: codexPathOverride } : {}),
+      ...(gateway ? { configOverrides: codexGatewayConfig(gateway) } : {}),
       env,
       onStderr: (line) => {
         if (liveSession) liveSession.emitTransportStderr(line);

package/src/providers/codex-app-server.ts

@@ -26,6 +26,7 @@ export interface CodexAppServerOptions {
   env: Readonly<Record<string, string | undefined>>;
   requestTimeoutMs?: number;
   onStderr?: (line: string) => void;
+  configOverrides?: Readonly<Record<string, CodexConfigValue | undefined>>;
 }
 
 type PendingRequest = {
@@ -53,6 +54,25 @@ export class CodexAppServerRpcError extends Error {
   }
 }
 
+/** `-c key=<TOML value>` pairs, one per top-level key; tables become inline tables. */
+export function configOverrideArgs(
+  overrides: Readonly<Record<string, CodexConfigValue | undefined>> = {},
+): string[] {
+  return Object.entries(overrides).flatMap(([key, value]) =>
+    value === undefined ? [] : ["-c", `${key}=${tomlValue(value)}`],
+  );
+}
+
+function tomlValue(value: CodexConfigValue): string {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) return `[${value.map(tomlValue).join(", ")}]`;
+  const fields = Object.entries(value as Record<string, CodexConfigValue | undefined>).flatMap(
+    ([key, field]) => (field === undefined ? [] : [`${JSON.stringify(key)} = ${tomlValue(field)}`]),
+  );
+  return `{ ${fields.join(", ")} }`;
+}
+
 /** Thin JSONL client for one `codex app-server --listen stdio://` process. */
 export class CodexAppServer {
   private readonly proc: ReturnType<typeof Bun.spawn>;
@@ -79,7 +99,13 @@ export class CodexAppServer {
     this.onStderr = options.onStderr;
 
     const codexPath = options.codexPath ?? resolveCodexPath(options.env.PATH);
-    const command = [codexPath, "app-server", "--listen", "stdio://"];
+    const command = [
+      codexPath,
+      ...configOverrideArgs(options.configOverrides),
+      "app-server",
+      "--listen",
+      "stdio://",
+    ];
 
     const env = Object.fromEntries(
       Object.entries(options.env).filter(

package/src/providers/pi-mono-extension.ts

@@ -8,6 +8,13 @@
 
 import type { ExtensionFactory, McpServerConfig } from "@earendil-works/pi-coding-agent";
 import { buildRatingsFromLlm, fetchRetrievalsForTask, postRatings } from "../be/memory/raters/llm";
+import {
+  advanceIdentityBaselines,
+  contentSha256,
+  PROFILE_FILE_IO,
+  type ProfileFileIO,
+  readIdentityBaselines,
+} from "../commands/profile-sync";
 import { checkToolLoop, clearToolHistory } from "../hooks/tool-loop-detection";
 import { renderGoalReminder } from "../prompts/goal-reminder";
 import { isSessionSummarySkipped } from "../utils/env-flag";
@@ -100,11 +107,16 @@ export async function fetchTaskDetails(
   }
 }
 
-/** Sync identity files (SOUL.md, IDENTITY.md, TOOLS.md) to server */
+/**
+ * Sync identity files (SOUL.md, IDENTITY.md, TOOLS.md) to server. A file whose
+ * hash still equals its baseline was not edited and is skipped, so a stale copy
+ * never overwrites a DB-side edit made during the session.
+ */
 export async function syncIdentityFilesToServer(
   config: SwarmHooksConfig,
   changeSource: "self_edit" | "session_sync" = "session_sync",
   signal?: AbortSignal,
+  io: ProfileFileIO = PROFILE_FILE_IO,
 ): Promise<void> {
   const updates: Record<string, string> = {};
   const paths: Record<string, string> = {
@@ -112,15 +124,14 @@ export async function syncIdentityFilesToServer(
     identityMd: "/workspace/IDENTITY.md",
     toolsMd: "/workspace/TOOLS.md",
   };
+  const baselines = await readIdentityBaselines(io.readFile);
 
   for (const [key, path] of Object.entries(paths)) {
     try {
-      const file = Bun.file(path);
-      if (await file.exists()) {
-        const content = await file.text();
-        if (content.trim() && content.length <= 65536) {
-          updates[key] = content;
-        }
+      const content = await io.readFile(path);
+      if (content === undefined || baselines?.[key] === contentSha256(content)) continue;
+      if (content.trim() && content.length <= 65536) {
+        updates[key] = content;
       }
     } catch {
       /* skip */
@@ -130,28 +141,27 @@ export async function syncIdentityFilesToServer(
   if (Object.keys(updates).length === 0) return;
 
   try {
-    await fetch(`${config.apiUrl}/api/agents/${config.agentId}/profile`, {
+    const resp = await fetch(`${config.apiUrl}/api/agents/${config.agentId}/profile`, {
       method: "PUT",
       headers: apiHeaders(config),
       body: JSON.stringify({ ...updates, changeSource }),
       signal,
     });
+    if (resp.ok) await advanceIdentityBaselines(updates, io);
   } catch {
     /* silently fail */
   }
 }
 
 /** Sync setup script to server */
-async function syncSetupScriptToServer(
+export async function syncSetupScriptToServer(
   config: SwarmHooksConfig,
   changeSource: "self_edit" | "session_sync" = "session_sync",
+  io: ProfileFileIO = PROFILE_FILE_IO,
 ): Promise<void> {
   try {
-    const file = Bun.file("/workspace/start-up.sh");
-    if (!(await file.exists())) return;
-
-    const raw = await file.text();
-    if (!raw.trim()) return;
+    const raw = await io.readFile("/workspace/start-up.sh");
+    if (!raw?.trim()) return;
 
     const markerStart = "# === Agent-managed setup (from DB) ===";
     const markerEnd = "# === End agent-managed setup ===";
@@ -166,12 +176,17 @@ async function syncSetupScriptToServer(
     }
 
     if (!content || content.length > 65536) return;
+    const baselines = await readIdentityBaselines(io.readFile);
+    if (baselines?.setupScript === contentSha256(content)) return;
 
-    await fetch(`${config.apiUrl}/api/agents/${config.agentId}/profile`, {
+    const resp = await fetch(`${config.apiUrl}/api/agents/${config.agentId}/profile`, {
       method: "PUT",
       headers: apiHeaders(config),
       body: JSON.stringify({ setupScript: content, changeSource }),
     });
+    if (resp.ok) {
+      await advanceIdentityBaselines({ setupScript: content }, io);
+    }
   } catch {
     /* silently fail */
   }

package/src/tasks/follow-up-gate.ts

@@ -0,0 +1,318 @@
+import { createLogEntry, getDbClient } from "../be/db";
+import { getScript } from "../be/scripts/db";
+import { runSavedScriptAsAgent } from "../be/scripts/run-saved";
+import type { AgentTask, ScriptRecord } from "../types";
+import {
+  isFollowUpGateScheduleId,
+  parseFollowUpGateScheduleIds,
+} from "../utils/follow-up-gate-schedule-ids";
+import { scrubSecrets } from "../utils/secret-scrubber";
+
+/**
+ * Follow-up gate, shadow mode. When a gated scheduled run's Lead follow-up is
+ * created, a configured verifier script checks the run after commit and the
+ * server records whether the follow-up could have been skipped. Shadow mode
+ * never skips or delays a follow-up.
+ */
+
+export const FOLLOW_UP_GATE_SHADOW_EVENT = "task_follow_up_gate_shadow" as const;
+
+export type FollowUpGateConfig = {
+  mode: "off" | "shadow";
+  scheduleIds: ReadonlySet<string>;
+  verifierScript: string;
+};
+
+export type GateIneligibleReason =
+  | "mode_off"
+  | "not_scheduled"
+  | "schedule_not_gated"
+  | "status_failed"
+  | "follow_up_instructions";
+
+/**
+ * Read the gate config on every call so a `swarm_config` reload applies. Any
+ * mode other than `shadow` reads as `off`, and malformed ids are ignored.
+ */
+export function readFollowUpGateConfig(env: NodeJS.ProcessEnv = process.env): FollowUpGateConfig {
+  const mode = env.FOLLOW_UP_GATE_MODE?.trim().toLowerCase() === "shadow" ? "shadow" : "off";
+  const scheduleIds = new Set(
+    parseFollowUpGateScheduleIds(env.FOLLOW_UP_GATE_SCHEDULE_IDS)
+      .filter(isFollowUpGateScheduleId)
+      .map((id) => id.toLowerCase()),
+  );
+  return { mode, scheduleIds, verifierScript: env.FOLLOW_UP_GATE_VERIFIER_SCRIPT?.trim() ?? "" };
+}
+
+/** Pure decision on whether a follow-up's worker task may be verified. */
+export function classifyFollowUpGate(input: {
+  task: Pick<AgentTask, "scheduleId" | "followUpConfig">;
+  status: "completed" | "failed";
+  config: FollowUpGateConfig;
+}): { eligible: true } | { eligible: false; reason: GateIneligibleReason } {
+  const { task, status, config } = input;
+  if (config.mode === "off") return { eligible: false, reason: "mode_off" };
+  if (!task.scheduleId) return { eligible: false, reason: "not_scheduled" };
+  if (!config.scheduleIds.has(task.scheduleId.toLowerCase())) {
+    return { eligible: false, reason: "schedule_not_gated" };
+  }
+  if (status === "failed") return { eligible: false, reason: "status_failed" };
+  if (task.followUpConfig?.onCompleted?.trim() || task.followUpConfig?.onFailed?.trim()) {
+    return { eligible: false, reason: "follow_up_instructions" };
+  }
+  return { eligible: true };
+}
+
+type VerifierScript = Pick<ScriptRecord, "name" | "version" | "contentHash">;
+
+export type FollowUpGateDeps = {
+  /** Resolve the global verifier script, or null when it does not exist. */
+  getVerifier: (name: string) => Promise<VerifierScript | null>;
+  /** Run the verifier as `agentId` and return its result, or throw. */
+  runVerifier: (
+    script: VerifierScript,
+    input: { taskId: string },
+    agentId: string,
+    signal: AbortSignal,
+  ) => Promise<unknown>;
+};
+
+const FOLLOW_UP_GATE_TIMEOUT_MS = 60_000;
+const FOLLOW_UP_GATE_MAX_IN_FLIGHT = 2;
+const TEXT_LIMIT = 300;
+const MAX_UNVERIFIED = 20;
+
+const defaultDeps: FollowUpGateDeps = {
+  getVerifier: (name) => getScript({ name, scope: "global" }),
+  runVerifier: async (script, input, agentId, signal) => {
+    const output = await runSavedScriptAsAgent({
+      script: script as ScriptRecord,
+      input,
+      agentId,
+      timeoutMs,
+      signal,
+    });
+    if (output.exitCode !== 0 || output.error || output.runtimeError) {
+      throw new Error(
+        output.runtimeError?.message ??
+          output.error ??
+          `script exited with code ${output.exitCode}`,
+      );
+    }
+    return output.result;
+  },
+};
+
+let timeoutMs = FOLLOW_UP_GATE_TIMEOUT_MS;
+let depsForTests: FollowUpGateDeps | null = null;
+let inFlight = 0;
+const pending = new Set<Promise<void>>();
+
+/** Replace the verifier lookup and runner. `null` restores the defaults. */
+export function setFollowUpGateDepsForTests(deps: FollowUpGateDeps | null): void {
+  depsForTests = deps;
+}
+
+/** Override the verifier deadline. `null` restores the 60s default. */
+export function setFollowUpGateTimeoutMsForTests(ms: number | null): void {
+  timeoutMs = ms ?? FOLLOW_UP_GATE_TIMEOUT_MS;
+}
+
+/** Wait until every scheduled shadow hook has written its row. */
+export async function drainFollowUpGateShadowForTest(): Promise<void> {
+  // Hooks run in FIFO order behind the client lock, so once this marker runs,
+  // every earlier hook has started and registered its promise.
+  await new Promise<void>((resolve) => getDbClient().afterCommit(resolve));
+  while (pending.size > 0) await Promise.allSettled([...pending]);
+}
+
+type ShadowArgs = {
+  task: Pick<AgentTask, "id" | "scheduleId" | "followUpConfig">;
+  status: "completed" | "failed";
+  followUpTaskId: string;
+  leadAgentId: string;
+};
+
+type ShadowRecord = {
+  decision: "would_skip" | "would_keep" | "error" | "ineligible";
+  reason: string | null;
+  verdict?: { ok: boolean | null; check: string | null; detail: string; controlsOk: boolean };
+  unverified?: string[];
+  verifier?: VerifierScript | null;
+  latencyMs?: number | null;
+  error?: string;
+};
+
+/**
+ * Record a shadow gate decision for a just-created follow-up. Returns
+ * synchronously: all work, including the row write, runs after commit. With
+ * the gate off or the schedule not gated, nothing is registered.
+ */
+export function scheduleFollowUpGateShadow(args: ShadowArgs): void {
+  const config = readFollowUpGateConfig();
+  const verdict = classifyFollowUpGate({ task: args.task, status: args.status, config });
+  if (
+    !verdict.eligible &&
+    (verdict.reason === "mode_off" ||
+      verdict.reason === "not_scheduled" ||
+      verdict.reason === "schedule_not_gated")
+  ) {
+    return;
+  }
+  const deps = depsForTests ?? defaultDeps;
+  getDbClient().afterCommit(() => {
+    const run = verdict.eligible
+      ? runShadow(args, config, deps)
+      : writeRecord(args, { decision: "ineligible", reason: verdict.reason });
+    pending.add(run);
+    const settle = () => {
+      pending.delete(run);
+    };
+    void run.then(settle, settle);
+  });
+}
+
+async function runShadow(
+  args: ShadowArgs,
+  config: FollowUpGateConfig,
+  deps: FollowUpGateDeps,
+): Promise<void> {
+  if (inFlight >= FOLLOW_UP_GATE_MAX_IN_FLIGHT) {
+    await writeRecord(args, { decision: "error", reason: "concurrency_cap" });
+    return;
+  }
+  inFlight++;
+  try {
+    await writeRecord(args, await verify(args, config, deps));
+  } finally {
+    inFlight--;
+  }
+}
+
+async function verify(
+  args: ShadowArgs,
+  config: FollowUpGateConfig,
+  deps: FollowUpGateDeps,
+): Promise<ShadowRecord> {
+  if (!config.verifierScript) return { decision: "error", reason: "no_verifier" };
+  const started = performance.now();
+  const latency = () => Math.round(performance.now() - started);
+  const controller = new AbortController();
+  const deadlineMs = timeoutMs;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let script: VerifierScript | null = null;
+  let timedOut = false;
+  try {
+    const run = (async () => {
+      script = await deps.getVerifier(config.verifierScript);
+      if (!script) return null;
+      return {
+        result: await deps.runVerifier(
+          script,
+          { taskId: args.task.id },
+          args.leadAgentId,
+          controller.signal,
+        ),
+      };
+    })();
+    // A run that settles after the deadline must not surface as an unhandled rejection.
+    run.catch(() => {});
+    const deadline = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+        reject(new Error(`verifier timed out after ${deadlineMs}ms`));
+      }, deadlineMs);
+    });
+    const outcome = await Promise.race([run, deadline]);
+    const verifier = verifierInfo(script);
+    if (!outcome) {
+      return { decision: "error", reason: "no_verifier", verifier, latencyMs: latency() };
+    }
+    const result = outcome.result;
+    if (!result || typeof result !== "object") {
+      return {
+        decision: "error",
+        reason: "verifier_error",
+        verifier,
+        latencyMs: latency(),
+        error: "verifier result is not an object",
+      };
+    }
+    return { ...mapVerdict(result as Record<string, unknown>), verifier, latencyMs: latency() };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      decision: "error",
+      reason: timedOut ? "timeout" : "verifier_error",
+      verifier: verifierInfo(script),
+      latencyMs: latency(),
+      error: clip(message),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function verifierInfo(script: VerifierScript | null): VerifierScript | null {
+  return script
+    ? { name: script.name, version: script.version, contentHash: script.contentHash }
+    : null;
+}
+
+/** `ok:true` with passing controls is `would_skip`; anything else keeps the follow-up. */
+function mapVerdict(result: Record<string, unknown>): ShadowRecord {
+  const ok = typeof result.ok === "boolean" ? result.ok : null;
+  const controls = result.controls as { ok?: unknown } | null | undefined;
+  const controlsOk = controls?.ok === true;
+  const unverified = Array.isArray(result.unverified)
+    ? result.unverified
+        .filter((name): name is string => typeof name === "string")
+        .slice(0, MAX_UNVERIFIED)
+        .map((name) => name.slice(0, 100))
+    : [];
+  return {
+    decision: ok === true && controlsOk ? "would_skip" : "would_keep",
+    reason: null,
+    verdict: {
+      ok,
+      check: typeof result.check === "string" ? result.check.slice(0, 100) : null,
+      detail: typeof result.detail === "string" ? clip(result.detail) : "",
+      controlsOk,
+    },
+    unverified,
+  };
+}
+
+function clip(text: string): string {
+  return scrubSecrets(text).slice(0, TEXT_LIMIT);
+}
+
+async function writeRecord(args: ShadowArgs, record: ShadowRecord): Promise<void> {
+  try {
+    await createLogEntry({
+      eventType: FOLLOW_UP_GATE_SHADOW_EVENT,
+      taskId: args.task.id,
+      agentId: args.leadAgentId,
+      metadata: {
+        v: 1,
+        mode: "shadow",
+        followUpTaskId: args.followUpTaskId,
+        scheduleId: args.task.scheduleId ?? null,
+        status: args.status,
+        decision: record.decision,
+        reason: record.reason,
+        verdict: record.verdict ?? null,
+        unverified: record.unverified ?? [],
+        verifier: record.verifier ?? null,
+        latencyMs: record.latencyMs ?? null,
+        ...(record.error ? { error: record.error } : {}),
+      },
+    });
+  } catch (err) {
+    console.warn(
+      `[follow-up-gate] Could not record shadow decision for task ${args.task.id.slice(0, 8)}:`,
+      scrubSecrets(err instanceof Error ? err.message : String(err)),
+    );
+  }
+}

package/src/tasks/worker-follow-up.ts

@@ -34,6 +34,7 @@ import {
 import { isEnvFlagEnabled } from "../utils/env-flag";
 import { taskAttachmentDisplayUrl } from "../utils/task-attachment-links";
 import { chatThreadOfContextKey } from "./context-key";
+import { scheduleFollowUpGateShadow } from "./follow-up-gate";
 import { taskModelPin } from "./model-pin";
 import { createTaskWithSiblingAwareness } from "./sibling-awareness";
 // Side-effect import: registers task lifecycle templates in the in-memory registry.
@@ -261,6 +262,9 @@ async function findDeferredWakeFor(taskId: string, agentId: string): Promise<Def
  * `all` wait with siblings still pending wakes nobody, so the follow-up stays.
  * A `followUpConfig.onCompleted` / `onFailed` instruction for this status also
  * keeps the follow-up, because the wake-up task does not carry that text.
+ *
+ * With `FOLLOW_UP_GATE_MODE=shadow`, a gated scheduled run also records a
+ * verifier's would-skip decision after commit; the follow-up is never skipped.
  */
 export async function createWorkerTaskFollowUp(args: {
   task: AgentTask;
@@ -392,7 +396,7 @@ export async function createWorkerTaskFollowUp(args: {
     );
     return null;
   }
-  return await createTaskWithSiblingAwareness(
+  const followUp = await createTaskWithSiblingAwareness(
     changes.description ?? followUpDescription,
     {
       agentId: followUpAgentId,
@@ -413,6 +417,22 @@ export async function createWorkerTaskFollowUp(args: {
     },
     { origin: "followUp" },
   );
+  if (followUp) {
+    try {
+      scheduleFollowUpGateShadow({
+        task,
+        status,
+        followUpTaskId: followUp.id,
+        leadAgentId: leadAgent.id,
+      });
+    } catch (err) {
+      console.warn(
+        `[worker-follow-up] Follow-up gate shadow failed for task ${task.id.slice(0, 8)}:`,
+        err instanceof Error ? err.message : String(err),
+      );
+    }
+  }
+  return followUp;
 }
 
 /** Hop cap for `deferredWorkChatContextKey`; a defer/resume chain is short. */

package/src/tests/codex-app-server.test.ts

@@ -1,4 +1,6 @@
 import { describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
   CodexAppServer,
@@ -205,4 +207,61 @@ describe("CodexAppServer", () => {
     },
     CHILD_PROCESS_TEST_BUDGET_MS,
   );
+
+  for (const { name, launchOnGateway } of [
+    {
+      name: "pinned Codex rejects a gateway turn on an app-server launched without it",
+      launchOnGateway: false,
+    },
+    {
+      name: "pinned Codex accepts a gateway turn on an app-server launched on the gateway",
+      launchOnGateway: true,
+    },
+  ]) {
+    test(
+      name,
+      async () => {
+        const gateway = {
+          model_provider: "swarm-gateway",
+          model_providers: {
+            "swarm-gateway": {
+              name: "Swarm gateway",
+              base_url: "http://127.0.0.1:9/v1",
+              env_key: "CODEX_GATEWAY_API_KEY",
+              wire_api: "responses",
+              requires_openai_auth: false,
+            },
+          },
+        };
+        const home = await mkdtemp(join(tmpdir(), "codex-app-server-provider-"));
+        const server = new CodexAppServer({
+          codexPath: join(import.meta.dir, "..", "..", "node_modules", ".bin", "codex"),
+          env: fixtureEnv({ HOME: home, CODEX_HOME: home, CODEX_GATEWAY_API_KEY: "example" }),
+          ...(launchOnGateway ? { configOverrides: gateway } : {}),
+        });
+        try {
+          const started = await server.request<{ thread: { id: string } }>("thread/start", {
+            cwd: home,
+            approvalPolicy: "never",
+            sandbox: "danger-full-access",
+            config: gateway,
+            ephemeral: true,
+          });
+          const turn = server.request("turn/start", {
+            threadId: started.thread.id,
+            input: [{ type: "text", text: "hi" }],
+          });
+          if (launchOnGateway) await turn;
+          else
+            await expect(turn).rejects.toThrow(
+              "This chat uses swarm-gateway, but your current provider is openai",
+            );
+        } finally {
+          await server.close();
+          await rm(home, { recursive: true, force: true });
+        }
+      },
+      CHILD_PROCESS_TEST_BUDGET_MS,
+    );
+  }
 });

package/src/tests/codex-gateway-route.test.ts

@@ -4,7 +4,10 @@
  * selection in the adapter, the presence gate, and the live check.
  */
 
-import { afterEach, describe, expect, spyOn, test } from "bun:test";
+import { afterAll, afterEach, beforeAll, describe, expect, spyOn, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { validateProviderCredentials } from "../commands/provider-credentials";
 import { CodexAdapter, checkCodexCredentials } from "../providers/codex-adapter";
 import type { ProviderSessionConfig } from "../providers/types";
@@ -75,6 +78,22 @@ afterEach(() => {
   globalThis.fetch = realFetch;
 });
 
+// The adapter reads `process.env.HOME` live (see `codexUserHome`) to decide
+// whether `~/.codex/auth.json` exists. A developer's real codex login would
+// make OAuth win over OPENAI_API_KEY and fail the API-key assertions, so run
+// the file against an empty home. The real auth.json is never touched.
+const realHome = process.env.HOME;
+let isolatedHome: string | undefined;
+beforeAll(() => {
+  isolatedHome = mkdtempSync(join(tmpdir(), "codex-gateway-route-home-"));
+  process.env.HOME = isolatedHome;
+});
+afterAll(() => {
+  if (realHome === undefined) delete process.env.HOME;
+  else process.env.HOME = realHome;
+  if (isolatedHome) rmSync(isolatedHome, { recursive: true, force: true });
+});
+
 describe("codex gateway route: adapter", () => {
   test("adds a Responses provider block and keeps OAuth and OPENAI_API_KEY out of the CLI env", async () => {
     const log = spyOn(console, "log");
@@ -103,6 +122,36 @@ describe("codex gateway route: adapter", () => {
     expect(logged.some((line) => line.endsWith("Using credential: gateway"))).toBe(true);
   });
 
+  test("launches the app-server on the gateway provider, and on the default without a gateway", async () => {
+    const launched = async (env: Record<string, string>) => {
+      let overrides: unknown = "not launched";
+      const adapter = new CodexAdapter({
+        bypassSubprocess: true,
+        appServerFactory: ({ configOverrides }) => {
+          overrides = configOverrides;
+          throw new Error("test stops before app-server spawn");
+        },
+      });
+      await expect(adapter.createSession(testConfig({ env }))).rejects.toThrow(
+        "test stops before app-server spawn",
+      );
+      return overrides;
+    };
+    expect(await launched({ ...GATEWAY_ENV, OPENAI_API_KEY: "sk-openai" })).toEqual({
+      model_provider: "swarm-gateway",
+      model_providers: {
+        "swarm-gateway": {
+          name: "Swarm gateway",
+          base_url: "https://sub2api.example.com/v1",
+          env_key: "CODEX_GATEWAY_API_KEY",
+          wire_api: "responses",
+          requires_openai_auth: false,
+        },
+      },
+    });
+    expect(await launched({ OPENAI_API_KEY: "sk-openai" })).toBeUndefined();
+  });
+
   test("a gateway URL on api.openai.com is not a gateway: no provider block", async () => {
     const { codexConfig, env } = await captureSpawn({
       CODEX_GATEWAY_BASE_URL: "https://api.openai.com/v1",