@jskit-ai/assistant-core 0.2.16 → 0.2.18

package/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- The API driver's state note, which carries the current time, follows the conversation as its last message instead of ending the system prompt, so the provider's prompt cache keeps the whole history from one turn to the next instead of charging it uncached on each turn's first model call (`@jskit-ai/agent` `runLoop`).
 - Assistant failures that reach a person translate: 63 more undotted codes render from `jskit.errors.<code>`, and 98 sentences that share a code with others, or are sent without one, carry a `messageCode` (`assistant.claude.*`, `assistant.codex.*`, `assistant.opencode.*`, `assistant.conversation.*`, `assistant.turn.*`). The English messages are unchanged.
 - The OpenCode version mismatch, Claude control-request timeout and unreadable saved Claude conversation errors carry `params` for their catalog English.
 - The assistant settings resource sends its system prompt field messages in the coded `{ code, message, params }` form.

package/examples/conversation/package.json

@@ -8,14 +8,14 @@
     "build": "vite build"
   },
   "dependencies": {
-    "@jskit-ai/assistant-core": "0.2.16",
-    "@jskit-ai/http-runtime": "0.2.6",
-    "@jskit-ai/kernel": "0.2.6",
+    "@jskit-ai/assistant-core": "0.2.18",
+    "@jskit-ai/http-runtime": "0.2.8",
+    "@jskit-ai/kernel": "0.2.8",
     "@mdi/js": "^7.4.47",
     "vue": "^3.5.13",
     "vuetify": "^4.0.0",
-    "@jskit-ai/connectors-core": "0.2.7",
-    "@jskit-ai/connectors-catalog": "0.2.7"
+    "@jskit-ai/connectors-core": "0.2.9",
+    "@jskit-ai/connectors-catalog": "0.2.9"
   },
   "devDependencies": {
     "@vitejs/plugin-vue": "^6.0.7",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant-core",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "type": "module",
   "scripts": {
     "test": "node --test --test-concurrency=1"
@@ -50,9 +50,9 @@
     "@ai-sdk/perplexity": "^4.0.43",
     "@ai-sdk/togetherai": "^3.0.49",
     "@ai-sdk/xai": "^4.0.58",
-    "@jskit-ai/agent": "0.1.0",
-    "@jskit-ai/resource-core": "0.1.197",
-    "@jskit-ai/resource-crud-core": "0.1.197",
+    "@jskit-ai/agent": "0.1.1",
+    "@jskit-ai/resource-core": "0.1.199",
+    "@jskit-ai/resource-crud-core": "0.1.199",
     "@mdi/js": "^7.4.47",
     "@openrouter/ai-sdk-provider": "^3.0.0",
     "ai": "^7.0.152",
@@ -61,8 +61,8 @@
     "ws": "^8.20.1"
   },
   "peerDependencies": {
-    "@jskit-ai/http-runtime": "0.2.6",
-    "@jskit-ai/kernel": "0.2.6",
+    "@jskit-ai/http-runtime": "0.2.8",
+    "@jskit-ai/kernel": "0.2.8",
     "vue": "^3.5.13",
     "vuetify": "^4.0.0"
   },

package/src/server/conversation/claudeNativeTurn.js

@@ -355,7 +355,15 @@ export function createClaudeConversationTurn({ conversationId, onEvent, process,
     } else if (event.type === "settled") {
       const state = event.status === "interrupted" ? "interrupted" : event.status === "failed" ? "failed" : "completed";
       if (bound) setClaudeTurnState(entry, state, event.error);
-      else if (!await updateState(state, event.error, event.generation)) return;
+      else if (entry.turn?.active && process.ownerClosing()) {
+        // A turn that ends on its own once shutdown has begun is left to the
+        // next server like one the shutdown stops: its saved record keeps the
+        // execution and the active turn, so that server's recovery interrupts
+        // the turn and runs the host's checkpoint. Run here, that checkpoint
+        // (a Git snapshot, say) could be refused or hold up shutdown.
+        resolveCompletion({ ...readResult(), status: "interrupted", error: "" });
+        return;
+      } else if (!await updateState(state, event.error, event.generation)) return;
     }
     const published = await onEvent(event);
     const change = event.type === "provider-event" ? claudeProviderChange(event.event) : "";

package/src/server/conversation/claudeSessionCleanup.js

@@ -121,7 +121,7 @@ export function createClaudeSessionCleanup({
       account.queries.invalidate().catch(() => {});
       return { ok: true, closed: 0 };
     }
-    closing = true;
+    beginShutdown();
     // 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)]);
@@ -130,6 +130,13 @@ export function createClaudeSessionCleanup({
     return retained.value;
   }
 
+  // The server's shutdown begins: the owner closes, so each running turn's
+  // end, and its checkpoint, is left to the next server, but nothing stops.
+  // The later server-shutdown invalidation stops the processes.
+  function beginShutdown() {
+    closing = true;
+  }
+
   // 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.
@@ -233,6 +240,7 @@ export function createClaudeSessionCleanup({
     closeSession,
     releaseSession,
     closeProject,
+    beginShutdown,
     invalidateRuntimes,
     drain,
     forget,

package/src/server/conversation/claudeTurn.js

@@ -701,6 +701,7 @@ export function createClaudeConversationOwner({
     closeSession: cleanup.closeSession,
     releaseSession: cleanup.releaseSession,
     closeProject: cleanup.closeProject,
+    beginShutdown: cleanup.beginShutdown,
     invalidateRuntimes: cleanup.invalidateRuntimes,
     drain: cleanup.drain,
     forget: cleanup.forget,

package/src/server/conversation/codexConversations.js

@@ -57,6 +57,11 @@ import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
  * @param {import("./codexProviderSelection.js").CodexProviderSelection["borrowSessionProvider"]} dependencies.borrowSessionProvider
  * @param {string} dependencies.steerFailedCode
  * @param {import("./codexTurn.js").CodexTurnOutcomes} dependencies.turnOutcomes
+ * @param {import("./codexTurn.js").CodexDeferCheckpoint} dependencies.deferCheckpoint Absent when the host predates
+ *   it, which then makes every checkpoint at once.
+ * @param {() => boolean} dependencies.isClosing Whether the server's shutdown has begun.
+ * @param {import("./codexTurn.js").CodexCaptureContext} dependencies.captureContext
+ * @param {import("./codexTurn.js").CodexRunInContext} dependencies.runInContext
  */
 export function createCodexConversationCommands({
   checkpoint,
@@ -73,10 +78,17 @@ export function createCodexConversationCommands({
   ensureSessionProvider,
   borrowSessionProvider,
   steerFailedCode,
-  turnOutcomes
+  turnOutcomes,
+  deferCheckpoint,
+  isClosing,
+  captureContext,
+  runInContext
 }) {
   const codexAppServerConversations = new Map();
   const codexAppServerConversationTurnStarts = new Map();
+  // The application's records of checkpoints left to the next server, which
+  // shutdown awaits before the process exits.
+  const codexAppServerDeferredCheckpoints = new Set();
   // Turns, detached runs and stops live in their own modules. Each receives the
   // registry above and the registry and context functions declared below.
   const {
@@ -157,6 +169,42 @@ export function createCodexConversationCommands({
     holdWhileActive(state);
   }
 
+  // Once the server's shutdown has begun a turn's checkpoint belongs to the
+  // next server: the application records it as owed, and that server's next
+  // read of the conversation makes it. Made now, a checkpoint (a Git snapshot,
+  // say) could be refused or hold up the host's bounded shutdown.
+  function leaveCheckpointToNextServer(state, ending) {
+    const deferred = Promise.resolve()
+      .then(() => runInContext(state.context, () => deferCheckpoint(state.sessionId, ending)))
+      .catch(() => null);
+    codexAppServerDeferredCheckpoints.add(deferred);
+    void deferred.finally(() => codexAppServerDeferredCheckpoints.delete(deferred));
+    return deferred;
+  }
+
+  /**
+   * At shutdown, each observed conversation's running turn: the stopped process
+   * ends it without a completion this server observes, so its interrupted
+   * checkpoint is left to the next server.
+   */
+  function leaveRunningTurnsToNextServer() {
+    if (!deferCheckpoint) return Promise.resolve([]);
+    const deferred = [];
+    for (const conversations of codexAppServerConversations.values()) {
+      for (const state of conversations.values()) {
+        if (!state.persistent || !state.unsubscribe || !state.runId || !codexAppServerConversationTurnIsActive(state.status)) continue;
+        deferred.push(leaveCheckpointToNextServer(state, {
+          outerTurnId: codexAppServerNativeOuterTurnId(state.conversationId, state.runId),
+          threadId: state.conversationId,
+          turnId: state.runId,
+          status: "interrupted",
+          turnOutcome: turnOutcomes.SERVICE_RESTART
+        }));
+      }
+    }
+    return Promise.all(deferred);
+  }
+
   function codexAppServerConversation(sessionId = "", conversationId = "") {
     return codexAppServerConversations.get(
       namespace(sessionId)
@@ -201,8 +249,8 @@ export function createCodexConversationCommands({
     let state = conversations.get(conversationId);
     if (state?.provider === provider && state.unsubscribe) return state;
     if (state) forgetObservation(state);
-    state = { conversationId, provider, persistent: true, status: "ready", runId: "", error: "", turnOutcome: "",
-      onEvent: ignoreCodexConversationEvent };
+    state = { sessionId, conversationId, provider, persistent: true, status: "ready", runId: "", error: "", turnOutcome: "",
+      context: captureContext(), onEvent: ignoreCodexConversationEvent };
     state.unsubscribe = provider.subscribe((notification) => {
       if (codexAppServerNotificationThreadId(notification) !== conversationId) return;
       const turnId = codexAppServerNotificationTurnId(notification);
@@ -228,13 +276,15 @@ export function createCodexConversationCommands({
         // A turn the person stopped reaches the checkpoint as cancelled, as Main turns do.
         const completedOutcome = state.turnOutcome;
         state.turnOutcome = "";
-        void checkpoint(sessionId, {
+        const ending = {
           outerTurnId: codexAppServerNativeOuterTurnId(conversationId, completedTurnId),
           threadId: conversationId,
           turnId: completedTurnId,
           status: completedStatus,
           turnOutcome: completedOutcome
-        }).catch(() => {});
+        };
+        if (isClosing() && deferCheckpoint) leaveCheckpointToNextServer(state, ending);
+        else void checkpoint(sessionId, ending).catch(() => {});
       }
       holdWhileActive(state);
     });
@@ -284,6 +334,13 @@ export function createCodexConversationCommands({
     if (goal?.status === "active") status = "inProgress";
     Object.assign(state, { runId, status, goal });
     holdWhileActive(state);
+    // The application marks the run whose checkpoint a previous server's
+    // shutdown left owed (`stoppedByShutdown: { runId, ended }`). Recording
+    // that it ended lets the application make that checkpoint; a run the
+    // shutdown stopped reads interrupted with no error.
+    const shutdownStop = input.stoppedByShutdown;
+    const endedAtShutdown = Boolean(runId) && shutdownStop?.runId === runId && !codexAppServerConversationTurnIsActive(status);
+    if (endedAtShutdown) await shutdownStop.ended();
     const messages = [];
     for (const turn of turns) {
       const turnId = codexAppServerProviderTurnId(turn);
@@ -321,7 +378,7 @@ export function createCodexConversationCommands({
       goal,
       admitted: Boolean(input.messageId && turns.some((turn) => codexAppServerProviderTurnClientIds(turn).includes(input.messageId))),
       rawText: latestText.trim(),
-      error: state.error || codexAppServerThreadError(thread)
+      error: endedAtShutdown && status === "interrupted" ? "" : state.error || codexAppServerThreadError(thread)
     };
   }
 
@@ -555,6 +612,8 @@ export function createCodexConversationCommands({
   return Object.freeze({
     codexAppServerConversations,
     codexAppServerConversationTurnStarts,
+    deferredCheckpoints: codexAppServerDeferredCheckpoints,
+    leaveRunningTurnsToNextServer,
     codexAppServerConversation,
     hasActiveConversation,
     observeCodexConversation,

package/src/server/conversation/codexRunJournal.js

@@ -3,6 +3,32 @@ import crypto from "node:crypto";
 import { isRecord, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 
 const CODEX_APP_SERVER_PROMPT_CLAIM_GRACE_MS = 15000;
+const CODEX_APP_SERVER_STOPPED_BY_SHUTDOWN_EVENT = "codex-app-server-stopped-by-shutdown";
+
+/**
+ * Marks the session's running turn as stopped by the server's shutdown, so the
+ * next server records its interruption as a restart. Nothing else of the saved
+ * run changes.
+ * @param {{ createRuntime: import("./codexTurn.js").CodexCreateRuntime, turnState: import("./codexTurn.js").CodexTurnStateReader }} dependencies
+ * @param {string} sessionId
+ * @param {string} [threadId] the session's Main thread, when known
+ */
+export async function markCodexAppServerTurnStoppedByShutdown({ createRuntime, turnState }, sessionId = "", threadId = "") {
+  const normalizedSessionId = normalizeText(sessionId);
+  if (!normalizedSessionId) return { marked: false };
+  const runtime = await createRuntime();
+  let marked = false;
+  await runtime.store.mutateSession(normalizedSessionId, async () => {
+    const turn = turnState(await runtime.getSession(normalizedSessionId).catch(() => null) || {});
+    if (!turn.active || !turn.turnId || (normalizeText(threadId) && turn.threadId !== normalizeText(threadId))) return;
+    await runtime.store.writeAgentRunEvent(normalizedSessionId, CODEX_APP_SERVER_AGENT_RUN_ID, {
+      event: { kind: CODEX_APP_SERVER_STOPPED_BY_SHUTDOWN_EVENT },
+      patch: { stoppedByShutdownTurnId: turn.turnId }
+    });
+    marked = true;
+  });
+  return { marked };
+}
 
 function terminalCodexAppServerAgentRunState(status = "") {
   const normalizedStatus = normalizeText(status);
@@ -40,6 +66,7 @@ function codexAppServerDateValueMs(value = "") {
  * @param {number} dependencies.finalizingGraceMs
  * @param {(session: object, run: object) => boolean} dependencies.admissionTaskFinished
  * @param {string} dependencies.orphanedPromptMessage
+ * @param {() => boolean} dependencies.isClosing Whether the server's shutdown has begun.
  */
 export function createCodexRunJournal({
   namespace,
@@ -57,7 +84,8 @@ export function createCodexRunJournal({
   idlePublishPayload,
   finalizingGraceMs,
   admissionTaskFinished,
-  orphanedPromptMessage
+  orphanedPromptMessage,
+  isClosing
 }) {
   const codexAppServerCompletedTurns = new Set();
   const codexAppServerProcessedTurns = new Set();
@@ -394,6 +422,10 @@ export function createCodexRunJournal({
   }
 
   async function markCodexAppServerTurnIdle(sessionId = "", input = {}) {
+    // Once shutdown has begun the turn's end, and its checkpoint, are left to the next server's recovery, as after a crash.
+    if (isClosing()) {
+      return { ok: true, processed: false, reason: "left_to_next_server" };
+    }
     const status = normalizeText(input.status) || "completed";
     const result = await publishCodexAppServerAgentRun(sessionId, {
       error: normalizeText(input.error),

package/src/server/conversation/codexRuntimeLifecycle.js

@@ -6,6 +6,9 @@ import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 /** @typedef {ReturnType<typeof import("./codexTurn.js").createCodexAppServerRunOwner>} CodexRunOwner */
 /** @typedef {(event: string, details: object) => void} CodexDebugLog */
 
+/** A lifecycle without running turns to hand over leaves none. */
+async function leaveNoTurns() {}
+
 /**
  * Shutdown, wellbeing timers and managed-session records for shared Codex
  * runtimes. It works on the run/provider owners' collections; it owns no servers.
@@ -23,6 +26,8 @@ import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
  * @param {CodexDebugLog} dependencies.debugLog
  * @param {(error: unknown) => unknown} dependencies.debugError
  * @param {{ message: string, code: string, retryable: boolean } | null} [dependencies.closingError]
+ * @param {() => Promise<unknown>} [dependencies.leaveTurnsToNextServer] When shutdown begins, leaves each running
+ *   turn's end, and its checkpoint, to the next server.
  */
 export function createCodexRuntimeLifecycle({
   pendingWork,
@@ -35,7 +40,8 @@ export function createCodexRuntimeLifecycle({
   continueGoalAfterAccountChange,
   debugLog,
   debugError,
-  closingError = null
+  closingError = null,
+  leaveTurnsToNextServer = leaveNoTurns
 }) {
   const codexAppServerSessionClosures = new Map();
   const codexAppServerWellbeingTimers = new Map();
@@ -44,6 +50,7 @@ export function createCodexRuntimeLifecycle({
   let codexAppServerThreadReconcileGeneration = 0;
   let codexAppServerServerClosing = false;
   let codexAppServerShutdownPromise = null;
+  let codexAppServerTurnsLeft = null;
 
   function assertOpen() {
     if (!closingError) return providerSessions.assertOpen();
@@ -216,11 +223,20 @@ export function createCodexRuntimeLifecycle({
     }
   }
 
+  // The server's shutdown begins: the closing fence is set and each running
+  // turn's end, and its checkpoint, is left to the next server, but nothing
+  // stops. The later server-shutdown invalidation stops the runtimes.
   function beginCodexAppServerShutdown() {
     if (codexAppServerServerClosing) {
       return;
     }
     codexAppServerServerClosing = true;
+    // Taken now, before any runtime stops, while each running turn is known.
+    codexAppServerTurnsLeft = (async () => leaveTurnsToNextServer())().catch(error => {
+      debugLog("appServerShutdown.leaveTurns.error", { error: debugError(error) });
+    }).finally(() => {
+      codexAppServerTurnsLeft = null;
+    });
     providerSessions.owner.beginShutdown();
     codexAppServerThreadReconcileGeneration += 1;
     for (const providerKey of [...codexAppServerWellbeingTimers.keys()]) {
@@ -231,6 +247,8 @@ export function createCodexRuntimeLifecycle({
   async function drainCodexAppServerControllerTasks() {
     while (true) {
       const pending = new Set([
+        ...(codexAppServerTurnsLeft ? [codexAppServerTurnsLeft] : []),
+        ...pendingWork.deferredCheckpoints.values(),
         ...pendingWork.conversationTurnStarts.values(),
         ...helperLifecycle.projectOperations.values(),
         ...helperLifecycle.cleanups.values(),
@@ -356,6 +374,7 @@ export function createCodexRuntimeLifecycle({
 
   return Object.freeze({
     get closing() { return codexAppServerServerClosing; },
+    beginShutdown: beginCodexAppServerShutdown,
     assertOpen,
     get reconcileGeneration() { return codexAppServerThreadReconcileGeneration; },
     nextReconcileGeneration,

package/src/server/conversation/codexTurn.js

@@ -10,7 +10,7 @@ import { createCodexNotificationObserver } from "./codexNotificationObserver.js"
 import { createCodexThreadStatus } from "./codexThreadStatus.js";
 import { createCodexTurnRecovery } from "./codexTurnRecovery.js";
 import { createCodexResultSettlement } from "./codexResultSettlement.js";
-import { createCodexRunJournal } from "./codexRunJournal.js";
+import { createCodexRunJournal, markCodexAppServerTurnStoppedByShutdown } from "./codexRunJournal.js";
 import { createCodexRenewalCommands } from "./codexRenewalCommands.js";
 import { createCodexGoalCommands } from "./codexGoalCommands.js";
 import { createCodexProviderSelection } from "./codexProviderSelection.js";
@@ -80,6 +80,13 @@ export { codexAppServerThreadIsMissing } from "./codexProviderThreads.js";
 /** @typedef {typeof CODEX_TURN_OUTCOMES} CodexTurnOutcomes */
 /** @typedef {(runtime: any, session: object, options: object) => Promise<any>} CodexAdmissionRecovery */
 /** @typedef {(sessionId: string, input: object) => Promise<unknown>} CodexCheckpoint */
+/**
+ * Records a scoped conversation turn's checkpoint as owed to the next server,
+ * once the server's shutdown has begun. The application passes the run back
+ * on that server's next read as `stoppedByShutdown: { runId, ended }`, and
+ * makes the checkpoint when `ended` is called.
+ * @typedef {(sessionId: string, input: { outerTurnId: string, threadId: string, turnId: string, status: string, turnOutcome: string }) => Promise<unknown>} CodexDeferCheckpoint
+ */
 
 /**
  * The application hooks that add metadata to the turns a run writes.
@@ -161,6 +168,8 @@ function runInNoContext(_context, operation) {
  * @param {string} [options.messageIdPrefix]
  * @param {object} [options.idlePublishPayload]
  * @param {CodexCheckpoint} [options.checkpoint]
+ * @param {CodexDeferCheckpoint} options.deferCheckpoint A host that predates it leaves it out: a scoped
+ *   conversation turn that ends during shutdown then makes its checkpoint at once, and one the shutdown stops makes none.
  * @param {Partial<CodexMessageMetadataHooks>} [options.messageMetadata]
  * @param {boolean} [options.persistCommentary]
  * @param {string} [options.deliveryStateMetadataKey]
@@ -204,6 +213,7 @@ export function createCodexAppServerRunOwner({
   messageIdPrefix = "codex:",
   idlePublishPayload,
   checkpoint = answerNothing,
+  deferCheckpoint,
   messageMetadata = {},
   persistCommentary = true,
   deliveryStateMetadataKey = "assistant_delivery",
@@ -317,7 +327,8 @@ export function createCodexAppServerRunOwner({
     idlePublishPayload,
     finalizingGraceMs,
     admissionTaskFinished,
-    orphanedPromptMessage
+    orphanedPromptMessage,
+    isClosing: () => runOwner.runtimeLifecycle?.closing === true
   });
   const admissionRecovery = recoverAdmission || codexRunJournal.recoverAbandonedPromptClaim;
 
@@ -424,7 +435,11 @@ export function createCodexAppServerRunOwner({
     ensureSessionProvider: codexProviderSelection.ensureSessionProvider,
     borrowSessionProvider: codexProviderSelection.borrowSessionProvider,
     steerFailedCode,
-    turnOutcomes
+    turnOutcomes,
+    deferCheckpoint,
+    isClosing: () => runOwner.runtimeLifecycle?.closing === true,
+    captureContext,
+    runInContext
   });
 
   const codexObservationControl = createCodexObservationControl({
@@ -636,6 +651,7 @@ export function createCodexAppServerRunOwner({
     clearSessionRecoveryTimers: codexRunJournal.clearSessionRecoveryTimers,
     publishAgentRun: codexRunJournal.publishAgentRun,
     markTurnIdle: codexRunJournal.markTurnIdle,
+    markTurnStoppedByShutdown,
     finalizeAssistantResult: codexResultSettlement.finalizeAssistantResult,
     finalizedTurns: codexAppServerOutput.finalizedTurns,
     liveProgressItems: codexAppServerOutput.liveProgressItems,
@@ -661,8 +677,10 @@ export function createCodexAppServerRunOwner({
         reasoningPersistQueues: codexAppServerOutput.reasoningPersistQueues,
         resultFinalizations: codexResultSettlement.resultFinalizations,
         threadReconciliations: codexThreadReadiness.threadReconciliations,
-        notificationTasks: codexAppServerNotificationQueue.tasks
+        notificationTasks: codexAppServerNotificationQueue.tasks,
+        deferredCheckpoints: codexConversations.deferredCheckpoints
       },
+      leaveTurnsToNextServer: leaveRunningTurnsToNextServer,
       observer: codexNotificationObserver,
       checkManagedConnection: codexThreadReadiness.checkManagedConnection,
       providerSessions,
@@ -678,6 +696,7 @@ export function createCodexAppServerRunOwner({
       providerSessions.owner.attachRuntimeLifecycle(runOwner.runtimeLifecycle);
       providerSessions.assertOpen = runOwner.runtimeLifecycle.assertOpen;
     }
+    runOwner.beginShutdown = runOwner.runtimeLifecycle.beginShutdown;
     runOwner.invalidateRuntimes = runOwner.runtimeLifecycle.invalidateRuntimes;
     Object.assign(runOwner, createCodexSessionReconciliation({
       readiness: codexThreadReadiness, recoverSessionObservationLoss,
@@ -685,6 +704,24 @@ export function createCodexAppServerRunOwner({
       createRuntime, namespace, turnState, sessionIdRequiredError, debugLog, debugError
     }));
   }
+  function markTurnStoppedByShutdown(sessionId = "", threadId = "") {
+    return markCodexAppServerTurnStoppedByShutdown({ createRuntime, turnState }, sessionId, threadId);
+  }
+
+  // At shutdown each running turn's end, and its checkpoint, belong to the
+  // next server: Main turns are marked so it records their interruption as a
+  // restart, and scoped conversations leave their checkpoints owed.
+  async function leaveRunningTurnsToNextServer() {
+    const results = await Promise.allSettled([
+      codexConversations.leaveRunningTurnsToNextServer(),
+      ...[...providerSessions.managed.values()].map(managed => Promise.resolve().then(() => runInContext(
+        managed.projectContext, () => markTurnStoppedByShutdown(managed.sessionId, managed.threadId))))
+    ]);
+    for (const result of results) {
+      if (result.status === "rejected") debugLog("appServerShutdown.leaveTurn.error", { error: debugError(result.reason) });
+    }
+  }
+
   const cleanup = createCodexSessionCleanup({
     namespace,
     runOwner,

package/src/server/conversation/codexTurnEndings.js

@@ -253,9 +253,9 @@ export function createCodexTurnEndings({
     const normalizedStatus = normalizeText(status);
     let base = "Codex app-server failed before completing this turn.";
     if (normalizedStatus === "interrupted") {
-      base = outcome === turnOutcomes.CONTROL_RECONFIGURATION
-        ? "Codex app-server was interrupted while its controls were restored."
-        : "Codex app-server was interrupted before completing this turn.";
+      if (outcome === turnOutcomes.CONTROL_RECONFIGURATION) base = "Codex app-server was interrupted while its controls were restored.";
+      else if (outcome === turnOutcomes.SERVICE_RESTART) base = "Codex app-server was interrupted by a restart before completing this turn.";
+      else base = "Codex app-server was interrupted before completing this turn.";
     }
     const normalizedError = normalizeText(error);
     return normalizedError ? `${base} ${normalizedError}` : base;
@@ -277,17 +277,20 @@ export function createCodexTurnEndings({
     const normalizedThreadId = normalizeText(threadId);
     const normalizedTurnId = normalizeText(turnId);
     const normalizedStatus = normalizeText(status) || "failed";
+    const runtime = await createRuntime();
     let resolvedOutcome = normalizeText(outcome);
     if (!resolvedOutcome) {
       if (normalizedStatus === "interrupted") {
         const recorded = provider ? provider.interruptionOutcome(normalizedThreadId, normalizedTurnId) : "";
-        resolvedOutcome = [turnOutcomes.USER_CANCELLED, turnOutcomes.CONTROL_RECONFIGURATION].includes(recorded)
-          ? recorded : turnOutcomes.INTERRUPTED;
+        if ([turnOutcomes.USER_CANCELLED, turnOutcomes.CONTROL_RECONFIGURATION].includes(recorded)) resolvedOutcome = recorded;
+        // The previous server's shutdown stopped this turn: a restart, not a failure.
+        else if (codexAppServerAgentRun(await runtime.getSession(normalizedSessionId))?.stoppedByShutdownTurnId === normalizedTurnId) {
+          resolvedOutcome = turnOutcomes.SERVICE_RESTART;
+        } else resolvedOutcome = turnOutcomes.INTERRUPTED;
       } else {
         resolvedOutcome = turnOutcomes.PROVIDER_FAILURE;
       }
     }
-    const runtime = await createRuntime();
     const staleFailure = async () => {
       const turn = turnState(await runtime.getSession(normalizedSessionId));
       if (codexAppServerTurnCanReceiveProviderCompletion(turn, normalizedThreadId, normalizedTurnId)) {

package/src/server/conversation/nativeConversationLifecycle.js

@@ -218,6 +218,27 @@ function createNativeConversationLifecycle({ authorize, defaultHost, hostPrepare
     return driver.invalidateRuntimes(prepared);
   }
 
+  // The server's shutdown begins before anything stops, on the same trusted
+  // boundary: the configured owner sets its closing fence and leaves each
+  // running turn's end, and its checkpoint, to the next server, synchronously.
+  // A later invalidation with reason "server-shutdown" stops its processes.
+  function beginNativeShutdown({ context, input = {} }) {
+    if (!hostPrepares) {
+      throw new TypeError("Native shutdown requires a configured conversation host.");
+    }
+    const prepared = defaultHost.conversation({ context, input, operation: "beginShutdown" });
+    if (!prepared || isThenable(prepared) ||
+        !["codex", "claude", "opencode"].includes(prepared.engine) || !prepared.native ||
+        !Object.hasOwn(prepared, "input") || !Object.hasOwn(prepared, "context")) {
+      throw new TypeError("Native shutdown requires synchronous configured host preparation.");
+    }
+    const driver = providers.createDriver(prepared.engine, defaultHost);
+    if (!implementsOperation(driver, "beginShutdown")) {
+      throw new TypeError("The selected conversation driver does not implement native shutdown.");
+    }
+    return driver.beginShutdown(prepared);
+  }
+
   // Startup reconciliation and subscription reset use the existing trusted
   // lifecycle caller. Native owners retain their own shutdown fences and tasks.
   function reconcileNativeSessions({ context, sessions, options = {} }) {
@@ -363,6 +384,7 @@ function createNativeConversationLifecycle({ authorize, defaultHost, hostPrepare
     createNativeConversation,
     runNativeDetachedConversation,
     closeNativeProject,
+    beginNativeShutdown,
     invalidateNativeRuntimes,
     reconcileNativeSessions,
     unsubscribeNativeSessions,

package/src/server/conversation/openCodeProcessOwner.js

@@ -441,12 +441,17 @@ export function createOpenCodeProcessOwner({ processes, processStarts, monitors,
     };
   }
 
+  // The server's shutdown begins: the owner closes, so each running turn's
+  // end, and its checkpoint, is left to the next server, but nothing stops.
+  // The later server-shutdown invalidation stops the processes.
+  function beginShutdown() {
+    closed = true;
+    clearTimeout(storageIdle);
+    storageIdle = null;
+  }
+
   async function invalidateRuntimes(input = {}, preparation) {
-    if (normalizeNullableText(input.reason) === "server-shutdown") {
-      closed = true;
-      clearTimeout(storageIdle);
-      storageIdle = null;
-    }
+    if (normalizeNullableText(input.reason) === "server-shutdown") beginShutdown();
     const application = preparation.release;
     // readable-check: allow method-probe - input validation: a connection change carries the publication of the application's saved connections
     if (typeof input.publish === "function") {
@@ -567,6 +572,7 @@ export function createOpenCodeProcessOwner({ processes, processStarts, monitors,
     releaseProcessTarget,
     closeSession,
     closeProject,
+    beginShutdown,
     invalidateRuntimes,
     releaseRenewalPredecessorProcessExitProof,
     releaseProcessExitProof

package/src/server/conversation/openCodeRuntime.js

@@ -226,6 +226,7 @@ export function createOpenCodeSharedRuntime({ onStop = ignoreRuntimeStop, scope,
     sendPreparedMessage: sessionTurns.sendPreparedMessage,
     inspectPreparedMessage: sessionTurns.inspectPreparedMessage,
     interruptPreparedTurn: sessionTurns.interruptPreparedTurn,
+    beginShutdown: processOwner.beginShutdown,
     invalidateRuntimes: processOwner.invalidateRuntimes,
     releaseRenewalPredecessorProcessExitProof: processOwner.releaseRenewalPredecessorProcessExitProof,
     releaseProcessExitProof: processOwner.releaseProcessExitProof,