@jskit-ai/assistant-core 0.2.2 → 0.2.4

package/src/server/conversation/claudeTurn.js

@@ -14,6 +14,7 @@ function failure(message, code = "assistant_claude_turn_failed") {
 
 const text = normalizeNullableText;
 const now = () => new Date().toISOString();
+const CLAUDE_SIGNED_OUT_MESSAGE = "Claude isn't connected. Sign in to Claude, then send your message again.";
 
 function hasPendingClaudeStartup(entry) {
   return entry.startupCleanup?.pending === true && entry.startupCleanup.executionId === entry.executionId;
@@ -27,6 +28,16 @@ function nativeWorkSettled(entry) {
   return !entry.sending && !entry.process && !entry.executionId && !entry.command && !entry.stopPending;
 }
 
+// Work this server is running: a send, command or stop in progress, a live
+// process, or a startup still lending cleanup. A restored execution with none
+// of these belongs to an earlier server; no Claude process outlives the
+// server that started it.
+function runsNativeWork(entry) {
+  return Boolean(entry.sending || entry.process || entry.command || entry.stopPending || hasPendingClaudeStartup(entry));
+}
+
+const ACTIVE_TURN_STATES = ["starting", "active", "finalizing"];
+
 export function claudeNativeMessageId(id) {
   const value = createHash("sha256").update(String(id)).digest("hex");
   return `${value.slice(0, 8)}-${value.slice(8, 12)}-4${value.slice(13, 16)}-8${value.slice(17, 20)}-${value.slice(20, 32)}`;
@@ -181,9 +192,13 @@ export function createClaudeConversationOwner({
   // Otherwise the host retains entries and their original checkpoint order.
   const bound = Boolean(store.releaseExecution);
   const isTurnActive = entry => bound ? entry.nativeTurn.read().active : Boolean(entry.turn?.active);
+  // What cleanup must stop: running work, or custody (an execution or an
+  // active turn) that only a verified stop retires. An idle entry has nothing
+  // to stop, and stopping it would only rewrite its saved record.
+  const holdsNativeWork = entry => runsNativeWork(entry) || Boolean(entry.executionId) || isTurnActive(entry);
 
   function createAccountQueries({ accountIdentity, createProcess }) {
-    return createClaudeAccountQueries({ accountIdentity,
+    return createClaudeAccountQueries({ accountIdentity, configRoot,
       processes: () => entries.values(), isClosing: () => closing, createProcess });
   }
 
@@ -227,6 +242,12 @@ export function createClaudeConversationOwner({
     return readClaudeHistory({ configRoot, workdir: entry.nativeWorkdir, conversationId: entry.id });
   }
 
+  function savedState(saved, conversationId) {
+    if (!saved) return {};
+    try { return JSON.parse(saved); }
+    catch { throw createError(`The saved Claude conversation ${conversationId} is unreadable. Restore its saved conversation state.`); }
+  }
+
   async function open(context, { conversationId = "", mainId, create = false,
     cleanupExecutionId, recoveringCleanup = false, nativeWorkdir = context.workdir } = {}) {
     const main = !conversationId || conversationId === mainId;
@@ -246,7 +267,7 @@ export function createClaudeConversationOwner({
     let saved = store.read(context, id);
     if (saved && typeof saved.then === "function") saved = await saved;
     if (!main && !saved && !create && !recoveringCleanup) throw createError("This Claude conversation is unavailable.");
-    const state = saved ? JSON.parse(saved) : {};
+    const state = savedState(saved, id);
     const entry = { id, key, main, persistent: state.persistent === true, context, process: null, startupCleanup: null,
       executionId: state.executionId || (recoveringCleanup ? cleanupExecutionId : ""), preparationRevision: 0,
       accountIdentities: state.accountIdentities || (state.accountIdentity ? { anthropic: state.accountIdentity } : {}),
@@ -326,9 +347,9 @@ export function createClaudeConversationOwner({
 
   async function ensureReady(entry) {
     if (entry.process) {
-      // Status reads retain active instructions; apply changes at idle admission.
-      if (isTurnActive(entry)) await bindAccount(entry);
-      else await ensureProcess(entry);
+      // Status reads retain an active turn's instructions and account: an
+      // account change never stops running work. Both apply at idle admission.
+      if (!isTurnActive(entry)) await ensureProcess(entry);
     } else {
       await bindAccount(entry);
       if (entry.executionId && !hasPendingClaudeStartup(entry)) await entry.nativeTurn.stopProcess("Claude's previous process exit could not be confirmed.");
@@ -707,7 +728,7 @@ export function createClaudeConversationOwner({
       else await input.onPromptSending?.({ threadId: entry.id, displayAttachments: input.displayAttachments, turnMetadata: actorMetadata });
       if (input.signal?.aborted) throw Object.assign(createError("The goal command was stopped before delivery."), { delivery: "not-sent" });
       await entry.nativeTurn.send(command ? entry.process.client : native.client, command ? preparation.message(entry, input) : prompt,
-        { messageId: uuid, accept, ...(command ? { timeoutMs: command.timeoutMs } : {}) });
+        { messageId: uuid, accept, steer: steering, ...(command ? { timeoutMs: command.timeoutMs } : {}) });
     } catch (error) {
       if (!command) await entry.nativeTurn.stopProcess(error.message);
       throw error;
@@ -763,9 +784,11 @@ export function createClaudeConversationOwner({
       threadId: entry.id, turnId: accepted ? turnId : "" };
   }
 
-  async function hasActiveTemporaryConversation(context, { acquire }) {
-    await restoreSessionEntries(context, { acquire });
-    return [...entries.values()].some((entry) => entry.context.key === context.key && !entry.main && entry.turn?.active);
+  // Temporary work this server runs. Saved conversations are not reopened to
+  // answer: a turn an earlier server saved as active ended with that server.
+  function hasActiveTemporaryConversation(context) {
+    return [...entries.values()].some((entry) => entry.context.key === context.key && !entry.main &&
+      isTurnActive(entry) && runsNativeWork(entry));
   }
 
   function hasActiveConversation(binding) {
@@ -804,16 +827,28 @@ export function createClaudeConversationOwner({
     return [...entries.values()].filter((entry) => entry.context.key === context.key);
   }
 
+  // A session's close stops what this server runs for it, then reopens only
+  // saved custody an earlier server left. Once the owner is closing for an
+  // account change or shutdown it reopens nothing.
   async function closeSession(context, application) {
-    const ctx = await application.readContext(context);
+    return closeRetained(await application.readContext(context), application,
+      { recover: !closing, forget: context.forgetConversationBinding === true });
+  }
+
+  // Renewal proof release ends a session this server no longer uses. Its own
+  // close already recovered saved custody while its record could be written.
+  async function releaseSession(context, application) {
+    return closeRetained(await application.readContext(context), application, { recover: false, forget: true });
+  }
+
+  async function closeRetained(ctx, application, { recover, forget: forgetEntries }) {
     closingSessions.add(ctx.key);
     try {
-      await restoreSessionEntries(ctx, { acquire });
+      if (recover) await recoverSavedCustody(ctx);
       const proofs = await drain(ctx.key);
       const terminal = await application.terminals.close(ctx.sessionId);
-      if (terminal?.ok !== false && context.forgetConversationBinding === true) {
-        forget(ctx.key);
-      }
+      // A forgotten entry is drained: everything it held is in its saved record.
+      if (terminal?.ok !== false && forgetEntries) forget(ctx.key);
       return { ok: terminal?.ok !== false, closed: proofs.length + Number(terminal?.closed || 0),
         processExitProof: proofs.at(-1) || { exited: true, scopeEmpty: true }, processExitProofs: proofs };
     } finally {
@@ -821,19 +856,27 @@ export function createClaudeConversationOwner({
     }
   }
 
-  async function closeProject(input = {}, application) {
-    const root = text(input.projectContextRoot);
-    const contexts = new Map([...entries.values()]
-      .filter((entry) => !root || path.resolve(store.projectContextRoot(entry)) === path.resolve(root))
-      .map((entry) => [entry.context.key, entry.context]));
-    let closed = 0;
-    let ok = true;
-    for (const ctx of contexts.values()) {
-      const result = await closeSession(ctx, application);
-      closed += result.closed;
-      ok &&= result.ok;
+  // Saved custody an earlier server left: an execution whose exit is still
+  // unproven, or a turn saved as active. Only those conversations are reopened,
+  // so a verified stop can retire them; idle saved conversations stay closed.
+  async function recoverSavedCustody(ctx) {
+    let saved = store.readSessionConversations(ctx);
+    if (saved && typeof saved.then === "function") saved = await saved;
+    for (const conversationId of saved.ids) {
+      if (entries.has(`${ctx.key}\0${conversationId}`)) continue;
+      let record = store.read(saved.context, conversationId);
+      if (record && typeof record.then === "function") record = await record;
+      const state = savedState(record, conversationId);
+      if (state.executionId || ACTIVE_TURN_STATES.includes(state.state)) await acquire(saved.context, conversationId);
     }
-    return { ok, closed };
+  }
+
+  // Project close releases what this server runs for the project's sessions,
+  // from their retained entries alone, and forgets them: nothing uses them.
+  function closeProject(input = {}, application) {
+    const root = text(input.projectContextRoot);
+    return eachSession(entry => !root || path.resolve(store.projectContextRoot(entry)) === path.resolve(root),
+      ctx => closeRetained(ctx, application, { recover: false, forget: true }));
   }
 
   async function invalidateRuntimes(input = {}, application, account) {
@@ -842,44 +885,78 @@ export function createClaudeConversationOwner({
       return stopSelected(entry => store.modelProviderId(entry) === input.modelProviderId,
         "The provider connection changed.");
     }
-    closing = true;
-    try {
-      await account.queries.invalidate().catch(account.failure);
-      return await stopRetained(application);
-    } finally {
-      closing = input.reason === "server-shutdown";
+    if (input.reason !== "server-shutdown") {
+      // An account change stops and waits on nothing. Claude Code reads its
+      // credentials for every request, so running work continues on the newly
+      // connected account or ends at once as signed out; each conversation
+      // rebinds its account at its next idle admission. Only the account's
+      // cached reads are dropped. A cancelled query's process stop that fails
+      // stays owned and is retried before the next query.
+      account.queries.invalidate().catch(() => {});
+      return { ok: true, closed: 0 };
     }
-  }
-
-  // Account changes and shutdown stop only what this server runs: a Claude
-  // process cannot outlive the server that started it, so retained entries
-  // hold every one. Saved conversations are not reopened just to be stopped.
-  async function stopRetained(application) {
-    const sessions = new Map([...entries.values()].map(entry => [entry.context.key, entry.context.sessionId]));
+    closing = true;
+    // Neither waits for the other: a failed account query cleanup must not
+    // leave the sessions' processes running.
+    const [queries, retained] = await Promise.allSettled([account.queries.invalidate(), stopRetained(application)]);
+    if (queries.status === "rejected") await account.failure(queries.reason);
+    if (retained.status === "rejected") throw retained.reason;
+    return retained.value;
+  }
+
+  // Shutdown stops only what this server runs: a Claude process cannot outlive
+  // the server that started it, so retained entries hold every one. Saved
+  // conversations are not reopened just to be stopped.
+  function stopRetained(application) {
+    return eachSession(() => true, ctx => closeRetained(ctx, application, { recover: false, forget: false }));
+  }
+
+  // Sessions close independently and together: one that fails is reported by
+  // its ID while every other session still stops.
+  async function eachSession(select, close) {
+    const contexts = new Map([...entries.values()].filter(select).map(entry => [entry.context.key, entry.context]));
+    const settled = await Promise.allSettled([...contexts.values()].map(ctx => close(ctx)));
     let closed = 0;
-    let ok = true;
-    for (const [key, sessionId] of sessions) {
-      closed += (await drain(key)).length;
-      const terminal = await application.terminals.close(sessionId);
-      closed += Number(terminal?.closed || 0);
-      ok &&= terminal?.ok !== false;
-    }
-    return { ok, closed };
+    const failed = [];
+    [...contexts.values()].forEach((ctx, index) => {
+      const result = settled[index];
+      if (result.status === "fulfilled") closed += result.value.closed;
+      const error = result.status === "rejected" ? result.reason?.message || String(result.reason)
+        : result.value.ok === false ? "Its Claude Code terminal could not be closed." : "";
+      if (error) failed.push({ sessionId: ctx.sessionId, error });
+    });
+    return { ok: failed.length === 0, closed, failed,
+      ...(failed.length ? { error: failed.map(({ sessionId, error }) => `Claude session ${sessionId}: ${error}`).join(" ") } : {}) };
   }
 
   async function drain(key) {
     const selected = [...entries.values()].filter(entry => entry.context.key === key);
+    // Fence configuration still in progress: it must not start a process later.
+    for (const entry of selected) entry.preparationRevision++;
+    const proofs = [];
+    let failure;
+    async function stop() {
+      for (const entry of selected) if (holdsNativeWork(entry)) {
+        try { proofs.push(await entry.nativeTurn.stopProcess()); }
+        catch (error) { failure ||= error; }
+      }
+    }
     // Startup already lends cleanup before initialization completes. Stop it
     // first; waiting for the preparation queue first can exhaust host shutdown.
-    for (const entry of selected) await entry.nativeTurn.stopProcess();
+    await stop();
     await Promise.allSettled(selected.map(entry => entry.nativeTurn.whenIdle()));
-    const proofs = [];
-    for (const entry of selected) proofs.push(await entry.nativeTurn.stopProcess());
+    await stop();
+    // Every other entry still stopped; the first failure keeps the close retryable.
+    if (failure) throw failure;
     return proofs;
   }
 
   function forget(contextKey) {
-    for (const [key, entry] of entries) if (entry.context.key === contextKey) entries.delete(key);
+    for (const [key, entry] of entries) if (entry.context.key === contextKey) {
+      // Nothing would ever stop a process a forgotten entry started.
+      entry.disposed = true;
+      entries.delete(key);
+    }
   }
 
   async function close(entry) {
@@ -904,12 +981,22 @@ export function createClaudeConversationOwner({
     }
   }
 
+  // A provider connection change stops the matching work this server runs.
+  // Each entry stops on its own, so one failure is reported by ID.
   async function stopSelected(select, reason) {
     let closed = 0;
-    for (const entry of entries.values()) if (select(entry)) {
-      await entry.nativeTurn.stopProcess(reason); closed++;
+    const failed = [];
+    for (const entry of [...entries.values()].filter(select)) {
+      entry.preparationRevision++;
+      if (!holdsNativeWork(entry)) continue;
+      try {
+        await entry.nativeTurn.stopProcess(reason);
+        closed++;
+      } catch (error) {
+        failed.push({ sessionId: entry.context.sessionId, conversationId: entry.id, error: error.message });
+      }
     }
-    return { ok: true, closed };
+    return { ok: failed.length === 0, closed, failed };
   }
 
   async function wait(entry, input, { context, acquire }) {
@@ -1172,7 +1259,7 @@ export function createClaudeConversationOwner({
   }
 
   return Object.freeze({ applicationToolsSupported: true, entries, closingSessions, get closing() { return closing; }, createAccountQueries, open, acquire, createConversation, snapshot, readRetainedTurn, readFinalAssistantResult, readHistory, nativeWorkSettled, ensureReady, ensureProcess, readContextUsage, compactContext, releaseRetainedGoal, stopForTerminal, prepareTerminal, send, startTurn,
-    interrupt, read, inspectAdmission, hasActiveTemporaryConversation, hasActiveConversation, retireConversationHistory, reconcileSessions, restoreSessionEntries, closeSession, closeProject, invalidateRuntimes, drain, forget, close, deleteConversation, recover, stopSelected, wait, stopConversation,
+    interrupt, read, inspectAdmission, hasActiveTemporaryConversation, hasActiveConversation, retireConversationHistory, reconcileSessions, restoreSessionEntries, closeSession, releaseSession, closeProject, invalidateRuntimes, drain, forget, close, deleteConversation, recover, stopSelected, wait, stopConversation,
     readGoal, updateGoal, renewal, run, steer, cancel });
 }
 
@@ -1189,6 +1276,10 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
   // Inputs Claude has begun reading. A queued steer joins the running loop, so
   // one result can finish several of them; queued-only input stays in flight.
   const startedInputs = new Set();
+  // Steers written into a running loop that Claude has not begun reading. Claude
+  // Code reads queued input only when the running tool call returns.
+  const waitingSteers = new Set();
+  let steeringClient = null;
   const tasks = new Set();
   let turnId = "";
   let messageId = "";
@@ -1222,6 +1313,20 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
     clearFinalAssistantResult();
   }
 
+  // A waiting steer would otherwise sit behind a long foreground command (or a
+  // wait loop) until it returns. Claude's Ctrl+B control moves foreground Bash
+  // and subagents to the background: they keep running and report completion,
+  // and the blocked tool call returns so Claude reads the steer now.
+  function backgroundForegroundWork() {
+    const client = steeringClient;
+    if (!waitingSteers.size || !client?.request || stopped || cancelling) return;
+    void client.request({ subtype: "background_tasks" }).then(
+      () => publish({ type: "diagnostic", stage: "steering_backgrounded", pendingCommands: inFlight.size, backgroundTasks: tasks.size }),
+      // An older CLI still reads the steer when its tool call returns.
+      error => publish({ type: "diagnostic", stage: "steering_background_failed", error: error.message })
+    ).catch(() => {});
+  }
+
   function currentReceiptOwner(owner) {
     return Boolean(entry && owner && inputOwner === owner && acceptedInput === owner &&
       owner.commandId === currentCommandId && entry.process && entry.process === owner.process &&
@@ -1466,6 +1571,7 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
         currentCommandId = uuid;
         startedInputs.add(uuid);
       }
+      if (frame.state !== "queued") waitingSteers.delete(uuid);
       if (frame.state === "completed") {
         inFlight.delete(uuid);
         startedInputs.delete(uuid);
@@ -1509,6 +1615,8 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
         for (const task of frame.tasks || []) if (task.task_id && !task.ambient) tasks.add(task.task_id);
       }
       if (frame.subtype === "task_started" && frame.task_id && !frame.ambient) tasks.add(frame.task_id);
+      // A command Claude started before reading a waiting steer would hold it too.
+      if (frame.subtype === "task_started") backgroundForegroundWork();
       if (["task_notification", "task_updated"].includes(frame.subtype) &&
           ["completed", "failed", "stopped", "killed"].includes(frame.status || frame.patch?.status)) {
         tasks.delete(frame.task_id);
@@ -1596,7 +1704,10 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
       for (const id of pendingAssistantMessages.keys()) await flushAssistantMessages(id, role);
       const output = typeof frame.structured_output === "object" ? JSON.stringify(frame.structured_output) : String(frame.result || "");
       checkOutput(output);
-      const message = failed ? (frame.errors || []).join("; ") || output || frame.subtype : "";
+      // A conversation whose account signed out under it ends its next request
+      // at once with Claude Code's own "Not logged in" answer.
+      const message = !failed ? "" : /^Not logged in\b/u.test(output) ? CLAUDE_SIGNED_OUT_MESSAGE
+        : (frame.errors || []).join("; ") || output || frame.subtype;
       result = failed ? "" : output;
       if (result && ![...messages.values()].some((block) => block.complete && block.role === "assistant" && block.text === result)) {
         await publishMessage({ id: `claude_${frame.uuid || turnId}_result`, role: "assistant", text: result, complete: true,
@@ -1646,6 +1757,8 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
     admissions.clear();
     inFlight.clear();
     startedInputs.clear();
+    waitingSteers.clear();
+    steeringClient = null;
     tasks.clear();
     // Verified process cleanup can precede Claude's terminal generation frame.
     // Retain already displayed text for the existing transcript reader, with
@@ -1714,7 +1827,7 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
       acceptedInput = null;
       clearFinalAssistantResult();
     },
-    async send(client, message, { messageId: uuid, accept, timeoutMs = 30_000 } = {}) {
+    async send(client, message, { messageId: uuid, accept, timeoutMs = 30_000, steer = false } = {}) {
       if (!active || stopped || cancelling) throw Object.assign(
         failure("Claude has no active turn for this message.", !active && !stopped && !cancelling
           ? "conversation_steer_turn_finished" : "assistant_claude_turn_failed"),
@@ -1730,14 +1843,20 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
       const admitted = Promise.withResolvers();
       void admitted.promise.catch(() => {});
       inFlight.add(uuid);
+      if (steer) {
+        waitingSteers.add(uuid);
+        steeringClient = client;
+      }
       const timer = setTimeout(() => admitted.reject(Object.assign(
         failure("Claude has not acknowledged this prompt. Its delivery is uncertain.", "assistant_claude_admission_unknown"),
         { delivery: "uncertain" }
       )), timeoutMs);
       admissions.set(uuid, { ...admitted, accept, timer, receiptOwner });
       try {
-        await Promise.all([client.send(message, { messageId: uuid, sessionId: conversationId }), admitted.promise]);
+        await Promise.all([client.send(message, { messageId: uuid, sessionId: conversationId })
+          .then(() => { if (steer) backgroundForegroundWork(); }), admitted.promise]);
       } catch (error) {
+        waitingSteers.delete(uuid);
         if (inputOwner === receiptOwner) invalidateFinalAssistantResult();
         throw error;
       } finally {
@@ -1753,7 +1872,8 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
       }
       // Claude Code acknowledges streamed input as queued and folds it into the
       // running turn after the current tool call, or starts it once the main
-      // loop is idle. Interrupting instead would kill a running foreground tool.
+      // loop is idle. Interrupting instead would kill a running foreground tool;
+      // send() moves such a tool to the background so the steer is read now.
       // The next input owns completion now: a result or task finishing before
       // it starts must not settle this turn with the previous answer.
       outcome = null;

package/src/server/conversation/codexAuthPreflight.js

@@ -11,6 +11,8 @@ import { normalizeNullableText as normalizeAgentText } from "./normalize.js";
 // reconnect-required output marks the stored credentials invalid.
 const CODEX_AUTH_PREFLIGHT_TIMEOUT_MS = 15000;
 const CODEX_AUTH_PREFLIGHT_OUTPUT_TAIL_BYTES = 4096;
+// The host names this run where it lists running work.
+const CODEX_AUTH_PREFLIGHT_EXECUTION = Object.freeze({ label: "Checking the Codex sign-in", operationId: "codex-auth-preflight" });
 
 function tailAppend(text = "", chunk = "", maxBytes = CODEX_AUTH_PREFLIGHT_OUTPUT_TAIL_BYTES) {
   const next = `${String(text || "")}${String(chunk || "")}`;
@@ -60,6 +62,7 @@ async function runCodexAuthPreflight({
       command: codexCommand,
       credentialHome: codexAppServerCredentialHome(normalizedToolHomeSource, baseEnv),
       cwd: processCwd,
+      execution: CODEX_AUTH_PREFLIGHT_EXECUTION,
       inheritProcessEnv: false,
       mode: "capture",
       timeout: normalizePositiveInteger(timeoutMs, { fallback: CODEX_AUTH_PREFLIGHT_TIMEOUT_MS })

package/src/server/conversation/codexConfiguration.js

@@ -1,10 +1,12 @@
 import { createHash } from "node:crypto";
 import { execFile } from "node:child_process";
-import { open, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
 import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
 import { normalizeNullableText } from "./normalize.js";
+import { codexDisabledProcessFeatureArguments } from "./codexHomeStorage.js";
 
 const execute = promisify(execFile);
 const CODEX_THREAD_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
@@ -101,7 +103,8 @@ export function codexInteractiveArguments({
   return [
     command,
     ...(disableStartupUpdates ? ["-c", "check_for_update_on_startup=false"] : []),
-    ...(remoteEndpoint ? ["--remote", remoteEndpoint] : []),
+    // A remote terminal uses its app-server's features; a local one starts its own.
+    ...(remoteEndpoint ? ["--remote", remoteEndpoint] : codexDisabledProcessFeatureArguments()),
     "--model",
     model,
     "-c",
@@ -155,10 +158,42 @@ export async function codexAppServerProjectHookTrustConfig(provider, cwd = "", {
   return { "hooks.state": state };
 }
 
+// What an exported catalogue was made from: the Codex binary, the catalogue
+// source and added models, and the metadata (never the contents) of the home's
+// account and configuration files. A bare command name has no binary identity,
+// so its catalogue is exported on every start.
+async function codexModelCatalogRevision({ command, codexHome, bundled, additionalModels }) {
+  if (!path.isAbsolute(command)) return null;
+  const identity = async (file) => {
+    const found = await stat(file).catch(() => null);
+    return found && [found.dev, found.ino, found.size, found.mtimeMs, found.ctimeMs];
+  };
+  const binary = await identity(command);
+  if (!binary) return null;
+  return createHash("sha256").update(JSON.stringify({
+    command, binary, bundled, additionalModels,
+    auth: await identity(path.join(codexHome, "auth.json")),
+    config: await identity(path.join(codexHome, "config.toml"))
+  })).digest("hex");
+}
+
 // Codex's model manager reads model_catalog_json once, before any threads
 // exist. A thread override changes routing, but cannot supply model metadata.
 // Export from the installed CLI so native model definitions stay CLI-owned.
-export async function prepareCodexModelCatalog({ command, runtimeDir, bundled = false, signal, additionalModels = [] }) {
+// An app-server start reuses the runtime's exported catalogue until its
+// revision changes, so reconnects and idle restarts run no exporter.
+export async function prepareCodexModelCatalog({
+  command, runtimeDir, bundled = false, signal, additionalModels = [],
+  codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex")
+}) {
+  const catalogPath = path.join(runtimeDir, "models.json");
+  const revisionPath = path.join(runtimeDir, "models.revision");
+  const revisionInput = { command, codexHome, bundled, additionalModels };
+  const revision = await codexModelCatalogRevision(revisionInput);
+  if (revision && await stat(catalogPath).then(() => true, () => false) &&
+      await readFile(revisionPath, "utf8").catch(() => "") === revision) {
+    return catalogPath;
+  }
   let catalog;
   const models = new Map();
   try {
@@ -185,15 +220,18 @@ export async function prepareCodexModelCatalog({ command, runtimeDir, bundled =
   for (const model of additionalModels) {
     models.set(model.slug, { ...model, priority: ++priority });
   }
-  const catalogPath = path.join(runtimeDir, "models.json");
   const temporary = `${catalogPath}.tmp`;
   try {
     signal?.throwIfAborted();
+    await rm(revisionPath, { force: true });
     await writeFile(temporary, JSON.stringify({ ...catalog, models: [...models.values()] }), { mode: 0o600 });
     await rename(temporary, catalogPath);
   } finally {
     await rm(temporary, { force: true });
   }
+  // The exporter can refresh the account's tokens; record what it left behind.
+  const exported = await codexModelCatalogRevision(revisionInput);
+  if (exported) await writeFile(revisionPath, exported, { mode: 0o600 });
   return catalogPath;
 }