@desplega.ai/agent-swarm 1.165.0 → 1.167.0

package/src/tests/claude-hook-output.test.ts

@@ -0,0 +1,233 @@
+/**
+ * Claude Code hook stdout contract.
+ *
+ * Claude Code parses hook stdout as JSON only when the whole stdout is one
+ * JSON object. A plain status line before a block made the block land as
+ * text, and the tool call ran anyway. Plain stdout on PreToolUse/PostToolUse
+ * never reaches the model, so nudges on those events must be JSON
+ * `additionalContext`.
+ *
+ * Each test runs the real hook as a subprocess against a fake API.
+ */
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import pkg from "../../package.json";
+import { CHILD_PROCESS_TEST_BUDGET_MS, runChild } from "./test-proc";
+
+const SERVER_NAME = pkg.config?.name ?? "agent-swarm";
+const HOOK_PATH = join(import.meta.dir, "..", "hooks", "hook.ts");
+
+type FakeState = {
+  isLead: boolean;
+  cancelledTaskId: string | null;
+  shouldBlockPolling: boolean;
+};
+
+const state: FakeState = { isLead: false, cancelledTaskId: null, shouldBlockPolling: false };
+let server: ReturnType<typeof Bun.serve>;
+let projectDir: string;
+
+beforeAll(async () => {
+  server = Bun.serve({
+    port: 0,
+    fetch(req) {
+      const url = new URL(req.url);
+      if (url.pathname === "/me") {
+        return Response.json({
+          id: "00000000-0000-4000-8000-000000000001",
+          name: "probe",
+          isLead: state.isLead,
+          status: "busy",
+          shouldBlockPolling: state.shouldBlockPolling,
+          inbox: {
+            unreadCount: 2,
+            mentionsCount: 0,
+            offeredTasksCount: 1,
+            poolTasksCount: 0,
+            inProgressCount: 1,
+            recentMentions: [],
+          },
+        });
+      }
+      if (url.pathname === "/cancelled-tasks") {
+        const cancelled = state.cancelledTaskId
+          ? [{ id: state.cancelledTaskId, task: "t", failureReason: "stop now" }]
+          : [];
+        return Response.json({ cancelled });
+      }
+      return Response.json({ ok: true });
+    },
+  });
+  projectDir = await mkdtemp(join(tmpdir(), "claude-hook-output-"));
+  await Bun.write(
+    join(projectDir, ".mcp.json"),
+    JSON.stringify({
+      mcpServers: {
+        [SERVER_NAME]: {
+          url: `http://127.0.0.1:${server.port}/mcp`,
+          headers: {
+            Authorization: "Bearer test",
+            "X-Agent-ID": "00000000-0000-4000-8000-000000000001",
+          },
+        },
+      },
+    }),
+  );
+});
+
+afterAll(async () => {
+  server.stop(true);
+  await rm(projectDir, { recursive: true, force: true });
+});
+
+async function runHook(event: Record<string, unknown>, taskId: string) {
+  const taskFile = join(projectDir, `task-${taskId}.json`);
+  await Bun.write(
+    taskFile,
+    JSON.stringify({ taskId, agentId: "a", startedAt: new Date().toISOString() }),
+  );
+  const env: Record<string, string | undefined> = {
+    ...process.env,
+    CLAUDE_PROJECT_DIR: projectDir,
+    TASK_FILE: taskFile,
+  };
+  return runChild(["bun", HOOK_PATH], {
+    cwd: projectDir,
+    env,
+    stdin: JSON.stringify({ cwd: projectDir, ...event }),
+  });
+}
+
+/** Assert stdout is exactly one JSON object and return it. */
+function parseSoleJson(stdout: string): Record<string, unknown> {
+  const trimmed = stdout.trim();
+  expect(trimmed.split("\n")).toHaveLength(1);
+  return JSON.parse(trimmed) as Record<string, unknown>;
+}
+
+const bashTouch = {
+  tool_name: "Bash",
+  tool_input: { command: "touch /tmp/probe" },
+};
+
+describe("claude hook stdout", () => {
+  test(
+    "blocked PreToolUse prints exactly one deny JSON object",
+    async () => {
+      const taskId = crypto.randomUUID();
+      Object.assign(state, { isLead: false, cancelledTaskId: taskId, shouldBlockPolling: false });
+      const result = await runHook({ hook_event_name: "PreToolUse", ...bashTouch }, taskId);
+      expect(result.exitCode).toBe(0);
+      const out = parseSoleJson(result.stdout) as {
+        hookSpecificOutput: Record<string, string>;
+      };
+      expect(out.hookSpecificOutput.hookEventName).toBe("PreToolUse");
+      expect(out.hookSpecificOutput.permissionDecision).toBe("deny");
+      expect(out.hookSpecificOutput.permissionDecisionReason).toContain("TASK CANCELLED");
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "blocked UserPromptSubmit prints only the block JSON, no status line",
+    async () => {
+      const taskId = crypto.randomUUID();
+      Object.assign(state, { isLead: false, cancelledTaskId: taskId, shouldBlockPolling: false });
+      const result = await runHook({ hook_event_name: "UserPromptSubmit", prompt: "go" }, taskId);
+      expect(result.exitCode).toBe(0);
+      const out = parseSoleJson(result.stdout);
+      expect(out.decision).toBe("block");
+      expect(String(out.reason)).toContain("TASK CANCELLED");
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "UserPromptSubmit without a block still prints the status line and tray",
+    async () => {
+      Object.assign(state, { isLead: false, cancelledTaskId: null, shouldBlockPolling: false });
+      const result = await runHook(
+        { hook_event_name: "UserPromptSubmit", prompt: "go" },
+        crypto.randomUUID(),
+      );
+      expect(result.stdout).toContain('You are registered as worker agent "probe"');
+      expect(result.stdout).toContain("📬 2 unread");
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "unblocked PreToolUse prints nothing on stdout",
+    async () => {
+      Object.assign(state, { isLead: false, cancelledTaskId: null, shouldBlockPolling: false });
+      const result = await runHook(
+        { hook_event_name: "PreToolUse", ...bashTouch },
+        crypto.randomUUID(),
+      );
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout.trim()).toBe("");
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "polling limit blocks poll-task with one deny JSON object",
+    async () => {
+      Object.assign(state, { isLead: true, cancelledTaskId: null, shouldBlockPolling: true });
+      const result = await runHook(
+        { hook_event_name: "PreToolUse", tool_name: "mcp__agent-swarm__poll-task", tool_input: {} },
+        crypto.randomUUID(),
+      );
+      const out = parseSoleJson(result.stdout) as {
+        hookSpecificOutput: Record<string, string>;
+      };
+      expect(out.hookSpecificOutput.permissionDecision).toBe("deny");
+      expect(out.hookSpecificOutput.permissionDecisionReason).toContain("POLLING LIMIT");
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "loop warning reaches the model as PreToolUse additionalContext",
+    async () => {
+      Object.assign(state, { isLead: false, cancelledTaskId: null, shouldBlockPolling: false });
+      const taskId = crypto.randomUUID();
+      let stdout = "";
+      try {
+        for (let i = 0; i < 14 && stdout.trim() === ""; i++) {
+          stdout = (await runHook({ hook_event_name: "PreToolUse", ...bashTouch }, taskId)).stdout;
+        }
+      } finally {
+        await rm(`/tmp/agent-swarm-tool-history/${taskId}.json`, { force: true });
+      }
+      const out = parseSoleJson(stdout) as { hookSpecificOutput: Record<string, string> };
+      expect(out.hookSpecificOutput.hookEventName).toBe("PreToolUse");
+      expect(out.hookSpecificOutput.additionalContext).toStartWith("Warning: ");
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS * 3,
+  );
+
+  test(
+    "lead send-task reminder reaches the model as PostToolUse additionalContext",
+    async () => {
+      Object.assign(state, { isLead: true, cancelledTaskId: null, shouldBlockPolling: false });
+      const result = await runHook(
+        {
+          hook_event_name: "PostToolUse",
+          tool_name: "mcp__agent-swarm__send-task",
+          tool_input: {},
+          tool_response: { task: { id: "task-123" } },
+        },
+        crypto.randomUUID(),
+      );
+      const out = parseSoleJson(result.stdout) as {
+        hookSpecificOutput: Record<string, string>;
+      };
+      expect(out.hookSpecificOutput.hookEventName).toBe("PostToolUse");
+      expect(out.hookSpecificOutput.additionalContext).toContain("Task ID: task-123.");
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+});

package/src/tests/claude-sdk-process.fixture.ts

@@ -1,3 +1,5 @@
+import { rename } from "node:fs/promises";
+
 const mode = process.env.CLAUDE_SDK_FIXTURE_MODE;
 const stateFile = process.env.CLAUDE_SDK_FIXTURE_STATE_FILE;
 const sessionId = "11111111-1111-4111-8111-111111111111";
@@ -13,6 +15,15 @@ if (!mode || !stateFile) {
   process.exit(2);
 }
 
+// The test polls for the state file and parses it as soon as it exists.
+// Bun.write creates the file before filling it, so write-then-rename keeps
+// the reader from ever seeing an empty file.
+async function writeStateFile(path: string, state: Record<string, unknown>): Promise<void> {
+  const temporaryPath = `${path}.tmp`;
+  await Bun.write(temporaryPath, JSON.stringify(state));
+  await rename(temporaryPath, path);
+}
+
 function writeMessage(message: Record<string, unknown>): void {
   console.log(JSON.stringify(message));
 }
@@ -145,7 +156,7 @@ if (mode === "cancel") {
     stdout: "ignore",
     stderr: "ignore",
   });
-  await Bun.write(stateFile, JSON.stringify({ fixturePid: process.pid, childPid: child.pid }));
+  await writeStateFile(stateFile, { fixturePid: process.pid, childPid: child.pid });
 }
 
 async function handleLine(line: string): Promise<boolean> {
@@ -191,7 +202,7 @@ async function handleLine(line: string): Promise<boolean> {
   }
 
   if (mode !== "queue" || userMessages.length < 3) return false;
-  await Bun.write(stateFile, JSON.stringify({ argv, userMessages }));
+  await writeStateFile(stateFile, { argv, userMessages });
   for (let index = 0; index < userMessages.length; index++) {
     const turn = index + 1;
     writeMessage(assistantMessage(`accepted:${userMessages[index]}`, turn));

package/src/tests/codex-adapter-pool-auth-revalidate.test.ts

@@ -34,6 +34,7 @@
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "bun:test";
 import { unlink } from "node:fs/promises";
 import { createServer, type Server } from "node:http";
+import { join } from "node:path";
 import { closeDb, initDb } from "../be/db";
 import { handleOAuthLocks } from "../http/oauth-locks";
 import { resolveCodexAuthMode } from "../providers/codex-adapter.js";
@@ -45,6 +46,7 @@ const TEST_DB_PATH = "./test-codex-adapter-pool-auth-revalidate.sqlite";
 const MOCK_API_URL = "http://localhost:3013";
 const MOCK_API_KEY = "example-test-api-key";
 const FAKE_HOME = "/home/fake-pool-worker";
+const FAKE_AUTH_PATH = join(FAKE_HOME, ".codex", "auth.json");
 
 process.env.SECRETS_ENCRYPTION_KEY = Buffer.alloc(32, 4).toString("base64");
 
@@ -106,14 +108,14 @@ function fakeAuthJsonFs(initialContent: string) {
   let file: string | null = initialContent;
   const fs = {
     readFile: async (path: string): Promise<string> => {
-      if (path !== `${FAKE_HOME}/.codex/auth.json` || file === null) {
+      if (path !== FAKE_AUTH_PATH || file === null) {
         throw new Error("ENOENT");
       }
       return file;
     },
     mkdir: async (): Promise<undefined> => undefined,
     writeFile: async (path: string, data: string): Promise<void> => {
-      expect(path).toBe(`${FAKE_HOME}/.codex/auth.json`);
+      expect(path).toBe(FAKE_AUTH_PATH);
       file = data;
     },
   };

package/src/tests/codex-adapter.test.ts

@@ -167,6 +167,66 @@ function makeFakeAppServer(
   };
 }
 
+// Cost JSON (minus durationMs) the pre-split adapter (origin/main 97deb6c6)
+// produced for the notification sequence in the "unchanged by the context
+// split" test.
+const PRE_SPLIT_COST_JSON =
+  '{"sessionId":"","taskId":"","agentId":"agent-test","totalCostUsd":0.3675,"inputTokens":390000,"outputTokens":7500,"reasoningOutputTokens":1900,"cacheReadTokens":320000,"cacheWriteTokens":3000,"numTurns":2,"model":"gpt-5.4","isError":false,"provider":"codex"}';
+
+type AppServerTokenUsage = {
+  total: Record<string, number>;
+  last?: Record<string, number>;
+  modelContextWindow?: number | null;
+};
+
+function breakdown(input: number, cached: number, output: number, reasoning = 0, cacheWrite = 0) {
+  return {
+    inputTokens: input,
+    cachedInputTokens: cached,
+    cacheWriteInputTokens: cacheWrite,
+    outputTokens: output,
+    reasoningOutputTokens: reasoning,
+    totalTokens: input + output,
+  };
+}
+
+/**
+ * Run an app-server session where each turn sends one
+ * `thread/tokenUsage/updated` notification per model request. The first turn
+ * is the initial prompt; later turns are queued follow-ups.
+ */
+async function runAppServerTurns(
+  turns: AppServerTokenUsage[][],
+): Promise<{ emitted: ProviderEvent[]; result: ProviderResult }> {
+  const threadId = "thread-token-usage";
+  let turnNumber = 0;
+  const fake = makeFakeAppServer((method, _params, emit) => {
+    if (method === "thread/start") return { thread: { id: threadId } };
+    if (method !== "turn/start") throw new Error(`Unexpected method: ${method}`);
+    const turnId = `turn-${++turnNumber}`;
+    const updates = turns[turnNumber - 1] ?? [];
+    queueMicrotask(() => {
+      emit("turn/started", { threadId, turn: { id: turnId, status: "inProgress" } });
+      for (const tokenUsage of updates) {
+        emit("thread/tokenUsage/updated", { threadId, turnId, tokenUsage });
+      }
+      emit("turn/completed", { threadId, turn: { id: turnId, status: "completed", error: null } });
+    });
+    return { turn: { id: turnId } };
+  });
+  const session = await new CodexAdapter({
+    bypassSubprocess: true,
+    appServerFactory: () => fake.client as never,
+  }).createSession(testConfig({ taskId: "", apiUrl: "", apiKey: "" }));
+  const emitted: ProviderEvent[] = [];
+  session.onEvent((event) => emitted.push(event));
+  for (let i = 1; i < turns.length; i++) {
+    await session.deliverSteering?.({ mode: "queue", text: `follow-up ${i}` });
+  }
+  const result = await session.waitForCompletion();
+  return { emitted, result };
+}
+
 /**
  * Because `CodexSession` is not exported, we load the module source and
  * instantiate it via `eval` of a small helper module. This is brittle but
@@ -431,6 +491,88 @@ describe("Codex app-server session", () => {
     ).toMatchObject({ toolName: "Write" });
   });
 
+  test("context follows the latest request, not the turn's summed usage", async () => {
+    // Two requests in one turn. The cumulative total (1.3M input) exceeds the
+    // 1.05M gpt-5.4 window; neither single request does.
+    const { emitted } = await runAppServerTurns([
+      [
+        {
+          total: breakdown(600_000, 500_000, 1_000),
+          last: breakdown(600_000, 500_000, 1_000),
+        },
+        {
+          total: breakdown(1_300_000, 1_100_000, 3_000),
+          last: breakdown(700_000, 600_000, 2_000),
+        },
+      ],
+    ]);
+
+    const snapshots = emitted.filter((event) => event.type === "context_usage");
+    expect(snapshots.map((event) => event.contextUsedTokens)).toEqual([601_000, 702_000]);
+    for (const snapshot of snapshots) {
+      expect(snapshot.contextUsedTokens).toBeLessThanOrEqual(702_000);
+      expect(snapshot.contextTotalTokens).toBe(1_050_000);
+      expect(snapshot.contextPercent).toBeLessThan(100);
+      expect(snapshot.contextFormula).toBe("input-cache-output");
+    }
+    expect(snapshots.at(-1)?.contextPercent).toBeCloseTo((702_000 / 1_050_000) * 100, 6);
+  });
+
+  test("per-turn cost and usage totals are unchanged by the context split", async () => {
+    // `last` and `modelContextWindow` must not move cost or usage totals.
+    const { result } = await runAppServerTurns([
+      [
+        {
+          total: breakdown(120_000, 90_000, 2_000, 500, 1_000),
+          last: breakdown(120_000, 90_000, 2_000, 500, 1_000),
+          modelContextWindow: 258_400,
+        },
+        {
+          total: breakdown(250_000, 200_000, 5_000, 1_200, 2_500),
+          last: breakdown(130_000, 110_000, 3_000, 700, 1_500),
+          modelContextWindow: 258_400,
+        },
+      ],
+      [
+        {
+          total: breakdown(390_000, 320_000, 7_500, 1_900, 3_000),
+          last: breakdown(140_000, 120_000, 2_500, 700, 500),
+          modelContextWindow: 258_400,
+        },
+      ],
+    ]);
+
+    const { durationMs: _durationMs, ...cost } = result.cost ?? ({} as Record<string, unknown>);
+    expect(JSON.stringify(cost)).toBe(PRE_SPLIT_COST_JSON);
+  });
+
+  test("modelContextWindow from the app-server wins over the models.dev fallback", async () => {
+    const { emitted } = await runAppServerTurns([
+      [
+        {
+          total: breakdown(50_000, 40_000, 1_000),
+          last: breakdown(50_000, 40_000, 1_000),
+          modelContextWindow: 258_400,
+        },
+        {
+          total: breakdown(110_000, 90_000, 2_000),
+          last: breakdown(60_000, 50_000, 1_000),
+          modelContextWindow: null,
+        },
+      ],
+    ]);
+
+    const snapshots = emitted.filter((event) => event.type === "context_usage");
+    expect(snapshots).toHaveLength(2);
+    expect(snapshots[0]).toMatchObject({ contextUsedTokens: 51_000, contextTotalTokens: 258_400 });
+    expect(snapshots[0]?.contextPercent).toBeCloseTo((51_000 / 258_400) * 100, 6);
+    // A null window falls back to the models.dev window for the model.
+    expect(snapshots[1]).toMatchObject({
+      contextUsedTokens: 61_000,
+      contextTotalTokens: 1_050_000,
+    });
+  });
+
   test("abort uses turn/interrupt and scrubs complete provider events", async () => {
     const requests: string[] = [];
     const fake = makeFakeAppServer((method, _params, emit) => {
@@ -550,6 +692,13 @@ describe("Codex app-server session", () => {
               outputTokens: 9,
               reasoningOutputTokens: 6,
             },
+            last: {
+              inputTokens: 30,
+              cachedInputTokens: 11,
+              cacheWriteInputTokens: 4,
+              outputTokens: 4,
+              reasoningOutputTokens: 2,
+            },
           },
         });
         emit("turn/completed", {
@@ -581,9 +730,10 @@ describe("Codex app-server session", () => {
     expect(
       emitted.find((event) => event.type === "custom" && event.name === "codex.reasoning"),
     ).toMatchObject({ data: { text: "First thought\nSecond thought" } });
-    expect(emitted.find((event) => event.type === "context_usage")).toMatchObject({
-      contextUsedTokens: 53,
-    });
+    // Context comes from `last` (30 + 4), not the turn total (44 + 9).
+    expect(emitted.filter((event) => event.type === "context_usage")).toEqual([
+      expect.objectContaining({ contextUsedTokens: 34 }),
+    ]);
   });
 
   test("keeps failed-turn usage and treats retrying errors as diagnostics", async () => {
@@ -701,6 +851,10 @@ describe("CodexSession event mapping", () => {
       { type: "thread.started", thread_id: "thread-abc" },
       { type: "turn.started" },
       { type: "item.completed", item: agentMsg as ThreadItem },
+      {
+        type: "context.updated",
+        usage: { input_tokens: 100, cached_input_tokens: 25, output_tokens: 50 },
+      },
       {
         type: "turn.completed",
         usage: { input_tokens: 100, cached_input_tokens: 25, output_tokens: 50 },
@@ -808,15 +962,9 @@ describe("CodexSession event mapping", () => {
     }
   });
 
-  test("Phase 9: chatty turn uses the models.dev context window under the unified formula", async () => {
-    // Phase 9 deliberately swapped Codex's per-adapter peak-proxy formula
-    // (`(input - cached) + output`) for the unified `input + output` formula
-    // shared with every other provider. The trade-off: a chatty Codex turn
-    // — where `input_tokens` is the SUM across every model call in the turn
-    // — over-reports compared to the peak-proxy variant. The clamp at 100%
-    // keeps the gauge sensible; downstream consumers reading the new
-    // `contextFormula='input-cache-output'` tag know it's apples-to-apples
-    // across providers. Numbers below are from the verify-plan transcript.
+  test("a chatty turn's summed usage is billed but never reported as context", async () => {
+    // A turn's usage sums every model request in it, so it can exceed the
+    // window. Only `context.updated` (one request) may become context_usage.
     const agentMsg: AgentMessageItem = {
       id: "msg-1",
       type: "agent_message",
@@ -829,9 +977,9 @@ describe("CodexSession event mapping", () => {
       {
         type: "turn.completed",
         usage: {
-          input_tokens: 357142, // total exceeded the old hardcoded 200k window
-          cached_input_tokens: 278912, // most of input is cache reuse
-          output_tokens: 2156,
+          input_tokens: 4_850_000, // summed across the turn, above the 1.05M window
+          cached_input_tokens: 4_700_000,
+          output_tokens: 54_343,
         },
       },
     ];
@@ -843,22 +991,14 @@ describe("CodexSession event mapping", () => {
 
     const { emitted } = await runSessionWithFakeThread(events, config);
 
-    const contextUsage = emitted.find((e) => e.type === "context_usage");
-    expect(contextUsage).toBeDefined();
-    if (contextUsage && contextUsage.type === "context_usage") {
-      // Phase 9 unified: input + output = 357142 + 2156 = 359298.
-      expect(contextUsage.contextUsedTokens).toBe(359298);
-      expect(contextUsage.contextTotalTokens).toBe(1_050_000);
-      expect(contextUsage.contextPercent).toBeCloseTo((359298 / 1_050_000) * 100, 6);
-      expect(contextUsage.contextFormula).toBe("input-cache-output");
-    }
+    expect(emitted.some((e) => e.type === "context_usage")).toBe(false);
 
     // Cost still uses the full input_tokens — billing semantics are
     // preserved (cached portion gets the cached rate, uncached gets full).
     const resultEvent = emitted.findLast((e) => e.type === "result");
     if (resultEvent && resultEvent.type === "result") {
-      expect(resultEvent.cost.inputTokens).toBe(357142);
-      expect(resultEvent.cost.cacheReadTokens).toBe(278912);
+      expect(resultEvent.cost.inputTokens).toBe(4_850_000);
+      expect(resultEvent.cost.cacheReadTokens).toBe(4_700_000);
       expect(resultEvent.cost.totalCostUsd).toBeGreaterThan(0);
     }
   });

package/src/tests/codex-oauth-auth-timestamps.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, test } from "bun:test";
+import { codexOAuthAuthJson } from "../../scripts/e2e/harness";
+import { authJsonToCredentials, credentialsToAuthJson } from "../providers/codex-oauth/auth-json";
+import type { CodexOAuthCredentials } from "../providers/codex-oauth/types";
+
+const credentials: CodexOAuthCredentials = {
+  access: "example-access-token",
+  refresh: "example-refresh-token",
+  accountId: "example-account",
+  expires: Date.UTC(2099, 0, 1),
+};
+
+describe("Codex auth.json timestamps", () => {
+  test("records the write time separately from the access-token expiry", () => {
+    const before = Date.now();
+    const auth = credentialsToAuthJson(credentials);
+    const after = Date.now();
+
+    expect(Date.parse(auth.last_refresh)).toBeGreaterThanOrEqual(before);
+    expect(Date.parse(auth.last_refresh)).toBeLessThanOrEqual(after);
+    expect(authJsonToCredentials(auth).expires).toBe(credentials.expires);
+  });
+
+  test("reads expiry from a native CLI JWT instead of last_refresh", () => {
+    const expiresSeconds = 1_800_000_000;
+    const access = `header.${btoa(JSON.stringify({ exp: expiresSeconds }))}.signature`;
+    const auth = {
+      auth_mode: "chatgpt" as const,
+      OPENAI_API_KEY: null,
+      tokens: {
+        id_token: access,
+        access_token: access,
+        refresh_token: credentials.refresh,
+        account_id: credentials.accountId,
+      },
+      last_refresh: "2026-10-01T00:00:00.000Z",
+    };
+
+    expect(authJsonToCredentials(auth).expires).toBe(expiresSeconds * 1000);
+  });
+
+  test("prefers the current JWT over metadata left from an older token", () => {
+    const auth = credentialsToAuthJson(credentials);
+    auth.tokens.access_token = `header.${btoa(JSON.stringify({ exp: 1_800_000_000 }))}.signature`;
+    expect(authJsonToCredentials(auth).expires).toBe(1_800_000_000_000);
+  });
+
+  test("retains the explicit expiry when a JWT has no usable exp claim", () => {
+    for (const exp of [undefined, "1800000000", null, -1]) {
+      const access = `header.${btoa(JSON.stringify({ exp }))}.signature`;
+      const auth = credentialsToAuthJson({ ...credentials, access });
+      expect(authJsonToCredentials(auth).expires).toBe(credentials.expires);
+    }
+  });
+
+  test("keeps the legacy expiry-in-last_refresh fallback for opaque tokens", () => {
+    const auth = credentialsToAuthJson(credentials);
+    delete auth.expires;
+    auth.last_refresh = new Date(credentials.expires).toISOString();
+    expect(authJsonToCredentials(auth).expires).toBe(credentials.expires);
+  });
+
+  test("preserves expiry without exposing a pool refresh token", () => {
+    const auth = credentialsToAuthJson(credentials, { includeRefreshToken: false });
+    expect(auth.tokens.refresh_token).toBe("");
+    expect(authJsonToCredentials(auth).expires).toBe(credentials.expires);
+  });
+
+  test("seeds the black-box harness with separate refresh and expiry timestamps", () => {
+    const before = Date.now();
+    const auth = JSON.parse(codexOAuthAuthJson(JSON.stringify(credentials)));
+    expect(Date.parse(auth.last_refresh)).toBeGreaterThanOrEqual(before);
+    expect(Date.parse(auth.last_refresh)).toBeLessThanOrEqual(Date.now());
+    expect(authJsonToCredentials(auth)).toEqual(credentials);
+  });
+});