@jskit-ai/assistant-core 0.1.213 → 0.1.214

package/src/server/conversation/codexOutput.js

@@ -37,6 +37,7 @@ export function createCodexAppServerOutput({
   debugLog,
   debugError,
   liveProgressMaxLength,
+  persistCommentary = true,
   storeReadError,
   messageMetadata,
   snapshotRecoveryItemLimit
@@ -639,24 +640,28 @@ export function createCodexAppServerOutput({
       const writer = role === "commentary"
         ? store.writeConversationCommentaryMessage
         : store.writeConversationThinkingMessage;
-      written = await writer.call(store, normalizedSessionId, {
-        ...(streamMessageId ? { outputId: streamMessageId } : {}),
-        messageId: codexAppServerConversationMessageId(
-          normalizedThreadId,
-          codexAppServerNotificationTurnId(notification) || turn.turnId,
-          role,
+      if (role !== "commentary" || persistCommentary) {
+        written = await writer.call(store, normalizedSessionId, {
+          ...(streamMessageId ? { outputId: streamMessageId } : {}),
+          messageId: codexAppServerConversationMessageId(
+            normalizedThreadId,
+            codexAppServerNotificationTurnId(notification) || turn.turnId,
+            role,
+            text
+          ),
+          requireOpenTurn: false,
+          nativeIdentity: { threadId: normalizedThreadId, turnId: codexAppServerNotificationTurnId(notification) || turn.turnId },
           text
-        ),
-        requireOpenTurn: false,
-        nativeIdentity: { threadId: normalizedThreadId, turnId: codexAppServerNotificationTurnId(notification) || turn.turnId },
-        text
-      });
-      if (!written) {
-        codexAppServerLiveProgressItems.delete(key);
-        codexAppServerLiveProgressFingerprints.delete(fingerprintKey);
+        });
+        if (!written) {
+          codexAppServerLiveProgressItems.delete(key);
+          codexAppServerLiveProgressFingerprints.delete(fingerprintKey);
+        }
       }
       const payload = {
-        conversationStream: store.completeConversationStreamMessage(normalizedSessionId, streamMessageId)
+        conversationStream: await store.completeConversationStreamMessage(normalizedSessionId, streamMessageId, {
+          text, role, nativeIdentity: { threadId: normalizedThreadId, turnId: codexAppServerNotificationTurnId(notification) || turn.turnId }
+        })
       };
       if (written) {
         payload.conversationLogPatch = { turn: written, type: "upsert-turn" };

package/src/server/conversation/codexProvider.js

@@ -16,7 +16,7 @@ import {
 import { prepareCodexHistory } from "./codexHistoryAdapter.js";
 import { createCodexConversationAdapter } from "./providers/codex.js";
 import { exportCodexNativeHistory } from "./codexNativeHistoryExport.js";
-import { retireNativeConversation } from "./nativeHistoryExport.js";
+import { retireNativeConversation, readStoppedNativeDatabase } from "./nativeHistoryExport.js";
 import { isPlainObject, normalizeText as normalizeAgentText } from "./normalize.js";
 import {
   codexAppServerProviderThreadTurns,
@@ -135,6 +135,41 @@ async function retireCodexConversationHistory(provider, binding, {
     remove: () => provider.deleteThread(binding.conversationId) });
 }
 
+// Native Codex0.159.1 keeps goals in its separate goals_1.sqlite store.
+// Return its original SQL fields; the host owns stopped conversion eligibility,
+// including rejecting active/blocked/limited goals and resolving SQLite home.
+async function readCodexNativeGoal(databasePath, { threadId, signal } = {}) {
+  if (!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/u.test(threadId || "") ||
+      path.basename(databasePath || "") !== "goals_1.sqlite") {
+    throw new TypeError("Codex goal inspection requires its exact thread ID and supported goals_1.sqlite path.");
+  }
+  return readStoppedNativeDatabase(databasePath, database => {
+    const columns = database.prepare("PRAGMA table_info(thread_goals)").all();
+    const text = ["thread_id", "goal_id", "objective", "status"];
+    const integers = ["token_budget", "tokens_used", "time_used_seconds", "created_at_ms", "updated_at_ms"];
+    if (!columns.some(column => column.name === "thread_id" && column.pk === 1) ||
+        text.some(name => !columns.some(column => column.name === name && column.type === "TEXT")) ||
+        integers.some(name => !columns.some(column => column.name === name && column.type === "INTEGER"))) {
+      throw new Error("Codex's saved native goal schema is unsupported; no history was changed.");
+    }
+    const rows = database.prepare(`SELECT thread_id, goal_id, objective, status, token_budget,
+      tokens_used, time_used_seconds, created_at_ms, updated_at_ms
+      FROM thread_goals WHERE thread_id = ? LIMIT 2`).all(threadId);
+    if (!rows.length) return null;
+    const row = rows[0];
+    if (rows.length !== 1 || row.thread_id !== threadId ||
+        !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/u.test(row.goal_id || "") ||
+        typeof row.objective !== "string" ||
+        !["active", "paused", "blocked", "usage_limited", "budget_limited", "complete"].includes(row.status) ||
+        row.token_budget !== null && (!Number.isSafeInteger(row.token_budget) || row.token_budget < 0) ||
+        ["tokens_used", "time_used_seconds", "created_at_ms", "updated_at_ms"].some(key =>
+          !Number.isSafeInteger(row[key]) || row[key] < 0)) {
+      throw new Error("Codex's saved native goal is unsupported or ambiguous; no history was changed.");
+    }
+    return row;
+  }, { signal });
+}
+
 async function codexAppServerThreadHasReadableHistory(provider = null, threadId = "") {
   const normalizedThreadId = normalizeAgentText(threadId);
   if (!normalizedThreadId || typeof provider?.readThread !== "function") {
@@ -2025,7 +2060,9 @@ export class CodexAppServerAgentProvider {
       throw new TypeError("Codex tool dispatch requires its exact thread and handler.");
     }
     if (this.threadRequestHandlers.has(threadId)) throw new Error("This Codex thread already has an application tool owner.");
-    const registration = { handler };
+    const runInContext = this.options.runInContext;
+    const registration = { handler: typeof runInContext === "function"
+      ? request => runInContext(() => handler(request)) : handler };
     this.threadRequestHandlers.set(threadId, registration);
     const client = this.client;
     client?.setRequestHandler?.(request => this.handleServerRequest(request, client));
@@ -2768,7 +2805,7 @@ export {
   codexAppServerThreadHasReadableHistory, deleteCodexAppServerThread, deleteCodexAppServerHelperThread,
   inspectCodexAppServerMessageAdmission,
   codexCliResumeCommand, codexLocalImageInput, codexTextInput, codexTurnInput, shellQuote,
-  exportCodexNativeHistory, retireCodexConversationHistory
+  exportCodexNativeHistory, retireCodexConversationHistory, readCodexNativeGoal
 };
 export {
   createCodexAppServerProviderOwner,

package/src/server/conversation/codexProviderOwner.js

@@ -231,6 +231,7 @@ export function createCodexAppServerProviderOwner({
       create: onObservationLost => {
         const parameters = {
           ...prepared.parameters,
+          runInContext: prepared.runInContext,
           onClose() { unsubscribeControls?.(); },
           beforeResumeThread(threadId) {
             return prepared.runInContext(async () => {
@@ -561,12 +562,120 @@ export function createCodexAppServerProviderOwner({
     });
   }
 
+  async function invalidateProviderThreads(modelProviderId, includeOwned, toolHomeSource) {
+    const groups = new Map();
+    const inventory = [...providerRecords()];
+    if (includeOwned) for (const record of codexAppServerOwnedRuntimes.values()) {
+      if (!inventory.some(candidate => candidate.provider === record.provider)) inventory.push(record);
+    }
+    for (const record of inventory) {
+      if (!inScope(record)) continue;
+      const key = codexAppServerOwnedRuntimeKey(record.providerKey, record.providerOptions);
+      if (!groups.has(key)) groups.set(key, []);
+      groups.get(key).push(record);
+    }
+    const results = [], failed = [];
+    for (const [runtimeKey, peers] of groups) {
+      try {
+        await withRuntimeLifecycle(runtimeKey, async () => {
+          const available = peers.filter(record => record.provider.client?.isOpen());
+          if (!available.length) {
+            if (peers.some(record => record.provider.runtime || record.provider.runtimeStopOwner ||
+                codexAppServerOwnedRuntimes.get(runtimeKey)?.provider === record.provider)) {
+              throw new Error("Codex's existing control connection is unavailable. Restore it before changing this provider connection.");
+            }
+            return;
+          }
+          const request = (record, method, params) => {
+            const client = record.provider.client;
+            if (!client?.isOpen()) throw new Error("Codex's control connection closed during provider retirement. Restore it and retry.");
+            return client.request(method, params, { signal: AbortSignal.timeout(5_000) });
+          };
+          const selectedHome = normalizeText(toolHomeSource);
+          const dedicated = Boolean(selectedHome && peers.some(record =>
+            normalizeText(record.providerOptions.toolHomeSource) === selectedHome));
+          if (dedicated && peers.some(record => normalizeText(record.providerOptions.toolHomeSource) !== selectedHome)) {
+            throw new Error("Codex's provider credential home has other native consumers. Close its native terminal/helper and retry; unrelated runtimes remain running.");
+          }
+          const inspector = available[0], candidates = new Set(), seen = new Set();
+          let cursor;
+          do {
+            const page = await request(inspector, "thread/loaded/list", { limit: 100, ...(cursor ? { cursor } : {}) });
+            if (!Array.isArray(page?.data)) throw new Error("Codex returned an invalid loaded-thread inventory. Restore its connection before retrying.");
+            for (const id of page.data) {
+              if (typeof id !== "string" || !id) throw new Error("Codex returned an invalid loaded-thread identity.");
+              candidates.add(id);
+            }
+            cursor = page.nextCursor;
+            if (cursor && (typeof cursor !== "string" || seen.has(cursor) || seen.size >= 100)) throw new Error("Codex's loaded-thread inventory did not finish.");
+            if (cursor) seen.add(cursor);
+          } while (cursor);
+          for (const { provider } of peers) for (const [id, binding] of provider.threadEnvironments || []) {
+            if (dedicated || binding.params?.modelProvider === modelProviderId) candidates.add(id);
+          }
+          const threadIds = [];
+          for (const id of candidates) {
+            const { thread } = await request(inspector, "thread/read", { threadId: id, includeTurns: false });
+            if (!thread || thread.id !== id || typeof thread.modelProvider !== "string" || !thread.modelProvider ||
+                !(typeof thread.status === "string" ? thread.status : thread.status?.type)) {
+              throw new Error("Codex returned an untrustworthy thread/provider inventory. Restore its connection before changing credentials.");
+            }
+            if (dedicated && thread.modelProvider !== modelProviderId) {
+              throw new Error("Codex's provider credential home retains another provider thread. Close its native terminal/helper and retry; unrelated threads remain running.");
+            }
+            if (thread.modelProvider === modelProviderId) threadIds.push(id);
+          }
+          if (!threadIds.length && !dedicated) return;
+          const error = Object.assign(new Error("This Codex provider connection changed. Work is stopped; use Send or Resume after reconnecting."), {
+            code: "codex_provider_connection_changed"
+          });
+          for (const { provider } of peers) for (const threadId of threadIds) provider.conversationRuntime?.invalidateThread(threadId);
+          await Promise.allSettled(peers.flatMap(({ provider }) => threadIds
+            .map(id => provider.threadEnvironmentTasks?.get(id)).filter(Boolean)));
+          // The same observation journal retains selected stop ownership. Peers
+          // with other threads must keep their admission and active work intact.
+          for (const record of available) await record.observation?.prepare({ provider: record.provider, error, threadIds });
+          for (const threadId of threadIds) {
+            await inspector.provider.stopThreadForObservationLoss(threadId);
+            for (const record of available) {
+              const detached = await request(record, "thread/unsubscribe", { threadId });
+              if (!["unsubscribed", "notSubscribed", "notLoaded"].includes(detached?.status)) throw new Error("Codex did not confirm selected-thread detachment.");
+            }
+            const { thread } = await request(inspector, "thread/read", { threadId, includeTurns: false });
+            if ((typeof thread?.status === "string" ? thread.status : thread?.status?.type) !== "notLoaded") {
+              throw new Error("Close the native Codex terminal using this provider, then retry changing its connection. Another subscriber retained the selected thread; the shared server and other conversations remain running.");
+            }
+          }
+          if (dedicated) {
+            // A curated default also lives in this exact isolated helper's
+            // native config cache. Reuse verified retirement only after proving
+            // every loaded/cached thread belongs to the selected provider.
+            const owned = codexAppServerOwnedRuntimes.get(runtimeKey);
+            if (!owned || !peers.some(record => record.provider === owned.provider)) {
+              throw new Error("Codex's dedicated provider runtime ownership cannot be verified. Restore its control connection and retry.");
+            }
+            await owned.scope.stopOwnedRuntime(owned, { cached: false, preserveProcessExitProof: true, requireVerifiedExit: true });
+          }
+          for (const record of available) await record.observation?.complete({ provider: record.provider, error, threadIds, sharedStop: dedicated });
+          if (dedicated) for (const record of peers) record.scope.closeProvider(record.providerKey);
+          results.push({ runtimeKey, threadIds, stopped: true, sharedProcessRetained: !dedicated,
+            ...(dedicated ? { dedicatedRuntimeRetired: true } : {}) });
+        });
+      } catch (error) {
+        failed.push({ runtimeKey, error: error.message, retryable: true });
+      }
+    }
+    return { ok: failed.length === 0, failed, results, providerCount: results.length, stopped: results.reduce((sum, result) => sum + result.threadIds.length, 0) };
+  }
+
   async function invalidateRuntimes({
     includeOwned = false,
     requireVerifiedExit = false,
     stopOwnedRuntimes = false,
-    toolHomeSource = ""
+    toolHomeSource = "",
+    modelProviderId = ""
   } = {}) {
+    if (modelProviderId) return withLifecycle(() => invalidateProviderThreads(modelProviderId, includeOwned, toolHomeSource));
     codexAppServerChatModelCatalog = null;
     const normalizedToolHomeSource = normalizeText(toolHomeSource);
     const ownedRecordsByProvider = new Map(

package/src/server/conversation/codexTurn.js

@@ -93,6 +93,7 @@ export function createCodexAppServerRunOwner({
   idlePublishPayload = null,
   checkpoint = async () => null,
   messageMetadata = {},
+  persistCommentary = true,
   deliveryStateMetadataKey = "assistant_delivery",
   hasRuntime = () => true,
   recoverAdmission = null,
@@ -117,6 +118,7 @@ export function createCodexAppServerRunOwner({
   interruptFailedCode = "codex_turn_interrupt_failed",
   errorPrefix = ""
 } = {}) {
+  if (typeof persistCommentary !== "boolean") throw new TypeError("Invalid Codex commentary persistence policy.");
   if (!Number.isSafeInteger(finalizingGraceMs) || finalizingGraceMs < 1) {
     throw new TypeError("Invalid Codex finalizing grace.");
   }
@@ -195,6 +197,7 @@ export function createCodexAppServerRunOwner({
     debugLog,
     debugError,
     liveProgressMaxLength,
+    persistCommentary,
     storeReadError,
     messageMetadata,
     snapshotRecoveryItemLimit

package/src/server/conversation/continuity.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { isCompletedEnvelopeTurn } from "./transcript.js";
 
 // A final answer keeps its identity when an application edits its visible text.
 export function conversationMessageIdentity(turnId, message) {
@@ -15,7 +16,13 @@ export function conversationMessageVersion(message, { includeData = false } = {}
 
 /** Keep native delivery and its history cursor in the same durable record. */
 export function createConversationChangeover({ state, transcript, agent, identity, presentation = {}, log = () => {},
-  captureContext = false, applicationMessages = false }) {
+  captureContext = false, applicationMessages = false, maximumInitialMessages = 30,
+  maximumInitialMessageCharacters = Infinity }) {
+  if (!Number.isSafeInteger(maximumInitialMessages) || maximumInitialMessages < 0 ||
+      maximumInitialMessageCharacters !== Infinity &&
+      (!Number.isSafeInteger(maximumInitialMessageCharacters) || maximumInitialMessageCharacters < 1)) {
+    throw new TypeError("Initial native history requires a non-negative message limit and a positive text limit.");
+  }
   const {
     label = "Conversation changeover",
     applicationName = "the application",
@@ -100,7 +107,13 @@ export function createConversationChangeover({ state, transcript, agent, identit
       code: unconfirmedCode, messageId, threadId, error: unconfirmedMessage };
   }
 
-  async function send({ engineId, messages, input, turnMetadata }) {
+  async function send({ engineId, messages, input, turnMetadata, completedEnvelope = false, excludedMessageIds = [] }) {
+    if (typeof completedEnvelope !== "boolean" || !Array.isArray(excludedMessageIds) ||
+        excludedMessageIds.some(id => typeof id !== "string" || !id.trim() || id.length > 128) ||
+        new Set(excludedMessageIds).size !== excludedMessageIds.length || excludedMessageIds.length && !completedEnvelope) {
+      throw new TypeError("Native history exclusions require a tracked completed envelope and exact message IDs.");
+    }
+    const excluded = new Set(excludedMessageIds);
     const value = await readState({ engineId, messages });
     const binding = value.engines[engineId] ||= { seen: {} };
     rememberReplies(value, engineId, messages);
@@ -165,17 +178,19 @@ export function createConversationChangeover({ state, transcript, agent, identit
     const snapshot = Object.fromEntries(messages.map((message) => [message.id, message.version]));
     const returning = Object.keys(binding.seen).length > 0;
     const changed = messages.filter((message) => binding.seen[message.id] !== message.version);
+    const renderChanged = changed.filter(message => !excluded.has(message.messageId));
     const deleted = Object.keys(binding.seen).filter((id) => !Object.hasOwn(snapshot, id));
     const switched = value.lastEngine !== engineId;
     // A new native conversation gets the recent bubbles. A returning one gets
     // every missed/edited bubble, even if the edit is older than that window.
-    const catchup = returning ? changed : messages.slice(-30);
+    const catchup = (returning ? changed : maximumInitialMessages ? messages.slice(-maximumInitialMessages) : [])
+      .filter(message => !excluded.has(message.messageId));
     let pending = binding.pending;
     if (pending && pending.messageId !== input.messageId) {
       delete binding.pending;
       pending = null;
     }
-    if (!pending && (switched || changed.length || deleted.length)) {
+    if (!pending && (switched || renderChanged.length || deleted.length)) {
       const handover = value.replacement?.engineId === engineId && value.replacement.status === "ready"
         ? value.replacement.handover : "";
       const preamble = [
@@ -187,7 +202,10 @@ export function createConversationChangeover({ state, transcript, agent, identit
         ...(handover ? ["This is a fresh native context. Earlier native history remains separate. The saved continuity briefing follows:",
           JSON.stringify({ handover })] : []),
         JSON.stringify({ messages: catchup.map(({ version, originalVersion, receipt, ...message }) => ({
-          ...message, ...(binding.seen[message.id] ? { corrected: true } : {})
+          ...message,
+          ...(!returning && typeof message.text === "string" && message.text.length > maximumInitialMessageCharacters
+            ? { text: message.text.slice(0, maximumInitialMessageCharacters) } : {}),
+          ...(binding.seen[message.id] ? { corrected: true } : {})
         })), removedMessageIds: deleted }),
         `[End ${label}]`,
         "",
@@ -247,7 +265,7 @@ export function createConversationChangeover({ state, transcript, agent, identit
 }
 
 function writtenMessages(history, native = false) {
-  return history.flatMap(turn => (turn.messages || []).filter(message => message.role !== "thinking")
+  return history.filter(turn => !isCompletedEnvelopeTurn(turn)).flatMap(turn => (turn.messages || []).filter(message => message.role !== "thinking")
     .map(message => ({ id: conversationMessageIdentity(turn.turnId, message),
       role: message.role === "system" && turn.metadata?.runtime?.origin === "application" ? "application" : message.role,
       messageId: message.messageId, text: message.text,

package/src/server/conversation/index.js

@@ -1,5 +1,5 @@
 export { createConversationTranscript } from "./transcript.js";
-export { conversationMessageIdentity, conversationMessageVersion, createConversationChangeover } from "./continuity.js";
+export { conversationMessageIdentity, conversationMessageVersion, conversationHistoryVersions, createConversationChangeover, conversationRequestText } from "./continuity.js";
 export { createMemoryConversationStorage } from "./memoryStorage.js";
 export { createConversationStorage, createReentrantConversationStorage,
   createConversationOperationLease, beginConversationOperation, finishConversationOperation } from "./storage.js";

package/src/server/conversation/nativeHistoryExport.js

@@ -1,6 +1,103 @@
 import path from "node:path";
+import { chmod, copyFile, lstat, mkdtemp, open, realpath, rm } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { tmpdir } from "node:os";
+import { pathToFileURL } from "node:url";
 import { createHash } from "node:crypto";
 
+// Providers retain their grammar; stopped file custody belongs to this owner.
+// Immutable reads require no journal. A valid stopped WAL is read from private
+// copies so SQLite can build its own SHM without touching native storage.
+export async function readStoppedNativeDatabase(databasePath, read, { signal } = {}) {
+  if (!path.isAbsolute(databasePath || "") || typeof read !== "function") {
+    throw new TypeError("Native inspection requires an absolute database path and reader.");
+  }
+  const journalError = () => new Error("Native storage still has a journal sidecar that cannot be inspected safely. Keep its original storage owner stopped; inspection does not checkpoint or remove it.");
+  const inspect = async () => {
+    const files = {};
+    for (const suffix of ["", "-wal", "-shm", "-journal"]) {
+      signal?.throwIfAborted();
+      const file = `${databasePath}${suffix}`;
+      let info;
+      try { info = await lstat(file); }
+      catch (error) { if (suffix && error.code === "ENOENT") continue; throw error; }
+      if (!info.isFile() || info.isSymbolicLink() || await realpath(file) !== file) {
+        throw new Error("Native storage must be a regular file at its original canonical path.");
+      }
+      files[suffix] = info;
+    }
+    if (files["-journal"] || Boolean(files["-wal"]) !== Boolean(files["-shm"])) throw journalError();
+    return files;
+  };
+  const before = await inspect();
+  const fingerprint = async file => {
+    const hash = createHash("sha256");
+    try {
+      for await (const chunk of createReadStream(file, { signal })) hash.update(chunk);
+      return hash.digest("hex");
+    } catch (error) {
+      if (signal?.aborted) throw signal.reason;
+      throw error;
+    }
+  };
+  const unchanged = async (digests = null) => {
+    const after = await inspect();
+    if (JSON.stringify(Object.keys(before)) !== JSON.stringify(Object.keys(after)) ||
+        Object.keys(before).some(suffix => ["dev", "ino", "size", "mtimeMs", "ctimeMs", "mode"].some(key => before[suffix][key] !== after[suffix][key]))) {
+      throw new Error("Native storage changed during inspection. Keep all of its writers stopped before retrying.");
+    }
+    if (digests) for (const suffix of Object.keys(before)) {
+      if (await fingerprint(`${databasePath}${suffix}`) !== digests[suffix]) {
+        throw new Error("Native storage changed during inspection. Keep all of its writers stopped before retrying.");
+      }
+    }
+  };
+  const { DatabaseSync } = await import("node:sqlite");
+  let directory;
+  let database;
+  let result;
+  let digests;
+  try {
+    signal?.throwIfAborted();
+    let target = `${pathToFileURL(databasePath).href}?mode=ro&immutable=1`;
+    if (before["-wal"]) {
+      // Eligibility only: SQLite owns WAL frames, checksums and committed pages.
+      const header = Buffer.alloc(32);
+      const wal = await open(`${databasePath}-wal`, "r");
+      let bytesRead;
+      try { ({ bytesRead } = await wal.read(header, 0, header.length, 0)); }
+      finally { await wal.close(); }
+      const magic = header.readUInt32BE(0);
+      const pageSize = header.readUInt32BE(8);
+      if (bytesRead !== 32 || ![0x377f0682, 0x377f0683].includes(magic) || header.readUInt32BE(4) !== 3007000 ||
+          pageSize < 512 || pageSize > 65536 || (pageSize & (pageSize - 1)) !== 0 || before["-shm"].size < 32768) throw journalError();
+      digests = {};
+      for (const suffix of Object.keys(before)) digests[suffix] = await fingerprint(`${databasePath}${suffix}`);
+      await unchanged(digests);
+      directory = await mkdtemp(path.join(tmpdir(), "assistant-native-snapshot-"));
+      const snapshot = path.join(directory, "native.db");
+      for (const suffix of ["", "-wal"]) {
+        signal?.throwIfAborted();
+        await copyFile(`${databasePath}${suffix}`, `${snapshot}${suffix}`);
+        await chmod(`${snapshot}${suffix}`, 0o600);
+        if (await fingerprint(`${snapshot}${suffix}`) !== digests[suffix]) throw new Error("Native storage changed while copying its stopped snapshot.");
+      }
+      await unchanged(digests);
+      target = `${pathToFileURL(snapshot).href}?mode=ro`;
+    }
+    database = new DatabaseSync(target, { readOnly: true });
+    database.exec("PRAGMA query_only=ON; BEGIN");
+    result = await read(database);
+    signal?.throwIfAborted();
+    database.exec("ROLLBACK");
+    await unchanged(digests);
+  } finally {
+    try { database?.close(); }
+    finally { if (directory) await rm(directory, { recursive: true, force: true }); }
+  }
+  return result;
+}
+
 export function canonicalNativeHistoryJson(value) {
   return JSON.stringify(value, (_key, entry) => entry && typeof entry === "object" && !Array.isArray(entry)
     ? Object.fromEntries(Object.keys(entry).sort().map((key) => [key, entry[key]])) : entry);

package/src/server/conversation/openCodeClient.js

@@ -1,7 +1,7 @@
 import { pathToFileURL } from "node:url";
 import { Buffer } from "node:buffer";
 import path from "node:path";
-import { createNativeHistoryExport, retireNativeConversation } from "./nativeHistoryExport.js";
+import { createNativeHistoryExport, readStoppedNativeDatabase, retireNativeConversation } from "./nativeHistoryExport.js";
 
 const OPENCODE_RESPONSE_LIMIT_BYTES = 2 * 1024 * 1024;
 const OPENCODE_CATALOG_LIMIT_BYTES = 32 * 1024 * 1024;
@@ -122,6 +122,51 @@ function normalizedMessageRows(value = null) {
   });
 }
 
+/** Inspect stopped native storage without starting OpenCode or changing its files. */
+async function readOpenCodeConversationDatabase({ databasePath, conversationId, onMessage, signal } = {}) {
+  if (!path.isAbsolute(databasePath || "") || !/^ses_[a-zA-Z0-9_]{1,256}$/u.test(conversationId || "") ||
+      typeof onMessage !== "function") throw new TypeError("OpenCode inspection requires its exact database, conversation and message reader.");
+  const unavailable = () => new Error("OpenCode native storage could not be inspected completely. Keep its writers stopped and inspect its original database before retrying.");
+  try {
+    return await readStoppedNativeDatabase(databasePath, async database => {
+      const session = database.prepare("SELECT * FROM session WHERE id = ?").get(conversationId);
+      if (!session || session.id !== conversationId || !path.isAbsolute(session.directory || "")) throw unavailable();
+      if (database.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'session_input'").get() &&
+          database.prepare("SELECT 1 FROM session_input WHERE session_id = ? AND promoted_seq IS NULL LIMIT 1").get(conversationId)) {
+        throw new Error("OpenCode has an unpromoted native request. Inspect it before restoring continuity; no request was repeated.");
+      }
+      const output = createNativeHistoryExport(async ({ message }) => onMessage(normalizedMessageRows([message])[0]), { signal });
+      const parts = database.prepare("SELECT id, message_id, session_id, data FROM part WHERE message_id = ? ORDER BY id");
+      for (const row of database.prepare("SELECT id, session_id, data FROM message WHERE session_id = ? ORDER BY time_created, id").iterate(conversationId)) {
+        signal?.throwIfAborted();
+        if (!/^msg_[a-zA-Z0-9_]{1,256}$/u.test(row.id)) throw unavailable();
+        let bytes = Buffer.byteLength(row.data);
+        if (bytes > 64 * 1024 * 1024) throw unavailable();
+        const data = JSON.parse(row.data);
+        if (!data || typeof data !== "object" || Array.isArray(data) || !["user", "assistant"].includes(data.role)) throw unavailable();
+        const content = [];
+        for (const part of parts.iterate(row.id)) {
+          signal?.throwIfAborted();
+          bytes += Buffer.byteLength(part.data);
+          if (bytes > 64 * 1024 * 1024 || part.session_id !== conversationId || part.message_id !== row.id ||
+              !/^prt_[a-zA-Z0-9_]{1,256}$/u.test(part.id)) throw unavailable();
+          const value = JSON.parse(part.data);
+          if (!value || typeof value !== "object" || Array.isArray(value)) throw unavailable();
+          content.push({ ...value, id: part.id, sessionID: part.session_id, messageID: part.message_id });
+        }
+        // Same original MessageV2 storage projection: native columns own IDs.
+        await output.emit({ type: "message", message: { info: { ...data, id: row.id, sessionID: row.session_id }, parts: content }, text: [] });
+      }
+      return { session, ...output.complete() };
+    }, { signal });
+  } catch (error) {
+    if (signal?.aborted) throw signal.reason;
+    if (String(error?.message || "").startsWith("OpenCode ") ||
+        String(error?.message || "").startsWith("Native storage ")) throw error;
+    throw unavailable();
+  }
+}
+
 function providerCapabilityMedia(value = null) {
   const source = record(value);
   return Object.fromEntries([
@@ -710,6 +755,7 @@ async function retireOpenCodeConversationHistory(storageClient, controlClient, b
 }
 
 export {
+  readOpenCodeConversationDatabase,
   retireOpenCodeConversationHistory,
   openCodeAssistantMessageText,
   OPENCODE_RESPONSE_LIMIT_BYTES,