@gkorepanov/ccodex 0.5.0-rc.2 → 0.5.0-rc.21

package/dist/claude/threads.js

@@ -1,19 +1,22 @@
 import { randomUUID } from "node:crypto";
-import { existsSync, statSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { deleteSession, forkSession, renameSession } from "@anthropic-ai/claude-agent-sdk";
 import { v7 as uuidv7 } from "uuid";
 import { packageVersion } from "../management/commands.js";
 import { invalidParams, invalidRequest, requestedModel } from "../protocol/codex.js";
-import { historyCursors, paginateItems, paginateTurns, startedTurn } from "../protocol/turnPagination.js";
+import { anchorCursor, historyCursors, occurrencesPage, paginateItems, paginateTurns, startedTurn, turnOccurrences } from "../protocol/turnPagination.js";
+import { claudeEffort, ULTRA } from "./delegation.js";
 import { normalizeUserInput } from "./inputMapper.js";
 import { claudeModelLabel, modelCatalogValue, normalizeClaudeModelIdentifier } from "./modelSelection.js";
 import { NativeSessionCatalog } from "./native/catalog.js";
+import { firstMatch } from "./native/search.js";
 import { nativeThread } from "./native/projector.js";
 import { projectSubagents } from "./native/subagents.js";
 import { readTranscriptRecords } from "./native/records.js";
-import { summarizeTranscript, userText } from "./native/summary.js";
-import { codexPermissions, mapClaudeModel, mapSkill, permissionModeFrom, withProbeQuery } from "./sdk.js";
+import { preview, summarizeTranscript, userText } from "./native/summary.js";
+import { claudeMode, codexPermissions, mapClaudeModel, mapSkill, permissionSettings, withProbeQuery } from "./sdk.js";
 import { killProcesses, sessionProcesses } from "./processes.js";
 import { ClaudeSession } from "./session.js";
 /** Claude's standard context window, until a session of the model reports its own. */
@@ -28,6 +31,13 @@ const IDLE_MS = Number(process.env.CCODEX_E2E_IDLE_MS) || 30 * 60_000;
 const RESUME_WARM_MS = Number(process.env.CCODEX_E2E_RESUME_WARM_MS) || 10_000;
 /** Claude processes kept at most (each holds its session in memory: 250–550 MB); tests lower it. */
 const MAX_PROCESSES = Number(process.env.CCODEX_E2E_MAX_PROCESSES) || 10;
+/** A chat's permissions and plan mode from the mode its transcript last recorded (in plan mode, meta.json keeps its own). */
+function recordedPermissions(threadId, recorded, meta) {
+    if (recorded !== "plan")
+        return { permissionMode: (recorded ?? "default"), plan: false };
+    const kept = meta.plan(threadId);
+    return { permissionMode: (kept?.permissionMode ?? "default"), plan: kept?.plan ?? true };
+}
 /** The Claude side of the gateway: catalog of native sessions, live sessions, side chats, models, skills. */
 export class ClaudeThreads {
     config;
@@ -38,6 +48,9 @@ export class ClaudeThreads {
     sides = new Map();
     /** `agent-<id>` sub-agent thread → the native session whose transcript directory holds it. */
     subagentRoots = new Map();
+    /** Threads rolled back but not continued yet: their kept history ends at this record. A restart meanwhile shows
+     *  the rolled-back messages again. */
+    leaves = new Map();
     /** Sub-agents spawned live, shown until Claude has written their transcript. */
     spawnedSubagents = new Map();
     /** Context window of each Claude model, as its sessions report it. */
@@ -47,6 +60,11 @@ export class ClaudeThreads {
     models_;
     defaultModel = null;
     rateLimitWindows = new Map();
+    usage;
+    /** Why Claude's plan limits could not be read, when they could not. */
+    usageError;
+    /** Weekly windows of single models (e.g. Fable), from Claude's `/usage` data. */
+    modelLimits = [];
     stopWatching;
     onTurnCompleted;
     constructor(config, gateway, logger) {
@@ -56,8 +74,15 @@ export class ClaudeThreads {
         this.catalog = new NativeSessionCatalog(join(config.claudeHome, "projects"), { path: join(config.dataDir, "claude-catalog.json"), key: packageVersion() });
     }
     async start() {
-        // The model list maps transcripts' resolved model ids to picker values (see pickerModel).
-        void this.models().catch(() => undefined);
+        // The model list maps transcripts' resolved model ids to picker values (see pickerModel): the one Claude reported last
+        // time at once (a chat opened right after a start waits for no probe), the fresh one once the probe answers.
+        const cached = this.cachedModels();
+        if (cached) {
+            this.models_ = Promise.resolve(this.useModels(cached));
+            void this.probeModels().then((models) => { this.models_ = Promise.resolve(models); }, () => undefined);
+        }
+        else
+            void this.models().catch(() => undefined);
         await this.catalog.refresh();
         this.gateway.meta.prune((segment) => segment.provider === "codex" || this.catalog.get(segment.threadId) !== undefined);
         const known = new Map(this.catalog.sessions().map((summary) => [summary.sessionId, summary.customTitle ?? summary.aiTitle]));
@@ -87,7 +112,7 @@ export class ClaudeThreads {
     /** CPU seconds each command of a loaded session used, and since when unchanged. */
     cpuSeen = new Map();
     sweeper;
-    /** What CCodex last did to each chat's process and commands, and why (shown by /ccstate). */
+    /** What CCodex last did to each chat's process and commands, and why (shown by /cc). */
     actions = new Map();
     act(session, event, text, pids) {
         this.logger.info(event, { threadId: session.threadId, pids });
@@ -127,7 +152,7 @@ export class ClaudeThreads {
                 this.act(session, "claude.tasks.hung", `stopped its background tasks: their commands used no CPU for ${idle}`, pids);
                 void session.stopTasks().catch(() => killProcesses(pids));
             }
-            else if (session.quiet(now, IDLE_MS) && !this.gateway.subscribers(session.threadId)) {
+            else if (session.quiet(now, IDLE_MS) && !this.gateway.subscribers(session.threadId).size) {
                 this.act(session, "claude.unloaded", `unloaded the chat: nobody had it open and it was quiet for ${idle}`, pids);
                 this.sessions.delete(session.threadId);
                 void session.unload().then(() => killProcesses(pids ?? []));
@@ -182,20 +207,34 @@ export class ClaudeThreads {
         return {
             ...summary,
             aiTitle: this.gateway.titles.naming(summary.sessionId) ? null : summary.aiTitle,
-            model: session?.settings.model ?? (summary.model && this.pickerModel(summary.model)),
-            reasoningEffort: session?.settings.effort ?? summary.reasoningEffort,
+            model: session?.settings.model ?? this.recordedModel(summary),
+            reasoningEffort: session?.settings.effort ?? this.recordedEffort(summary),
         };
     }
+    /** A chat's model from its transcript; in plan mode meta.json's (Claude plans a Haiku chat on Sonnet, see Meta.setPlan). */
+    recordedModel(summary) {
+        const planned = summary.permissionMode === "plan" ? this.gateway.meta.plan(summary.sessionId)?.model : undefined;
+        return planned ?? (summary.model && this.pickerModel(summary.model));
+    }
+    /** A chat's effort from its transcript (Claude records `ultra` as the max it runs at, told to delegate); in plan mode meta.json's. */
+    recordedEffort(summary) {
+        if (summary.permissionMode === "plan")
+            return this.gateway.meta.plan(summary.sessionId)?.effort ?? null;
+        return summary.delegating && summary.reasoningEffort === claudeEffort(ULTRA) ? ULTRA : summary.reasoningEffort;
+    }
     /** Transcripts name the resolved model (`claude-haiku-4-5-…`); the picker (and a live session) its value (`haiku`). */
     pickerModel(model) {
         const id = normalizeClaudeModelIdentifier(model);
         return this.pickerValues.get(id) ?? id;
     }
     /** Every native session as a list row (sub-agents excluded; they are listed through their parent). */
+    search(term) {
+        return this.catalog.search(this.config.claudeBinary, term);
+    }
     threads() {
         const rows = this.catalog.sessions().map((summary) => this.decorate(nativeThread(summary.sessionId, this.headerOf(summary, this.sessions.get(summary.sessionId)), { status: this.status(summary.sessionId) })));
         for (const session of this.sessions.values()) {
-            if (!this.catalog.get(session.threadId))
+            if (session.started && !this.catalog.get(session.threadId))
                 rows.push(this.decorate(this.freshThread(session)));
         }
         return rows;
@@ -216,7 +255,7 @@ export class ClaudeThreads {
         return nativeThread(session.threadId, {
             cwd: session.settings.cwd, gitBranch: null, createdAt: now, updatedAt: now, preview: "",
             customTitle: this.pendingNames.get(session.threadId) ?? null, aiTitle: null, model: session.settings.model, reasoningEffort: session.settings.effort,
-            serviceTier: session.settings.fast ? "fast" : null, permissionMode: session.settings.permissionMode, cliVersion: null, goal: null,
+            serviceTier: session.settings.fast ? "fast" : null, permissionMode: claudeMode(session.settings), cliVersion: null, goal: null,
         }, { status: this.status(session.threadId) });
     }
     // ---- reads ----
@@ -225,7 +264,7 @@ export class ClaudeThreads {
             await this.catalog.refresh();
         if (!this.catalog.get(threadId))
             return undefined;
-        return this.catalog.projection(threadId, this.gateway.meta.leaf(threadId));
+        return this.catalog.projection(threadId, this.leaves.get(threadId));
     }
     subagentRoot(threadId) {
         const known = this.subagentRoots.get(threadId);
@@ -278,7 +317,7 @@ export class ClaudeThreads {
     subagentSpawned(session, item, running) {
         const childId = item.receiverThreadIds[0];
         const now = Math.floor(Date.now() / 1000);
-        const header = { ...summarizeTranscript([]), cwd: session.settings.cwd, preview: item.prompt ?? "", model: item.model, createdAt: now, updatedAt: now };
+        const header = { ...summarizeTranscript([]), cwd: session.settings.cwd, preview: preview(item.prompt ?? ""), model: item.model, createdAt: now, updatedAt: now };
         const thread = nativeThread(childId, header, {
             status: { type: "active", activeFlags: [] },
             subagent: { parentThreadId: session.threadId, depth: 1, nickname: `${item.agentsStates[childId].message} [${claudeModelLabel(item.model ?? "Claude")}]` },
@@ -370,15 +409,7 @@ export class ClaudeThreads {
                 throw invalidParams(`thread not found: ${threadId}`);
             return { thread: this.decorate(this.freshThread(session)), turns: session.liveTurn() ? [session.liveTurn()] : [] };
         }
-        let turns = [...projection.turns];
-        const live = session?.liveTurn();
-        if (live) {
-            const index = turns.findIndex((turn) => turn.id === live.id);
-            if (index >= 0)
-                turns = [...turns.slice(0, index), { ...turns[index], status: "inProgress", completedAt: null }];
-            else
-                turns.push(live);
-        }
+        const turns = this.withLive(threadId, projection.turns);
         const summary = this.catalog.get(threadId);
         const header = summary ? this.headerOf(summary, session) : undefined;
         const thread = header
@@ -386,6 +417,110 @@ export class ClaudeThreads {
             : { ...projection.thread, turns: [] };
         return { thread: this.decorate(thread), turns, usage: projection.tokenUsage };
     }
+    /** The thread without its history: the catalog's header, no transcript read. */
+    async thread(threadId) {
+        const side = this.sides.get(threadId);
+        if (side)
+            return this.sideThread(side);
+        if (!this.catalog.get(threadId))
+            await this.catalog.refresh();
+        if (!this.paged(threadId))
+            return (await this.read(threadId)).thread;
+        await this.models().catch(() => undefined);
+        return this.decorate(nativeThread(threadId, this.headerOf(this.catalog.get(threadId), this.sessions.get(threadId)), { status: this.status(threadId) }));
+    }
+    /** A main session with a transcript: its history is read page by page (a sub-agent's, a small file of one turn, whole). */
+    paged(threadId) {
+        return !threadId.startsWith("agent-") && !this.sides.has(threadId) && this.catalog.has(threadId);
+    }
+    pages(threadId) {
+        return this.catalog.pages(threadId, this.leaves.get(threadId));
+    }
+    /** The running turn is the newest one, before Claude writes any of it too (a turn it goes on in after an answer). */
+    running(threadId, turnId) {
+        return this.sessions.get(threadId)?.liveTurn()?.id === turnId;
+    }
+    /** History turns with the live turn as the session shows it, and the background commands still running as running. */
+    withLive(threadId, history) {
+        const session = this.sessions.get(threadId);
+        const running = session?.runningCommands;
+        let turns = running?.size ? history.map((turn) => ({
+            ...turn,
+            items: turn.items.map((item) => running.has(item.id) ? { ...item, status: "inProgress", exitCode: null, aggregatedOutput: null, durationMs: null } : item),
+        })) : [...history];
+        const live = session?.liveTurn();
+        // Stock's stale turns: one the transcript leaves unfinished with none running here (its Claude died with a daemon
+        // restart) was interrupted. A sub-agent runs in its parent's session.
+        if (!live)
+            return threadId.startsWith("agent-") ? turns : turns.map((turn) => turn.status === "inProgress" ? { ...turn, status: "interrupted" } : turn);
+        const index = turns.findIndex((turn) => turn.id === live.id);
+        if (index >= 0)
+            turns = [...turns.slice(0, index), { ...turns[index], status: "inProgress", completedAt: null }];
+        else
+            turns.push(live);
+        return turns;
+    }
+    /** The newest turns (at least `count` unless history is shorter). */
+    async newestTurns(threadId, count) {
+        if (!this.catalog.get(threadId))
+            await this.catalog.refresh();
+        if (!this.paged(threadId))
+            return this.read(threadId);
+        const { pages, source } = this.pages(threadId);
+        const window = await pages.newest(source, count);
+        return { turns: this.withLive(threadId, window.turns), usage: window.projection.tokenUsage };
+    }
+    async turnsPage(threadId, params) {
+        if (!this.catalog.get(threadId))
+            await this.catalog.refresh();
+        const anchor = params.cursor ? anchorCursor("turnId", params.cursor) : undefined;
+        const descending = (params.sortDirection ?? "desc") === "desc";
+        // Oldest first from the start: the one page that needs all of history.
+        if (!this.paged(threadId) || !descending && !anchor)
+            return paginateTurns((await this.read(threadId)).turns, params);
+        const { pages, source } = this.pages(threadId);
+        const limit = Math.max(1, Math.min(params.limit ?? 25, 100));
+        const window = !anchor || this.running(threadId, anchor.anchor) ? await pages.newest(source, limit + 1)
+            : descending ? await pages.around(source, anchor.anchor, limit + 1)
+                : await pages.since(source, anchor.anchor);
+        return paginateTurns(this.withLive(threadId, window.turns), params);
+    }
+    /** Stock's `thread/searchOccurrences`: history is read back only to the first message holding the term (ripgrep finds it). */
+    async searchOccurrences(threadId, params) {
+        if (!String(params.searchTerm ?? "").trim())
+            throw invalidRequest("thread/searchOccurrences requires a non-empty searchTerm");
+        if (!this.catalog.get(threadId))
+            await this.catalog.refresh();
+        let turns;
+        if (this.paged(threadId)) {
+            const { pages, source } = this.pages(threadId);
+            const at = await firstMatch(this.config.claudeBinary, source.path, params.searchTerm);
+            turns = this.withLive(threadId, at === undefined ? [] : (await pages.reaching(source, at)).turns);
+        }
+        else
+            turns = (await this.read(threadId)).turns;
+        return occurrencesPage(turnOccurrences(turns, params.searchTerm), params);
+    }
+    async itemsPage(threadId, params) {
+        if (!this.catalog.get(threadId))
+            await this.catalog.refresh();
+        // Desktop always names the turn; items across the whole thread need all of it.
+        if (!this.paged(threadId) || !params.turnId)
+            return paginateItems((await this.read(threadId)).turns, params);
+        const { pages, source } = this.pages(threadId);
+        const window = this.running(threadId, params.turnId) ? await pages.newest(source, 1) : await pages.around(source, params.turnId, 0);
+        const turn = this.withLive(threadId, window.turns).find((candidate) => candidate.id === params.turnId);
+        const anchor = params.cursor ? anchorCursor("itemId", params.cursor)?.anchor : undefined;
+        if (!anchor || turn.items.some((item) => item.id === anchor))
+            return paginateItems([turn], params);
+        // Desktop pages an older turn from the thread's last item (the resume's backwards cursor): stock places the anchor
+        // in the whole thread, so it stands here in a marker turn on its side of this one.
+        const newest = (await this.newestTurns(threadId, 1)).turns;
+        const turnAt = newest.findIndex((candidate) => candidate.id === turn.id);
+        const anchorAt = newest.findIndex((candidate) => candidate.items.some((item) => item.id === anchor));
+        const marker = { ...turn, id: `${turn.id}:anchor`, items: [{ type: "agentMessage", id: anchor, text: "", phase: null, memoryCitation: null }] };
+        return paginateItems((anchorAt >= 0 ? anchorAt > turnAt : turnAt < 0) ? [turn, marker] : [marker, turn], params);
+    }
     settings(threadId) {
         const session = this.sessions.get(threadId);
         if (session)
@@ -393,10 +528,10 @@ export class ClaudeThreads {
         const summary = this.catalog.get(threadId);
         return {
             cwd: summary?.cwd ?? process.cwd(),
-            model: summary?.model ? this.pickerModel(summary.model) : this.defaultModel,
-            effort: summary?.reasoningEffort ?? null,
+            model: (summary && this.recordedModel(summary)) || this.defaultModel,
+            effort: summary ? this.recordedEffort(summary) : null,
             fast: summary?.serviceTier === "fast",
-            permissionMode: (summary?.permissionMode ?? "default"),
+            ...recordedPermissions(threadId, summary?.permissionMode, this.gateway.meta),
         };
     }
     /** Common fields of thread/start|resume|fork responses and thread/settings/updated. */
@@ -433,7 +568,7 @@ export class ClaudeThreads {
             effort: settings.effort,
             summary: null,
             collaborationMode: {
-                mode: settings.permissionMode === "plan" ? "plan" : "default",
+                mode: settings.plan ? "plan" : "default",
                 settings: { model: response.model, reasoning_effort: settings.effort, developer_instructions: null },
             },
             multiAgentMode: "explicitRequestOnly",
@@ -449,7 +584,7 @@ export class ClaudeThreads {
             model,
             effort: params.effort ?? params.collaborationMode?.settings?.reasoning_effort ?? current.effort,
             fast: tier === undefined ? current.fast : tier === "fast" || tier === "priority",
-            permissionMode: permissionModeFrom(params) ?? current.permissionMode,
+            ...permissionSettings(params, current),
         };
     }
     // ---- sessions ----
@@ -459,14 +594,14 @@ export class ClaudeThreads {
             return session;
         if (!this.catalog.get(threadId))
             throw invalidParams(`thread not found: ${threadId}`);
-        const leaf = this.gateway.meta.leaf(threadId);
+        const leaf = this.leaves.get(threadId);
         session = new ClaudeSession(this, threadId, this.settings(threadId), { exists: true, ...(leaf ? { resumeAt: leaf } : {}) });
         this.sessions.set(threadId, session);
         return session;
     }
     /** The session continued from the rollback leaf: its new records end the history from now on. */
     resumedAtLeaf(threadId) {
-        this.gateway.meta.setLeaf(threadId, null);
+        this.leaves.delete(threadId);
     }
     turnCompleted(session, turnId) {
         const threadId = session.threadId;
@@ -479,6 +614,9 @@ export class ClaudeThreads {
             const goal = this.goal(threadId);
             if (JSON.stringify(goal) === before)
                 return;
+            // A goal replaced meanwhile (edited, paused, cleared) is no news: Desktop would clear the new goal for its completion.
+            if (goal && session.goalObjective !== undefined && goal.objective !== session.goalObjective)
+                return;
             if (goal)
                 this.gateway.emit(threadId, "thread/goal/updated", { threadId, turnId, goal });
             else
@@ -486,13 +624,22 @@ export class ClaudeThreads {
         });
         this.onTurnCompleted?.(threadId, turnId);
     }
-    /** Claude's native `/goal` as a Codex ThreadGoal (Claude tracks no budget or time). */
+    /**
+     * Claude's native `/goal` as a Codex ThreadGoal (Claude tracks no budget or time); a paused one is kept in meta.json.
+     * The goal last sent to Claude is the chat's: Claude records a `/goal` a moment after taking it.
+     */
     goal(threadId) {
-        const goal = this.catalog.get(threadId)?.goal;
+        const paused = this.gateway.meta.pausedGoal(threadId);
+        const recorded = this.catalog.get(threadId)?.goal;
+        const sent = this.sessions.get(threadId)?.goalObjective;
+        const now = Math.floor(Date.now() / 1000);
+        const goal = paused ? { ...paused, met: false }
+            : sent === undefined || sent === recorded?.objective ? recorded
+                : sent && { objective: sent, createdAt: now, updatedAt: now, met: false };
         if (!goal)
             return null;
         return {
-            threadId, objective: goal.objective, status: goal.met ? "complete" : "active", tokenBudget: null, tokensUsed: 0,
+            threadId, objective: goal.objective, status: paused ? "paused" : goal.met ? "complete" : "active", tokenBudget: null, tokensUsed: 0,
             timeUsedSeconds: Math.max(0, goal.updatedAt - goal.createdAt), createdAt: goal.createdAt, updatedAt: goal.updatedAt,
         };
     }
@@ -500,14 +647,26 @@ export class ClaudeThreads {
         // Sub-agent activity is shown by the parent's collabAgentToolCall item; child history is read from disk.
     }
     onRateLimit(info) {
-        if (!info?.rateLimitType)
+        if (!info)
             return;
-        this.rateLimitWindows.set(info.rateLimitType, {
-            status: info.status,
-            usedPercent: Math.round(Number(info.utilization ?? (info.status === "rejected" ? 1 : 0)) * 100),
-            windowDurationMins: WINDOW_MINUTES[info.rateLimitType] ?? null,
-            resetsAt: typeof info.resetsAt === "number" ? info.resetsAt : null,
-        });
+        // A turn's event carries every plan window Claude knows in `unifiedWindows` (utilization as a fraction); `status`,
+        // and `utilization` if any, are about the window `rateLimitType` names. A window without one keeps the last known.
+        const windows = { ...info.unifiedWindows };
+        if (info.rateLimitType)
+            windows[info.rateLimitType] = { resetsAt: info.resetsAt, utilization: info.utilization, ...windows[info.rateLimitType] };
+        for (const [type, window] of Object.entries(windows)) {
+            const status = type === info.rateLimitType ? info.status : "allowed";
+            const usedPercent = typeof window.utilization === "number" ? Math.round(window.utilization * 100)
+                : status === "rejected" ? 100 : this.rateLimitWindows.get(type)?.usedPercent;
+            if (usedPercent === undefined)
+                continue;
+            this.rateLimitWindows.set(type, {
+                status,
+                usedPercent,
+                windowDurationMins: WINDOW_MINUTES[type] ?? null,
+                resetsAt: typeof window.resetsAt === "number" ? window.resetsAt : null,
+            });
+        }
         const snapshot = this.rateLimitSnapshot();
         for (const connection of this.gateway.connections) {
             if (connection.provider === "claude")
@@ -529,34 +688,118 @@ export class ClaudeThreads {
             rateLimitReachedType: [...this.rateLimitWindows.values()].some((value) => value.status === "rejected") ? "rate_limit_reached" : null,
         };
     }
+    /** Claude's plan limits: read from Claude's `/usage` data at most once a minute, and as turns report them. */
     async rateLimits() {
+        if (!this.usage || Date.now() - this.usage.at > 60_000)
+            this.usage = { at: Date.now(), done: this.readUsage() };
+        await this.usage.done;
         const snapshot = this.rateLimitSnapshot();
         return { rateLimits: snapshot, rateLimitsByLimitId: { claude: snapshot } };
     }
+    async readUsage() {
+        try {
+            const usage = await withProbeQuery(this.config, undefined, (probe) => probe.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET({ skipBehaviors: true }));
+            // No windows at all: claude.ai's usage endpoint failed (e.g. rate-limited) and Claude had nothing recent cached.
+            if (usage.rate_limits_available && !usage.rate_limits)
+                throw new Error("claude.ai's usage endpoint did not answer");
+            this.usageError = usage.rate_limits_available ? undefined : "no plan limits for this login (API key or cloud provider)";
+            // Absent when Claude answers from its cached data: the last known stay.
+            if (usage.rate_limits?.model_scoped)
+                this.modelLimits = usage.rate_limits.model_scoped.filter((row) => typeof row.utilization === "number").map((row) => ({
+                    name: row.display_name,
+                    window: { usedPercent: Math.round(row.utilization), windowDurationMins: 10_080, resetsAt: row.resets_at ? Math.floor(Date.parse(row.resets_at) / 1000) : null },
+                }));
+            for (const type of ["five_hour", "seven_day", "seven_day_opus", "seven_day_sonnet"]) {
+                const window = usage.rate_limits?.[type];
+                if (typeof window?.utilization !== "number")
+                    continue;
+                this.rateLimitWindows.set(type, {
+                    status: window.utilization >= 100 ? "rejected" : "allowed",
+                    usedPercent: Math.round(window.utilization),
+                    windowDurationMins: WINDOW_MINUTES[type],
+                    resetsAt: window.resets_at ? Math.floor(Date.parse(window.resets_at) / 1000) : null,
+                });
+            }
+        }
+        catch (error) {
+            this.usageError = `limits unavailable: ${error instanceof Error ? error.message : String(error)}`;
+            this.logger.warn("claude.usage.unavailable", { error: this.usageError });
+        }
+    }
     rateLimitWindowsText() {
         return [...this.rateLimitWindows.entries()].map(([key, value]) => `${key}: ${value.usedPercent}% used${value.resetsAt ? `, resets ${new Date(value.resetsAt * 1000).toISOString().slice(0, 16).replace("T", " ")} UTC` : ""} (${value.status})`);
     }
     // ---- models and skills ----
     models() {
-        this.models_ ??= withProbeQuery(this.config, undefined, (probe) => probe.supportedModels()).then((models) => {
-            const resolved = models.find((model) => model.value === "default")?.resolvedModel;
-            this.defaultModel = resolved ? normalizeClaudeModelIdentifier(resolved) : null;
-            for (const model of models) {
-                if (model.value !== "default" && model.resolvedModel)
-                    this.pickerValues.set(normalizeClaudeModelIdentifier(model.resolvedModel), modelCatalogValue(model));
-            }
-            return models.filter((model) => model.value !== "default").map((model) => mapClaudeModel(model, this.config.modelPrefix));
-        }).catch((error) => {
+        this.models_ ??= this.probeModels().catch((error) => {
             this.models_ = undefined;
             throw error;
         });
         return this.models_;
     }
+    get modelsPath() {
+        return join(this.config.dataDir, "claude-models.json");
+    }
+    cachedModels() {
+        try {
+            return JSON.parse(readFileSync(this.modelsPath, "utf8"));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Asks Claude for its models and keeps them for the next start. */
+    async probeModels() {
+        const models = await withProbeQuery(this.config, undefined, async (probe) => {
+            const models = await probe.supportedModels();
+            // Claude's own context budget per model: its window, capped by settings such as CLAUDE_CODE_AUTO_COMPACT_WINDOW.
+            for (const model of models) {
+                await probe.setModel(model.value);
+                model.contextWindow = (await probe.getContextUsage({ detail: "summary" })).maxTokens;
+            }
+            return models;
+        });
+        const temporary = `${this.modelsPath}.${process.pid}.tmp`;
+        void writeFile(temporary, JSON.stringify(models), { mode: 0o600 }).then(() => rename(temporary, this.modelsPath)).catch(() => undefined);
+        return this.useModels(models);
+    }
+    useModels(models) {
+        const resolved = models.find((model) => model.value === "default")?.resolvedModel;
+        this.defaultModel = resolved ? normalizeClaudeModelIdentifier(resolved) : null;
+        for (const model of models) {
+            if (model.value !== "default" && model.resolvedModel)
+                this.pickerValues.set(normalizeClaudeModelIdentifier(model.resolvedModel), modelCatalogValue(model));
+            if (!model.contextWindow)
+                continue;
+            this.contextWindows.set(modelCatalogValue(model), model.contextWindow);
+            if (model.resolvedModel)
+                this.contextWindows.set(normalizeClaudeModelIdentifier(model.resolvedModel), model.contextWindow);
+        }
+        const mapped = models.filter((model) => model.value !== "default").map((model) => mapClaudeModel(model, this.config.modelPrefix));
+        for (const [index, model] of models.filter((model) => model.value !== "default").entries()) {
+            if (!model.supportedEffortLevels?.length)
+                continue;
+            const effort = mapped[index].defaultReasoningEffort;
+            this.defaultEfforts.set(modelCatalogValue(model), effort);
+            if (model.resolvedModel)
+                this.defaultEfforts.set(normalizeClaudeModelIdentifier(model.resolvedModel), effort);
+        }
+        return mapped;
+    }
+    /** The effort Claude runs at: the chat's, else its model's default as the picker shows it (Claude's own may differ). */
+    effort(settings) {
+        return settings.effort ?? this.defaultEfforts.get(normalizeClaudeModelIdentifier(settings.model || this.defaultModel || "")) ?? null;
+    }
+    /** The context window Claude works with for a model (picker value or resolved id; none: the default model). */
+    contextWindow(model) {
+        return this.contextWindows.get(normalizeClaudeModelIdentifier(model || this.defaultModel || "")) ?? DEFAULT_CONTEXT_WINDOW;
+    }
     modelLabel(model) {
         return model ? claudeModelLabel(model) : "Claude (default)";
     }
     pendingNames = new Map();
     pickerValues = new Map();
+    defaultEfforts = new Map();
     skillCache = new Map();
     async skills(cwds) {
         const entries = await Promise.all(cwds.map(async (cwd) => {
@@ -588,7 +831,10 @@ export class ClaudeThreads {
     }
     async sideTurn(side, params) {
         const input = normalizeUserInput(params.input ?? []);
-        const question = input.flatMap((item) => item.type === "text" ? [item.text] : []).join("\n");
+        // Desktop's description turn (after a rename) wants JSON matching its schema; Claude's side question answers in prose.
+        const schema = params.outputSchema;
+        const typed = input.flatMap((item) => item.type === "text" ? [item.text] : []).join("\n");
+        const question = schema ? `${typed}\n\nAnswer with only a JSON object matching this JSON Schema, nothing else:\n${JSON.stringify(schema)}` : typed;
         const id = randomUUID();
         const started = Math.floor(Date.now() / 1000);
         const turn = { id, items: [], itemsView: "full", status: "inProgress", error: null, startedAt: started, completedAt: null, durationMs: null };
@@ -607,6 +853,8 @@ export class ClaudeThreads {
                 text = await this.session(side.sourceId).askSideQuestion(history.length
                     ? `Earlier in this side conversation:\n${history.join("\n")}\n\nNew question: ${question}`
                     : question);
+                if (schema)
+                    text = JSON.stringify(JSON.parse(text.slice(text.indexOf("{"), text.lastIndexOf("}") + 1)));
             }
             catch (error) {
                 text = `Side question failed: ${error instanceof Error ? error.message : String(error)}`;
@@ -633,12 +881,11 @@ export class ClaudeThreads {
         switch (method) {
             case "thread/start": return this.startThread(connection, params);
             case "thread/resume": return this.resume(connection, params);
-            case "thread/read": {
-                const { thread, turns } = await this.read(threadId);
-                return { thread: { ...thread, turns: params.includeTurns ? turns : [] } };
-            }
-            case "thread/turns/list": return paginateTurns((await this.read(threadId)).turns, params);
-            case "thread/items/list": return paginateItems((await this.read(threadId)).turns, params);
+            // All turns only when asked for them (deprecated for paginated threads; Desktop pages).
+            case "thread/read": return { thread: params.includeTurns ? await this.read(threadId).then(({ thread, turns }) => ({ ...thread, turns })) : await this.thread(threadId) };
+            case "thread/turns/list": return this.turnsPage(threadId, params);
+            case "thread/items/list": return this.itemsPage(threadId, params);
+            case "thread/searchOccurrences": return this.searchOccurrences(threadId, params);
             case "turn/start": {
                 this.gateway.subscribe(threadId, connection);
                 return { turn: await this.session(threadId).startTurn(params) };
@@ -658,7 +905,7 @@ export class ClaudeThreads {
                 const archived = method === "thread/archive";
                 this.gateway.meta.setArchived(threadId, archived);
                 this.gateway.emit(threadId, archived ? "thread/archived" : "thread/unarchived", { threadId });
-                return archived ? {} : { thread: (await this.read(threadId)).thread };
+                return archived ? {} : { thread: await this.thread(threadId) };
             }
             case "thread/delete": return this.delete(threadId);
             case "thread/fork": return this.fork(connection, params);
@@ -669,13 +916,18 @@ export class ClaudeThreads {
                 return {};
             }
             case "thread/settings/update": {
-                const session = this.session(threadId);
-                if (await session.updateSettings(params)) {
-                    this.gateway.emit(threadId, "thread/settings/updated", { threadId, threadSettings: this.threadSettings(session.settings) });
-                }
+                await this.session(threadId).updateSettings(params);
                 return {};
             }
-            case "thread/metadata/update": return { thread: (await this.read(threadId)).thread };
+            // Claude's settings have no per-turn scope: the running turn's change stays for the chat.
+            case "turn/settings/update": {
+                const session = this.sessions.get(threadId);
+                if (!session?.busy)
+                    return { status: "targetUnavailable" };
+                await session.updateSettings(params);
+                return { status: "applied" };
+            }
+            case "thread/metadata/update": return { thread: await this.thread(threadId) };
             case "thread/attachment/list": return { data: [], nextCursor: null };
             case "thread/inject_items": {
                 await this.session(threadId).inject((params.items ?? []).map((item) => JSON.stringify(item)).join("\n"));
@@ -687,9 +939,11 @@ export class ClaudeThreads {
                 return { goal: goal?.status === "complete" ? null : goal };
             }
             case "thread/goal/set": {
+                await this.catalog.refresh();
                 const now = Math.floor(Date.now() / 1000);
                 const current = this.goal(threadId);
                 if (params.objective) {
+                    this.gateway.meta.setPausedGoal(threadId, null);
                     const session = this.session(threadId);
                     const goal = {
                         threadId, objective: params.objective, status: "active", tokenBudget: null, tokensUsed: 0, timeUsedSeconds: 0,
@@ -698,21 +952,41 @@ export class ClaudeThreads {
                     // Like stock, the goal's turn starts after the answer: Desktop shows the goal message itself on the answer.
                     setImmediate(() => {
                         this.gateway.emit(threadId, "thread/goal/updated", { threadId, turnId: null, goal });
-                        session.command(`/goal ${params.objective}`)
+                        session.goal(params.objective, current?.status === "active")
                             .catch((error) => this.logger.warn("claude.goal.start-failed", { threadId, error: String(error) }));
                     });
                     return { goal };
                 }
-                if (params.status && params.status !== "active" && current?.status === "active")
-                    await this.session(threadId).command("/goal clear");
-                return { goal: current ? { ...current, status: params.status ?? current.status, updatedAt: now } : null };
+                // Claude's `/goal` has no pause: pausing clears it there (stopping its turn) and keeps it in meta.json; resuming
+                // sets it again.
+                const pausing = params.status === "paused" && current?.status === "active";
+                const resuming = params.status === "active" && current?.status === "paused";
+                if (!pausing && !resuming)
+                    return { goal: current };
+                const goal = { ...current, status: params.status, updatedAt: now, timeUsedSeconds: Math.max(0, now - current.createdAt) };
+                this.gateway.meta.setPausedGoal(threadId, pausing ? { objective: goal.objective, createdAt: goal.createdAt, updatedAt: now } : null);
+                setImmediate(() => {
+                    this.gateway.emit(threadId, "thread/goal/updated", { threadId, turnId: null, goal });
+                    this.session(threadId).goal(pausing ? "clear" : goal.objective, pausing)
+                        .catch((error) => this.logger.warn("claude.goal.update-failed", { threadId, error: String(error) }));
+                });
+                return { goal };
             }
             case "thread/goal/clear": {
+                await this.catalog.refresh();
                 const goal = this.goal(threadId);
-                if (goal?.status === "active")
-                    await this.session(threadId).command("/goal clear");
-                this.gateway.emit(threadId, "thread/goal/cleared", { threadId });
-                return { cleared: goal !== null };
+                if (!goal)
+                    return { cleared: false };
+                this.gateway.meta.setPausedGoal(threadId, null);
+                setImmediate(() => {
+                    this.gateway.emit(threadId, "thread/goal/cleared", { threadId });
+                    // Claude drops a met goal itself.
+                    if (goal.status === "active") {
+                        this.session(threadId).goal("clear", true)
+                            .catch((error) => this.logger.warn("claude.goal.clear-failed", { threadId, error: String(error) }));
+                    }
+                });
+                return { cleared: true };
             }
             case "thread/queue/list": return { data: this.sessions.get(threadId)?.queued ?? [], nextCursor: null };
             case "thread/queue/add": {
@@ -768,6 +1042,7 @@ export class ClaudeThreads {
             }
             case "thread/turns/list": return paginateTurns(side.turns, params);
             case "thread/items/list": return paginateItems(side.turns, params);
+            case "thread/searchOccurrences": return occurrencesPage(turnOccurrences(side.turns, params.searchTerm), params);
             case "thread/unsubscribe":
             case "thread/delete":
             case "thread/archive":
@@ -795,13 +1070,14 @@ export class ClaudeThreads {
     async startThread(connection, params) {
         await this.models().catch(() => undefined);
         const settings = this.settingsFrom(params, {
-            cwd: params.cwd ?? process.cwd(), model: this.defaultModel, effort: null, fast: false, permissionMode: "default",
+            cwd: params.cwd ?? process.cwd(), model: this.defaultModel, effort: null, fast: false, permissionMode: "default", plan: false,
         });
         const session = this.create(settings);
         const threadId = session.threadId;
         this.gateway.subscribe(threadId, connection);
         const thread = this.decorate(this.freshThread(session));
-        this.gateway.emit(threadId, "thread/started", { thread });
+        // After the response, as stock: Desktop hides its new-chat draft's `thread/started` only once it knows the id.
+        setImmediate(() => this.gateway.emit(threadId, "thread/started", { thread }));
         this.gateway.titles.track(threadId);
         this.prewarm(session);
         return { thread, ...this.settingsResponse(settings) };
@@ -830,10 +1106,11 @@ export class ClaudeThreads {
     async resume(connection, params) {
         const threadId = params.threadId;
         this.gateway.subscribe(threadId, connection);
-        const { thread, turns, usage } = await this.read(threadId);
+        const thread = await this.thread(threadId);
+        const { turns, usage } = await this.newestTurns(threadId, 1);
         // Like stock, the context meter follows a resume (Desktop's /status reads it).
         if (usage?.last) {
-            const modelContextWindow = this.contextWindows.get((thread.model ?? "").slice(this.config.modelPrefix.length)) ?? DEFAULT_CONTEXT_WINDOW;
+            const modelContextWindow = this.contextWindow(thread.model?.slice(this.config.modelPrefix.length));
             setImmediate(() => this.gateway.emit(threadId, "thread/tokenUsage/updated", { threadId, turnId: turns.at(-1)?.id ?? null, tokenUsage: { ...usage, modelContextWindow } }));
         }
         // A sub-agent has no session of its own: it shows the model and directory it runs with.
@@ -845,8 +1122,8 @@ export class ClaudeThreads {
         const response = {
             thread: { ...thread, turns: params.excludeTurns ? [] : turns },
             ...this.settingsResponse(settings),
-            collaborationMode: null,
-            initialTurnsPage: params.initialTurnsPage ? paginateTurns(turns, params.initialTurnsPage) : null,
+            collaborationMode: this.threadSettings(settings).collaborationMode,
+            initialTurnsPage: params.initialTurnsPage ? await this.turnsPage(threadId, { ...params.initialTurnsPage, threadId }) : null,
             ...historyCursors(turns),
         };
         return response;
@@ -866,6 +1143,33 @@ export class ClaudeThreads {
         this.gateway.emit(threadId, "thread/name/updated", { threadId, threadName: name });
         return {};
     }
+    /** The goal of a Claude backend the chat switches away from, out of Claude (a running goal turn stops). */
+    async takeGoal(threadId) {
+        await this.catalog.refresh();
+        const goal = this.goal(threadId);
+        if (goal?.status === "active")
+            await this.session(threadId).goal("clear", true);
+        this.gateway.meta.setPausedGoal(threadId, null);
+        return goal?.status === "complete" ? null : goal;
+    }
+    /** A goal the chat brings to this Claude backend as it switches (or keeps as a switch fails). */
+    async giveGoal(threadId, goal) {
+        if (goal.status === "paused")
+            this.gateway.meta.setPausedGoal(threadId, { objective: goal.objective, createdAt: goal.createdAt, updatedAt: goal.updatedAt });
+        else
+            await this.session(threadId).goal(goal.objective, false);
+    }
+    /** A Claude backend the chat switched away from: nothing of it runs on (background tasks, process). */
+    async retire(threadId) {
+        const session = this.sessions.get(threadId);
+        if (!session)
+            return;
+        this.sessions.delete(threadId);
+        await session.stopTasks();
+        const pids = sessionProcesses().filter((process) => process.session === threadId).map((process) => process.pid);
+        await session.unload();
+        killProcesses(pids);
+    }
     /** Removes a session with its transcript (also what a failed switch to Claude leaves behind). */
     async discard(threadId) {
         await this.sessions.get(threadId)?.unload();
@@ -873,6 +1177,7 @@ export class ClaudeThreads {
         await this.catalog.refresh();
         if (this.catalog.get(threadId))
             await deleteSession(threadId);
+        this.catalog.dropPages(threadId);
         this.gateway.meta.forget(threadId);
         await this.catalog.refresh();
     }
@@ -883,14 +1188,12 @@ export class ClaudeThreads {
     }
     /** Last transcript record of the turn before `turnId` (or of `turnId` itself when `inclusive`). */
     async boundaryBefore(threadId, turnId, inclusive) {
-        const projection = await this.projection(threadId);
-        if (!projection)
+        if (!this.catalog.get(threadId))
+            await this.catalog.refresh();
+        if (!this.catalog.get(threadId))
             throw invalidParams(`thread not found: ${threadId}`);
-        const index = projection.turns.findIndex((turn) => turn.id === turnId);
-        if (index < 0)
-            throw invalidParams(`turn not found: ${turnId}`);
-        const kept = projection.turns[inclusive ? index : index - 1];
-        return kept ? projection.turnBoundaries.find((boundary) => boundary.turnId === kept.id)?.messageUuid ?? null : null;
+        const { pages, source } = this.pages(threadId);
+        return pages.boundary(source, turnId, inclusive).catch(() => { throw invalidParams(`turn not found: ${turnId}`); });
     }
     async fork(connection, params) {
         const sourceId = params.threadId;
@@ -904,19 +1207,20 @@ export class ClaudeThreads {
         }
         const upTo = params.lastTurnId ? await this.boundaryBefore(sourceId, params.lastTurnId, true)
             : params.beforeTurnId ? await this.boundaryBefore(sourceId, params.beforeTurnId, false)
-                : this.gateway.meta.leaf(sourceId) ?? null;
+                : this.leaves.get(sourceId) ?? null;
         const summary = this.catalog.get(sourceId);
         if (!summary)
             throw invalidParams(`thread not found: ${sourceId}`);
         const { sessionId } = await forkSession(sourceId, { ...(upTo ? { upToMessageId: upTo } : {}) });
         await this.catalog.refresh();
         this.gateway.subscribe(sessionId, connection);
-        const { thread, turns } = await this.read(sessionId);
+        const thread = await this.thread(sessionId);
+        const turns = params.excludeTurns ? [] : (await this.newestTurns(sessionId, 25)).turns;
         const forked = { ...thread, forkedFromId: sourceId };
-        this.gateway.emit(sessionId, "thread/started", { thread: forked });
+        setImmediate(() => this.gateway.emit(sessionId, "thread/started", { thread: forked }));
         const settings = this.settingsFrom(params, this.settings(sourceId));
         this.sessions.set(sessionId, new ClaudeSession(this, sessionId, settings, { exists: true }));
-        return { thread: { ...forked, turns: params.excludeTurns ? [] : turns }, ...this.settingsResponse(settings) };
+        return { thread: { ...forked, turns }, ...this.settingsResponse(settings) };
     }
     async truncate(threadId, leaf) {
         const session = this.sessions.get(threadId);
@@ -926,32 +1230,35 @@ export class ClaudeThreads {
         await session?.unload();
         this.sessions.delete(threadId);
         if (leaf) {
-            this.gateway.meta.setLeaf(threadId, leaf);
+            this.leaves.set(threadId, leaf);
             return;
         }
         // Everything rolled back: Claude neither resumes nor starts anew a transcript without messages, so the session
         // starts over under its id with its settings, and its name comes back with its first turn.
         const name = this.catalog.get(threadId).customTitle;
         await deleteSession(threadId);
-        this.gateway.meta.setLeaf(threadId, null);
+        this.catalog.dropPages(threadId);
+        this.leaves.delete(threadId);
         await this.catalog.refresh();
         this.sessions.set(threadId, new ClaudeSession(this, threadId, settings, { exists: false }));
         if (name)
             this.pendingNames.set(threadId, name);
     }
     async rollback(threadId, numTurns) {
-        const projection = await this.projection(threadId);
-        if (!projection)
+        if (!this.catalog.get(threadId))
+            await this.catalog.refresh();
+        if (!this.catalog.get(threadId))
             throw invalidParams(`thread not found: ${threadId}`);
-        const keep = projection.turns.length - numTurns;
-        const leaf = keep > 0 ? projection.turnBoundaries.find((boundary) => boundary.turnId === projection.turns[keep - 1].id)?.messageUuid ?? null : null;
-        await this.truncate(threadId, leaf);
-        const { thread, turns } = await this.read(threadId);
-        return { thread: { ...thread, turns } };
+        const { pages, source } = this.pages(threadId);
+        const { turns: history } = await pages.newest(source, numTurns + 1);
+        const kept = history.at(-numTurns - 1);
+        await this.truncate(threadId, kept ? await pages.boundary(source, kept.id, true) : null);
+        return { thread: { ...await this.thread(threadId), turns: (await this.newestTurns(threadId, 25)).turns } };
     }
     async revert(threadId, beforeTurnId) {
         await this.truncate(threadId, await this.boundaryBefore(threadId, beforeTurnId, false));
-        const { thread, turns } = await this.read(threadId);
+        const thread = await this.thread(threadId);
+        const { turns } = await this.newestTurns(threadId, 1);
         this.gateway.emit(threadId, "thread/reverted", { threadId });
         return { thread, ...historyCursors(turns) };
     }
@@ -997,14 +1304,15 @@ export class ClaudeThreads {
             effort: settings.effort,
             fast: settings.fast,
             permissionMode: settings.permissionMode,
+            plan: settings.plan,
+            cwd: settings.cwd,
             loaded: session !== undefined,
             process: session?.loaded ?? false,
             actions: this.actions.get(threadId) ?? [],
-            running: session?.busy ?? false,
+            turnId: session?.turn?.id ?? null,
             usage: session?.totalUsage,
-            contextWindow: session?.contextWindow ?? null,
+            contextWindow: this.contextWindow(session?.liveModel ?? settings.model),
             lastUsage: session?.lastUsage,
-            costUsd: session?.costUsd ?? 0,
             backgroundTasks: session?.tasks.size ?? 0,
         };
     }