@cjhyy/code-shell-core 0.8.2 → 0.8.4

package/dist/credentials/use-credential-tool.js

@@ -19,8 +19,11 @@ import { logger } from "../logging/logger.js";
 import { credentialAccessScope, getCredentialAccess, materializeCookieSecret, sweepStaleCredentialCookieFiles, } from "./access.js";
 const TOOL_NAME = "UseCredential";
 const BASE_DESCRIPTION = "Use a stored credential (token / API key / login cookie) to run a command. " +
-    "Call with NO arguments first to list available credentials (id + label + type); " +
-    "then call again with `id` to fetch one. Token/link credentials return their secret " +
+    "Prefer this tool over reading a browser credential store, asking the user to log in again, " +
+    "or manually exporting credentials. Before `--cookies-from-browser` or retrying an " +
+    "authentication failure, check stored credentials here. If `Currently available` names a " +
+    "matching id, fetch it directly; otherwise call with NO arguments first to list available " +
+    "credentials (id + label + type), then call again with `id`. Token/link credentials return their secret " +
     "value; cookie credentials are materialized to a temporary Netscape cookies.txt file " +
     "(use it as `yt-dlp --cookies <cookiesFile>` / `curl -b <cookiesFile>`). " +
     "Each use is gated by a quick user approval unless auto-approve is on.";

package/dist/engine/engine.js

