@gkorepanov/ccodex 0.5.0-rc.8 → 0.5.0

package/dist/claude/threads.js

@@ -6,15 +6,17 @@ import { deleteSession, forkSession, renameSession } from "@anthropic-ai/claude-
 import { v7 as uuidv7 } from "uuid";
 import { packageVersion } from "../management/commands.js";
 import { invalidParams, invalidRequest, requestedModel } from "../protocol/codex.js";
-import { anchorCursor, 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, permissionSettings, 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. */
@@ -29,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;
@@ -39,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. */
@@ -48,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) {
@@ -78,7 +95,7 @@ export class ClaudeThreads {
                 if (!known.has(id) && !this.sessions.has(id) && !this.gateway.meta.hidden(id)) {
                     this.gateway.broadcast("thread/started", { thread: this.decorate(nativeThread(id, header, { status: this.status(id) })) });
                 }
-                else if (known.has(id) && known.get(id) !== name && name) {
+                else if (known.has(id) && known.get(id) !== name && name && !this.gateway.meta.hidden(id)) {
                     this.gateway.emit(id, "thread/name/updated", { threadId: id, threadName: name });
                 }
                 known.set(id, name);
@@ -95,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 });
@@ -135,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 ?? []));
@@ -190,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;
@@ -224,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 ----
@@ -233,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);
@@ -286,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")}]` },
@@ -403,7 +434,7 @@ export class ClaudeThreads {
         return !threadId.startsWith("agent-") && !this.sides.has(threadId) && this.catalog.has(threadId);
     }
     pages(threadId) {
-        return this.catalog.pages(threadId, this.gateway.meta.leaf(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) {
@@ -418,8 +449,10 @@ export class ClaudeThreads {
             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 turns;
+            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 }];
@@ -452,6 +485,22 @@ export class ClaudeThreads {
                 : 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();
@@ -479,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. */
@@ -519,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",
@@ -545,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;
@@ -565,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
@@ -572,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,
         };
     }
@@ -586,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")
@@ -615,10 +688,44 @@ 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})`);
     }
@@ -635,7 +742,9 @@ export class ClaudeThreads {
     }
     cachedModels() {
         try {
-            return JSON.parse(readFileSync(this.modelsPath, "utf8"));
+            const cache = JSON.parse(readFileSync(this.modelsPath, "utf8"));
+            // As stock's models cache: one another version wrote (another Claude, another model list) is stale.
+            return cache.version === packageVersion() ? cache.models : undefined;
         }
         catch {
             return undefined;
@@ -643,9 +752,17 @@ export class ClaudeThreads {
     }
     /** Asks Claude for its models and keeps them for the next start. */
     async probeModels() {
-        const models = await withProbeQuery(this.config, undefined, (probe) => probe.supportedModels());
+        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);
+        void writeFile(temporary, JSON.stringify({ version: packageVersion(), models }), { mode: 0o600 }).then(() => rename(temporary, this.modelsPath)).catch(() => undefined);
         return this.useModels(models);
     }
     useModels(models) {
@@ -654,14 +771,37 @@ export class ClaudeThreads {
         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);
         }
-        return models.filter((model) => model.value !== "default").map((model) => mapClaudeModel(model, this.config.modelPrefix));
+        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) => {
@@ -693,7 +833,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 };
@@ -712,6 +855,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)}`;
@@ -742,6 +887,7 @@ export class ClaudeThreads {
             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) };
@@ -772,10 +918,7 @@ 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 {};
             }
             // Claude's settings have no per-turn scope: the running turn's change stays for the chat.
@@ -798,9 +941,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,
@@ -809,21 +954,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": {
@@ -843,7 +1008,7 @@ export class ClaudeThreads {
             case "thread/backgroundTerminals/list": {
                 const session = this.sessions.get(threadId);
                 return {
-                    data: [...session?.tasks.values() ?? []].filter((task) => task.taskType === "local_bash").map((task) => ({
+                    data: (session?.backgroundTasks ?? []).filter((task) => task.taskType === "local_bash").map((task) => ({
                         itemId: task.toolUseId ?? task.taskId, processId: task.taskId, command: task.description, cwd: session.settings.cwd,
                         osPid: null, cpuPercent: null, rssKb: null,
                     })),
@@ -879,6 +1044,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":
@@ -906,13 +1072,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) };
@@ -945,7 +1112,7 @@ export class ClaudeThreads {
         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.
@@ -957,7 +1124,7 @@ export class ClaudeThreads {
         const response = {
             thread: { ...thread, turns: params.excludeTurns ? [] : turns },
             ...this.settingsResponse(settings),
-            collaborationMode: null,
+            collaborationMode: this.threadSettings(settings).collaborationMode,
             initialTurnsPage: params.initialTurnsPage ? await this.turnsPage(threadId, { ...params.initialTurnsPage, threadId }) : null,
             ...historyCursors(turns),
         };
@@ -978,6 +1145,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();
@@ -1015,7 +1209,7 @@ 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}`);
@@ -1025,7 +1219,7 @@ export class ClaudeThreads {
         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 }, ...this.settingsResponse(settings) };
@@ -1038,7 +1232,7 @@ 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
@@ -1046,7 +1240,7 @@ export class ClaudeThreads {
         const name = this.catalog.get(threadId).customTitle;
         await deleteSession(threadId);
         this.catalog.dropPages(threadId);
-        this.gateway.meta.setLeaf(threadId, null);
+        this.leaves.delete(threadId);
         await this.catalog.refresh();
         this.sessions.set(threadId, new ClaudeSession(this, threadId, settings, { exists: false }));
         if (name)
@@ -1112,15 +1306,16 @@ 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,
+            backgroundTasks: session?.backgroundTasks.length ?? 0,
         };
     }
     /** The summary of Claude's latest compaction if nothing was said since ("" otherwise). */