@jskit-ai/assistant-core 0.2.0 → 0.2.2

package/examples/conversation/package.json

@@ -8,7 +8,7 @@
     "build": "vite build"
   },
   "dependencies": {
-    "@jskit-ai/assistant-core": "0.2.0",
+    "@jskit-ai/assistant-core": "0.2.2",
     "@jskit-ai/http-runtime": "0.2.0",
     "@jskit-ai/kernel": "0.2.0",
     "@mdi/js": "^7.4.47",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant-core",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "scripts": {
     "test": "node --test --test-concurrency=1"

package/src/server/conversation/claudeProcess.js

@@ -10,6 +10,8 @@ import { CLAUDE_APPLICATION_TOOL_SERVER } from "./claudeTools.js";
 import { nativeCommandHook, validateCommandWrapper } from "./commandWrapper.js";
 
 const statusReads = new WeakMap();
+const STATUS_REUSE_MS = 30_000;
+const STATUS_UNFINISHED_GRACE_MS = 5 * 60_000;
 const CLAUDE_EXIT_WAIT_MS = 5_000;
 
 /** Person-facing cause for a Claude process that ended without being stopped. */
@@ -51,12 +53,21 @@ export async function readClaudeCodeAuthStatus({
   const revision = JSON.stringify(revisions);
   const previous = reads.get(key);
   if (previous?.revision === revision && (previous.pending || previous.expiresAt > Date.now())) return previous.value;
-  const entry = { revision, pending: true, expiresAt: 0 };
+  // Claude's last answer for these exact account files.
+  const answered = previous?.revision === revision ? previous.answered : null;
+  const entry = { revision, pending: true, expiresAt: 0, answered };
   reads.set(key, entry);
-  entry.value = readNativeClaudeCodeAuthStatus({ env, credentialHome, command, commandRunner, signal }).then((status) => {
+  entry.value = readNativeClaudeCodeAuthStatus({ env, credentialHome, command, commandRunner, signal }).then(({ status, unfinished }) => {
+    // A read the host timed out or refused for now says nothing about the account.
+    const value = unfinished && answered && Date.now() - answered.at < STATUS_UNFINISHED_GRACE_MS
+      ? answered.status : Object.freeze(status);
     // Keychain changes cannot be observed with file metadata on macOS.
-    if (!status.error && process.platform !== "darwin") entry.expiresAt = Date.now() + 30_000;
-    return Object.freeze(status);
+    if (process.platform !== "darwin") {
+      // Unfinished reads back off too, so a busy host is not probed again by every caller.
+      if (!status.error || unfinished) entry.expiresAt = Date.now() + STATUS_REUSE_MS;
+      if (!status.error) entry.answered = { status: value, at: Date.now() };
+    }
+    return value;
   }).finally(() => { entry.pending = false; });
   return entry.value;
 }
@@ -67,6 +78,12 @@ async function readNativeClaudeCodeAuthStatus({ env, credentialHome, command, co
     credentialHome, cwd: credentialHome.home, mode: "capture",
     timeout: 30_000, maxBuffer: 64 * 1024, ...(signal ? { signal } : {})
   });
+  const status = claudeCodeAuthStatus(result);
+  return { status, unfinished: Boolean(status.error) && result.ok !== true &&
+    (result.timedOut === true || result.retryable === true) };
+}
+
+function claudeCodeAuthStatus(result) {
   const failure = result.error ? { loggedIn: false, error: result.error }
     : { loggedIn: false, error: "Claude Code is not connected.", messageCode: "assistant.claude.notConnected", messageParams: {} };
   if (!result.ok && (result.exitCode !== 1 || result.timedOut || result.signal)) return failure;
@@ -226,6 +243,32 @@ export function claudePlanUsage(value) {
     windows, checkedAt: Date.now() };
 }
 
+// Plan usage is read through a conversation's live process at most this often,
+// and otherwise through a one-shot Claude started only for the read.
+const PLAN_USAGE_LIVE_READ_MS = 60_000;
+const PLAN_USAGE_IDLE_READ_MS = 300_000;
+// A verified reading stays current until the next idle read, one client poll and
+// its read deadline could have replaced it.
+const PLAN_USAGE_CURRENT_MS = 420_000;
+
+/**
+ * Claude Code answers `get_usage` from the usage endpoint, or from its saved copy
+ * of that answer while under a minute old, including the endpoint's `limits` list.
+ * While that read fails or is held after a 429, it answers from the rate-limit
+ * headers of the answering process's last API response, which can be hours old,
+ * and omits `limits`. The answer has no age, so only one with `limits` is current.
+ */
+function claudePlanUsageVerified(value) {
+  return !value.rate_limits_available || Array.isArray(value.rate_limits?.limits);
+}
+
+function presentPlanUsage(reading) {
+  if (!reading) return { status: "unavailable", windows: [] };
+  if (reading.status !== "available") return reading;
+  const currentForMs = PLAN_USAGE_CURRENT_MS - (Date.now() - reading.checkedAt);
+  return currentForMs > 0 ? { ...reading, currentForMs } : { ...reading, status: "stale" };
+}
+
 export function claudeCatalogueModels(initialization) {
   return (initialization.models || []).map((model) => ({
     id: model.value, label: model.displayName || model.value, description: model.description || "",
@@ -242,7 +285,7 @@ export function createClaudeAccountQueries({ createProcess, accountIdentity, pro
   const accountReads = new Set();
   let catalog;
   const catalogStarts = new Map();
-  let planUsage;
+  const planUsage = new Map();
   const planUsagePending = new Map();
   let revision = 0;
 
@@ -257,12 +300,16 @@ export function createClaudeAccountQueries({ createProcess, accountIdentity, pro
     accountProcessStops.delete(native);
   }
 
-  async function readAccountProcess(identity, expectedRevision, purpose, read) {
+  function ownedProcess(identity) {
+    return [...processes()].find((entry) =>
+      entry.process && !entry.stopping && entry.accountIdentity === identity);
+  }
+
+  async function readAccountProcess(identity, expectedRevision, purpose, read, { borrow = true } = {}) {
     assertCurrent(expectedRevision);
     for (const native of accountProcessStops) await stopAccountProcess(native);
     assertCurrent(expectedRevision);
-    const owned = [...processes()].find((entry) =>
-      entry.process && !entry.stopping && entry.accountIdentity === identity);
+    const owned = borrow ? ownedProcess(identity) : null;
     const controller = new AbortController();
     accountReads.add(controller);
     const cancelled = Promise.withResolvers();
@@ -306,26 +353,50 @@ export function createClaudeAccountQueries({ createProcess, accountIdentity, pro
       assertCurrent(expectedRevision);
       const identity = await accountIdentity(context);
       assertCurrent(expectedRevision);
-      if (planUsage?.identity === identity && Date.now() - planUsage.checkedAt < 60_000) return planUsage;
       if (planUsagePending.has(identity)) return planUsagePending.get(identity);
+      // One reading per account; a started process is stopped after its read.
+      const usage = planUsage.get(identity) || { liveReadAt: -Infinity, temporaryReadAt: -Infinity, reading: null };
+      planUsage.set(identity, usage);
+      const live = Boolean(ownedProcess(identity));
+      const liveDue = live && Date.now() - usage.liveReadAt >= PLAN_USAGE_LIVE_READ_MS;
+      const temporaryDue = () => Date.now() - usage.temporaryReadAt >= PLAN_USAGE_IDLE_READ_MS;
+      if (!liveDue && (live || !temporaryDue())) return presentPlanUsage(usage.reading);
       const pending = (async () => {
-        const value = await readAccountProcess(identity, expectedRevision, "usage", (native) => native.client.request(
-          { subtype: "get_usage", skip_behaviors: true }));
-        if (identity !== await accountIdentity(context)) return { status: "unavailable", windows: [] };
-        assertCurrent(expectedRevision);
-        planUsage = { ...claudePlanUsage(value), identity };
-        return planUsage;
+        // A live process's held endpoint read is its own, so a fresh one-shot Claude
+        // may still reach the endpoint when the live answer cannot prove it is current.
+        for (const borrow of liveDue ? [true, false] : [false]) {
+          if (!borrow && !temporaryDue()) break;
+          usage[borrow ? "liveReadAt" : "temporaryReadAt"] = Date.now();
+          let value;
+          try {
+            value = await readAccountProcess(identity, expectedRevision, "usage", (native) => native.client.request(
+              { subtype: "get_usage", skip_behaviors: true }), { borrow });
+          } catch (cause) {
+            if (borrow || !liveDue) throw cause;
+            assertCurrent(expectedRevision);
+            break;
+          }
+          if (identity !== await accountIdentity(context)) return { status: "unavailable", windows: [] };
+          assertCurrent(expectedRevision);
+          // An answer that cannot prove it is current keeps the last verified reading.
+          if (claudePlanUsageVerified(value)) {
+            usage.reading = { ...claudePlanUsage(value), identity };
+            break;
+          }
+        }
+        return presentPlanUsage(usage.reading);
       })().finally(() => { planUsagePending.delete(identity); });
       planUsagePending.set(identity, pending);
       return pending;
     },
-    invalidateUsage() { planUsage = null; },
+    // A native usage change lets the next request read again without hiding the last reading.
+    invalidateUsage() { for (const usage of planUsage.values()) usage.liveReadAt = -Infinity; },
     async invalidate() {
       revision++;
       for (const controller of accountReads) controller.abort(error("Claude account query was cancelled for reconnection."));
       await Promise.allSettled([...catalogStarts.values(), ...planUsagePending.values()]);
       catalog = null;
-      planUsage = null;
+      planUsage.clear();
       for (const native of accountProcessStops) await stopAccountProcess(native);
     }
   });

package/src/server/conversation/claudeTurn.js

@@ -19,6 +19,14 @@ function hasPendingClaudeStartup(entry) {
   return entry.startupCleanup?.pending === true && entry.startupCleanup.executionId === entry.executionId;
 }
 
+// Claude records an admitted prompt in its history, and only a send in
+// progress writes prompts to a live process. With neither left, a prompt
+// missing from history can never arrive. A turn left marked active by a
+// lost process does not change that.
+function nativeWorkSettled(entry) {
+  return !entry.sending && !entry.process && !entry.executionId && !entry.command && !entry.stopPending;
+}
+
 export function claudeNativeMessageId(id) {
   const value = createHash("sha256").update(String(id)).digest("hex");
   return `${value.slice(0, 8)}-${value.slice(8, 12)}-4${value.slice(13, 16)}-8${value.slice(17, 20)}-${value.slice(20, 32)}`;
@@ -563,7 +571,13 @@ export function createClaudeConversationOwner({
       timeoutMessage: "Claude timed out summarising its context." });
   }
 
-  async function send(entry, input = {}, { renewal = false, command, applicationCommand } = {}) {
+  async function send(entry, ...args) {
+    entry.sending = (entry.sending || 0) + 1;
+    try { return await dispatchPrompt(entry, ...args); }
+    finally { entry.sending -= 1; }
+  }
+
+  async function dispatchPrompt(entry, input = {}, { renewal = false, command, applicationCommand } = {}) {
     const message = command ? input.text : text(input.message || input.prompt);
     if (!command && !message) throw createError("Enter a message for Claude.");
     const context = entry.context;
@@ -732,10 +746,11 @@ export function createClaudeConversationOwner({
     }
     const requestIds = new Map((input.requestMessageIds || [input.messageId]).filter(id => typeof id === "string" && id)
       .map(id => [claudeNativeMessageId(id), id]));
+    const admitted = history.userIds.includes(claudeNativeMessageId(input.messageId || ""));
     return { ...entry.nativeTurn.readResult(), ok: true,
       messages: [...messages.values()].map(message => ({ ...message,
         ...(message.userId ? { requestMessageId: requestIds.get(message.userId) || "" } : {}) })), text: current.text || history.text,
-      admitted: history.userIds.includes(claudeNativeMessageId(input.messageId || "")) };
+      admitted, notAdmitted: !admitted && Boolean(input.messageId) && nativeWorkSettled(entry) };
   }
 
   async function inspectAdmission(entry, input) {
@@ -743,7 +758,8 @@ export function createClaudeConversationOwner({
     const history = await readHistory(entry);
     const turnId = claudeNativeMessageId(input.messageId);
     const accepted = history.userIds.includes(turnId);
-    return { ok: true, admission: accepted ? "accepted" : "unknown", messageId: input.messageId,
+    const admission = accepted ? "accepted" : nativeWorkSettled(entry) ? "not-admitted" : "unknown";
+    return { ok: true, admission, messageId: input.messageId,
       threadId: entry.id, turnId: accepted ? turnId : "" };
   }
 
@@ -829,12 +845,28 @@ export function createClaudeConversationOwner({
     closing = true;
     try {
       await account.queries.invalidate().catch(account.failure);
-      return await closeProject(undefined, application);
+      return await stopRetained(application);
     } finally {
       closing = input.reason === "server-shutdown";
     }
   }
 
+  // Account changes and shutdown stop only what this server runs: a Claude
+  // process cannot outlive the server that started it, so retained entries
+  // hold every one. Saved conversations are not reopened just to be stopped.
+  async function stopRetained(application) {
+    const sessions = new Map([...entries.values()].map(entry => [entry.context.key, entry.context.sessionId]));
+    let closed = 0;
+    let ok = true;
+    for (const [key, sessionId] of sessions) {
+      closed += (await drain(key)).length;
+      const terminal = await application.terminals.close(sessionId);
+      closed += Number(terminal?.closed || 0);
+      ok &&= terminal?.ok !== false;
+    }
+    return { ok, closed };
+  }
+
   async function drain(key) {
     const selected = [...entries.values()].filter(entry => entry.context.key === key);
     // Startup already lends cleanup before initialization completes. Stop it
@@ -1139,7 +1171,7 @@ export function createClaudeConversationOwner({
     if (!bound) return { value: delivered.value };
   }
 
-  return Object.freeze({ applicationToolsSupported: true, entries, closingSessions, get closing() { return closing; }, createAccountQueries, open, acquire, createConversation, snapshot, readRetainedTurn, readFinalAssistantResult, readHistory, ensureReady, ensureProcess, readContextUsage, compactContext, releaseRetainedGoal, stopForTerminal, prepareTerminal, send, startTurn,
+  return Object.freeze({ applicationToolsSupported: true, entries, closingSessions, get closing() { return closing; }, createAccountQueries, open, acquire, createConversation, snapshot, readRetainedTurn, readFinalAssistantResult, readHistory, nativeWorkSettled, ensureReady, ensureProcess, readContextUsage, compactContext, releaseRetainedGoal, stopForTerminal, prepareTerminal, send, startTurn,
     interrupt, read, inspectAdmission, hasActiveTemporaryConversation, hasActiveConversation, retireConversationHistory, reconcileSessions, restoreSessionEntries, closeSession, closeProject, invalidateRuntimes, drain, forget, close, deleteConversation, recover, stopSelected, wait, stopConversation,
     readGoal, updateGoal, renewal, run, steer, cancel });
 }

package/src/server/conversation/codexProviderOwner.js

@@ -63,7 +63,8 @@ export function createCodexAppServerProviderOwner({
   runtimeBusyCode = "codex_app_server_runtime_busy",
   exitUnverifiedCode = "codex_runtime_exit_unverified",
   requiredStopCode = "codex_runtime_exit_unverified",
-  runtimeCloseError = "Codex app-server runtime close failed."
+  runtimeCloseError = "Codex app-server runtime close failed.",
+  transientIdleMs = 60_000
 } = {}) {
   const scopeRoot = normalizeText(runtimeRoot) ? path.resolve(runtimeRoot) : "";
   const records = new Map();
@@ -73,6 +74,8 @@ export function createCodexAppServerProviderOwner({
   let closing = false;
   let runtimeLifecycle = null;
   let codexAppServerChatModelCatalog = null;
+  // Providers borrowed by work that is not a conversation, terminal or helper.
+  const transientReleases = new Map();
 
   const providers = {
     get: key => records.get(key)?.provider,
@@ -274,7 +277,53 @@ export function createCodexAppServerProviderOwner({
     return provider;
   }
 
+  // A conversation, terminal or helper keeps a provider a storage read created.
+  // Every exported way to reach a provider for real use claims it here.
+  function claimTransient(providerKey = "") {
+    const key = normalizeText(providerKey);
+    const release = transientReleases.get(key);
+    if (!release) return;
+    clearTimeout(release.timer);
+    transientReleases.delete(key);
+  }
+
   async function ensureSession(context, mainThreadId = "") {
+    claimTransient(context.providerKey);
+    return acquireSession(context, mainThreadId);
+  }
+
+  // Native storage inventory and retirement borrow a session provider. A short
+  // idle after the last such use lets consecutive reads share one process; the
+  // release then stops it unless another provider still uses it.
+  async function withTransientSession(context, operation) {
+    const providerKey = context.providerKey;
+    let release = transientReleases.get(providerKey);
+    // An existing provider or a managed main thread already has a real user.
+    if (!release && (records.has(providerKey) || context.runOwner?.runtimeLifecycle?.managedThreadId?.(providerKey))) {
+      return operation(await acquireSession(context));
+    }
+    if (!release) transientReleases.set(providerKey, release = { users: 0, timer: null });
+    clearTimeout(release.timer);
+    release.users += 1;
+    try {
+      return await operation(await acquireSession(context));
+    } finally {
+      release.users -= 1;
+      if (release.users === 0 && transientReleases.get(providerKey) === release && !closing) {
+        release.timer = setTimeout(() => {
+          if (transientReleases.get(providerKey) !== release) return;
+          transientReleases.delete(providerKey);
+          if (closing) return;
+          stopCachedProvider(providerKey).catch(error => debugLog("appServerRuntime.transientRelease.error", {
+            error: debugError(error), providerKey
+          }));
+        }, transientIdleMs);
+        release.timer.unref?.();
+      }
+    }
+  }
+
+  async function acquireSession(context, mainThreadId = "") {
     const sessionId = context.sessionId;
     const providerOptions = context.providerOptions;
     const providerKey = context.providerKey;
@@ -1156,9 +1205,10 @@ export function createCodexAppServerProviderOwner({
     return { exitFailure };
   }
 
+  // A provider a storage read borrowed is not the session's conversation.
   async function readPlanUsage(sessionKey) {
     for (const [key, provider] of providers) {
-      if (providerOwners.get(key)?.sessionKey === sessionKey &&
+      if (providerOwners.get(key)?.sessionKey === sessionKey && !transientReleases.has(key) &&
           !provider.isHelperProvider() && provider.isAvailable()) {
         return provider.readPlanUsage();
       }
@@ -1169,7 +1219,7 @@ export function createCodexAppServerProviderOwner({
   async function readSessionGoal(sessionKey, threadId) {
     if (!threadId) return { status: "available", threadId: "", goal: null };
     for (const [key, provider] of providers) {
-      if (providerOwners.get(key)?.sessionKey === sessionKey &&
+      if (providerOwners.get(key)?.sessionKey === sessionKey && !transientReleases.has(key) &&
           !provider.isHelperProvider() && provider.isAvailable()) {
         const result = await provider.readGoal(threadId);
         return { status: "available", threadId, goal: result.goal || null };
@@ -1181,10 +1231,17 @@ export function createCodexAppServerProviderOwner({
   const api = Object.freeze({
     providers, providerOwners, ownedRuntimes, lifecycleTasks, runtimeAcquisitions,
     withLifecycle, runtimeIsShared, rememberOwnedRuntime, forgetOwnedRuntime, attachRuntimeLifecycle,
-    acquireRuntime, createProvider, createNativeProvider, providerForSession, ensureSession, retireAndCloseProvider, closeProvider, stopOwnedRuntime, stopCachedProvider, stopProvider, stopThreadBeforeRelease, readModelCatalog, invalidateRuntimes, recover,
+    acquireRuntime: options => { claimTransient(options?.providerKey); return acquireRuntime(options); },
+    createProvider: options => { claimTransient(options?.providerKey); return createProvider(options); },
+    providerForSession: context => { claimTransient(context.providerKey); return providerForSession(context); },
+    createNativeProvider, ensureSession, withTransientSession, retireAndCloseProvider, closeProvider, stopOwnedRuntime, stopCachedProvider, stopProvider, stopThreadBeforeRelease, readModelCatalog, invalidateRuntimes, recover,
     reportRecoveryEvent, pendingRecovery, readSessionGoal, readPlanUsage, stopCachedProvidersForSession, stopProvidersForProject, drainThreadEnvironmentTasks, stopPersistedRuntime, sessionExitProof,
     unsubscribeSessionThread, releasePersistedRuntimeProof, releasePreparedRuntimeProof, releaseSession,
-    beginShutdown() { closing = true; }
+    beginShutdown() {
+      closing = true;
+      for (const release of transientReleases.values()) clearTimeout(release.timer);
+      transientReleases.clear();
+    }
   });
   return api;
 }

package/src/server/conversation/continuity.js

@@ -122,7 +122,7 @@ export function createConversationChangeover({ state, transcript, agent, identit
       code: unconfirmedCode, messageId, threadId, error: unconfirmedMessage };
   }
 
-  async function send({ engineId, messages, input, turnMetadata, completedEnvelope = false, excludedMessageIds = [] }) {
+  async function send({ engineId, messages, input, turnMetadata, completedEnvelope = false, excludedMessageIds = [], inspectOnly = false }) {
     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) {
@@ -163,20 +163,28 @@ export function createConversationChangeover({ state, transcript, agent, identit
       const receipt = savedReceipt ? { admission: "accepted" } : await agent.inspectMessageAdmission({
         messageId: pending.messageId, threadId: pending.threadId
       }).catch(() => null);
-      if (receipt?.admission !== "accepted") {
+      if (receipt?.admission === "not-admitted") {
+        // The engine proved this attempt never arrived. It was not sent, so
+        // a send may dispatch it (or a newer message) without duplicating it.
+        pending.attempted = false;
+        await persist();
+        log({ event: "not-sent", engineId, messageId: pending.messageId, threadId: pending.threadId });
+        if (inspectOnly) return { ok: false, delivered: false, notSent: true, messageId: pending.messageId, threadId: pending.threadId };
+      } else if (receipt?.admission !== "accepted") {
         log({ event: "unconfirmed", engineId, messageId: pending.messageId, threadId: pending.threadId });
         return unconfirmed(pending.messageId, pending.threadId);
-      }
-      await transcript.writeUserMessage({
-        text: pending.displayMessage, messageId: pending.messageId,
-        attachments: pending.displayAttachments,
-        ...(pending.data !== undefined ? { data: pending.data } : {}),
-        turnMetadata: { ...pending.turnMetadata, ...turnMetadata }
-      });
-      await markDelivered(pending.seen);
-      log({ event: "accepted", engineId, messageId: pending.messageId, threadId: pending.threadId, recovered: true });
-      if (pending.messageId === input.messageId) {
-        return { ok: true, delivered: true, messageId: input.messageId, threadId: pending.threadId };
+      } else {
+        await transcript.writeUserMessage({
+          text: pending.displayMessage, messageId: pending.messageId,
+          attachments: pending.displayAttachments,
+          ...(pending.data !== undefined ? { data: pending.data } : {}),
+          turnMetadata: { ...pending.turnMetadata, ...turnMetadata }
+        });
+        await markDelivered(pending.seen);
+        log({ event: "accepted", engineId, messageId: pending.messageId, threadId: pending.threadId, recovered: true });
+        if (pending.messageId === input.messageId) {
+          return { ok: true, delivered: true, messageId: input.messageId, threadId: pending.threadId };
+        }
       }
     }
 

package/src/server/conversation/openCodeRuntime.js

@@ -169,7 +169,7 @@ export async function ensureOpenCodeSession(target, { selection, model, workdir
 
 // The production provider's users and pending acquisitions share this owner.
 // Hosts supply authorized startup inputs and their own publication/cleanup work.
-export function createOpenCodeSharedRuntime({ onStop = () => {}, scope } = {}) {
+export function createOpenCodeSharedRuntime({ onStop = () => {}, scope, storageIdleMs = 60_000 } = {}) {
   if (scope !== undefined && !path.isAbsolute(scope)) throw new TypeError("OpenCode runtime scopes require an absolute directory.");
   if (scope && sharedRuntimes.has(scope)) return sharedRuntimes.get(scope);
   const processes = new Map();
@@ -184,6 +184,8 @@ export function createOpenCodeSharedRuntime({ onStop = () => {}, scope } = {}) {
   let failedStartup = null;
   let closed = false;
   let connectionChanging = false;
+  let storageReads = 0;
+  let storageIdle = null;
 
   function requireConnectionAvailable() {
     if (connectionChanging) throw Object.assign(new Error("OpenCode is changing a connection. Retry after the connection change finishes."), {
@@ -291,6 +293,29 @@ export function createOpenCodeSharedRuntime({ onStop = () => {}, scope } = {}) {
     }
   }
 
+  // Native storage inventory and retirement borrow the shared server; they are
+  // not users that keep it running. A short idle after the last read lets one
+  // maintenance pass share it, then it stops unless a conversation uses it.
+  async function withStorageProcess(start, operation, failure = error => { throw error; }) {
+    clearTimeout(storageIdle);
+    storageIdle = null;
+    storageReads += 1;
+    try {
+      return await operation(await ensure(null, start).catch(failure));
+    } finally {
+      storageReads -= 1;
+      if (storageReads === 0 && !closed) {
+        storageIdle = setTimeout(() => {
+          storageIdle = null;
+          if (storageReads === 0 && processes.size === 0 && processStarts.size === 0) {
+            stop("opencode-storage-read-finished").catch(() => null);
+          }
+        }, storageIdleMs);
+        storageIdle.unref?.();
+      }
+    }
+  }
+
   function targetFor(key, prepared) {
     const current = processes.get(key);
     const nativeId = prepared.upstreamSessionId;
@@ -346,7 +371,7 @@ export function createOpenCodeSharedRuntime({ onStop = () => {}, scope } = {}) {
       if (processStarts.get(key) === start) processStarts.delete(key);
       if (!processes.has(key)) {
         await onFailure();
-        if (processes.size === 0 && processStarts.size === 0 && !failedStartup) {
+        if (processes.size === 0 && processStarts.size === 0 && storageReads === 0 && !failedStartup) {
           await stop("opencode-session-start-failed").catch(() => null);
         }
       }
@@ -365,7 +390,7 @@ export function createOpenCodeSharedRuntime({ onStop = () => {}, scope } = {}) {
       processes.delete(target.key);
       await onRemoved?.();
     }
-    return !retainSharedProcess && processes.size === 0 && processStarts.size === 0
+    return !retainSharedProcess && processes.size === 0 && processStarts.size === 0 && storageReads === 0
       ? stop()
       : { exited: true, sharedProcessRetained: true };
   }
@@ -444,7 +469,7 @@ export function createOpenCodeSharedRuntime({ onStop = () => {}, scope } = {}) {
       application.ownsTarget(target) && (!projectContextRoot || target.projectContextRoot === path.resolve(projectContextRoot))
     ));
     const results = await Promise.all(targets.map((target) => releaseProcessTarget(target, {}, application)));
-    if (processes.size === 0 && (sharedProcess || failedStartup)) {
+    if (processes.size === 0 && storageReads === 0 && (sharedProcess || failedStartup)) {
       results.push(await stop(text(input.reason) || "opencode-project-close").catch(application.failure));
     }
     return {
@@ -456,6 +481,8 @@ export function createOpenCodeSharedRuntime({ onStop = () => {}, scope } = {}) {
   async function invalidateRuntimes(input = {}, preparation) {
     if (text(input.reason) === "server-shutdown") {
       closed = true;
+      clearTimeout(storageIdle);
+      storageIdle = null;
     }
     const application = preparation.release;
     if (typeof input.publish === "function") {
@@ -1767,7 +1794,7 @@ export function createOpenCodeSharedRuntime({ onStop = () => {}, scope } = {}) {
     get current() { return sharedProcess; },
     get closed() { return closed; },
     get cleanupPending() { return Boolean(failedStartup); },
-    acquire, targetFor, ensure, release, releaseTarget, releaseProcessTarget, closeSession, closeProject,
+    acquire, targetFor, ensure, withStorageProcess, release, releaseTarget, releaseProcessTarget, closeSession, closeProject,
     startPreparedProcess, acquirePrepared, createPreparedConversation, runPreparedRenewalTurn, selectPreparedConversation, existingPreparedConversation,
     runPreparedConversationTurn, readPreparedConversation, waitPreparedConversationTurn, stopPreparedConversation, deletePreparedConversation,
     sendPreparedMessage, inspectPreparedMessage, interruptPreparedTurn,

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

@@ -432,7 +432,8 @@ export function createClaudeConversationDriver({ connections, host = {}, limits
           if (supplied) {
             await acquire(context);
             const result = await owner.inspectAdmission(await acquire(context), input);
-            return representation === "native" ? result : { accepted: result.admission === "accepted" };
+            return representation === "native" ? result
+              : { accepted: result.admission === "accepted", notAdmitted: result.admission === "not-admitted" };
           }
           if (verifyAccount === true) {
             const binding = input.receiptBinding;
@@ -446,7 +447,8 @@ export function createClaudeConversationDriver({ connections, host = {}, limits
           }
           const history = await owner.readHistory(entry);
           const nativeId = claudeNativeMessageId(input.messageId);
-          return { accepted: history.userIds.includes(nativeId),
+          const accepted = history.userIds.includes(nativeId);
+          return { accepted, notAdmitted: !accepted && owner.nativeWorkSettled(entry),
             messages: history.messages.filter(message => message.userId === nativeId) };
         },
         steer: command => owner.steer(control, command, commandOptions),

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

@@ -126,10 +126,11 @@ export function createCodexConversationDriver({ connections, host = {}, limits =
       runtime: createCodexAppServerRuntime({ credentials, execution: processExecution, configuration }) };
   }
 
-  async function nativeStorageProvider({ sessionId, native, binding, context }) {
+  // Storage work borrows the shared process; it is not a user that keeps it running.
+  async function withNativeStorageProvider({ sessionId, native, binding, context }, operation) {
     const prepared = await native.preparation.storage(sessionId, binding, context);
-    return { provider: await native.providerOwner.ensureSession(prepared.providerContext),
-      toolHomeSource: prepared.toolHomeSource };
+    return native.providerOwner.withTransientSession(prepared.providerContext,
+      provider => operation(provider, prepared.toolHomeSource));
   }
 
   async function disposeNative({ sessionId, namespace, native, options }) {
@@ -160,17 +161,17 @@ export function createCodexConversationDriver({ connections, host = {}, limits =
     deleteDetachedConversation({ sessionId, native, input, context }) {
       return native.runOwner.deleteDetachedThread(sessionId, input, context);
     },
-    async listConversationStorage(prepared) {
-      const { provider } = await nativeStorageProvider(prepared);
+    listConversationStorage(prepared) {
       const { binding } = prepared;
-      return (await provider.listNativeThreadsForCwd(binding.workdir)).map((conversationId) => ({ ...binding, conversationId }));
+      return withNativeStorageProvider(prepared, async provider =>
+        (await provider.listNativeThreadsForCwd(binding.workdir)).map((conversationId) => ({ ...binding, conversationId })));
     },
-    async retireConversationHistory(prepared) {
-      const { provider, toolHomeSource } = await nativeStorageProvider(prepared);
-      return retireCodexConversationHistory(provider, prepared.binding, {
-        toolHomeSource, beforeDelete: prepared.context.beforeDelete, signal: prepared.context.signal,
-        errorPrefix: prepared.native.errorPrefix
-      });
+    retireConversationHistory(prepared) {
+      return withNativeStorageProvider(prepared, (provider, toolHomeSource) =>
+        retireCodexConversationHistory(provider, prepared.binding, {
+          toolHomeSource, beforeDelete: prepared.context.beforeDelete, signal: prepared.context.signal,
+          errorPrefix: prepared.native.errorPrefix
+        }));
     },
     invalidateRuntimes({ native, input }) {
       return native.runOwner.invalidateRuntimes(input, native.preparation);

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

@@ -76,10 +76,10 @@ export function createOpenCodeConversationDriver({ connections, host = {}, limit
     return { text: prepared, content: input.content };
   }
 
-  async function nativeStorageTarget({ native, context }) {
+  function withNativeStorageTarget({ native, context }, operation) {
     const prepared = native.preparation.storage(context);
-    return native.owner.ensure(null, async () =>
-      native.owner.startPreparedProcess(await prepared.process())).catch(prepared.failure);
+    return native.owner.withStorageProcess(async () =>
+      native.owner.startPreparedProcess(await prepared.process()), operation, prepared.failure);
   }
 
   async function disposeNative({ native, options }) {
@@ -127,17 +127,18 @@ export function createOpenCodeConversationDriver({ connections, host = {}, limit
       const prepared = await native.preparation.existing(input, context, { operation: "delete" });
       return native.owner.deletePreparedConversation(prepared, input);
     },
-    async listConversationStorage(prepared) {
-      const target = await nativeStorageTarget(prepared);
+    listConversationStorage(prepared) {
       const { binding, context } = prepared;
-      return (await target.server.client.listConversationsForDirectory(binding.workdir, { signal: context.signal }))
-        .map((row) => ({ ...binding, conversationId: row.id }));
+      return withNativeStorageTarget(prepared, async target =>
+        (await target.server.client.listConversationsForDirectory(binding.workdir, { signal: context.signal }))
+          .map((row) => ({ ...binding, conversationId: row.id })));
     },
-    async retireConversationHistory(prepared) {
-      const target = await nativeStorageTarget(prepared);
-      // Native status is scoped to the saved project instance, not the control server.
-      const client = openCodeServerForDirectory(target.server, prepared.binding.workdir).client;
-      return retireOpenCodeConversationHistory(target.server.client, client, prepared.binding, prepared.context);
+    retireConversationHistory(prepared) {
+      return withNativeStorageTarget(prepared, target => {
+        // Native status is scoped to the saved project instance, not the control server.
+        const client = openCodeServerForDirectory(target.server, prepared.binding.workdir).client;
+        return retireOpenCodeConversationHistory(target.server.client, client, prepared.binding, prepared.context);
+      });
     },
     closeProject({ native, input }) {
       return native.owner.closeProject(input, native.preparation.projectCleanup());