@@ -1501,7 +1501,9 @@ export class Engine {
         this.lastMessages = messages;
         // Wire up LLM summarization for context compaction
         // Uses a lightweight call without tools
-        contextManager.setTranscriptPath(session.transcript.getFilePath());
+        if (session.transcript.isPersistent()) {
+            contextManager.setTranscriptPath(session.transcript.getFilePath());
+        }
         // Re-derive frozen persistence decisions from the messages we just
         // loaded. Skipped on cold start (messages == [userContextMsg] only).
         // Critical for resume — otherwise a result that was persisted last
@@ -1704,14 +1706,17 @@ export class Engine {
         // capture the persisted total at run start and fold this run's usage onto
         // it (see foldRunUsage). Snapshot now, before any turn boundary fires.
         const usageBaseline = { ...session.state.tokenUsage };
-        const sessionDir = join(this.config.sessionStorageDir ?? sessionsRoot(), session.state.sessionId);
-        const fileHistoryHook = registerFileHistoryHook({
-            hooks: this.hooks,
-            sessionDir,
-            cwd,
-            getTurnSeq: () => session.state.turnSeq,
-            contributions: this.capabilities.flatMap((capability) => [...(capability.fileHistory ?? [])]),
-        });
+        const fileHistoryHook = isEphemeralSessionState(session.state)
+            ? { dispose() { } }
+            : registerFileHistoryHook({
+                hooks: this.hooks,
+                sessionDir: join(this.config.sessionStorageDir ?? sessionsRoot(), session.state.sessionId),
+                cwd,
+                getTurnSeq: () => session.state.turnSeq,
+                contributions: this.capabilities.flatMap((capability) => [
+                    ...(capability.fileHistory ?? []),
+                ]),
+            });
         // Hook: agent start
         await this.emitHook("on_agent_start", {
             sessionId: session.state.sessionId,
@@ -2800,7 +2805,9 @@ export class Engine {
                 maxTokens: this.resolveMaxContextTokens(),
                 ...Object.fromEntries(Object.entries(this.resolveContextRatios()).filter(([, v]) => v !== undefined)),
             });
-            contextManager.setTranscriptPath(session.transcript.getFilePath());
+            if (session.transcript.isPersistent()) {
+                contextManager.setTranscriptPath(session.transcript.getFilePath());
+            }
             contextManager.initReplacementStateFromMessages(sourceMessages);
             this.lastContextManager = contextManager;
         }

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  *
  * Public API exports.
  */
-export declare const VERSION = "0.8.2";
+export declare const VERSION = "0.8.4";
 export type { Message, ContentBlock, ToolDefinition, ToolCall, ToolResult, RegisteredTool, TranscriptEvent, TranscriptEventType, SessionState, SessionKind, SessionWorkspace, SessionForkLineage, ContextUsageAnchor, SessionStatus, TokenUsage, CompiledInput, PermissionDecision, PermissionMode, PermissionRule, TurnPhase, TurnResult, TerminalReason, TurnCompletionKind, StreamEvent, StreamCallback, LLMConfig, ClientDefaults, LLMResponse, Settings, MCPServerConfig, } from "./types.js";
 export type { GoalConfig, GoalLifecycleConfig, GoalLifecyclePhase, GoalLifecycleTerminalReason, GoalLifecycleV1, } from "./goal/lifecycle.js";
 export { FrameworkError, LLMError, LLMRateLimitError, ContextLimitError, ToolError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError, PermissionDeniedError, SessionError, TranscriptError, ConfigError, SandboxUnavailableError, } from "./exceptions.js";

package/dist/index.js

@@ -3,7 +3,7 @@
  *
  * Public API exports.
  */
-export const VERSION = "0.8.2";
+export const VERSION = "0.8.4";
 // ─── Exceptions ──────────────────────────────────────────────────
 export { FrameworkError, LLMError, LLMRateLimitError, ContextLimitError, ToolError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError, PermissionDeniedError, SessionError, TranscriptError, ConfigError, SandboxUnavailableError, } from "./exceptions.js";
 // ─── Engine (primary API) ────────────────────────────────────────

package/dist/llm/providers/openai.js

@@ -145,6 +145,52 @@ export async function runStreamWithWatchdog(stream, opts = {}) {
     }
     return text;
 }
+const MISSING_TOOL_RESULT_WIRE_TEXT = "Error: Tool execution did not complete before the conversation resumed.";
+/**
+ * OpenAI requires each assistant tool_calls batch to be followed immediately
+ * by exactly one role:tool message per id. Normalize at the provider boundary
+ * as a final guard against legacy/corrupt transcripts: keep the latest result
+ * for a duplicate id, synthesize a request-local result for a missing id, and
+ * discard tool messages that were never declared by the preceding assistant.
+ */
+function normalizeOpenAIToolMessagePairs(messages) {
+    const normalized = [];
+    for (let index = 0; index < messages.length; index++) {
+        const message = messages[index];
+        if (message.role === "tool")
+            continue;
+        normalized.push(message);
+        if (message.role !== "assistant")
+            continue;
+        const toolCalls = message.tool_calls;
+        const expectedIds = Array.isArray(toolCalls)
+            ? toolCalls
+                .map((toolCall) => toolCall.id)
+                .filter((id) => typeof id === "string" && id.length > 0)
+            : [];
+        if (expectedIds.length === 0)
+            continue;
+        const expected = new Set(expectedIds);
+        const latestResultById = new Map();
+        let cursor = index + 1;
+        while (cursor < messages.length && messages[cursor]?.role === "tool") {
+            const toolMessage = messages[cursor];
+            if (expected.has(toolMessage.tool_call_id)) {
+                latestResultById.set(toolMessage.tool_call_id, toolMessage);
+            }
+            cursor++;
+        }
+        for (const id of expectedIds) {
+            normalized.push(latestResultById.get(id) ?? {
+                role: "tool",
+                tool_call_id: id,
+                content: MISSING_TOOL_RESULT_WIRE_TEXT,
+            });
+        }
+        index = cursor - 1;
+    }
+    return normalized;
+}
 export class OpenAIClient extends LLMClientBase {
     _client = null;
     // Sticky override: once the endpoint tells us `max_tokens` is rejected for
@@ -839,10 +885,11 @@ export class OpenAIClient extends LLMClientBase {
                 }
             }
         }
+        const normalized = normalizeOpenAIToolMessagePairs(result);
         if (this.isOpenRouterAnthropic) {
-            this.applyAnthropicCacheBreakpoints(result);
+            this.applyAnthropicCacheBreakpoints(normalized);
         }
