@jskit-ai/assistant-core 0.1.239 → 0.1.241

package/src/server/conversation/codexProviderOwner.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import { stat } from "node:fs/promises";
 import { CodexAppServerAgentProvider } from "./codexProvider.js";
 import { codexAppServerProjectHookTrustConfig } from "./codexConfiguration.js";
+import { normalizeCodexRunText as normalizeText } from "./codexTurnState.js";
 
 // Moved from Vibe64's codexTerminal provider owner. Caller-local provider keys
 // are grouped without duplicating the inventory. Recovery and sharing always
@@ -9,7 +10,6 @@ import { codexAppServerProjectHookTrustConfig } from "./codexConfiguration.js";
 const codexAppServerProviders = new Map();
 const codexAppServerOwnedRuntimes = new Map();
 const codexAppServerRuntimeLifecycles = new Map();
-const normalizeText = value => String(value || "").trim();
 
 export function codexAppServerOwnedRuntimeKey(providerKey = "", providerOptions = {}) {
   const runtimeDir = normalizeText(providerOptions?.runtimeDir);
@@ -36,7 +36,7 @@ export function codexAppServerRuntimeStopWasVerified(result = {}) {
     result?.runtimeDirRemoved === true;
 }
 
-async function directoryExists(filePath = "") {
+export async function directoryExists(filePath = "") {
   try {
     return (await stat(filePath)).isDirectory();
   } catch (error) {

package/src/server/conversation/codexProviderSelection.js

@@ -1,9 +1,10 @@
 import { normalizeCodexRunText } from "./codexTurnState.js";
 import { codexAppServerProjectHookTrustConfig } from "./codexConfiguration.js";
-import { createCodexAppServerModelCatalogCache } from "./codexProvider.js";
+import { createCodexAppServerModelCatalogCache } from "./codexModelCatalog.js";
 import { readCodexAppServerAccountIdentity } from "./codexHelperExecution.js";
 
-// Private composition of unchanged operations from the original run owner.
+// Provider acquisition and per-operation provider contexts for a run owner's
+// managed threads, with their model catalogue and account identity reads.
 export function createCodexProviderSelection({
   providerSessions,
   turnState,
@@ -16,6 +17,25 @@ export function createCodexProviderSelection({
     cacheMs: modelCatalogCacheMs,
     errorPrefix
   });
+  function sessionConnection(sessionId, providerOptions) {
+    return providerSessions.context(normalizeCodexRunText(sessionId), providerOptions);
+  }
+
+  function ensureSessionProvider(sessionId, providerOptions, threadId) {
+    return providerSessions.owner.ensureSession(sessionConnection(sessionId, providerOptions), threadId);
+  }
+
+  function rememberManagedSession(sessionId, providerOptions, { executionRoot, workdir, threadId } = {}) {
+    const connection = sessionConnection(sessionId, providerOptions);
+    connection.runOwner.runtimeLifecycle.rememberManagedSession(connection.providerKey, {
+      providerOptions,
+      sessionId: normalizeCodexRunText(sessionId),
+      executionRoot,
+      threadId,
+      workdir
+    });
+  }
+
   function managedProviderKeyForThread(sessionId, workdir, threadId) {
     for (const [providerKey, managed] of providerSessions.managed) {
       const provider = providerSessions.owner.providers.get(providerKey);
@@ -54,9 +74,7 @@ export function createCodexProviderSelection({
       const provider = providerSessions.owner.providers.get(providerKey);
       if (provider) {
         return {
-          provider: await providerSessions.owner.ensureSession(
-            providerSessions.context(normalizedSessionId, managed.providerOptions)
-          ),
+          provider: await ensureSessionProvider(normalizedSessionId, managed.providerOptions),
           providerKey,
           providerOptions: managed.providerOptions
         };
@@ -76,22 +94,18 @@ export function createCodexProviderSelection({
     const activeProvider = await ensureCodexAppServerProviderForActiveTurn(session, managedIdentity);
     const provider = activeProvider?.provider;
     if (provider) return provider;
-    const providerOptions = await prepareProviderOptions();
-    return await providerSessions.owner.ensureSession(
-      providerSessions.context(normalizeCodexRunText(sessionId), providerOptions)
-    );
+    return await ensureSessionProvider(sessionId, await prepareProviderOptions());
   }
 
-  async function codexAppServerRuntimeForVisibleTerminal(sessionId, session, options, managedIdentity, prepareProviderOptions) {
+  async function codexAppServerRuntimeForVisibleTerminal(rawSessionId, session, options, managedIdentity, prepareProviderOptions) {
+    const sessionId = normalizeCodexRunText(rawSessionId);
     const activeProvider = await ensureCodexAppServerProviderForActiveTurn(session, managedIdentity);
     const providerOptions = activeProvider?.providerOptions || await prepareProviderOptions();
-    const provider = activeProvider?.provider || await providerSessions.owner.ensureSession(
-      providerSessions.context(normalizeCodexRunText(sessionId), providerOptions)
-    );
+    const provider = activeProvider?.provider || await ensureSessionProvider(sessionId, providerOptions);
     await codexAppServerProjectHookTrustConfig(provider, options.workdir, {
       persist: true
     });
-    const providerKey = activeProvider?.providerKey || providerSessions.context(sessionId, providerOptions).providerKey;
+    const providerKey = activeProvider?.providerKey || sessionConnection(sessionId, providerOptions).providerKey;
     return providerSessions.owner.acquireRuntime({
       operation: () => provider.ensureRuntime(),
       provider,
@@ -112,9 +126,7 @@ export function createCodexProviderSelection({
         );
         if (activeProvider) return { provider: activeProvider.provider || null, reused: true };
         return {
-          provider: await providerSessions.owner.ensureSession(providerSessions.context(
-            normalizeCodexRunText(sessionId), await context.providerOptions(currentSession)
-          )),
+          provider: await ensureSessionProvider(sessionId, await context.providerOptions(currentSession)),
           reused: false
         };
       }
@@ -130,9 +142,8 @@ export function createCodexProviderSelection({
         const activeProvider = await ensureCodexAppServerProviderForActiveTurn(
           currentSession, context.managedIdentity(currentSession)
         );
-        return activeProvider?.provider || await providerSessions.owner.ensureSession(
-          providerSessions.context(normalizeCodexRunText(sessionId), await context.providerOptions(currentSession))
-        );
+        return activeProvider?.provider ||
+          await ensureSessionProvider(sessionId, await context.providerOptions(currentSession));
       },
       observationOwner(threadId) {
         for (const [key, managed] of providerSessions.managed) {
@@ -150,9 +161,7 @@ export function createCodexProviderSelection({
     return {
       threadId: context.threadId,
       async acquireProvider(current) {
-        return providerSessions.owner.ensureSession(providerSessions.context(
-          normalizeCodexRunText(sessionId), await context.providerOptions(current)
-        ));
+        return ensureSessionProvider(sessionId, await context.providerOptions(current));
       }
     };
   }
@@ -160,22 +169,11 @@ export function createCodexProviderSelection({
   function codexAppServerSessionObserverOptions(sessionId, providerOptions) {
     return {
       get providerKey() {
-        return providerSessions.context(normalizeCodexRunText(sessionId), providerOptions).providerKey;
+        return sessionConnection(sessionId, providerOptions).providerKey;
       }
     };
   }
 
-  function rememberCodexAppServerPreparedThread(sessionId, providerOptions, context, thread) {
-    const connection = providerSessions.context(sessionId, providerOptions);
-    connection.runOwner.runtimeLifecycle.rememberManagedSession(connection.providerKey, {
-      providerOptions,
-      sessionId,
-      executionRoot: context.executionRoot,
-      threadId: thread.threadId,
-      workdir: context.workdir
-    });
-  }
-
 
   async function readExecutionProfileModelCatalog(sessionId, preparation) {
     if (!preparation.assistantScope) {
@@ -184,9 +182,7 @@ export function createCodexProviderSelection({
         restoration.projectRuntimeRoot, restoration.context
       ));
     }
-    const provider = preparation.provider || await providerSessions.owner.ensureSession(
-      providerSessions.context(normalizeCodexRunText(sessionId), await preparation.providerOptions)
-    );
+    const provider = preparation.provider || await ensureSessionProvider(sessionId, await preparation.providerOptions);
     return readCodexAppServerModelCatalog(provider, { signal: preparation.signal });
   }
 
@@ -196,7 +192,7 @@ export function createCodexProviderSelection({
       restoration.projectRuntimeRoot, restoration.context
     ));
     const providerOptions = await preparation.providerOptions;
-    const context = providerSessions.context(sessionId, providerOptions);
+    const context = sessionConnection(sessionId, providerOptions);
     const provider = await providerSessions.owner.withLifecycle(
       () => providerSessions.owner.providerForSession(context),
       context.providerKey,
@@ -216,6 +212,8 @@ export function createCodexProviderSelection({
     codexAppServerControlContext,
     codexAppServerObservationRecoveryContext,
     codexAppServerSessionObserverOptions,
-    rememberCodexAppServerPreparedThread
+    sessionConnection,
+    ensureSessionProvider,
+    rememberManagedSession
   };
 }

package/src/server/conversation/codexRenewalCommands.js

@@ -1,7 +1,8 @@
-import { codexAppServerTurnStatusIsSuccessfulComplete, codexAppServerTurnStatusIsProviderFailure, normalizeCodexRunText, codexAppServerErrorMessage } from "./codexTurnState.js";
+import { codexAppServerTurnStatusIsSuccessfulComplete, codexAppServerTurnStatusIsProviderFailure, codexAppServerErrorMessage } from "./codexTurnState.js";
 import { createCodexAppServerDetachedTurnWatcher, waitForCodexAppServerTurn } from "./codexDetachedTurn.js";
-import { resumeExactCodexAppServerThread, startFreshCodexAppServerThread, sendCodexAppServerPrompt } from "./codexProvider.js";
-import { codexAppServerProviderTurnId, codexAppServerProviderTurnError, inspectCodexAppServerRenewalThread } from "./codexEvents.js";
+import { codexAppServerDeliveredTurn, sendCodexAppServerPrompt } from "./codexProvider.js";
+import { resumeExactCodexAppServerThread, startFreshCodexAppServerThread } from "./codexRenewalThreads.js";
+import { codexAppServerProviderTurnId, inspectCodexAppServerRenewalThread } from "./codexEvents.js";
 
 // Private composition of unchanged operations from the original run owner.
 export function createCodexRenewalCommands({
@@ -41,7 +42,9 @@ export function createCodexRenewalCommands({
 
     observer.subscribeEvents(sessionId, provider, threadId,
       selection.codexAppServerSessionObserverOptions(sessionId, context.providerOptions));
-    selection.rememberCodexAppServerPreparedThread(sessionId, context.providerOptions, context, resumed);
+    selection.rememberManagedSession(sessionId, context.providerOptions, {
+      executionRoot: context.executionRoot, workdir: context.workdir, threadId: resumed.threadId
+    });
 
     let result = null;
     let reconciled = Boolean(targetTurn);
@@ -112,8 +115,8 @@ export function createCodexRenewalCommands({
           provider,
           threadId
         }, context);
-        turnId = normalizeCodexRunText(delivery.turn?.id);
-        status = normalizeCodexRunText(delivery.turn?.status || delivery.turn?.raw?.status);
+        const delivered = codexAppServerDeliveredTurn(delivery);
+        ({ turnId, status } = delivered);
         if (!turnId) {
           throw errors.create("handover_identity_missing");
         }
@@ -129,7 +132,7 @@ export function createCodexRenewalCommands({
           watcher.failAfterDetailGrace(errors.create(
             "failed",
             { status },
-            codexAppServerProviderTurnError(delivery.turn || {})
+            delivered.error
           ));
         } else if (codexAppServerTurnStatusIsSuccessfulComplete(status)) {
           await watcher.completeNow(status);
@@ -250,8 +253,8 @@ export function createCodexRenewalCommands({
           readOnly: true,
           threadId
         }, context);
-        turnId = normalizeCodexRunText(delivery.turn?.id);
-        status = normalizeCodexRunText(delivery.turn?.status || delivery.turn?.raw?.status);
+        const delivered = codexAppServerDeliveredTurn(delivery);
+        ({ turnId, status } = delivered);
         if (!turnId) {
           throw errors.create("seed_identity_missing");
         }
@@ -262,7 +265,7 @@ export function createCodexRenewalCommands({
           watcher.failAfterDetailGrace(errors.create(
             "failed",
             { status },
-            codexAppServerProviderTurnError(delivery.turn || {})
+            delivered.error
           ));
         } else if (codexAppServerTurnStatusIsSuccessfulComplete(status)) {
           await watcher.completeNow(status);

package/src/server/conversation/codexRenewalThreads.js

@@ -0,0 +1,412 @@
+import { normalizeNullableText as normalizeAgentText } from "./normalize.js";
+import { codexAppServerProjectHookTrustConfig, codexAppServerTextHasControlCharacters } from "./codexConfiguration.js";
+import {
+  codexAppServerRequestIsInvalid,
+  CODEX_APP_SERVER_THREAD_INVENTORY_ID_MAX_LENGTH,
+  CODEX_APP_SERVER_THREAD_INVENTORY_MAX_COUNT
+} from "./codexProvider.js";
+
+// Renewal thread operations: resume the exact retained thread, or prove a
+// genuinely fresh successor thread for one renewal operation.
+const CODEX_RENEWAL_UNMATERIALIZED_THREAD_SUFFIX =
+  "is not materialized yet; includeTurns is unavailable before first user message";
+
+export function defineCodexRenewalThreadIds(value = [], {
+  errorCode = "codex_renewal_fresh_thread_required"
+} = {}) {
+  if (
+    !Array.isArray(value) ||
+    value.length > CODEX_APP_SERVER_THREAD_INVENTORY_MAX_COUNT
+  ) {
+    throw codexRenewalThreadError(
+      errorCode,
+      "The successor assistant thread inventory is invalid."
+    );
+  }
+  const threadIds = value.map((threadId) => normalizeAgentText(threadId));
+  if (
+    threadIds.some((threadId) => (
+      !threadId ||
+      threadId.length > CODEX_APP_SERVER_THREAD_INVENTORY_ID_MAX_LENGTH ||
+      codexAppServerTextHasControlCharacters(threadId)
+    )) ||
+    new Set(threadIds).size !== threadIds.length
+  ) {
+    throw codexRenewalThreadError(
+      errorCode,
+      "The successor assistant thread inventory contains an invalid identity."
+    );
+  }
+  return Object.freeze([...threadIds].sort());
+}
+
+async function listCodexRenewalThreadIds(provider, workdir, errorCode) {
+  if (typeof provider?.listAppServerThreadsForCwd !== "function") {
+    throw codexRenewalThreadError(
+      errorCode,
+      "The assistant provider cannot inventory the successor's exact session threads."
+    );
+  }
+  const normalizedWorkdir = normalizeAgentText(workdir);
+  const inventory = await provider.listAppServerThreadsForCwd({
+    cwd: normalizedWorkdir
+  });
+  if (normalizeAgentText(inventory?.cwd) !== normalizedWorkdir) {
+    throw codexRenewalThreadError(
+      errorCode,
+      "The assistant provider returned a thread inventory for a different session source."
+    );
+  }
+  return defineCodexRenewalThreadIds(inventory?.threadIds, { errorCode });
+}
+
+function assertCodexRenewalThreadSnapshot(threadSnapshot = null, {
+  threadId = "",
+  workdir = "",
+  errorCode
+} = {}) {
+  const expectedThreadId = normalizeAgentText(threadId);
+  const expectedWorkdir = normalizeAgentText(workdir);
+  const actualThreadId = codexAppServerThreadResponseId(threadSnapshot);
+  const actualWorkdir = normalizeAgentText(
+    threadSnapshot?.cwd ||
+    threadSnapshot?.raw?.cwd ||
+    threadSnapshot?.response?.thread?.cwd
+  );
+  if (actualThreadId !== expectedThreadId || actualWorkdir !== expectedWorkdir) {
+    throw codexRenewalThreadError(
+      errorCode,
+      "The assistant provider could not verify the exact successor thread and session source.",
+      {
+        actualThreadId,
+        actualWorkdir,
+        expectedThreadId,
+        expectedWorkdir
+      }
+    );
+  }
+  return threadSnapshot;
+}
+
+function codexRenewalThreadNeedsStatusRead(error = null, threadId = "") {
+  const normalizedThreadId = normalizeAgentText(threadId);
+  return Boolean(
+    normalizedThreadId &&
+    (
+      (
+        codexAppServerRequestIsInvalid(error, "thread/read") &&
+        normalizeAgentText(error?.message) ===
+          `thread ${normalizedThreadId} ${CODEX_RENEWAL_UNMATERIALIZED_THREAD_SUFFIX}`
+      ) ||
+      (
+        Number(error?.code) === -32601 &&
+        normalizeAgentText(error?.method) === "thread/read"
+      )
+    )
+  );
+}
+
+async function readCodexRenewalSuccessorThreadSnapshot({
+  provider,
+  threadId = "",
+  workdir = "",
+  errorCode
+} = {}) {
+  try {
+    return assertCodexRenewalThreadSnapshot(
+      await provider.readThread(threadId),
+      { threadId, workdir, errorCode }
+    );
+  } catch (error) {
+    if (
+      !codexRenewalThreadNeedsStatusRead(error, threadId) ||
+      typeof provider?.readThreadStatus !== "function"
+    ) {
+      throw error;
+    }
+    return assertCodexRenewalThreadSnapshot(
+      await provider.readThreadStatus(threadId),
+      { threadId, workdir, errorCode }
+    );
+  }
+}
+
+export function codexRenewalThreadError(code, message, details = {}, {
+  retryable = false
+} = {}) {
+  const error = new Error(message);
+  error.code = code;
+  error.details = {
+    ...details,
+    retryable
+  };
+  error.retryable = retryable;
+  return error;
+}
+
+function codexAppServerThreadResponseId(thread = null, fallback = "") {
+  return normalizeAgentText(
+    thread?.id ||
+    thread?.response?.thread?.id ||
+    fallback
+  );
+}
+
+/** Resume only the supplied retained thread; native read failures never replace it. */
+export async function resumeExactCodexAppServerThread({
+  expectedThreadId = "",
+  provider,
+  settings,
+  projectHooks = false,
+  workdir = "",
+  errorCode = "codex_renewal_thread_unreadable"
+} = {}) {
+  const normalizedWorkdir = normalizeAgentText(workdir);
+  const normalizedExpectedThreadId = normalizeAgentText(expectedThreadId);
+  if (
+    typeof provider?.ensureRuntime !== "function" ||
+    typeof provider?.resumeThread !== "function" ||
+    typeof provider?.readThread !== "function"
+  ) {
+    throw codexRenewalThreadError(
+      errorCode,
+      "The old assistant provider cannot read its exact main thread.",
+      { expectedThreadId: normalizedExpectedThreadId }
+    );
+  }
+  const appServerRuntime = await provider.ensureRuntime();
+  const config = projectHooks
+    ? await codexAppServerProjectHookTrustConfig(provider, normalizedWorkdir)
+    : null;
+  const { threadSettings } = await settings(normalizedWorkdir, config);
+  let thread = null;
+  let threadSnapshot = null;
+  try {
+    thread = await provider.resumeThread(normalizedExpectedThreadId, threadSettings);
+    const resumedThreadId = codexAppServerThreadResponseId(thread, normalizedExpectedThreadId);
+    if (resumedThreadId !== normalizedExpectedThreadId) {
+      throw codexRenewalThreadError(
+        errorCode,
+        "The old assistant provider resumed a different thread.",
+        {
+          expectedThreadId: normalizedExpectedThreadId,
+          resumedThreadId
+        }
+      );
+    }
+    threadSnapshot = await provider.readThread(normalizedExpectedThreadId);
+  } catch (error) {
+    if (
+      error?.code === errorCode ||
+      codexAppServerRequestIsInvalid(error, "thread/resume") ||
+      codexAppServerRequestIsInvalid(error, "thread/read")
+    ) {
+      if (error?.code === errorCode) {
+        throw error;
+      }
+      throw codexRenewalThreadError(
+        errorCode,
+        "The old assistant thread cannot be read. Write or edit the handover manually instead.",
+        {
+          expectedThreadId: normalizedExpectedThreadId,
+          providerError: normalizeAgentText(error?.message)
+        }
+      );
+    }
+    throw error;
+  }
+  return Object.freeze({
+    appServerRuntime,
+    thread,
+    threadId: normalizedExpectedThreadId,
+    threadSnapshot,
+    threadSettings
+  });
+}
+
+/** Preserve the original baseline → create/adopt → durable identity → first-read order. */
+export async function startFreshCodexAppServerThread({
+  provider,
+  settings,
+  projectHooks = false,
+  identity,
+  resumableThreadId = "",
+  forbiddenThreadId = "",
+  operationId = "",
+  workdir = "",
+  errorCode = "codex_renewal_fresh_thread_required",
+  applicationName = "The application"
+} = {}) {
+  const normalizedWorkdir = normalizeAgentText(workdir);
+  const normalizedForbiddenThreadId = normalizeAgentText(forbiddenThreadId);
+  const normalizedOperationId = normalizeAgentText(operationId);
+  if (resumableThreadId && resumableThreadId === normalizedForbiddenThreadId) {
+    throw codexRenewalThreadError(
+      errorCode,
+      "The renewed session cannot reuse the old session's assistant thread.",
+      { forbiddenThreadId: normalizedForbiddenThreadId }
+    );
+  }
+  if (
+    typeof provider?.ensureRuntime !== "function" ||
+    typeof provider?.resumeThread !== "function" ||
+    typeof provider?.readThread !== "function" ||
+    typeof provider?.startThread !== "function"
+  ) {
+    throw codexRenewalThreadError(
+      errorCode,
+      "The assistant provider cannot prove a genuinely fresh renewal thread."
+    );
+  }
+  const appServerRuntime = await provider.ensureRuntime();
+  const config = projectHooks
+    ? await codexAppServerProjectHookTrustConfig(provider, normalizedWorkdir)
+    : null;
+  const { threadSettings, threadStartSettings } = await settings(normalizedWorkdir, config);
+  let fresh = false;
+  let thread = null;
+  let threadSnapshot = null;
+  let baselineThreadIds = Object.freeze([]);
+  if (resumableThreadId) {
+    try {
+      thread = await provider.resumeThread(resumableThreadId, threadSettings);
+      const resumedThreadId = codexAppServerThreadResponseId(thread, resumableThreadId);
+      if (resumedThreadId !== resumableThreadId) {
+        throw codexRenewalThreadError(
+          errorCode,
+          "The assistant provider resumed a different renewal thread.",
+          {
+            expectedThreadId: resumableThreadId,
+            resumedThreadId
+          }
+        );
+      }
+      threadSnapshot = await readCodexRenewalSuccessorThreadSnapshot({
+        provider,
+        threadId: resumableThreadId,
+        workdir: normalizedWorkdir,
+        errorCode
+      });
+    } catch (error) {
+      if (
+        error?.code === errorCode ||
+        codexAppServerRequestIsInvalid(error, "thread/resume") ||
+        codexAppServerRequestIsInvalid(error, "thread/read")
+      ) {
+        if (error?.code === errorCode) {
+          throw error;
+        }
+        throw codexRenewalThreadError(
+          errorCode,
+          `The previously started renewal thread is no longer readable; ${applicationName} will not replace it silently.`,
+          {
+            expectedThreadId: resumableThreadId,
+            providerError: normalizeAgentText(error?.message)
+          }
+        );
+      }
+      throw error;
+    }
+  } else {
+    if (!normalizedOperationId) {
+      throw codexRenewalThreadError(
+        errorCode,
+        "Starting a fresh successor thread requires its exact renewal operation id."
+      );
+    }
+    baselineThreadIds = await identity.readBaseline();
+    if (!baselineThreadIds) {
+      baselineThreadIds = await listCodexRenewalThreadIds(
+        provider,
+        normalizedWorkdir,
+        errorCode
+      );
+      await identity.writeBaseline(baselineThreadIds);
+    }
+    const currentThreadIds = await listCodexRenewalThreadIds(
+      provider,
+      normalizedWorkdir,
+      errorCode
+    );
+    const baseline = new Set(baselineThreadIds);
+    const candidateThreadIds = currentThreadIds.filter((threadId) => !baseline.has(threadId));
+    if (candidateThreadIds.length > 1) {
+      throw codexRenewalThreadError(
+        errorCode,
+        `More than one unclaimed assistant thread appeared for this renewal; ${applicationName} will not guess which one is authoritative.`,
+        { candidateThreadIds }
+      );
+    }
+    if (candidateThreadIds.length === 1) {
+      const [candidateThreadId] = candidateThreadIds;
+      thread = await provider.resumeThread(candidateThreadId, threadSettings);
+      const resumedThreadId = codexAppServerThreadResponseId(thread, candidateThreadId);
+      if (resumedThreadId !== candidateThreadId) {
+        throw codexRenewalThreadError(
+          errorCode,
+          "The assistant provider resumed a different recovered renewal thread.",
+          {
+            expectedThreadId: candidateThreadId,
+            resumedThreadId
+          }
+        );
+      }
+      threadSnapshot = await readCodexRenewalSuccessorThreadSnapshot({
+        provider,
+        threadId: candidateThreadId,
+        workdir: normalizedWorkdir,
+        errorCode
+      });
+    } else {
+      thread = await provider.startThread(threadStartSettings);
+      fresh = true;
+    }
+  }
+  const threadId = codexAppServerThreadResponseId(thread, resumableThreadId);
+  if (
+    !threadId ||
+    threadId === normalizedForbiddenThreadId ||
+    (fresh && baselineThreadIds.includes(threadId))
+  ) {
+    throw codexRenewalThreadError(
+      errorCode,
+      threadId
+        ? "The assistant provider reused the old session's thread instead of starting a fresh one."
+        : "The assistant provider did not return a fresh renewal thread id.",
+      {
+        forbiddenThreadId: normalizedForbiddenThreadId,
+        threadId
+      }
+    );
+  }
+  await identity.write({ appServerRuntime, threadId, workdir: normalizedWorkdir });
+  if (fresh) {
+    try {
+      threadSnapshot = await readCodexRenewalSuccessorThreadSnapshot({
+        provider,
+        threadId,
+        workdir: normalizedWorkdir,
+        errorCode
+      });
+    } catch (error) {
+      throw codexRenewalThreadError(
+        errorCode,
+        `The newly started renewal thread cannot be read; ${applicationName} will not replace it silently.`,
+        {
+          providerError: normalizeAgentText(error?.message),
+          threadId
+        },
+        { retryable: true }
+      );
+    }
+  }
+  return Object.freeze({
+    appServerRuntime,
+    fresh,
+    thread,
+    threadId,
+    threadSnapshot,
+    threadStartSettings,
+    threadSettings
+  });
+}