@jskit-ai/assistant-core 0.2.16 → 0.2.17

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.17",
+    "@jskit-ai/http-runtime": "0.2.7",
+    "@jskit-ai/kernel": "0.2.7",
     "@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.8",
+    "@jskit-ai/connectors-catalog": "0.2.8"
   },
   "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.17",
   "type": "module",
   "scripts": {
     "test": "node --test --test-concurrency=1"
@@ -51,8 +51,8 @@
     "@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/resource-core": "0.1.198",
+    "@jskit-ai/resource-crud-core": "0.1.198",
     "@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.7",
+    "@jskit-ai/kernel": "0.2.7",
     "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,

package/src/server/conversation/openCodeTurn.js

@@ -478,9 +478,10 @@ export async function waitForOpenCodeFinalResponse(client, conversationId, turn,
 /**
  * Production detached-turn lifetime. Applications project the completed native
  * result before observation is closed, then publish/checkpoint their own state.
- * A turn the server's shutdown stopped (`turn.stoppedByShutdown`) ends
- * interrupted however its wait ended, and `afterClose` is told so: the
- * application leaves its checkpoint to the next server.
+ * A turn the server's shutdown stopped (`turn.stoppedByShutdown`), or that
+ * ends on its own once shutdown has begun, ends interrupted however its wait
+ * ended, and `afterClose` is told so: the application leaves its checkpoint to
+ * the next server.
  * @param {import("./openCodeProcessOwner.js").OpenCodeProcessOwner} processOwner
  */
 export async function observeOpenCodeTurnCompletion(processOwner, target, conversationId, turn, {
@@ -489,6 +490,10 @@ export async function observeOpenCodeTurnCompletion(processOwner, target, conver
   const turnAbort = turn.abortController;
   let stopped = true;
   let outcome = "completed";
+  const leftToNextServer = () => {
+    if (processOwner.closed) turn.stoppedByShutdown = true;
+    return turn.stoppedByShutdown === true;
+  };
   try {
     const options = { ...waitOptions, signal: AbortSignal.any([
       signal, ...(timeoutMs ? [AbortSignal.timeout(timeoutMs)] : [])
@@ -496,14 +501,14 @@ export async function observeOpenCodeTurnCompletion(processOwner, target, conver
     const completion = finalResponse
       ? await waitForOpenCodeFinalResponse(target.server.client, conversationId, turn, { ...finalResponse, ...options })
       : await waitForOpenCodeMessages(target.server.client, conversationId, () => turn.inputMessageId, options);
-    if (turn.stoppedByShutdown) {
+    if (leftToNextServer()) {
       outcome = "interrupted";
       return { interrupted: true };
     }
     return await projectResult(completion);
   } catch (error) {
     const failure = signal.aborted ? signal.reason : error;
-    outcome = turn.interrupted || turn.stoppedByShutdown ? "interrupted" : "failed";
+    outcome = leftToNextServer() || turn.interrupted ? "interrupted" : "failed";
     if (outcome === "interrupted") return { interrupted: true };
     if (!target.abortController.signal.aborted) {
       try {

package/src/server/conversation/openCodeTurnMonitor.js

@@ -355,8 +355,10 @@ export function createOpenCodeTurnMonitor({ processes, monitors, turns, processO
         // server: its saved run stays active and carries the shutdown's mark,
         // so that server's recovery records the turn interrupted and runs the
         // host's checkpoint. Run here, that checkpoint (a Git snapshot, say)
-        // would hold the host's bounded shutdown for as long as it takes. A
-        // user's Stop ends its turn as interrupted here.
+        // could be refused or hold the host's bounded shutdown for as long as
+        // it takes. A turn that ends on its own once shutdown has begun is left
+        // the same way. A user's Stop outside shutdown ends its turn here.
+        if (processOwner.closed && finalState !== "active") turn.stoppedByShutdown = true;
         const nextServerEnds = turn.stoppedByShutdown === true && finalState !== "active";
         // Claim retirement before awaited cleanup/checkpointing. A new Send
         // joins this monitor's cleanup instead of steering an unobserved turn.

package/src/server/conversation/providers/claudeDriver.js

@@ -346,6 +346,10 @@ export function createClaudeConversationDriver({
     return native.owner.closeProject(input, native.application);
   }
 
+  function beginShutdown({ native }) {
+    return native.owner.beginShutdown();
+  }
+
   function invalidateRuntimes({ native, input }) {
     return native.owner.invalidateRuntimes(input, native.application, native.account);
   }
@@ -568,6 +572,7 @@ export function createClaudeConversationDriver({
     listConversationStorage,
     retireConversationHistory,
     closeProject,
+    beginShutdown,
     invalidateRuntimes,
     reconcileSessions,
     createConversation,

package/src/server/conversation/providers/codexDriver.js

@@ -63,6 +63,10 @@ function nativeGoalChanged() {
   });
 }
 
+function beginShutdown({ native }) {
+  return native.runOwner.beginShutdown();
+}
+
 /**
  * Conversations own threads and observers on the account's shared native runtime.
  * @param {object} dependencies
@@ -653,6 +657,7 @@ export function createCodexConversationDriver({ connections, host = {}, limits =
     deleteDetachedConversation,
     listConversationStorage,
     retireConversationHistory,
+    beginShutdown,
     invalidateRuntimes,
     reconcileSessions,
     unsubscribeSessions,

package/src/server/conversation/providers/opencodeDriver.js

@@ -126,6 +126,10 @@ export function createOpenCodeConversationDriver({
     return native.owner.closeProject(input, native.preparation.projectCleanup());
   }
 
+  function beginShutdown({ native }) {
+    return native.owner.beginShutdown();
+  }
+
   function invalidateRuntimes({ native, input }) {
     return native.owner.invalidateRuntimes(input, native.preparation);
   }
@@ -375,6 +379,7 @@ export function createOpenCodeConversationDriver({
     listConversationStorage,
     retireConversationHistory,
     closeProject,
+    beginShutdown,
     invalidateRuntimes,
     reconcileSessions,
     createConversation,

package/src/server/conversation/runtime.js

@@ -227,6 +227,7 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
     runNativeDetachedConversation: lifecycle.runNativeDetachedConversation,
     open: handles.open,
     closeNativeProject: lifecycle.closeNativeProject,
+    beginNativeShutdown: lifecycle.beginNativeShutdown,
     invalidateNativeRuntimes: lifecycle.invalidateNativeRuntimes,
     reconcileNativeSessions: lifecycle.reconcileNativeSessions,
     unsubscribeNativeSessions: lifecycle.unsubscribeNativeSessions,

package/test/claudeLifecycle.test.js

@@ -242,6 +242,34 @@ test("Claude shutdown leaves a running turn's end and its checkpoint to the next
   assert.deepEqual(custody(JSON.parse(f.session("a").records.get(MAIN_IDS.a))), { executionId: "", state: "interrupted" });
 });
 
+test("once Claude's shutdown has begun, a turn that ends on its own is left to the next server, which runs its one checkpoint", { timeout: 5_000 }, async t => {
+  const f = await lifecycleFixture(t);
+  const a = await f.running("a");
+  const saved = f.session("a").records.get(MAIN_IDS.a);
+  f.owner.beginShutdown();
+  assert.deepEqual(f.calls.stops, [], "beginning the shutdown stopped nothing");
+  // The turn ends on its own.
+  await f.processes[0].options.onEvent({ type: "result", subtype: "success", result: "Done." });
+  assert.deepEqual(f.calls.checkpoints, [], "the turn's end ran no checkpoint");
+  assert.equal(f.session("a").records.get(MAIN_IDS.a), saved, "the saved record keeps the active turn");
+  assert.equal((await f.owner.invalidateRuntimes({ reason: "server-shutdown" }, f.application, f.account)).ok, true);
+  assert.equal(a.process, null, "the full stop still stopped the process");
+  assert.deepEqual(f.calls.checkpoints, []);
+  // The next server's close proves that exit, then interrupts the turn through its checkpoint, once.
+  f.restart();
+  assert.equal((await f.owner.closeSession({ sessionId: "a" }, f.application)).ok, true);
+  assert.equal((await f.owner.closeSession({ sessionId: "a" }, f.application)).ok, true);
+  assert.deepEqual(f.calls.checkpoints, ["a:interrupted"]);
+});
+
+test("outside shutdown a Claude turn that ends on its own still runs its checkpoint at once", { timeout: 5_000 }, async t => {
+  const f = await lifecycleFixture(t);
+  await f.running("a");
+  await f.processes[0].options.onEvent({ type: "result", subtype: "success", result: "Done." });
+  assert.deepEqual(f.calls.checkpoints, ["a:completed"]);
+  assert.equal(JSON.parse(f.session("a").records.get(MAIN_IDS.a)).state, "completed");
+});
+
 test("Claude project close releases its sessions from memory without reopening saved conversations", async t => {
   const f = await lifecycleFixture(t);
   await f.idle("a");

package/test/codexConversationsCheckpoint.test.js

@@ -20,6 +20,8 @@ function persistentConversationFixture() {
   };
   const commands = createCodexConversationCommands({
     async checkpoint(_sessionId, input) { checkpoints.push(input); },
+    // Outside shutdown, with no request contexts.
+    isClosing: () => false, captureContext: () => null, runInContext: (_context, operation) => operation(),
     conversationPreparation: { async context() { return { result: { provider } }; } },
     namespace: (sessionId) => sessionId,
     // The provider owner still holds the provider observing the conversation;

package/test/codexLifecycleIsolation.test.js

@@ -231,6 +231,8 @@ function conversationCommands({ context = async () => ({ result: { ok: false, co
   providerSessions = {} } = {}) {
   return createCodexConversationCommands({
     checkpoint: async () => {},
+    // Outside shutdown, with no request contexts.
+    isClosing: () => false, captureContext: () => null, runInContext: (_context, operation) => operation(),
     conversationPreparation: {
       context,
       scope,

package/test/codexShutdownStop.test.js

@@ -0,0 +1,168 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createCodexConversationCommands } from "../src/server/conversation/codexConversations.js";
+import { createCodexRuntimeLifecycle } from "../src/server/conversation/codexRuntimeLifecycle.js";
+
+// A Temporary chat's Codex turn that the server's shutdown stops, or that ends
+// while the server is stopping, leaves its checkpoint to the next server: the
+// application records it as owed, and that server's next read makes it once.
+
+const turnOutcomes = { USER_CANCELLED: "user_cancelled", SERVICE_RESTART: "service_restart" };
+
+// One server's observed conversation. `latest` is the turn Codex's history
+// reports to a read; turn notifications reach the conversation's observer.
+function server({ closing = false, latest = { id: "turn-1", status: "inProgress", items: [] }, threadError = null } = {}) {
+  const checkpoints = [];
+  const deferred = [];
+  const listeners = new Set();
+  const emit = notification => listeners.forEach(listener => listener(notification));
+  const provider = {
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    async readThreadStatus(threadId) {
+      return { raw: { id: threadId, historyMode: "paginated", status: "idle", ...(threadError ? { error: threadError } : {}) } };
+    },
+    async listThreadTurns() { return { data: [latest] }; },
+    async readGoal() { return { goal: null }; },
+    async stopThreadForObservationLoss() {}
+  };
+  const lifecycle = { closing };
+  const commands = createCodexConversationCommands({
+    async checkpoint(sessionId, input) { checkpoints.push({ sessionId, ...input }); },
+    async deferCheckpoint(sessionId, input) { deferred.push({ sessionId, ...input }); },
+    isClosing: () => lifecycle.closing,
+    captureContext: () => null,
+    runInContext: (_context, operation) => operation(),
+    codexAppServerConversationMessageId: (...parts) => parts.join(":"),
+    conversationPreparation: { async context() { return { result: { provider } }; } },
+    namespace: sessionId => sessionId,
+    providerSessions: { owner: { providers: new Map([["provider", provider]]), holdProvider: () => () => {} } },
+    turnOutcomes
+  });
+  const startTurn = () => {
+    commands.observeCodexConversation("session", "thread", provider);
+    emit({ method: "turn/started", params: { threadId: "thread", turn: { id: "turn-1", status: "inProgress" } } });
+  };
+  const complete = status => emit({ method: "turn/completed", params: { threadId: "thread", turn: { id: "turn-1", status } } });
+  const read = stoppedByShutdown => commands.readPersistentCodexConversation("session", { conversationId: "thread", stoppedByShutdown },
+    { provider }).then(({ status, error, runId }) => ({ status, error, runId }));
+  return { checkpoints, deferred, commands, lifecycle, startTurn, complete, read };
+}
+
+const OWED = { sessionId: "session", outerTurnId: "codex:thread:turn-1", threadId: "thread", turnId: "turn-1" };
+
+test("shutdown leaves a running Temporary turn's interrupted checkpoint to the next server, which makes it once on its read", async () => {
+  const first = server();
+  first.startTurn();
+  first.lifecycle.closing = true;
+  await first.commands.leaveRunningTurnsToNextServer();
+  assert.deepEqual(first.checkpoints, [], "shutdown made no checkpoint");
+  assert.deepEqual(first.deferred, [{ ...OWED, status: "interrupted", turnOutcome: "service_restart" }]);
+
+  // The stopped process ends the turn natively as interrupted.
+  const next = server({ latest: { id: "turn-1", status: "interrupted", items: [] }, threadError: { message: "Turn aborted." } });
+  const ended = [];
+  const mark = runId => ({ runId, async ended() { ended.push(runId); } });
+  assert.deepEqual(await next.read(mark("turn-1")), { status: "interrupted", error: "", runId: "turn-1" });
+  assert.deepEqual(ended, ["turn-1"], "recording the stopped run lets the application make its checkpoint");
+  assert.deepEqual(await next.read(undefined), { status: "interrupted", error: "Turn aborted.", runId: "turn-1" },
+    "an unmarked interruption keeps Codex's own report");
+  await next.read(mark("turn-0"));
+  assert.deepEqual(ended, ["turn-1"], "only the marked run is recorded as ended");
+  assert.deepEqual(next.checkpoints, []);
+});
+
+test("a Temporary turn that ends on its own while the server stops leaves its checkpoint, with its own outcome, to the next server", async () => {
+  const f = server();
+  f.startTurn();
+  f.lifecycle.closing = true;
+  f.complete("completed");
+  await Promise.all(f.commands.deferredCheckpoints);
+  assert.deepEqual(f.checkpoints, []);
+  assert.deepEqual(f.deferred, [{ ...OWED, status: "completed", turnOutcome: "" }]);
+  assert.equal(f.commands.deferredCheckpoints.size, 0, "shutdown awaits each deferred record");
+
+  // The next server reads the completed turn as completed, and makes its checkpoint.
+  const next = server({ latest: { id: "turn-1", status: "completed", items: [] } });
+  const ended = [];
+  assert.equal((await next.read({ runId: "turn-1", async ended() { ended.push("turn-1"); } })).status, "completed");
+  assert.deepEqual(ended, ["turn-1"]);
+});
+
+test("outside shutdown a Temporary turn's end still makes its checkpoint at once", async () => {
+  const f = server();
+  f.startTurn();
+  f.complete("interrupted");
+  assert.deepEqual(f.checkpoints, [{ ...OWED, status: "interrupted", turnOutcome: "" }]);
+  assert.deepEqual(f.deferred, []);
+  await f.commands.leaveRunningTurnsToNextServer();
+  assert.deepEqual(f.deferred, [], "a finished turn owes nothing at shutdown");
+});
+
+// The run owner's runtime lifecycle, with the owner calls it makes recorded.
+function runtimeLifecycle(calls, leaveTurnsToNextServer) {
+  return createCodexRuntimeLifecycle({
+    pendingWork: { conversationTurnStarts: new Map(), messageDeliveries: new Map(), reasoningPersistQueues: new Map(),
+      resultFinalizations: new Map(), threadReconciliations: new Map(), notificationTasks: new Map(), deferredCheckpoints: new Set() },
+    observer: { eventSubscriptions: new Map() },
+    checkManagedConnection: async () => {},
+    providerSessions: { managed: new Map(), assertOpen() {}, owner: {
+      lifecycleTasks: new Set(), runtimeAcquisitions: new Set(),
+      beginShutdown() { calls.push("owner-shutdown"); },
+      async invalidateRuntimes() { calls.push("stop-runtimes"); return { failed: [], providerCount: 0, results: [], stopped: 0 }; }
+    } },
+    helperLifecycle: { projectOperations: new Map(), cleanups: new Map(), mutations: new Map(), restores: new Map(), turnStarts: new Map() },
+    captureContext: () => null,
+    runInContext: (_context, operation) => operation(),
+    debugLog() {},
+    debugError: error => error?.message,
+    leaveTurnsToNextServer
+  });
+}
+
+test("a Codex shutdown leaves the running turns to the next server before any runtime stops, and waits for their records", async () => {
+  const calls = [];
+  const recorded = Promise.withResolvers();
+  const lifecycle = runtimeLifecycle(calls, async () => {
+    calls.push("leave-turns");
+    await recorded.promise;
+    calls.push("turns-recorded");
+  });
+  const shutdown = lifecycle.invalidateRuntimes({ reason: "server-shutdown" }, { enabled: true });
+  assert.equal(lifecycle.closing, true);
+  await Promise.resolve();
+  recorded.resolve();
+  await shutdown;
+  assert.equal(calls[0], "leave-turns");
+  assert.ok(calls.indexOf("turns-recorded") < calls.lastIndexOf("stop-runtimes"), "shutdown waited for the records");
+});
+
+test("a begun Codex shutdown stops nothing, and a Temporary turn that then ends on its own leaves its checkpoint to the next server", async () => {
+  const f = server();
+  f.startTurn();
+  const calls = [];
+  const lifecycle = runtimeLifecycle(calls, () => f.commands.leaveRunningTurnsToNextServer());
+  Object.defineProperty(f.lifecycle, "closing", { get: () => lifecycle.closing });
+  lifecycle.beginShutdown();
+  assert.equal(lifecycle.closing, true, "the closing fence is set before the call returns");
+  assert.deepEqual(calls, ["owner-shutdown"], "beginning the shutdown stopped nothing");
+  f.complete("completed");
+  await Promise.all(f.commands.deferredCheckpoints);
+  assert.deepEqual(f.checkpoints, [], "the turn's end made no checkpoint");
+  assert.deepEqual(f.deferred.at(-1), { ...OWED, status: "completed", turnOutcome: "" }, "its own outcome is owed");
+
+  // The full stop that follows still stops the runtimes, and leaves the turns only once.
+  const deferred = f.deferred.length;
+  await lifecycle.invalidateRuntimes({ reason: "server-shutdown" }, { enabled: true });
+  assert.ok(calls.includes("stop-runtimes"));
+  assert.equal(f.deferred.length, deferred);
+  assert.deepEqual(f.checkpoints, []);
+
+  // The next server's read makes the owed checkpoint once.
+  const next = server({ latest: { id: "turn-1", status: "completed", items: [] } });
+  const ended = [];
+  assert.equal((await next.read({ runId: "turn-1", async ended() { ended.push("turn-1"); } })).status, "completed");
+  assert.deepEqual(ended, ["turn-1"]);
+});

package/test/codexTemporaryProviderRelease.test.js

@@ -53,6 +53,8 @@ function codexFixture(t, { idleMs = 20 } = {}) {
   });
   const commands = createCodexConversationCommands({
     async checkpoint() {},
+    // Outside shutdown, with no request contexts.
+    isClosing: () => false, captureContext: () => null, runInContext: (_context, operation) => operation(),
     codexAppServerConversationMessageId: (...parts) => parts.join(":"),
     codexAppServerStreamMessage: () => ({}),
     conversationPreparation: {

package/test/codexTurn.test.js

@@ -3856,3 +3856,60 @@ test("native history budget rejects unavailable dynamic limits before pending de
     assert.equal(sends, 0);
   }
 });
+
+test("a Main turn the previous server's shutdown stopped reads as interrupted by a restart, with one interrupted checkpoint", async () => {
+  const notices = [];
+  const checkpoints = [];
+  const f = await receiptFixture({
+    outcomeNotice(_runtime, _sessionId, _threadId, _turnId, outcome) { notices.push(outcome); },
+    checkpoint(_sessionId, input) { checkpoints.push(input); }
+  });
+  f.provider.interruptionOutcome = () => "";
+  // The shutdown marks the running turn and leaves the rest of its saved run as it was.
+  assert.deepEqual(await f.owner.markTurnStoppedByShutdown(f.sessionId, f.threadId), { marked: true });
+  assert.deepEqual({ state: f.run.state, stoppedByShutdownTurnId: f.run.stoppedByShutdownTurnId },
+    { state: "active", stoppedByShutdownTurnId: f.turnId });
+  assert.deepEqual(await f.owner.markTurnStoppedByShutdown(f.sessionId, "another-thread"), { marked: false });
+  // The next server reads the native turn as interrupted.
+  const result = await f.owner.stopTurnWithProviderFailure(f.sessionId, f.threadId, f.turnId, {
+    status: "interrupted", provider: f.provider, verifyInactive: false
+  });
+  assert.equal(result.status, "interrupted");
+  assert.match(result.error, /interrupted by a restart/u);
+  assert.deepEqual(notices, ["service_restart"]);
+  assert.deepEqual(checkpoints.map(({ status, turnOutcome }) => ({ status, turnOutcome })),
+    [{ status: "interrupted", turnOutcome: "service_restart" }]);
+  assert.equal(f.run.state, "interrupted");
+});
+
+test("an interrupted Main turn without the shutdown's mark keeps the plain interrupted outcome", async () => {
+  const notices = [];
+  const checkpoints = [];
+  const f = await receiptFixture({
+    outcomeNotice(_runtime, _sessionId, _threadId, _turnId, outcome) { notices.push(outcome); },
+    checkpoint(_sessionId, input) { checkpoints.push(input); }
+  });
+  f.provider.interruptionOutcome = () => "";
+  // A mark left by an earlier turn does not apply to this one.
+  f.run = { ...f.run, stoppedByShutdownTurnId: "an-earlier-turn" };
+  await f.owner.stopTurnWithProviderFailure(f.sessionId, f.threadId, f.turnId, {
+    status: "interrupted", provider: f.provider, verifyInactive: false
+  });
+  assert.deepEqual(notices, ["interrupted"]);
+  assert.deepEqual(checkpoints.map(({ turnOutcome }) => turnOutcome), ["interrupted"]);
+});
+
+test("a Main turn that ends once shutdown has begun is left to the next server, with no checkpoint now", async () => {
+  const f = await settlementFixture();
+  f.owner.runtimeLifecycle = { closing: true };
+  const before = structuredClone(f.run);
+  assert.deepEqual(await f.owner.markTurnIdle(f.sessionId, { status: "completed", threadId: f.threadId, turnId: f.turnId }),
+    { ok: true, processed: false, reason: "left_to_next_server" });
+  assert.deepEqual(f.run, before, "the saved run is unchanged");
+  assert.deepEqual(f.checkpoints, []);
+  // Outside shutdown the same end is recorded and checkpointed at once.
+  f.owner.runtimeLifecycle = { closing: false };
+  await f.owner.markTurnIdle(f.sessionId, { status: "completed", threadId: f.threadId, turnId: f.turnId });
+  assert.equal(f.run.state, "completed");
+  assert.deepEqual(f.checkpoints.map(({ status }) => status), ["completed"]);
+});

package/test/conversationSession.test.js

@@ -706,6 +706,35 @@ test("native invalidation preserves synchronous fences and failures without open
   await result;
 });
 
+test("beginning native shutdown reaches the configured owner synchronously and opens no conversation", async t => {
+  const input = { reason: "server-shutdown" };
+  const calls = [];
+  let asynchronousHost = true;
+  const native = { runOwner: {
+    beginShutdown() { calls.push("begin"); return "begun"; },
+    invalidateRuntimes() { assert.fail("Beginning shutdown stops nothing."); }
+  } };
+  const runtime = createConversationRuntime({
+    authorize() { assert.fail("Trusted shutdown must not acquire session authority."); },
+    storage: {
+      read() { assert.fail("Shutdown must not read a conversation."); },
+      write() { assert.fail("Shutdown must not allocate a conversation."); }
+    },
+    host: { conversation(request) {
+      calls.push("host");
+      assert.deepEqual(request, { context, input, operation: "beginShutdown" });
+      const prepared = { engine: "codex", native, context, input };
+      return asynchronousHost ? Promise.resolve(prepared) : prepared;
+    } }
+  });
+  t.after(() => runtime.close());
+  assert.throws(() => runtime.beginNativeShutdown({ context, input }), /synchronous configured host/);
+  assert.deepEqual(calls, ["host"]);
+  asynchronousHost = false;
+  assert.equal(runtime.beginNativeShutdown({ context, input }), "begun");
+  assert.deepEqual(calls, ["host", "host", "begin"], "the owner's fence is set before the call returns");
+});
+
 test("renewal proof cleanup preserves OpenCode failure, consumption and retry through the configured owner", async t => {
   const owner = createOpenCodeSharedRuntime({});
   const calls = [];

package/test/openCodeLifecycle.test.js

@@ -13,8 +13,8 @@ const ABORTED = "The operation was aborted.";
 const PROVIDER_FAILURE = "The provider refused this request.";
 
 // OpenCode's native history outlives each server that runs it. The turn's reply
-// is still being written until an interrupt ends it as aborted, or its provider
-// fails it.
+// is still being written until an interrupt ends it as aborted, its provider
+// fails it, or it completes on its own.
 function nativeOpenCode() {
   const rows = [
     { id: INPUT_ID, type: "user", time: { created: 1 } },
@@ -46,7 +46,11 @@ function nativeOpenCode() {
     rows[1] = { ...rows[1], error: { name: "APIError", data: { message: PROVIDER_FAILURE } }, time: { created: 2, completed: 3 } };
     busy = false;
   }
-  return { calls, create, fail };
+  function complete() {
+    rows[1] = { ...rows[1], text: "Done.", finish: "stop", time: { created: 2, completed: 3 } };
+    busy = false;
+  }
+  return { calls, create, fail, complete };
 }
 
 // One server with Vibe64's run rules: the session record keeps the OpenCode run
@@ -108,6 +112,8 @@ function server(native, saved, { turnEndCheckpoint = async () => {} } = {}) {
   return {
     runtime, calls, release,
     shutdown: () => runtime.invalidateRuntimes({ reason: "server-shutdown" }, { release }),
+    // The server's shutdown begins: nothing stops yet.
+    begin: () => runtime.beginShutdown(),
     async running() {
       const target = await runtime.acquirePrepared(processPreparation);
       void runtime.beginMessageMonitor(KEY, target, { id: INPUT_ID, eventStartedAt: 1, startedAt: "2026-11-05T00:00:00.000Z" }, {}, monitor);
@@ -284,3 +290,49 @@ test("OpenCode shutdown ends a temporary conversation's turn as interrupted, and
   await closed.entry.completion.catch(() => null);
   assert.deepEqual(closed.closes, [{ stopped: true, outcome: "failed", stoppedByShutdown: false }]);
 });
+
+test("once OpenCode's shutdown has begun, a main turn that ends on its own is left to the next server, which records it with one checkpoint", { timeout: 5_000 }, async t => {
+  const native = nativeOpenCode();
+  const saved = { run: null };
+  const first = server(native, saved);
+  t.after(() => first.shutdown());
+  await first.running();
+  first.begin();
+  assert.deepEqual({ interrupts: native.calls.interrupts, stops: native.calls.stops }, { interrupts: [], stops: 0 },
+    "beginning the shutdown stopped nothing");
+  native.complete();
+  await first.runtime.monitors.get(KEY);
+  assert.deepEqual(first.calls.checkpoints, [], "the turn's end made no checkpoint");
+  assert.deepEqual(runOf(saved), { active: true, state: "active", error: "", stoppedByShutdown: true, turnId: INPUT_ID });
+  assert.equal((await first.shutdown()).ok, true);
+  assert.equal(native.calls.stops, 1, "the full stop still proved the OpenCode process exit");
+  assert.deepEqual(first.calls.checkpoints, []);
+
+  const next = server(native, saved);
+  t.after(() => next.shutdown());
+  assert.equal((await next.ready()).ok, true);
+  assert.equal((await next.ready()).ok, true);
+  assert.deepEqual(next.calls.checkpoints, [`${INPUT_ID}:interrupted`], "the next server made the checkpoint once");
+  assert.deepEqual(runOf(saved), { active: false, state: "interrupted", error: "", stoppedByShutdown: true, turnId: INPUT_ID });
+});
+
+test("once OpenCode's shutdown has begun, a temporary conversation's turn that ends on its own leaves its checkpoint to the next server", { timeout: 5_000 }, async t => {
+  const native = nativeOpenCode();
+  const first = server(native, { run: null });
+  t.after(() => first.shutdown());
+  const { entry, closes } = await first.temporary("ses_temp");
+  first.begin();
+  native.complete();
+  assert.deepEqual(await entry.completion, { interrupted: true });
+  assert.deepEqual(native.calls.interrupts, [], "nothing interrupted the native turn");
+  assert.deepEqual(closes, [{ stopped: true, outcome: "interrupted", stoppedByShutdown: true }],
+    "the application is told to leave the turn's checkpoint to the next server");
+  assert.equal((await first.shutdown()).ok, true);
+
+  const next = server(native, { run: null });
+  t.after(() => next.shutdown());
+  const ended = [];
+  const read = await next.readTemporary("ses_temp", { runId: INPUT_ID, async ended() { ended.push(INPUT_ID); } });
+  assert.deepEqual({ status: read.status, error: read.error }, { status: "interrupted", error: "" });
+  assert.deepEqual(ended, [INPUT_ID], "recording the run lets the application make its checkpoint");
+});