-        return result;
+        return normalized;
     }
     /**
      * In-place: add prompt-cache breakpoints for Anthropic-over-OpenRouter.

package/dist/protocol/chat-session-manager.js

@@ -190,6 +190,14 @@ export class ChatSessionManager {
             return alreadyClosing;
         const s = this.sessions.get(sessionId);
         if (!s) {
+            if (sessionId.startsWith("qchat-")) {
+                try {
+                    this.engineSessionManager(this.factory({}))?.forgetEphemeralSession?.(sessionId);
+                }
+                catch {
+                    // Closing an already-expired process-local chat is idempotent.
+                }
+            }
             if (markClosed)
                 this.rememberClosedSession(sessionId);
             return Promise.resolve();
@@ -204,6 +212,7 @@ export class ChatSessionManager {
         clearCredentialSessionAllow(sessionId);
         clearInjectCredentialSessionAllow(sessionId);
         const finishClose = () => {
+            sessionManager?.forgetEphemeralSession?.(sessionId);
             this.unregisterMcpOwner(s);
             if (this.sessions.get(sessionId) === s)
                 this.sessions.delete(sessionId);

package/dist/run/EngineRunner.js

@@ -27,10 +27,11 @@ export const AUTOMATION_RUN_SOURCE = "automation";
 export const AUTOMATION_PROMPT_NOTE = "This is an unattended, scheduled automation run. No human is watching, and " +
     "AskUserQuestion will not reach anyone. You ARE the automation — do not ask " +
     "the user questions and do not offer to set up or schedule automation. " +
-    "Produce the requested output directly; when uncertain, state your assumption " +
-    "and proceed." +
-    " When finished, call UpdateAutomationMemory exactly once with a concise " +
-    "summary of this run's key findings/state for the next run.";
+    "When uncertain, state your assumption and proceed. When the work is ready, " +
+    "first call UpdateAutomationMemory exactly once with a concise summary of this " +
+    "run's key findings/state for the next run. After that call succeeds, return the " +
+    "complete requested output as the final assistant message. Do not replace the " +
+    "requested output with a completion acknowledgement or put it in a formatting tool.";
 /** Compose the run's appendSystemPrompt: prepend the automation note when the
  *  run is tagged source "automation", preserving any host-provided append. */
 export function buildAppendSystemPrompt(hostAppend, metadata) {

package/dist/session/session-manager.d.ts

@@ -18,7 +18,7 @@ export interface ForkSessionOptions {
     throughEventId?: string;
     /** `completed` is the interrupted snapshot used by ephemeral side chats. */
     snapshotMode?: "tail" | "completed";
-    /** Hide this temporary fork from ordinary session lists and resume pickers. */
+    /** Keep this temporary fork in process memory only. */
     ephemeral?: boolean;
 }
 export interface ForkSessionResult {
@@ -94,24 +94,22 @@ export declare class SessionManager {
     private readonly registeredCloseEpochs;
     private readonly workspaceCapability?;
     constructor(storageDir?: string, workspaceCapability?: SessionWorkspaceCapability);
+    private processLocalKey;
+    private processLocalBundle;
+    private storeProcessLocalBundle;
+    /** Forget a Quick Chat/side-chat bundle immediately; nothing remains on disk. */
+    forgetEphemeralSession(sessionId: string): boolean;
     private cleanupStaleForkStaging;
     /** Bind one Engine/session pair to the current close epoch without advancing it. */
     registerSessionGeneration(sessionId: string): number;
     /** Advance the close epoch once before close waits for the old run to settle. */
     incrementSessionGeneration(sessionId: string): number;
     /**
-     * Create a new on-disk session. If `explicitSessionId` is passed, use
-     * it verbatim (ChatSessionManager-driven hosts choose a logical sid like
-     * "tui-main" and expect us to honor it). Otherwise generate one with
-     * nanoid. Either way the on-disk directory is materialized and the
-     * state.json + transcript.jsonl files are written before return.
+     * Create a session. `qchat-` sessions stay process-local; ordinary sessions
+     * materialize state.json + transcript.jsonl before return.
      */
     create(cwd: string, model: string, provider: string, explicitSessionId?: string, parentSessionId?: string | null, origin?: import("../types.js").SessionOrigin, kind?: SessionKind): SessionBundle;
-    /**
-     * Whether a session directory exists on disk. Used by ChatSession-driven
-     * cold starts to decide between resume vs create-with-explicit-sid
-     * without catching SessionError.
-     */
+    /** Whether a persisted or process-local session exists. */
     exists(sessionId: string): boolean;
     /**
      * Cheap persisted-main-root probe — reads only state.json, NOT the transcript
@@ -142,10 +140,10 @@ export declare class SessionManager {
     }): string[];
     /** @deprecated Use readSessionMainRoot; retained for public API compatibility. */
     readCwd(sessionId: string): string | undefined;
-    /** Disk-only direct-parent ACL metadata. Undefined means unprovable/corrupt. */
+    /** Direct-parent ACL metadata. Undefined means unprovable/corrupt. */
     readParentSessionId(sessionId: string): string | null | undefined;
     /**
-     * Disk-only workspace pointer reader. Legacy sessions written before
+     * Workspace pointer reader. Legacy sessions written before
      * `workspace` existed are treated as main-workspace sessions rooted at
      * `state.cwd`; the read is intentionally non-mutating.
      */
@@ -306,6 +304,7 @@ export declare class SessionManager {
     /** Publish a summary-only top-level fork after summarization has succeeded. */
     createSummaryFork(sourceSessionId: string, options: SummaryForkOptions): ForkSessionResult;
     private readForkSnapshot;
+    private freezeForkSnapshot;
     private publishSessionAtomically;
     list(limit?: number, opts?: {
         excludeKinds?: readonly string[];

package/dist/session/session-manager.js

@@ -142,6 +142,12 @@ function adoptCompatibilityGoalMutation(state) {
         state.goalLifecycle = terminateGoalLifecycle(lifecycle, lifecycleTerminalReason(matchingTerminal.reason), matchingTerminal.terminatedAtMs ?? Date.now());
     }
 }
+// Quick Chat sessions are intentionally process-local. SessionManager
+// instances are created per Engine, so this registry lives at module scope to
+// let a fork created by one Engine be resumed by another without touching
+// disk. The storage root remains part of the key to preserve identity/data-root
+// isolation.
+const processLocalSessionBundles = new Map();
 const FORK_COPY_EVENT_TYPES = new Set([
     "message",
     "tool_use",
@@ -292,6 +298,26 @@ export class SessionManager {
         mkdirSync(this.sessionsDir, { recursive: true });
         this.cleanupStaleForkStaging();
     }
+    processLocalKey(sessionId) {
+        return `${this.sessionsDir}\0${sessionId}`;
+    }
+    processLocalBundle(sessionId) {
+        return processLocalSessionBundles.get(this.processLocalKey(sessionId));
+    }
+    storeProcessLocalBundle(bundle) {
+        processLocalSessionBundles.set(this.processLocalKey(bundle.state.sessionId), {
+            state: structuredClone(bundle.state),
+            transcript: bundle.transcript,
+        });
+    }
+    /** Forget a Quick Chat/side-chat bundle immediately; nothing remains on disk. */
+    forgetEphemeralSession(sessionId) {
+        assertSafeSessionId(sessionId);
+        const bundle = this.processLocalBundle(sessionId);
+        if (!bundle || !isEphemeralSessionState(bundle.state))
+            return false;
+        return processLocalSessionBundles.delete(this.processLocalKey(sessionId));
+    }
     cleanupStaleForkStaging() {
         let removed = 0;
         let entries;
@@ -336,11 +362,8 @@ export class SessionManager {
         return next;
     }
     /**
-     * Create a new on-disk session. If `explicitSessionId` is passed, use
-     * it verbatim (ChatSessionManager-driven hosts choose a logical sid like
-     * "tui-main" and expect us to honor it). Otherwise generate one with
-     * nanoid. Either way the on-disk directory is materialized and the
-     * state.json + transcript.jsonl files are written before return.
+     * Create a session. `qchat-` sessions stay process-local; ordinary sessions
+     * materialize state.json + transcript.jsonl before return.
      */
     create(cwd, model, provider, explicitSessionId, parentSessionId, origin, kind = "work") {
         // External callers may pass any string; nanoid output is trusted. Either
@@ -349,16 +372,6 @@ export class SessionManager {
         if (explicitSessionId !== undefined)
             assertSafeSessionId(explicitSessionId);
         const sessionId = explicitSessionId ?? nanoid(16);
-        const sessionDir = join(this.sessionsDir, sessionId);
-        try {
-            mkdirSync(sessionDir);
-        }
-        catch (err) {
-            if (err.code === "EEXIST") {
-                throw new SessionError(`Session already exists: ${sessionId}`);
-            }
-            throw err;
-        }
         const state = {
             sessionId,
             kind,
@@ -383,6 +396,33 @@ export class SessionManager {
             ...(sessionId.startsWith("qchat-") ? { ephemeral: true } : {}),
             ...(origin ? { origin } : {}),
         };
+        if (isEphemeralSessionState(state)) {
+            if (this.processLocalBundle(sessionId)) {
+                throw new SessionError(`Session already exists: ${sessionId}`);
+            }
+            const transcript = Transcript.inMemory(sessionId);
+            transcript.append("session_meta", {
+                sessionId,
+                cwd,
+                model,
+                provider,
+                startedAt: state.startedAt,
+                kind,
+            });
+            const bundle = { state, transcript };
+            this.storeProcessLocalBundle(bundle);
+            return bundle;
+        }
+        const sessionDir = join(this.sessionsDir, sessionId);
+        try {
+            mkdirSync(sessionDir);
+        }
+        catch (err) {
+            if (err.code === "EEXIST") {
+                throw new SessionError(`Session already exists: ${sessionId}`);
+            }
+            throw err;
+        }
         // Atomic write (tmp+rename) like saveState, so a crash during this one-time
         // create can't leave a torn state.json that resume() then fails to parse.
         const stateTarget = join(sessionDir, "state.json");
@@ -400,11 +440,7 @@ export class SessionManager {
         });
         return { state, transcript };
     }
-    /**
-     * Whether a session directory exists on disk. Used by ChatSession-driven
-     * cold starts to decide between resume vs create-with-explicit-sid
-     * without catching SessionError.
-     */
+    /** Whether a persisted or process-local session exists. */
     exists(sessionId) {
         // exists() is a probe — callers use it to decide between resume and
         // create-with-explicit-sid. Treat an invalid id as "not present"
@@ -415,6 +451,12 @@ export class SessionManager {
         catch {
             return false;
         }
+        if (this.processLocalBundle(sessionId))
+            return true;
+        // Never resurrect a legacy Quick Chat directory after the process-local
+        // record has expired.
+        if (sessionId.startsWith("qchat-"))
+            return false;
         return existsSync(join(this.sessionsDir, sessionId));
     }
     /**
@@ -430,6 +472,11 @@ export class SessionManager {
         catch {
             return undefined;
         }
+        const processLocal = this.processLocalBundle(sessionId);
+        if (processLocal)
+            return sessionMainRoot(processLocal.state);
+        if (sessionId.startsWith("qchat-"))
+            return undefined;
         const stateFile = join(this.sessionsDir, sessionId, "state.json");
         if (!existsSync(stateFile))
             return undefined;
@@ -449,6 +496,11 @@ export class SessionManager {
         catch {
             return undefined;
         }
+        const processLocal = this.processLocalBundle(sessionId);
+        if (processLocal)
+            return normalizedSessionKind(processLocal.state.kind);
+        if (sessionId.startsWith("qchat-"))
+            return undefined;
         const stateFile = join(this.sessionsDir, sessionId, "state.json");
         if (!existsSync(stateFile))
             return undefined;
@@ -464,6 +516,13 @@ export class SessionManager {
     readSessionWorkspaceProfile(sessionId) {
         try {
             assertSafeSessionId(sessionId);
+            const processLocal = this.processLocalBundle(sessionId);
+            if (processLocal) {
+                const profile = processLocal.state.workspaceProfile;
+                return typeof profile === "string" && profile ? profile : undefined;
+            }
+            if (sessionId.startsWith("qchat-"))
+                return undefined;
             const stateFile = join(this.sessionsDir, sessionId, "state.json");
             if (!existsSync(stateFile))
                 return undefined;
@@ -534,7 +593,7 @@ export class SessionManager {
     readCwd(sessionId) {
         return this.readSessionMainRoot(sessionId);
     }
-    /** Disk-only direct-parent ACL metadata. Undefined means unprovable/corrupt. */
+    /** Direct-parent ACL metadata. Undefined means unprovable/corrupt. */
     readParentSessionId(sessionId) {
         try {
             assertSafeSessionId(sessionId);
@@ -542,6 +601,13 @@ export class SessionManager {
         catch {
             return undefined;
         }
+        const processLocal = this.processLocalBundle(sessionId);
+        if (processLocal) {
+            const parent = processLocal.state.parentSessionId;
+            return parent === null || typeof parent === "string" ? parent : undefined;
+        }
+        if (sessionId.startsWith("qchat-"))
+            return undefined;
         const stateFile = join(this.sessionsDir, sessionId, "state.json");
         if (!existsSync(stateFile))
             return undefined;
@@ -556,7 +622,7 @@ export class SessionManager {
         }
     }
     /**
-     * Disk-only workspace pointer reader. Legacy sessions written before
+     * Workspace pointer reader. Legacy sessions written before
      * `workspace` existed are treated as main-workspace sessions rooted at
      * `state.cwd`; the read is intentionally non-mutating.
      */
@@ -567,6 +633,16 @@ export class SessionManager {
         catch {
             return undefined;
         }
+        const processLocal = this.processLocalBundle(sessionId);
+        if (processLocal) {
+            const state = processLocal.state;
+            if (isSessionWorkspace(state.workspace))
+                return structuredClone(state.workspace);
+            const mainRoot = sessionMainRoot(state);
+            return mainRoot ? { root: mainRoot, kind: "main" } : undefined;
+        }
+        if (sessionId.startsWith("qchat-"))
+            return undefined;
         const stateFile = join(this.sessionsDir, sessionId, "state.json");
         if (!existsSync(stateFile))
             return undefined;
@@ -601,6 +677,11 @@ export class SessionManager {
         catch {
             return undefined;
         }
+        const processLocal = this.processLocalBundle(sessionId);
+        if (processLocal)
+            return processLocal.state.archivedAt;
+        if (sessionId.startsWith("qchat-"))
+            return undefined;
         const stateFile = join(this.sessionsDir, sessionId, "state.json");
         if (!existsSync(stateFile))
             return undefined;
@@ -618,6 +699,19 @@ export class SessionManager {
     }
     recordWorkspaceHandoff(sessionId, from, to) {
         assertSafeSessionId(sessionId);
+        const processLocal = this.processLocalBundle(sessionId);
+        if (processLocal) {
+            processLocal.transcript.append("session_meta", {
+                sessionId,
+                cwd: to.root,
+                workspace: to,
+                handoffFrom: from?.root,
+                handoffAt: Date.now(),
+            });
+            return;
+        }
+        if (sessionId.startsWith("qchat-"))
+            return;
         const transcriptFile = join(this.sessionsDir, sessionId, "transcript.jsonl");
         if (!existsSync(transcriptFile))
             return;
@@ -645,15 +739,13 @@ export class SessionManager {
      */
     async resolveSessionWorkspaceForResume(sessionId) {
         assertSafeSessionId(sessionId);
-        const stateFile = join(this.sessionsDir, sessionId, "state.json");
-        if (!existsSync(stateFile)) {
-            throw new SessionError(`Session state file not found: ${sessionId}`);
-        }
         let state;
         try {
-            state = JSON.parse(readFileSync(stateFile, "utf-8"));
+            state = this.readPersistedState(sessionId);
         }
         catch (err) {
+            if (err instanceof SessionError)
+                throw err;
             throw new SessionError(`Session state is corrupt for ${sessionId}: ${err instanceof Error ? err.message : String(err)}`);
         }
         const mainRoot = sessionMainRoot(state);
@@ -731,6 +823,26 @@ export class SessionManager {
         catch {
             return undefined;
         }
+        const processLocal = this.processLocalBundle(sessionId);
+        if (processLocal) {
+            try {
+                const state = hydrateGoalLifecycle(structuredClone(processLocal.state));
+                const lifecycle = state.goalLifecycle;
+                if (!lifecycle || lifecycle.phase === "terminal")
+                    return undefined;
+                const goal = goalConfigFromLifecycle(lifecycle);
+                return {
+                    ...goal,
+                    goalId: goal.goalId ?? deriveLegacyGoalId(sessionId, goal),
+                    revision: goal.revision ?? 1,
+                };
+            }
+            catch {
+                return undefined;
+            }
+        }
+        if (sessionId.startsWith("qchat-"))
+            return undefined;
         const stateFile = join(this.sessionsDir, sessionId, "state.json");
         if (!existsSync(stateFile))
             return undefined;
@@ -873,6 +985,18 @@ export class SessionManager {
     }
     resume(sessionId) {
         assertSafeSessionId(sessionId);
+        const processLocal = this.processLocalBundle(sessionId);
+        if (processLocal) {
+            const state = hydrateGoalLifecycle(structuredClone(processLocal.state));
+            state.kind = normalizedSessionKind(state.kind);
+            state.status = "active";
+            delete state.lastCompletionKind;
+            Object.assign(state, normalizeCumulativeUsageCounters(state, state.tokenUsage));
+            return { state, transcript: processLocal.transcript };
+        }
+        if (sessionId.startsWith("qchat-")) {
+            throw new SessionError(`Session not found: ${sessionId}`);
+        }
         const sessionDir = join(this.sessionsDir, sessionId);
         if (!existsSync(sessionDir)) {
             throw new SessionError(`Session not found: ${sessionId}`);
@@ -1166,6 +1290,34 @@ export class SessionManager {
             (currentSessionCloseEpochs.get(this.generationKey(state.sessionId)) ?? 0) !== writerGeneration) {
             return { ok: false, reason: "generation_conflict" };
         }
+        const processLocal = this.processLocalBundle(state.sessionId);
+        if (processLocal) {
+            const persisted = structuredClone(processLocal.state);
+            const incomingKind = normalizedSessionKind(state.kind);
+            const persistedKind = normalizedSessionKind(persisted.kind);
+            if (incomingKind !== persistedKind)
+                return { ok: false, reason: "kind_conflict" };
+            state.kind = persistedKind;
+            const persistedRevision = persisted.stateRevision;
+            const incomingRevision = state.stateRevision;
+            const revisionsMatch = (persistedRevision === undefined && incomingRevision === undefined) ||
+                (typeof persistedRevision === "number" && incomingRevision === persistedRevision);
+            if (!revisionsMatch)
+                return { ok: false, reason: "revision_conflict" };
+            if (persisted.title !== undefined && !("title" in state))
+                state.title = persisted.title;
+            state.stateRevision = (persistedRevision ?? incomingRevision ?? 0) + 1;
+            const next = hydrateGoalLifecycle(structuredClone(stateForPersistence(state)));
+            this.rebaseLiveState(processLocal.state, next);
+            if (state !== processLocal.state)
+                this.rebaseLiveState(state, next);
+            return { ok: true };
+        }
+        // A closed process-local session must stay gone even if a late writer
+        // races the close fence.
+        if (isEphemeralSessionState(state)) {
+            return { ok: false, reason: "revision_conflict" };
+        }
         const sessionDir = join(this.sessionsDir, state.sessionId);
         mkdirSync(sessionDir, { recursive: true });
         const target = join(sessionDir, "state.json");
@@ -1272,6 +1424,12 @@ export class SessionManager {
         }
     }
     readPersistedState(sessionId) {
+        const processLocal = this.processLocalBundle(sessionId);
+        if (processLocal)
+            return hydrateGoalLifecycle(structuredClone(processLocal.state));
+        if (sessionId.startsWith("qchat-")) {
+            throw new SessionError(`Session state file not found: ${sessionId}`);
+        }
         const stateFile = join(this.sessionsDir, sessionId, "state.json");
         if (!existsSync(stateFile)) {
             throw new SessionError(`Session state file not found: ${sessionId}`);
@@ -1322,6 +1480,13 @@ export class SessionManager {
     /** Freeze and validate an inclusive source range before any model call. */
     selectContextPackage(sourceSessionId, range) {
         assertSafeSessionId(sourceSessionId);
+        const processLocal = this.processLocalBundle(sourceSessionId);
+        if (processLocal) {
+            return Transcript.selectContextRange(processLocal.transcript.getEvents(), range);
+        }
+        if (sourceSessionId.startsWith("qchat-")) {
+            throw new SessionError(`Session not found: ${sourceSessionId}`);
+        }
         const transcriptFile = join(this.sessionsDir, sourceSessionId, "transcript.jsonl");
         const stateFile = join(this.sessionsDir, sourceSessionId, "state.json");
         if (!existsSync(stateFile))
@@ -1377,6 +1542,13 @@ export class SessionManager {
         return { bundle, lineage, copiedEventCount: 0 };
     }
     readForkSnapshot(sourceSessionId, throughEventId, snapshotMode) {
+        const processLocal = this.processLocalBundle(sourceSessionId);
+        if (processLocal) {
+            return this.freezeForkSnapshot(sourceSessionId, structuredClone(processLocal.state), processLocal.transcript.getEvents(), throughEventId, snapshotMode);
+        }
+        if (sourceSessionId.startsWith("qchat-")) {
+            throw new SessionError(`Session not found: ${sourceSessionId}`);
+        }
         const sessionDir = join(this.sessionsDir, sourceSessionId);
         const stateFile = join(sessionDir, "state.json");
         const transcriptFile = join(sessionDir, "transcript.jsonl");
@@ -1393,7 +1565,10 @@ export class SessionManager {
         if (parsed.malformedLineCount > 0) {
             throw new SessionError(`Session transcript is malformed for ${sourceSessionId}: ${parsed.malformedLineCount} invalid line(s)`);
         }
-        const sourceEvents = structuredClone(parsed.events);
+        return this.freezeForkSnapshot(sourceSessionId, sourceState, parsed.events, throughEventId, snapshotMode);
+    }
+    freezeForkSnapshot(sourceSessionId, sourceState, events, throughEventId, snapshotMode) {
+        const sourceEvents = structuredClone([...events]);
         let frozen = sourceEvents;
         const effectiveCursor = snapshotMode === "completed" ? sourceState.completedThroughEventId : throughEventId;
         if (snapshotMode === "completed" && effectiveCursor === undefined) {
@@ -1436,6 +1611,17 @@ export class SessionManager {
     }
     publishSessionAtomically(targetSessionId, state, events) {
         const targetDir = join(this.sessionsDir, targetSessionId);
+        if (isEphemeralSessionState(state)) {
+            if (this.processLocalBundle(targetSessionId) || existsSync(targetDir)) {
+                throw new SessionError(`Session already exists: ${targetSessionId}`);
+            }
+            const bundle = {
+                state: hydrateGoalLifecycle(structuredClone(state)),
+                transcript: Transcript.fromMemoryEvents(targetSessionId, events),
+            };
+            this.storeProcessLocalBundle(bundle);
+            return bundle;
+        }
         if (existsSync(targetDir))
             throw new SessionError(`Session already exists: ${targetSessionId}`);
         const stagingDir = join(this.sessionsDir, `.pending-fork-${targetSessionId}-${nanoid(8)}`);