@gkorepanov/ccodex 0.3.0 → 0.4.0

package/dist/gateway/clientConnection.js

@@ -1,4 +1,4 @@
-import { v7 as uuidv7 } from "uuid";
+import { validate as isUuid, v7 as uuidv7 } from "uuid";
 import { WebSocket as WebSocketState } from "ws";
 import { connectStock } from "../codex/stockConnection.js";
 import { isRequest, isResponse, parseRpcMessage } from "../protocol/envelopes.js";
@@ -7,11 +7,44 @@ import { mergedModelList } from "./modelList.js";
 import { StockRpc } from "./stockRpc.js";
 import { mergedLoadedList, mergedThreadList } from "./threadList.js";
 import { ServerRequestIds } from "./serverRequestIds.js";
-import { transientSystemNotice } from "./transientNotice.js";
-export function attachClientConnection(client, stockSocket, claudeModels, claude, handoffs, subscriptions, logger, cursors, metrics, recorder, remoteControl) {
+import { providerMigrationCompleted, providerMigrationFailed, providerMigrationNotice, transientCommandNotice, transientSystemNotice, } from "./transientNotice.js";
+import { rateLimitNotifications } from "../claude/rateLimits.js";
+import { formatCCodexStatus, isCCodexStatusCommand } from "../claude/statusCommand.js";
+import { claudeCompactCommand } from "../claude/compactCommand.js";
+import { DEFAULT_FEATURES } from "../config/config.js";
+import { providerUnavailableMessage } from "../runtime/providerAvailability.js";
+import { formatCCodexState, isCCodexStateCommand } from "../state/stateCommand.js";
+import { StockStateTracker } from "../state/stockStateTracker.js";
+function requestedFast(serviceTier) {
+    return serviceTier === "fast" || serviceTier === "priority";
+}
+function claudeModelNoticeName(model) {
+    const name = model.replace(/^claude:/u, "").replace(/^claude-/u, "").split("-")[0] ?? model;
+    return `${name.charAt(0).toUpperCase()}${name.slice(1)}`;
+}
+function fastTransitionNotice(before, after, requestedTier) {
+    const effectiveRequest = requestedTier === undefined ? before?.serviceTier : requestedTier;
+    if (before && !requestedFast(before.serviceTier) && requestedFast(after.serviceTier)) {
+        return "Fast mode is on — usage limits may be consumed faster.";
+    }
+    if (requestedFast(effectiveRequest) && !requestedFast(after.serviceTier)) {
+        return `Fast was requested, but ${claudeModelNoticeName(after.model)} does not support it — continuing in Standard.`;
+    }
+    return undefined;
+}
+export function attachClientConnection(client, stockSocket, claudeModels, claude, handoffs, subscriptions, logger, cursors, metrics, recorder, remoteControl, features = DEFAULT_FEATURES, providerAvailability, sharedStockState) {
     const connectionId = uuidv7();
+    let resolveClosed;
+    let rejectClosed;
+    const closed = new Promise((resolve, reject) => {
+        resolveClosed = resolve;
+        rejectClosed = reject;
+    });
+    void closed.catch(() => undefined);
+    let connectionAlive = true;
     const stock = connectStock(stockSocket);
     const stockRpc = new StockRpc(stock);
+    const stockState = sharedStockState ?? new StockStateTracker();
     const queued = [];
     const requestStarted = new Map();
     const forwardedRequests = new Map();
@@ -32,9 +65,23 @@ export function attachClientConnection(client, stockSocket, claudeModels, claude
         const params = message.params && typeof message.params === "object"
             ? message.params
             : undefined;
+        const systemEphemeral = (message.method === "thread/start" || message.method === "thread/fork")
+            && params?.ephemeral === true
+            && (params.threadSource === "system" || (message.method === "thread/start" && params.threadSource !== "user"));
+        const internalEphemeralThread = typeof params?.threadId === "string"
+            && handoffs.ownsSystemEphemeral(connectionId, params.threadId);
+        const foreground = !systemEphemeral && !internalEphemeralThread
+            && ["thread/start", "thread/resume", "thread/fork", "turn/start"].includes(message.method)
+            ? "codex"
+            : undefined;
         forwardedRequests.set(requestKey(message.id), {
             method: message.method,
             ...(typeof params?.threadId === "string" ? { threadId: params.threadId } : {}),
+            ...(systemEphemeral
+                ? { systemEphemeral: message.params }
+                : {}),
+            ...(foreground ? { foreground } : {}),
+            ...(["thread/delete", "thread/unsubscribe"].includes(message.method) ? { clearForeground: true } : {}),
         });
     };
     metrics.connectionOpened();
@@ -56,6 +103,11 @@ export function attachClientConnection(client, stockSocket, claudeModels, claude
         emitNotice(notice);
         return notice;
     };
+    const emitFastTransition = (threadId, before, after, requestedTier) => {
+        const text = fastTransitionNotice(before, after, requestedTier);
+        if (text)
+            emitTransientNotice(threadId, text);
+    };
     const emitSystemError = (threadId, message) => {
         const now = Date.now();
         const key = `${threadId}\u0000${message}`;
@@ -78,6 +130,114 @@ export function attachClientConnection(client, stockSocket, claudeModels, claude
         completeLatency(id, "claude");
         sendJson({ id, error: { code, message: error instanceof Error ? error.message : String(error) } });
     };
+    let foreground;
+    let foregroundGeneration = 0;
+    let unknownStatusDiagnosed = false;
+    const emitRateLimits = (response) => {
+        for (const notification of rateLimitNotifications(response))
+            sendJson(notification);
+    };
+    const emitStockRateLimits = (value) => {
+        if (!value || typeof value !== "object")
+            return;
+        const result = value;
+        const buckets = result.rateLimitsByLimitId ? Object.values(result.rateLimitsByLimitId) : [];
+        const snapshots = buckets.length > 0 ? buckets : result.rateLimits ? [result.rateLimits] : [];
+        for (const rateLimits of snapshots)
+            sendJson({ method: "account/rateLimits/updated", params: { rateLimits } });
+    };
+    const combinedStatus = async (threadId) => {
+        const availability = providerAvailability
+            ? await providerAvailability.refreshAll()
+            : {
+                claude: { provider: "claude", state: "ready" },
+                codex: { provider: "codex", state: "ready" },
+            };
+        const [claudeUsage, codexRateLimits] = await Promise.all([
+            availability.claude.state === "ready"
+                ? claude.readRateLimitStatus(threadId).catch((error) => ({
+                    rateLimits: claude.cachedRateLimits(),
+                    unavailableReason: error instanceof Error ? error.message : String(error),
+                }))
+                : undefined,
+            availability.codex.state === "ready"
+                ? stockRpc.request("account/rateLimits/read", undefined).catch(() => undefined)
+                : undefined,
+        ]);
+        return formatCCodexStatus({
+            claude: { availability: availability.claude, ...(claudeUsage ? { usage: claudeUsage } : {}) },
+            codex: {
+                availability: availability.codex,
+                ...(codexRateLimits ? { rateLimits: codexRateLimits } : {}),
+            },
+        });
+    };
+    const threadState = async (threadId) => {
+        const logical = handoffs.logical?.(threadId);
+        if (logical?.epoch.provider === "claude") {
+            return formatCCodexState(claude.stateSnapshot(logical.epoch.backendThreadId));
+        }
+        if (claude.ownsThread(threadId))
+            return formatCCodexState(claude.stateSnapshot(threadId));
+        let response;
+        try {
+            response = logical
+                ? (await handoffs.requestLogical("thread/read", { threadId, includeTurns: true }, stockRpc)).result
+                : await stockRpc.request("thread/read", { threadId, includeTurns: true });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (!message.includes("includeTurns is unavailable")
+                && !message.includes("ephemeral threads do not support includeTurns"))
+                throw error;
+            response = logical
+                ? (await handoffs.requestLogical("thread/read", { threadId, includeTurns: false }, stockRpc)).result
+                : await stockRpc.request("thread/read", { threadId, includeTurns: false });
+        }
+        return formatCCodexState(stockState.snapshot(response.thread));
+    };
+    const publishForegroundRateLimits = (generation) => {
+        const selected = foreground;
+        if (!selected)
+            return;
+        if (selected.provider === "claude") {
+            const backend = handoffs.logical?.(selected.threadId)?.epoch.backendThreadId ?? selected.threadId;
+            void claude.readRateLimits(backend).then((response) => {
+                if (foregroundGeneration === generation && foreground?.provider === "claude")
+                    emitRateLimits(response);
+            }).catch((error) => logger.warn("claude.rate-limits.publish-failed", { connectionId, error: String(error) }));
+            return;
+        }
+        void (async () => {
+            if (providerAvailability && (await providerAvailability.read("codex")).state !== "ready")
+                return;
+            const response = await stockRpc.request("account/rateLimits/read", undefined);
+            if (foregroundGeneration === generation && foreground?.provider === "codex")
+                emitStockRateLimits(response);
+        })().catch((error) => logger.warn("codex.rate-limits.publish-failed", { connectionId, error: String(error) }));
+    };
+    const selectForeground = (provider, threadId) => {
+        foreground = { provider, threadId };
+        unknownStatusDiagnosed = false;
+        foregroundGeneration += 1;
+        publishForegroundRateLimits(foregroundGeneration);
+    };
+    const clearForeground = (threadId) => {
+        if (foreground?.threadId !== threadId)
+            return;
+        foreground = undefined;
+        foregroundGeneration += 1;
+    };
+    const diagnoseUnknownStatus = (signal) => {
+        if (unknownStatusDiagnosed)
+            return;
+        unknownStatusDiagnosed = true;
+        logger.warn("provider.status.unknown", {
+            connectionId,
+            signal,
+            behavior: "preserving provider-labelled stock payload until a foreground operation succeeds",
+        });
+    };
     const notificationSink = (method, params) => {
         if (method === "error" && params && typeof params === "object") {
             const failure = params;
@@ -101,9 +261,23 @@ export function attachClientConnection(client, stockSocket, claudeModels, claude
     const serverRequestSink = (id, method, params) => {
         sendJson({ id: serverRequestIds.wireId(id), method, params });
     };
-    subscriptions.attach(connectionId, notificationSink);
+    subscriptions.attach(connectionId, notificationSink, serverRequestSink);
+    claude.subscribeRateLimits(connectionId, (response) => {
+        if (foreground?.provider === "claude")
+            emitRateLimits(response);
+    });
+    const subscribedClaudeThreads = new Set();
     const subscribeClaude = (threadId) => {
-        subscriptions.subscribe(threadId, connectionId, notificationSink, serverRequestSink);
+        if (!connectionAlive
+            || !subscriptions.subscribe(threadId, connectionId, notificationSink, serverRequestSink))
+            return false;
+        subscribedClaudeThreads.add(threadId);
+        claude.cancelEphemeralRelease(threadId);
+        return true;
+    };
+    const muteClaudeDuringSnapshot = (threadId) => {
+        subscribeClaude(threadId);
+        subscriptions.mute(threadId, connectionId);
     };
     client.on("message", async (data, isBinary) => {
         recorder.frame(connectionId, "client_to_gateway", data, isBinary);
@@ -113,7 +287,10 @@ export function attachClientConnection(client, stockSocket, claudeModels, claude
             : undefined;
         if (message && isResponse(message) && internalServerRequestId) {
             const response = "result" in message ? message.result : { rpcError: message.error };
-            if (!claude.resolveServerRequest(internalServerRequestId, response)) {
+            if (handoffs.resolveStockServerRequest
+                && await handoffs.resolveStockServerRequest(internalServerRequestId, response))
+                return;
+            if (!await claude.resolveServerRequest(internalServerRequestId, response)) {
                 logger.warn("claude.interaction.unknown-response", { connectionId, requestId: internalServerRequestId });
             }
             return;
@@ -129,25 +306,119 @@ export function attachClientConnection(client, stockSocket, claudeModels, claude
                     sendResult(message.id, await mergedModelList((message.params ?? {}), stockRpc, claudeModels, logger, cursors));
                     return;
                 }
+                if (message.method === "account/rateLimits/read" && foreground?.provider === "claude") {
+                    const backend = handoffs.logical?.(foreground.threadId)?.epoch.backendThreadId ?? foreground.threadId;
+                    sendResult(message.id, await claude.readRateLimits(backend));
+                    return;
+                }
+                if (message.method === "account/usage/read" && foreground?.provider === "claude") {
+                    // The captured App status flow does not request this method. If a
+                    // client does, lifetime/streak Codex statistics have no Claude
+                    // equivalent and must not be mislabelled as provider usage.
+                    sendResult(message.id, {
+                        summary: {
+                            lifetimeTokens: null,
+                            peakDailyTokens: null,
+                            longestRunningTurnSec: null,
+                            currentStreakDays: null,
+                            longestStreakDays: null,
+                        },
+                        dailyUsageBuckets: null,
+                    });
+                    return;
+                }
+                if (message.method === "account/rateLimits/read" && !foreground)
+                    diagnoseUnknownStatus("account/rateLimits/read");
                 if (message.method === "thread/list") {
-                    sendResult(message.id, await mergedThreadList((message.params ?? {}), stockRpc, claude, cursors));
+                    sendResult(message.id, await mergedThreadList((message.params ?? {}), stockRpc, claude, cursors, handoffs));
                     return;
                 }
                 if (message.method === "thread/loaded/list") {
-                    sendResult(message.id, await mergedLoadedList((message.params ?? {}), stockRpc, claude, cursors));
+                    sendResult(message.id, await mergedLoadedList((message.params ?? {}), stockRpc, claude, cursors, handoffs));
                     return;
                 }
                 if (message.method === "thread/start") {
                     const params = (message.params ?? {});
                     if (params.model && claude.ownsModel(params.model)) {
                         const result = await claude.startThread(params);
+                        handoffs.observeDurableThread(connectionId, "claude");
                         sendResult(message.id, result);
+                        selectForeground("claude", result.thread.id);
                         subscribeClaude(result.thread.id);
-                        claude.announceThread(result.thread);
+                        await claude.announceThread(result.thread);
+                        emitFastTransition(result.thread.id, undefined, claude.currentThreadSettings(result.thread.id), params.serviceTier);
                         return;
                     }
                 }
                 const params = (message.params ?? {});
+                if (params.threadId && message.method === "turn/start"
+                    && (claude.ownsThread(params.threadId)
+                        || handoffs.logical?.(params.threadId)?.epoch.provider === "claude")) {
+                    const backend = handoffs.logical?.(params.threadId)?.epoch.backendThreadId ?? params.threadId;
+                    if (!claude.isChildProjection(backend)) {
+                        const promptedCompact = claudeCompactCommand((message.params ?? {}).input);
+                        if (promptedCompact) {
+                            const prepared = await claude.preparePromptedCompact(backend, promptedCompact);
+                            sendResult(message.id, prepared.response);
+                            selectForeground("claude", params.threadId);
+                            await prepared.announce();
+                            return;
+                        }
+                    }
+                }
+                if (params.threadId && message.method === "turn/start" && features.statusCommand) {
+                    const turn = (message.params ?? {});
+                    if (isCCodexStateCommand(turn.input)) {
+                        if (claude.ownsThread(params.threadId) && !claude.isChildProjection(params.threadId)) {
+                            const prepared = await claude.prepareStateTurn(turn, () => threadState(params.threadId));
+                            sendResult(message.id, prepared.response);
+                            selectForeground("claude", params.threadId);
+                            await prepared.announce();
+                            prepared.start();
+                        }
+                        else {
+                            const notice = transientCommandNotice(params.threadId, turn.input, await threadState(params.threadId), turn.clientUserMessageId ?? null);
+                            sendResult(message.id, notice.response);
+                            selectForeground(claude.ownsThread(params.threadId) ? "claude" : "codex", params.threadId);
+                            emitNotice(notice);
+                        }
+                        return;
+                    }
+                    if (isCCodexStatusCommand(turn.input)) {
+                        if (claude.ownsThread(params.threadId) && !claude.isChildProjection(params.threadId)) {
+                            const prepared = await claude.prepareStatusTurn(turn, () => combinedStatus(params.threadId));
+                            sendResult(message.id, prepared.response);
+                            selectForeground("claude", params.threadId);
+                            await prepared.announce();
+                            prepared.start();
+                        }
+                        else {
+                            const notice = transientCommandNotice(params.threadId, turn.input, await combinedStatus(claude.ownsThread(params.threadId) ? params.threadId : undefined), turn.clientUserMessageId ?? null);
+                            sendResult(message.id, notice.response);
+                            selectForeground(claude.ownsThread(params.threadId) ? "claude" : "codex", params.threadId);
+                            emitNotice(notice);
+                        }
+                        return;
+                    }
+                }
+                if (params.threadId && message.method === "turn/start"
+                    && (handoffs.logical?.(params.threadId)?.epoch.provider === "stock"
+                        || (!handoffs.logical?.(params.threadId) && !claude.ownsThread(params.threadId)))
+                    && providerAvailability) {
+                    let availability = await providerAvailability.read("codex");
+                    if (availability.state !== "ready")
+                        availability = await providerAvailability.refresh("codex");
+                    if (availability.state !== "ready") {
+                        const notice = transientSystemNotice(params.threadId, providerUnavailableMessage(availability), "error");
+                        sendResult(message.id, notice.response);
+                        selectForeground("codex", params.threadId);
+                        emitNotice(notice);
+                        return;
+                    }
+                }
+                if (params.threadId && message.method === "turn/start") {
+                    handoffs.observeDurableTurn(connectionId, (message.params ?? {}));
+                }
                 if (params.threadId && message.method === "thread/settings/update") {
                     const update = (message.params ?? {});
                     const staged = handoffs.interceptSettings(update);
@@ -161,6 +432,104 @@ export function attachClientConnection(client, stockSocket, claudeModels, claude
                         return;
                     }
                 }
+                if (params.threadId && message.method === "turn/start") {
+                    const turn = (message.params ?? {});
+                    const pending = handoffs.stageTurnSwitch
+                        ? handoffs.stageTurnSwitch(turn)
+                        : handoffs.pending(params.threadId);
+                    if (pending) {
+                        subscriptions.subscribe(params.threadId, connectionId, notificationSink, serverRequestSink);
+                        const migration = providerMigrationNotice(params.threadId);
+                        sendResult(message.id, migration.response);
+                        for (const notification of migration.notifications) {
+                            subscriptions.emitPublic(params.threadId, notification.method, notification.params);
+                        }
+                        const execute = async () => {
+                            const switchProviderTurn = handoffs.switchProviderTurn;
+                            let compacted = false;
+                            const completeCompaction = () => {
+                                if (compacted)
+                                    return;
+                                compacted = true;
+                                for (const notification of providerMigrationCompleted(params.threadId, migration)) {
+                                    subscriptions.emitPublic(params.threadId, notification.method, notification.params);
+                                }
+                            };
+                            if (switchProviderTurn) {
+                                await switchProviderTurn.call(handoffs, turn, migration.response.turn, stockRpc, connectionId, completeCompaction);
+                                selectForeground(pending.targetProvider === "claude" ? "claude" : "codex", params.threadId);
+                                return;
+                            }
+                            if (pending.sourceProvider === "claude") {
+                                const hidden = await claude.forkThread({
+                                    threadId: params.threadId, ephemeral: true, threadSource: "subAgent",
+                                });
+                                await claude.compactThread(hidden.thread.id);
+                                const target = await stockRpc.request("thread/start", {
+                                    model: pending.targetModel,
+                                    cwd: turn.cwd,
+                                    approvalPolicy: turn.approvalPolicy,
+                                    permissions: turn.permissions,
+                                });
+                                completeCompaction();
+                                await stockRpc.request("turn/start", { ...turn, threadId: target.thread.id });
+                                selectForeground("codex", params.threadId);
+                                return;
+                            }
+                            const hidden = await stockRpc.request("thread/fork", {
+                                threadId: params.threadId, ephemeral: true, excludeTurns: true,
+                            });
+                            await stockRpc.request("turn/start", {
+                                threadId: hidden.thread.id,
+                                input: [{ type: "text", text: "Compact this task for a provider handoff.", text_elements: [] }],
+                            });
+                            const target = await claude.startThread({
+                                model: pending.targetModel,
+                                ...(turn.cwd !== undefined ? { cwd: turn.cwd } : {}),
+                                ...(turn.approvalPolicy !== undefined ? { approvalPolicy: turn.approvalPolicy } : {}),
+                                ...(turn.permissions !== undefined ? { permissions: turn.permissions } : {}),
+                            });
+                            const prepared = await claude.prepareTurn({ ...turn, threadId: target.thread.id });
+                            completeCompaction();
+                            await prepared.announce();
+                            prepared.start();
+                            selectForeground("claude", params.threadId);
+                        };
+                        void execute().catch((error) => {
+                            const message = error instanceof Error ? error.message : String(error);
+                            for (const notification of providerMigrationFailed(params.threadId, migration, message))
+                                subscriptions.emitPublic(params.threadId, notification.method, notification.params);
+                            for (const notification of transientSystemNotice(params.threadId, `Provider switch failed; your message was not sent\n  ↳ ${message}`, "error").notifications)
+                                subscriptions.emitPublic(params.threadId, notification.method, notification.params);
+                            const source = handoffs.logical?.(params.threadId);
+                            if (source)
+                                subscriptions.emitPublic(params.threadId, "thread/settings/updated", {
+                                    threadId: params.threadId,
+                                    threadSettings: {
+                                        ...source.epoch.settings,
+                                        model: source.epoch.model,
+                                        modelProvider: source.epoch.provider === "claude" ? "claude" : "openai",
+                                    },
+                                });
+                        });
+                        return;
+                    }
+                }
+                if (params.threadId && handoffs.logical?.(params.threadId)
+                    && message.method !== "thread/fork" && message.method !== "thread/rollback") {
+                    if (message.method === "thread/unsubscribe") {
+                        subscriptions.unsubscribe(params.threadId, connectionId);
+                        sendResult(message.id, { status: "unsubscribed" });
+                        clearForeground(params.threadId);
+                        return;
+                    }
+                    subscriptions.subscribe(params.threadId, connectionId, notificationSink, serverRequestSink);
+                    const handled = await handoffs.requestLogical(message.method, (message.params ?? {}), stockRpc);
+                    sendResult(message.id, handled.result);
+                    selectForeground(handled.provider === "claude" ? "claude" : "codex", params.threadId);
+                    await handled.after?.();
+                    return;
+                }
                 if (params.threadId && message.method === "turn/start") {
                     const target = handoffs.blockedTurnTarget((message.params ?? {}));
                     if (target) {
@@ -172,34 +541,92 @@ export function attachClientConnection(client, stockSocket, claudeModels, claude
                 }
                 if (params.threadId && message.method === "thread/fork") {
                     const forkParams = (message.params ?? {});
-                    if (handoffs.shouldFork(forkParams)) {
-                        emitTransientNotice(params.threadId, "Compacting before fork. If the App reports ‘Codex request timed out’, ignore it—the new task will still appear in the sidebar.");
-                        const result = await handoffs.fork(forkParams, stockRpc, connectionId);
-                        if (claude.ownsThread(result.thread.id)) {
-                            subscribeClaude(result.thread.id);
-                            claude.announceThread(result.thread);
-                        }
-                        else {
-                            subscriptions.emit(result.thread.id, "thread/started", { thread: result.thread });
+                    if (handoffs.isSystemEphemeralFork(forkParams)) {
+                        sendResult(message.id, await handoffs.forkSystemEphemeral(forkParams, stockRpc, connectionId));
+                        return;
+                    }
+                    const logicalFork = handoffs.forkLogical;
+                    const overlay = handoffs.overlay(params.threadId);
+                    if ((logicalFork && handoffs.logical?.(params.threadId)) || overlay?.epochs) {
+                        if (logicalFork) {
+                            sendResult(message.id, await logicalFork.call(handoffs, forkParams, stockRpc));
+                            return;
                         }
-                        sendResult(message.id, result);
+                        const turns = overlay.epochs.flatMap((epoch) => epoch.publicTurnIds.map((id) => ({ id, items: [], status: "completed" })));
+                        sendResult(message.id, { thread: { id: uuidv7(), forkedFromId: params.threadId, turns } });
                         return;
                     }
+                    if (forkParams.model) {
+                        const sourceProvider = claude.ownsThread(params.threadId) ? "claude" : "stock";
+                        const targetProvider = claude.ownsModel(forkParams.model) ? "claude" : "stock";
+                        if (sourceProvider !== targetProvider) {
+                            throw new RpcError(-32602, "Fork is same-provider only. Change the model and send a message to switch provider.");
+                        }
+                    }
+                }
+                if (params.threadId && message.method === "thread/delete"
+                    && handoffs.ownsSystemEphemeral(connectionId, params.threadId)) {
+                    const result = await stockRpc.request("thread/delete", message.params ?? {});
+                    handoffs.releaseSystemEphemeral(connectionId, params.threadId);
+                    sendResult(message.id, result);
+                    return;
+                }
+                if (params.threadId && message.method === "thread/unsubscribe"
+                    && handoffs.ownsSystemEphemeral(connectionId, params.threadId)) {
+                    const result = await stockRpc.request("thread/unsubscribe", message.params ?? {});
+                    handoffs.releaseSystemEphemeral(connectionId, params.threadId);
+                    sendResult(message.id, result);
+                    return;
                 }
                 if (params.threadId && message.method === "thread/delete" && !claude.ownsThread(params.threadId)
                     && (handoffs.pending(params.threadId) || handoffs.overlay(params.threadId))) {
                     const result = await stockRpc.request("thread/delete", message.params ?? {});
                     handoffs.clearThread(params.threadId);
                     sendResult(message.id, result);
+                    clearForeground(params.threadId);
+                    return;
+                }
+                if (params.threadId && message.method === "thread/rollback" && handoffs.logical?.(params.threadId)) {
+                    sendResult(message.id, await handoffs.rollbackLogicalFork((message.params ?? {}), stockRpc, connectionId));
                     return;
                 }
                 if (params.threadId && handoffs.overlay(params.threadId)) {
+                    if (message.method === "thread/rollback") {
+                        const rollback = (message.params ?? {});
+                        const logicalRollback = handoffs.rollbackLogicalFork;
+                        if (logicalRollback) {
+                            sendResult(message.id, await logicalRollback.call(handoffs, rollback, stockRpc, connectionId));
+                            return;
+                        }
+                        const overlay = handoffs.overlay(params.threadId);
+                        if (overlay.epochs) {
+                            const turns = overlay.epochs.flatMap((epoch) => epoch.publicTurnIds.map((turnId) => ({ epoch, turnId })));
+                            const selected = turns.at(turns.length - rollback.numTurns - 1);
+                            if (!selected)
+                                throw new RpcError(-32602, "Fork rollback removed every provider turn.");
+                            if (selected.epoch.provider === "claude") {
+                                await claude.forkThread({
+                                    threadId: selected.epoch.backendThreadId,
+                                    lastTurnId: selected.turnId,
+                                });
+                            }
+                            else {
+                                await stockRpc.request("thread/fork", {
+                                    threadId: selected.epoch.backendThreadId,
+                                    lastTurnId: selected.turnId,
+                                });
+                            }
+                            sendResult(message.id, {});
+                            return;
+                        }
+                    }
                     if (message.method === "thread/read") {
                         sendResult(message.id, await handoffs.readOverlay((message.params ?? {}), stockRpc));
                         return;
                     }
                     if (message.method === "thread/resume") {
                         sendResult(message.id, await handoffs.resumeOverlay((message.params ?? {}), stockRpc));
+                        selectForeground("codex", params.threadId);
                         return;
                     }
                     if (message.method === "thread/turns/list") {
@@ -213,15 +640,40 @@ export function attachClientConnection(client, stockSocket, claudeModels, claude
                 }
                 if (params.threadId && claude.ownsThread(params.threadId)) {
                     if (message.method === "thread/resume") {
-                        subscribeClaude(params.threadId);
-                        const result = await claude.resumeThread((message.params ?? {}));
-                        sendResult(message.id, result);
-                        claude.replayPendingRequests(params.threadId);
+                        muteClaudeDuringSnapshot(params.threadId);
+                        try {
+                            const prepared = await claude.prepareResume((message.params ?? {}));
+                            const result = prepared.response;
+                            const snapshotHighWatermark = claude.eventHighWatermark(params.threadId);
+                            const tokenUsage = claude.latestTokenUsage(params.threadId);
+                            sendResult(message.id, result);
+                            selectForeground("claude", params.threadId);
+                            subscriptions.unmute(params.threadId, connectionId);
+                            if (tokenUsage && tokenUsage.sequence <= snapshotHighWatermark) {
+                                notificationSink(tokenUsage.method, tokenUsage.params);
+                            }
+                            for (const event of claude.eventsAfter(params.threadId, snapshotHighWatermark)) {
+                                notificationSink(event.method, event.params);
+                            }
+                            await prepared.notifyGoalSnapshot(notificationSink);
+                            await claude.replayPendingRequests(params.threadId, connectionId);
+                            const failedFork = handoffs.claimFailedFork(params.threadId);
+                            if (failedFork)
+                                emitTransientNotice(params.threadId, `Cross-provider fork failed while the App was disconnected: ${failedFork}`, "error");
+                        }
+                        catch (error) {
+                            subscriptions.unmute(params.threadId, connectionId);
+                            subscriptions.unsubscribe(params.threadId, connectionId);
+                            throw error;
+                        }
                         return;
                     }
                     if (message.method === "thread/read") {
                         const read = (message.params ?? {});
                         sendResult(message.id, claude.readThread(read.threadId, read.includeTurns ?? false));
+                        const failedFork = handoffs.claimFailedFork(params.threadId);
+                        if (failedFork)
+                            emitTransientNotice(params.threadId, `Cross-provider fork failed while the App was disconnected: ${failedFork}`, "error");
                         return;
                     }
                     if (message.method === "thread/turns/list") {
@@ -235,7 +687,11 @@ export function attachClientConnection(client, stockSocket, claudeModels, claude
                     }
                     if (message.method === "thread/unsubscribe") {
                         subscriptions.unsubscribe(params.threadId, connectionId);
+                        subscribedClaudeThreads.delete(params.threadId);
                         sendResult(message.id, { status: "unsubscribed" });
+                        clearForeground(params.threadId);
+                        if (!subscriptions.hasSubscribers(params.threadId))
+                            await claude.releaseEphemeralThread(params.threadId);
                         return;
                     }
                     if (message.method === "thread/name/set") {
@@ -243,11 +699,16 @@ export function attachClientConnection(client, stockSocket, claudeModels, claude
                         return;
                     }
                     if (message.method === "thread/metadata/update") {
-                        sendResult(message.id, claude.updateThreadMetadata((message.params ?? {})));
+                        sendResult(message.id, await claude.updateThreadMetadata((message.params ?? {})));
                         return;
                     }
                     if (message.method === "thread/settings/update") {
-                        sendResult(message.id, await claude.updateThreadSettings((message.params ?? {})));
+                        const update = (message.params ?? {});
+                        const before = claude.currentThreadSettings(params.threadId);
+                        const result = await claude.updateThreadSettings(update);
+                        const after = claude.currentThreadSettings(params.threadId);
+                        sendResult(message.id, result);
+                        emitFastTransition(params.threadId, before, after, update.serviceTier);
                         return;
                     }
                     if (message.method === "thread/archive") {
@@ -255,20 +716,22 @@ export function attachClientConnection(client, stockSocket, claudeModels, claude
                         return;
                     }
                     if (message.method === "thread/unarchive") {
-                        sendResult(message.id, claude.unarchiveThread(params.threadId));
+                        sendResult(message.id, await claude.unarchiveThread(params.threadId));
                         return;
                     }
                     if (message.method === "thread/delete") {
                         const result = await claude.deleteThread(params.threadId);
                         handoffs.clearThread(params.threadId);
                         sendResult(message.id, result);
+                        clearForeground(params.threadId);
                         return;
                     }
                     if (message.method === "thread/fork") {
                         const result = await claude.forkThread((message.params ?? {}));
                         sendResult(message.id, result);
+                        selectForeground("claude", result.thread.id);
                         subscribeClaude(result.thread.id);
-                        claude.announceThread(result.thread);
+                        await claude.announceThread(result.thread);
                         return;
                     }
                     if (message.method === "thread/rollback") {
@@ -287,38 +750,67 @@ export function attachClientConnection(client, stockSocket, claudeModels, claude
                         sendResult(message.id, await claude.shellCommand((message.params ?? {})));
                         return;
                     }
+                    if (message.method === "thread/backgroundTerminals/clean") {
+                        sendResult(message.id, await claude.cleanBackgroundTerminals((message.params ?? {})));
+                        return;
+                    }
+                    if (message.method === "thread/backgroundTerminals/list") {
+                        sendResult(message.id, await claude.listBackgroundTerminals((message.params ?? {})));
+                        return;
+                    }
+                    if (message.method === "thread/backgroundTerminals/terminate") {
+                        sendResult(message.id, await claude.terminateBackgroundTerminal((message.params ?? {})));
+                        return;
+                    }
                     if (message.method === "review/start") {
                         const prepared = await claude.prepareReview((message.params ?? {}));
-                        sendResult(message.id, prepared.response);
                         if (prepared.forkedThread) {
                             subscribeClaude(prepared.forkedThread.id);
-                            claude.announceThread(prepared.forkedThread);
+                            await claude.announceThread(prepared.forkedThread);
                         }
-                        prepared.announce();
+                        sendResult(message.id, prepared.response);
+                        await prepared.announce();
                         prepared.start();
                         return;
                     }
                     if (message.method === "thread/goal/set") {
-                        sendResult(message.id, claude.setGoal((message.params ?? {})));
+                        const prepared = await claude.prepareGoalSet((message.params ?? {}));
+                        try {
+                            sendResult(message.id, prepared.response);
+                        }
+                        finally {
+                            await prepared.notify();
+                        }
                         return;
                     }
                     if (message.method === "thread/goal/get") {
-                        sendResult(message.id, claude.getGoal(params.threadId));
+                        sendResult(message.id, await claude.getGoal(params.threadId));
                         return;
                     }
                     if (message.method === "thread/goal/clear") {
-                        sendResult(message.id, claude.clearGoal(params.threadId));
+                        const prepared = await claude.prepareGoalClear(params.threadId);
+                        try {
+                            sendResult(message.id, prepared.response);
+                        }
+                        finally {
+                            await prepared.notify();
+                        }
                         return;
                     }
                     if (message.method === "turn/start") {
-                        const prepared = await claude.prepareTurn((message.params ?? {}));
+                        const turn = (message.params ?? {});
+                        const before = claude.currentThreadSettings(params.threadId);
+                        const prepared = await claude.prepareTurn(turn);
+                        const after = claude.currentThreadSettings(params.threadId);
                         sendResult(message.id, prepared.response);
-                        prepared.announce();
+                        selectForeground("claude", params.threadId);
+                        emitFastTransition(params.threadId, before, after, turn.serviceTier);
+                        await prepared.announce();
                         prepared.start();
                         return;
                     }
                     if (message.method === "turn/interrupt") {
-                        await claude.interruptTurn((message.params ?? {}).threadId);
+                        await claude.interruptTurn((message.params ?? {}));
                         sendResult(message.id, {});
                         return;
                     }
@@ -328,6 +820,11 @@ export function attachClientConnection(client, stockSocket, claudeModels, claude
                     }
                     throw new RpcError(-32601, `Method '${message.method}' is not implemented for Claude threads yet.`);
                 }
+                if (params.threadId && (message.method === "thread/read" || message.method === "thread/resume")) {
+                    const failedFork = handoffs.claimFailedFork(params.threadId);
+                    if (failedFork)
+                        emitTransientNotice(params.threadId, `Cross-provider fork failed while the App was disconnected: ${failedFork}`, "error");
+                }
             }
             catch (error) {
                 const failure = rpcError(error);
@@ -341,18 +838,28 @@ export function attachClientConnection(client, stockSocket, claudeModels, claude
                     ? message.params
                     : undefined;
                 const threadId = typeof params?.threadId === "string" ? params.threadId : undefined;
-                if (message.method === "turn/start" && threadId) {
+                const childProjection = Boolean(threadId && claude.isChildProjection(threadId));
+                if (message.method === "turn/start" && threadId && !childProjection) {
                     const notice = transientSystemNotice(threadId, failure.message, "error");
                     sendResult(message.id, notice.response);
                     emitNotice(notice);
                     return;
                 }
-                if (threadId)
+                if (threadId && !childProjection)
                     emitSystemError(threadId, failure.message);
                 sendError(message.id, failure.code, failure.message);
-                if (threadId) {
+                if (threadId && !childProjection) {
                     if (claude.ownsThread(threadId)) {
-                        claude.reportError(threadId, typeof params?.turnId === "string" ? params.turnId : undefined, failure.message, rpcCodexErrorInfo(failure.code));
+                        await claude.reportError(threadId, typeof params?.turnId === "string" ? params.turnId : undefined, failure.message, rpcCodexErrorInfo(failure.code)).catch((diagnosticError) => {
+                            logger.warn("claude.request.error-report-failed", {
+                                connectionId,
+                                method: message.method,
+                                originalError: failure.message,
+                                diagnosticError: diagnosticError instanceof Error
+                                    ? diagnosticError.message
+                                    : String(diagnosticError),
+                            });
+                        });
                     }
                     else {
                         sendJson({
@@ -369,12 +876,28 @@ export function attachClientConnection(client, stockSocket, claudeModels, claude
                 return;
             }
         }
-        trackForwardedRequest(message);
+        let forwarded = message;
+        if (message && isRequest(message) && message.method === "turn/start") {
+            const params = handoffs.prepareTitleTurn(connectionId, (message.params ?? {}));
+            if (params !== message.params)
+                forwarded = { ...message, params };
+        }
+        if (message && isRequest(message) && message.method === "thread/fork") {
+            const params = (message.params ?? {});
+            if (params.ephemeral !== true && params.threadSource !== "system") {
+                const completed = stockState.completeForkParams(params);
+                if (completed !== params)
+                    forwarded = { ...message, params: completed };
+            }
+        }
+        if (forwarded)
+            stockState.observeRequest(connectionId, forwarded);
+        trackForwardedRequest(forwarded);
         if (stock.readyState === WebSocketState.OPEN) {
-            stock.send(data, { binary: isBinary });
+            stock.send(forwarded === message ? data : JSON.stringify(forwarded), { binary: isBinary });
         }
         else {
-            queued.push({ data, isBinary });
+            queued.push({ data: forwarded === message ? data : Buffer.from(JSON.stringify(forwarded)), isBinary });
         }
     });
     stock.once("open", () => {
@@ -384,6 +907,11 @@ export function attachClientConnection(client, stockSocket, claudeModels, claude
     });
     stock.on("message", (data, isBinary) => {
         const message = isBinary ? undefined : parseRpcMessage(data);
+        if (message) {
+            stockState.observeResponse(connectionId, message);
+            stockState.observeNotification(message);
+        }
+        let foregroundAfterForward;
         if (message && "method" in message && !("id" in message) && message.method === "remoteControl/status/changed" && remoteControl) {
             remoteControl.intercept(connectionId, notificationSink, message.params);
             return;
@@ -392,17 +920,62 @@ export function attachClientConnection(client, stockSocket, claudeModels, claude
             completeLatency(message.id, "stock");
             const forwarded = forwardedRequests.get(requestKey(message.id));
             forwardedRequests.delete(requestKey(message.id));
-            if (forwarded?.threadId && "error" in message)
+            if (forwarded?.systemEphemeral && "result" in message) {
+                const result = message.result && typeof message.result === "object"
+                    ? message.result
+                    : undefined;
+                if (typeof result?.thread?.id === "string") {
+                    handoffs.registerForwardedEphemeralCandidate(connectionId, result.thread.id, forwarded.systemEphemeral);
+                }
+            }
+            if (forwarded?.threadId && isUuid(forwarded.threadId) && "error" in message) {
                 emitSystemError(forwarded.threadId, message.error.message);
+            }
+            if (forwarded && "result" in message) {
+                const result = message.result && typeof message.result === "object"
+                    ? message.result
+                    : undefined;
+                const resultThreadId = typeof result?.thread?.id === "string" ? result.thread.id : forwarded.threadId;
+                if (forwarded.foreground && resultThreadId) {
+                    handoffs.observeDurableThread(connectionId, "stock");
+                    foregroundAfterForward = () => selectForeground(forwarded.foreground, resultThreadId);
+                }
+                else if (forwarded.clearForeground && forwarded.threadId) {
+                    foregroundAfterForward = () => clearForeground(forwarded.threadId);
+                }
+            }
         }
         if (message && stockRpc.handle(message))
             return;
         if (message && "method" in message) {
+            if (!("id" in message) && message.method === "account/rateLimits/updated" && foreground?.provider === "claude") {
+                publishForegroundRateLimits(foregroundGeneration);
+                return;
+            }
+            if (!("id" in message) && message.method === "account/rateLimits/updated" && !foreground) {
+                diagnoseUnknownStatus("account/rateLimits/updated");
+            }
+            if (handoffs.captureInternalStockMessage(connectionId, message)) {
+                if (isRequest(message))
+                    stock.send(JSON.stringify({ id: message.id, result: { decision: "decline" } }));
+                return;
+            }
+            const rewritten = handoffs.rewriteTitleMessages(message);
+            if (rewritten) {
+                for (const output of rewritten)
+                    sendJson(output);
+                return;
+            }
             if (handoffs.suppressStockTargetMessage(connectionId, message)) {
                 if (isRequest(message))
                     stock.send(JSON.stringify({ id: message.id, result: { decision: "decline" } }));
                 return;
             }
+            if (handoffs.ownsStockBackendMessage?.(message)) {
+                if (isRequest(message))
+                    stock.send(JSON.stringify({ id: message.id, result: { decision: "decline" } }));
+                return;
+            }
             const params = message.params && typeof message.params === "object" ? message.params : undefined;
             const nestedThread = params?.thread && typeof params.thread === "object"
                 ? params.thread.id
@@ -417,17 +990,12 @@ export function attachClientConnection(client, stockSocket, claudeModels, claude
                 if (typeof error?.message === "string")
                     emitSystemError(threadId, error.message);
             }
-            if (threadId && handoffs.ownsInternalStockThread(threadId)) {
-                handoffs.recordInternalStockMessage(message);
-                if (isRequest(message))
-                    stock.send(JSON.stringify({ id: message.id, result: { decision: "decline" } }));
-                return;
-            }
         }
         if (client.readyState === WebSocketState.OPEN) {
             recorder.frame(connectionId, "gateway_to_client", data, isBinary);
             client.send(data, { binary: isBinary });
         }
+        foregroundAfterForward?.();
     });
     const closeClient = (code, reason) => {
         if (client.readyState === WebSocketState.OPEN)
@@ -439,17 +1007,45 @@ export function attachClientConnection(client, stockSocket, claudeModels, claude
     });
     stock.on("close", () => closeClient(1011, "Stock app-server closed"));
     client.on("error", (error) => logger.warn("connection.client.error", { connectionId, error: error.message }));
+    let closeStarted = false;
     client.on("close", (code, reason) => {
-        metrics.connectionClosed();
-        subscriptions.detach(connectionId);
-        handoffs.detachConnection(connectionId);
-        remoteControl?.detach(connectionId);
-        stockRpc.close(new Error("Client connection closed."));
-        if (stock.readyState === WebSocketState.OPEN || stock.readyState === WebSocketState.CONNECTING) {
-            stock.close();
-        }
-        logger.info("connection.closed", { connectionId });
-        recorder.connection("closed", connectionId, { code, reason: reason.toString("utf8") });
+        if (closeStarted)
+            return;
+        closeStarted = true;
+        connectionAlive = false;
+        void (async () => {
+            metrics.connectionClosed();
+            const releasedThreads = [...subscribedClaudeThreads];
+            subscribedClaudeThreads.clear();
+            subscriptions.detach(connectionId);
+            claude.unsubscribeRateLimits(connectionId);
+            const releases = await Promise.allSettled(releasedThreads.map(async (threadId) => {
+                if (!subscriptions.hasSubscribers(threadId))
+                    claude.scheduleEphemeralRelease(threadId);
+            }));
+            remoteControl?.detach(connectionId);
+            let detach;
+            try {
+                await handoffs.detachConnection(connectionId, stockRpc);
+            }
+            catch (error) {
+                detach = error;
+            }
+            stockState.detach(connectionId);
+            stockRpc.close(new Error("Client connection closed."));
+            if (stock.readyState === WebSocketState.OPEN || stock.readyState === WebSocketState.CONNECTING) {
+                stock.close();
+            }
+            logger.info("connection.closed", { connectionId });
+            recorder.connection("closed", connectionId, { code, reason: reason.toString("utf8") });
+            const errors = [
+                ...releases.flatMap((result) => result.status === "rejected" ? [result.reason] : []),
+                ...(detach === undefined ? [] : [detach]),
+            ];
+            if (errors.length > 0)
+                throw new AggregateError(errors, "Client connection cleanup failed.");
+        })().then(resolveClosed, rejectClosed);
     });
+    return { closed };
 }
 //# sourceMappingURL=clientConnection.js.map