yepanywhere 0.5.2 → 0.6.0

package/dist/supervisor/Supervisor.js

@@ -1,8 +1,13 @@
 import { randomUUID } from "node:crypto";
-import { truncateSessionTitle, } from "../../bundled/@yep-anywhere/shared/dist/index.js";
+import { DEFAULT_PROMPT_CACHE_KEEPALIVE_INACTIVITY_MINUTES, truncateSessionTitle, } from "../../bundled/@yep-anywhere/shared/dist/index.js";
 import { getLogger } from "../logging/logger.js";
+import { getProjectName } from "../projects/paths.js";
 import { getProvider } from "../sdk/providers/index.js";
-import { Process } from "./Process.js";
+import { CacheMissBillingMonitor } from "../services/CacheMissBillingMonitor.js";
+import { formatAgentRecapExcerpt } from "../sessions/agent-excerpt.js";
+import { isAwaySummaryMessage, latestRecapMessage, messageTimestampMs, toDurableRecapMessage, } from "../sessions/recap-overlays.js";
+import { normalizeSlashCommandName } from "../sdk/slashCommandEmulation.js";
+import { NATIVE_RECAP_FALLBACK_GRACE_MS, Process, } from "./Process.js";
 import { WorkerQueue, isQueueFullError, } from "./WorkerQueue.js";
 import { DEFAULT_IDLE_PREEMPT_THRESHOLD_MS, encodeProjectId, } from "./types.js";
 /** Maximum number of terminated processes to retain */
@@ -20,6 +25,32 @@ const LIVENESS_PROBE_CHECK_INTERVAL_MS = 30 * 1000;
 const LIVENESS_PROBE_REFRESH_MS = 60 * 1000;
 const DEFAULT_HEARTBEAT_TURN_TEXT = "continue";
 const DEFAULT_HEARTBEAT_TURNS_AFTER_MINUTES = 5;
+function thinkingConfigsEqual(current, next) {
+    if (current?.type !== next?.type)
+        return false;
+    if (!current || !next)
+        return true;
+    if (current.type === "adaptive" && next.type === "adaptive") {
+        return current.display === next.display;
+    }
+    if (current.type === "enabled" && next.type === "enabled") {
+        return (current.budgetTokens === next.budgetTokens &&
+            current.display === next.display);
+    }
+    return true;
+}
+function isDynamicThinkingModeConfig(thinking) {
+    return (!thinking ||
+        thinking.type === "disabled" ||
+        (thinking.type === "adaptive" && thinking.display === undefined));
+}
+function canApplyThinkingConfigDynamically(current, next) {
+    if (!isDynamicThinkingModeConfig(current))
+        return false;
+    if (!isDynamicThinkingModeConfig(next))
+        return false;
+    return current?.type !== next?.type;
+}
 const DEFAULT_INTERRUPT_TIMEOUT_MS = 2000;
 const FORCED_HEARTBEAT_INTERRUPT_PREAMBLE = "interrupted for heartbeat; resume interrupted command after responding:";
 const HEARTBEAT_RESET_PROBE_STATUSES = new Set(["active", "idle", "waiting-input"]);
@@ -28,6 +59,73 @@ const ACTIVE_HEARTBEAT_DOUBT_STATUSES = new Set([
     "recently-active-unverified",
     "long-silent-unverified",
 ]);
+const RESUME_COMPACT_WAIT_MS = 3 * 60 * 1000;
+export class ResumeCompactionError extends Error {
+    sessionId;
+    provider;
+    attempt;
+    recovery = "full-resume";
+    constructor(params) {
+        super(describeResumeCompactionAttempt(params.attempt));
+        this.name = "ResumeCompactionError";
+        this.sessionId = params.sessionId;
+        this.provider = params.provider;
+        this.attempt = params.attempt;
+    }
+}
+function describeResumeCompactionAttempt(attempt) {
+    switch (attempt.status) {
+        case "completed":
+            return `Compact-first resume completed with /${attempt.command}`;
+        case "timed-out":
+            return `Compact-first resume timed out after ${attempt.timeoutMs}ms waiting for /${attempt.command}`;
+        case "failed":
+            return attempt.command
+                ? `Compact-first resume failed after /${attempt.command}: ${attempt.reason}`
+                : `Compact-first resume failed: ${attempt.reason}`;
+        case "unavailable":
+            return `Compact-first resume unavailable: ${attempt.reason}`;
+        case "skipped":
+            return `Compact-first resume skipped: ${attempt.reason}`;
+    }
+}
+function isCompactBoundaryMessage(message) {
+    return message.type === "system" && message.subtype === "compact_boundary";
+}
+function compactFailureReason(message) {
+    if (message.type !== "system" ||
+        message.subtype !== "status" ||
+        message.compact_result !== "failed") {
+        return null;
+    }
+    return typeof message.compact_error === "string" && message.compact_error
+        ? message.compact_error
+        : "provider reported compaction failure";
+}
+function isCompactSuccessStatus(message) {
+    return (message.type === "system" &&
+        message.subtype === "status" &&
+        message.compact_result === "success");
+}
+/**
+ * Pure gate for the per-model compact-early threshold (task 029): true when a
+ * valid percent (1–99) and a known context window put live usage at or over
+ * the token threshold (percent% × window). Anything unknown or out of range
+ * yields false — the trigger never fires on missing usage. Semantics are
+ * "current usage already crosses the threshold", not a prediction of the next
+ * turn's size.
+ */
+export function crossesCompactThreshold(percent, contextWindow, inputTokens) {
+    if (typeof percent !== "number" || percent <= 0 || percent >= 100) {
+        return false;
+    }
+    if (typeof contextWindow !== "number" || contextWindow <= 0)
+        return false;
+    if (typeof inputTokens !== "number" || !Number.isFinite(inputTokens)) {
+        return false;
+    }
+    return inputTokens >= (percent / 100) * contextWindow;
+}
 function getStaleInTurnThresholdMs(provider) {
     return provider === "codex" || provider === "codex-oss"
         ? CODEX_STALE_IN_TURN_THRESHOLD_MS
@@ -100,6 +198,7 @@ const INITIAL_RECONCILE_DELAYS_MS = [1000, 3000];
 export class Supervisor {
     processes = new Map();
     sessionToProcess = new Map(); // sessionId -> processId
+    sessionActivationInFlight = new Map();
     observedProcessIds = new Set();
     everOwnedSessions = new Set(); // Sessions we've ever owned (for orphan detection)
     terminatedProcesses = []; // Recently terminated processes
@@ -113,14 +212,30 @@ export class Supervisor {
     idlePreemptThresholdMs;
     workerQueue;
     onSessionExecutor;
+    onContextWindowObserved;
     onSessionSummary;
     staleCheckTimer;
     getHeartbeatTurnSettings;
     getHeartbeatTurnCandidates;
+    getPromptCacheKeepaliveSettings;
+    cacheMissBillingMonitor;
     heartbeatTurnInFlight = false;
     heartbeatTurnTimer;
     livenessProbeTimer;
+    /**
+     * One-shot patient-queue re-checks keyed by process id. Bounded: armed only
+     * while a process holds patient deferred entries; cleared on unregister.
+     */
+    patientCheckTimers = new Map();
     interruptTimeoutMs;
+    sessionMetadataService;
+    sessionQueuePersistenceService;
+    // In-flight forked recaps, keyed by process id. The AbortController cancels
+    // the generator-fork helper turn when the parent becomes active again, so a
+    // returning user's new turn is never shadowed by a stale recap. See
+    // topics/recaps.md.
+    forkedRecapInFlight = new Map();
+    pendingForkedRecapRequests = new Map();
     constructor(options) {
         this.provider = options.provider ?? null;
         this.sdk = options.sdk ?? null;
@@ -136,11 +251,22 @@ export class Supervisor {
             maxQueueSize: options.maxQueueSize,
         });
         this.onSessionExecutor = options.onSessionExecutor;
+        this.onContextWindowObserved = options.onContextWindowObserved;
         this.onSessionSummary = options.onSessionSummary;
         this.getHeartbeatTurnSettings = options.getHeartbeatTurnSettings;
         this.getHeartbeatTurnCandidates = options.getHeartbeatTurnCandidates;
+        this.getPromptCacheKeepaliveSettings =
+            options.getPromptCacheKeepaliveSettings;
+        this.cacheMissBillingMonitor = new CacheMissBillingMonitor({
+            eventBus: options.eventBus,
+            sessionMetadataService: options.sessionMetadataService,
+            getSettings: options.getCacheMissBillingSettings,
+        });
         this.interruptTimeoutMs =
             options.interruptTimeoutMs ?? DEFAULT_INTERRUPT_TIMEOUT_MS;
+        this.sessionMetadataService = options.sessionMetadataService;
+        this.sessionQueuePersistenceService =
+            options.sessionQueuePersistenceService;
         this.staleCheckTimer = setInterval(() => this.terminateStaleProcesses(), STALE_CHECK_INTERVAL_MS);
         this.staleCheckTimer.unref(); // Don't keep process alive for cleanup
         this.heartbeatTurnTimer = setInterval(() => {
@@ -176,8 +302,52 @@ export class Supervisor {
         }
         return "off";
     }
-    async startSession(projectPath, message, permissionMode, modelSettings) {
-        const projectId = encodeProjectId(projectPath);
+    async waitForSessionActivation(sessionId) {
+        const activation = this.sessionActivationInFlight.get(sessionId);
+        if (!activation) {
+            return false;
+        }
+        try {
+            await activation;
+        }
+        catch {
+            // The caller will retry the ordinary resume path, which can surface the
+            // fresh failure or recover if the transient activation failed.
+        }
+        return true;
+    }
+    async startSessionActivation(sessionId, activate) {
+        const activation = Promise.resolve().then(activate);
+        this.sessionActivationInFlight.set(sessionId, activation);
+        try {
+            return (await activation);
+        }
+        finally {
+            if (this.sessionActivationInFlight.get(sessionId) === activation) {
+                this.sessionActivationInFlight.delete(sessionId);
+            }
+        }
+    }
+    registerPromptCacheKeepaliveViewer(process) {
+        if (!process.supportsPromptCacheKeepalive()) {
+            return () => { };
+        }
+        return process.registerPromptCacheKeepaliveLease({
+            getInactivityMs: () => {
+                const setting = this.getPromptCacheKeepaliveSettings?.(process.provider);
+                if (!setting?.enabled) {
+                    return null;
+                }
+                const inactivityMinutes = Number.isFinite(setting.inactivityMinutes) &&
+                    setting.inactivityMinutes > 0
+                    ? setting.inactivityMinutes
+                    : DEFAULT_PROMPT_CACHE_KEEPALIVE_INACTIVITY_MINUTES;
+                return inactivityMinutes * 60_000;
+            },
+        });
+    }
+    async startSession(projectPath, message, permissionMode, modelSettings, launchOptions) {
+        const projectId = launchOptions?.projectId ?? encodeProjectId(projectPath);
         // Check if at capacity
         if (this.isAtCapacity()) {
             // Try to preempt an idle worker
@@ -192,6 +362,7 @@ export class Supervisor {
                     type: "new-session",
                     projectPath,
                     projectId,
+                    workstreamId: launchOptions?.workstreamId,
                     message,
                     permissionMode,
                     modelSettings,
@@ -223,8 +394,8 @@ export class Supervisor {
      * Used for two-phase flow: create session first, upload files, then send message.
      * The agent will wait for a message to be pushed to the queue.
      */
-    async createSession(projectPath, permissionMode, modelSettings) {
-        const projectId = encodeProjectId(projectPath);
+    async createSession(projectPath, permissionMode, modelSettings, launchOptions) {
+        const projectId = launchOptions?.projectId ?? encodeProjectId(projectPath);
         // Check if at capacity
         if (this.isAtCapacity()) {
             // Try to preempt an idle worker
@@ -239,6 +410,7 @@ export class Supervisor {
                     type: "new-session",
                     projectPath,
                     projectId,
+                    workstreamId: launchOptions?.workstreamId,
                     message: { text: "" }, // Placeholder, will be replaced when first message sent
                     permissionMode,
                     modelSettings,
@@ -265,6 +437,60 @@ export class Supervisor {
         // Fall back to legacy mock SDK - not supported for create-only
         throw new Error("createSession requires provider or real SDK - legacy mock SDK not supported");
     }
+    /**
+     * Reactivate an existing session: spawn a live harness process bound to the
+     * session id WITHOUT delivering a user turn. The process resumes the session
+     * and idles on the queue (the same state it occupies after a completed turn),
+     * so the client can read live process state (model options, config) before
+     * any message is sent. Idempotent: returns the existing live process if the
+     * session is already owned.
+     *
+     * Provider-agnostic: rides the existing message-less resume path
+     * (`createProviderSession`/`createRealSession` with `resumeSessionId`), so
+     * Claude and Codex reactivate with no synthetic turn.
+     */
+    async reactivateSession(projectPath, resumeSessionId, permissionMode, modelSettings, options) {
+        const existing = this.getProcessForSession(resumeSessionId);
+        if (existing) {
+            if (!existing.isTerminated) {
+                return existing;
+            }
+            this.unregisterProcess(existing);
+        }
+        const activeActivation = this.sessionActivationInFlight.get(resumeSessionId);
+        if (activeActivation) {
+            return activeActivation;
+        }
+        return this.startSessionActivation(resumeSessionId, async () => {
+            const activated = this.getProcessForSession(resumeSessionId);
+            if (activated) {
+                if (!activated.isTerminated) {
+                    return activated;
+                }
+                this.unregisterProcess(activated);
+            }
+            if (this.isAtCapacity()) {
+                const preemptable = options?.preempt === false ? undefined : this.findPreemptableWorker();
+                if (preemptable) {
+                    await this.preemptWorker(preemptable);
+                }
+                else {
+                    // A background away-recap passes preempt:false: it should never evict
+                    // a live worker just to revive a different session for a recap.
+                    throw new Error("Cannot reactivate: server is at worker capacity and no idle process can be preempted");
+                }
+            }
+            const projectId = encodeProjectId(projectPath);
+            const provider = this.resolveProvider(modelSettings);
+            if (provider) {
+                return this.createProviderSession(projectPath, projectId, permissionMode, modelSettings, provider, resumeSessionId);
+            }
+            if (this.realSdk) {
+                return this.createRealSession(projectPath, projectId, permissionMode, modelSettings, resumeSessionId);
+            }
+            throw new Error("reactivateSession requires provider or real SDK - legacy mock SDK not supported");
+        });
+    }
     /**
      * Create a session using the real SDK without an initial message.
      * The session is created and waits for a message to be queued.
@@ -288,6 +514,7 @@ export class Supervisor {
             clientName: modelSettings?.clientName,
             globalInstructions: modelSettings?.globalInstructions,
             promptSuggestions: promptSuggestionMode === "native",
+            onProviderRetentionChange: () => this.handleProviderRetentionChanged(processHolder),
             onToolApproval: async (toolName, input, opts) => {
                 if (!processHolder.process) {
                     return { behavior: "deny", message: "Process not ready" };
@@ -295,7 +522,7 @@ export class Supervisor {
                 return processHolder.process.handleToolApproval(toolName, input, opts);
             },
         });
-        const { iterator, queue, abort, isProcessAlive, probeLiveness, getProviderActivity, setMaxThinkingTokens, interrupt, supportedModels, supportedCommands, setModel, } = result;
+        const { iterator, queue, abort, isProcessAlive, probeLiveness, getProviderActivity, getProviderRetention, setMaxThinkingTokens, interrupt, supportedModels, supportedCommands, setModel, publishAgentctlSessionId, } = result;
         const tempSessionId = resumeSessionId ?? randomUUID();
         const options = {
             projectPath,
@@ -303,11 +530,13 @@ export class Supervisor {
             sessionId: tempSessionId,
             idleTimeoutMs: this.idleTimeoutMs,
             queue,
+            sessionQueuePersistenceService: this.sessionQueuePersistenceService,
             abortFn: abort,
             isProcessAlive,
             shouldRetainIdleProcess: (sessionId) => this.shouldRetainIdleProcess(sessionId),
             probeLivenessFn: probeLiveness,
             getProviderActivityFn: getProviderActivity,
+            getProviderRetentionFn: getProviderRetention,
             pid: () => {
                 const p = result.pid;
                 return typeof p === "function" ? p() : p;
@@ -317,6 +546,7 @@ export class Supervisor {
             supportedModelsFn: supportedModels,
             supportedCommandsFn: supportedCommands,
             setModelFn: setModel,
+            publishAgentctlSessionIdFn: publishAgentctlSessionId,
             permissionMode: effectiveMode,
             provider: "claude", // Real SDK is always Claude
             model: modelSettings?.model,
@@ -326,6 +556,7 @@ export class Supervisor {
             executor: modelSettings?.executor,
             permissions: modelSettings?.permissions,
             recapMode: modelSettings?.recapMode,
+            recapAfterSeconds: modelSettings?.recapAfterSeconds,
             promptSuggestionMode,
             helperSideModel: modelSettings?.helperSideModel,
         };
@@ -344,6 +575,254 @@ export class Supervisor {
         await process.primeSupportedCommandsForMessage(message);
         return process.queueMessage(message, options);
     }
+    watchResumeCompaction(process, command, timeoutMs = RESUME_COMPACT_WAIT_MS) {
+        let finished = false;
+        let timeout;
+        let unsubscribe;
+        const finish = (attempt) => {
+            if (finished) {
+                return;
+            }
+            finished = true;
+            if (timeout) {
+                clearTimeout(timeout);
+            }
+            unsubscribe?.();
+            resolve(attempt);
+        };
+        let resolve;
+        const promise = new Promise((innerResolve) => {
+            resolve = innerResolve;
+        });
+        timeout = setTimeout(() => finish({ status: "timed-out", command, timeoutMs }), timeoutMs);
+        timeout.unref?.();
+        unsubscribe = process.subscribe((event) => {
+            if (event.type === "message") {
+                const failedReason = compactFailureReason(event.message);
+                if (failedReason) {
+                    finish({ status: "failed", command, reason: failedReason });
+                    return;
+                }
+                if (isCompactBoundaryMessage(event.message) ||
+                    isCompactSuccessStatus(event.message)) {
+                    finish({ status: "completed", command });
+                }
+                return;
+            }
+            if (event.type === "error") {
+                finish({
+                    status: "failed",
+                    command,
+                    reason: event.error.message,
+                });
+                return;
+            }
+            if (event.type === "terminated") {
+                finish({
+                    status: "failed",
+                    command,
+                    reason: event.reason,
+                });
+            }
+        });
+        return {
+            promise,
+            cancel: () => finish({
+                status: "failed",
+                command,
+                reason: "compact command was not queued",
+            }),
+        };
+    }
+    async findResumeCompactCommand(process) {
+        if (!process.supportsDynamicCommands) {
+            return {
+                ok: false,
+                attempt: {
+                    status: "unavailable",
+                    reason: "provider process does not advertise slash commands",
+                },
+            };
+        }
+        let commands;
+        try {
+            commands = await process.supportedCommands();
+        }
+        catch (error) {
+            return {
+                ok: false,
+                attempt: {
+                    status: "failed",
+                    reason: error instanceof Error ? error.message : String(error),
+                },
+            };
+        }
+        const command = commands
+            ?.map((candidate) => normalizeSlashCommandName(candidate.name))
+            .find((name) => name === "compact" || name === "compress");
+        if (!command) {
+            return {
+                ok: false,
+                attempt: {
+                    status: "unavailable",
+                    reason: "no compact/compress slash command advertised",
+                },
+            };
+        }
+        return { ok: true, command };
+    }
+    async tryResumeCompaction(process, options) {
+        if (process.provider !== "claude" && process.provider !== "claude-ollama") {
+            return {
+                status: "unavailable",
+                reason: `${process.provider} does not support compact-first resume`,
+            };
+        }
+        if (!options?.allowNonIdleStart && process.state.type !== "idle") {
+            return {
+                status: "skipped",
+                reason: `process was ${process.state.type}`,
+            };
+        }
+        const command = await this.findResumeCompactCommand(process);
+        if (!command.ok) {
+            return command.attempt;
+        }
+        const watcher = this.watchResumeCompaction(process, command.command);
+        const queued = process.queueMessage(
+        // Hidden: native compaction shows no `/compact` user turn, so neither
+        // should YA-initiated compaction (resume-time or threshold-triggered).
+        { text: `/${command.command}`, metadata: { hidden: true } }, { allowSteer: false });
+        if (!queued.success) {
+            watcher.cancel();
+            return {
+                status: "failed",
+                command: command.command,
+                reason: queued.error ?? "compact command was not accepted",
+            };
+        }
+        return watcher.promise;
+    }
+    /**
+     * Threshold-triggered preemptive compaction (task 029). When the per-model
+     * compact-at-% is set and live context already sits at/over that fraction of
+     * the model's window, run a `/compact` before delivering the next turn — the
+     * same native compaction the harness would eventually auto-fire, just
+     * earlier. Conservative per task 002: claude only, idle process only, only
+     * when usage is known. Best-effort — the turn is delivered regardless of the
+     * compaction outcome, and there is no retry loop. Reuses
+     * `tryResumeCompaction`, so the boundary the client renders is the native
+     * `compact_boundary` and the `/compact` carries no visible user echo.
+     *
+     * No double compaction: live usage is re-read and re-tested immediately
+     * before executing (there is no deferral gap between decide and run), so a
+     * prior compaction — the harness's enforced one or a previous voluntary one —
+     * that dropped usage below the threshold makes the next evaluation a no-op.
+     * The voluntary threshold also sits well below the harness's enforced point,
+     * so in steady state the two never fire together.
+     */
+    async maybeCompactBeforeDelivery(process, sessionId, modelSettings) {
+        const percent = modelSettings?.compactAtContextPercent;
+        if (typeof percent !== "number" || percent <= 0 || percent >= 100)
+            return;
+        // Only an idle claude process can be safely compacted before delivery;
+        // tryResumeCompaction also self-guards, but skip the usage read otherwise.
+        if (process.state.type !== "idle")
+            return;
+        if (process.provider !== "claude" && process.provider !== "claude-ollama") {
+            return;
+        }
+        // Prefer the route-resolved window; process.contextWindow is often
+        // undefined and ignores always-1M for opus/sonnet.
+        const contextWindow = modelSettings?.compactAtContextWindow ?? process.contextWindow;
+        if (!contextWindow || contextWindow <= 0)
+            return;
+        let inputTokens;
+        try {
+            const summary = await this.onSessionSummary?.(sessionId, process.projectId);
+            inputTokens = summary?.contextUsage?.inputTokens;
+        }
+        catch {
+            // Usage unavailable → never block the turn.
+            return;
+        }
+        if (!crossesCompactThreshold(percent, contextWindow, inputTokens))
+            return;
+        try {
+            const attempt = await this.tryResumeCompaction(process);
+            if (attempt.status !== "completed") {
+                getLogger().info({
+                    event: "threshold_compaction_skipped",
+                    sessionId,
+                    processId: process.id,
+                    status: attempt.status,
+                    percent,
+                    inputTokens,
+                    thresholdTokens: Math.round((percent / 100) * contextWindow),
+                }, "Threshold compaction did not complete; delivering turn as-is");
+            }
+        }
+        catch (error) {
+            getLogger().warn({
+                event: "threshold_compaction_failed",
+                sessionId,
+                processId: process.id,
+                error: error instanceof Error ? error.message : String(error),
+            }, "Threshold compaction errored; delivering turn as-is");
+        }
+    }
+    async queueAfterResumeCompaction(params) {
+        const attempt = await this.tryResumeCompaction(params.process, {
+            allowNonIdleStart: params.allowNonIdleStart,
+        });
+        if (attempt.status !== "completed") {
+            throw new ResumeCompactionError({
+                sessionId: params.sessionId,
+                provider: params.process.provider,
+                attempt,
+            });
+        }
+        const queued = await this.queueProcessMessage(params.process, params.message, {
+            allowSteer: false,
+        });
+        if (!queued.success) {
+            throw new Error(queued.error ?? "Failed to queue message after compact");
+        }
+    }
+    async startCompactFirstProviderResume(projectPath, projectId, message, resumeSessionId, permissionMode, modelSettings, provider) {
+        const process = await this.createProviderSession(projectPath, projectId, permissionMode, modelSettings, provider, resumeSessionId);
+        try {
+            await this.queueAfterResumeCompaction({
+                process,
+                sessionId: resumeSessionId,
+                message,
+                allowNonIdleStart: true,
+            });
+            return process;
+        }
+        catch (error) {
+            await process.abort();
+            this.unregisterProcess(process);
+            throw error;
+        }
+    }
+    async startCompactFirstRealResume(projectPath, projectId, message, resumeSessionId, permissionMode, modelSettings) {
+        const process = await this.createRealSession(projectPath, projectId, permissionMode, modelSettings, resumeSessionId);
+        try {
+            await this.queueAfterResumeCompaction({
+                process,
+                sessionId: resumeSessionId,
+                message,
+                allowNonIdleStart: true,
+            });
+            return process;
+        }
+        catch (error) {
+            await process.abort();
+            this.unregisterProcess(process);
+            throw error;
+        }
+    }
     /**
      * Start a session using the real SDK with full features.
      */
@@ -371,6 +850,7 @@ export class Supervisor {
             remoteEnv: modelSettings?.remoteEnv,
             globalInstructions: modelSettings?.globalInstructions,
             promptSuggestions: promptSuggestionMode === "native",
+            onProviderRetentionChange: () => this.handleProviderRetentionChanged(processHolder),
             onToolApproval: async (toolName, input, opts) => {
                 // Delegate to the process's handleToolApproval
                 if (!processHolder.process) {
@@ -379,18 +859,20 @@ export class Supervisor {
                 return processHolder.process.handleToolApproval(toolName, input, opts);
             },
         });
-        const { iterator, queue, abort, isProcessAlive, probeLiveness, getProviderActivity, setMaxThinkingTokens, interrupt, supportedModels, supportedCommands, setModel, } = result;
+        const { iterator, queue, abort, isProcessAlive, probeLiveness, getProviderActivity, getProviderRetention, setMaxThinkingTokens, interrupt, supportedModels, supportedCommands, setModel, publishAgentctlSessionId, } = result;
         const options = {
             projectPath,
             projectId,
             sessionId: tempSessionId,
             idleTimeoutMs: this.idleTimeoutMs,
             queue,
+            sessionQueuePersistenceService: this.sessionQueuePersistenceService,
             abortFn: abort,
             isProcessAlive,
             shouldRetainIdleProcess: (sessionId) => this.shouldRetainIdleProcess(sessionId),
             probeLivenessFn: probeLiveness,
             getProviderActivityFn: getProviderActivity,
+            getProviderRetentionFn: getProviderRetention,
             pid: () => {
                 const p = result.pid;
                 return typeof p === "function" ? p() : p;
@@ -400,6 +882,7 @@ export class Supervisor {
             supportedModelsFn: supportedModels,
             supportedCommandsFn: supportedCommands,
             setModelFn: setModel,
+            publishAgentctlSessionIdFn: publishAgentctlSessionId,
             permissionMode: effectiveMode,
             provider: "claude", // Real SDK is always Claude
             model: modelSettings?.model,
@@ -409,6 +892,7 @@ export class Supervisor {
             executor: modelSettings?.executor,
             permissions: modelSettings?.permissions,
             recapMode: modelSettings?.recapMode,
+            recapAfterSeconds: modelSettings?.recapAfterSeconds,
             promptSuggestionMode,
             helperSideModel: modelSettings?.helperSideModel,
         };
@@ -458,6 +942,7 @@ export class Supervisor {
             globalInstructions: modelSettings?.globalInstructions,
             promptSuggestions: promptSuggestionMode === "native",
             shouldEmitLiveDeltas: () => processHolder.process?.hasLiveDeltaSubscribers() ?? false,
+            onProviderRetentionChange: () => this.handleProviderRetentionChanged(processHolder),
             onToolApproval: async (toolName, input, opts) => {
                 if (!processHolder.process) {
                     return { behavior: "deny", message: "Process not ready" };
@@ -465,7 +950,7 @@ export class Supervisor {
                 return processHolder.process.handleToolApproval(toolName, input, opts);
             },
         });
-        const { iterator, queue, abort, isProcessAlive, probeLiveness, getProviderActivity, setMaxThinkingTokens, interrupt, steer, supportedModels, supportedCommands, setModel, } = result;
+        const { iterator, queue, abort, isProcessAlive, probeLiveness, getProviderActivity, getProviderRetention, setMaxThinkingTokens, interrupt, steer, supportedModels, supportedCommands, setModel, runProviderCommand, publishAgentctlSessionId, } = result;
         const tempSessionId = resumeSessionId ?? randomUUID();
         const options = {
             projectPath,
@@ -473,11 +958,14 @@ export class Supervisor {
             sessionId: tempSessionId,
             idleTimeoutMs: this.idleTimeoutMs,
             queue,
+            sessionQueuePersistenceService: this.sessionQueuePersistenceService,
             abortFn: abort,
             isProcessAlive,
             shouldRetainIdleProcess: (sessionId) => this.shouldRetainIdleProcess(sessionId),
             probeLivenessFn: probeLiveness,
             getProviderActivityFn: getProviderActivity,
+            getProviderRetentionFn: getProviderRetention,
+            refreshPromptCacheFn: result.refreshPromptCache,
             pid: () => {
                 const p = result.pid;
                 return typeof p === "function" ? p() : p;
@@ -488,6 +976,8 @@ export class Supervisor {
             supportedModelsFn: supportedModels,
             supportedCommandsFn: supportedCommands,
             setModelFn: setModel,
+            runProviderCommandFn: runProviderCommand,
+            publishAgentctlSessionIdFn: publishAgentctlSessionId,
             permissionMode: effectiveMode,
             provider: activeProvider.name,
             model: modelSettings?.model,
@@ -497,6 +987,7 @@ export class Supervisor {
             executor: modelSettings?.executor,
             permissions: modelSettings?.permissions,
             recapMode: modelSettings?.recapMode,
+            recapAfterSeconds: modelSettings?.recapAfterSeconds,
             promptSuggestionMode,
             helperSideModel: modelSettings?.helperSideModel,
         };
@@ -527,6 +1018,9 @@ export class Supervisor {
         const result = await activeProvider.startSession({
             cwd: projectPath,
             resumeSessionId,
+            resumeSessionAt: resumeSessionId
+                ? modelSettings?.resumeSessionAt
+                : undefined,
             permissionMode: effectiveMode,
             model: modelSettings?.model,
             serviceTier: modelSettings?.serviceTier,
@@ -537,6 +1031,7 @@ export class Supervisor {
             globalInstructions: modelSettings?.globalInstructions,
             promptSuggestions: promptSuggestionMode === "native",
             shouldEmitLiveDeltas: () => processHolder.process?.hasLiveDeltaSubscribers() ?? false,
+            onProviderRetentionChange: () => this.handleProviderRetentionChanged(processHolder),
             onToolApproval: async (toolName, input, opts) => {
                 if (!processHolder.process) {
                     return { behavior: "deny", message: "Process not ready" };
@@ -544,7 +1039,7 @@ export class Supervisor {
                 return processHolder.process.handleToolApproval(toolName, input, opts);
             },
         });
-        const { iterator, queue, abort, isProcessAlive, probeLiveness, getProviderActivity, setMaxThinkingTokens, interrupt, steer, supportedModels, supportedCommands, setModel, } = result;
+        const { iterator, queue, abort, isProcessAlive, probeLiveness, getProviderActivity, getProviderRetention, setMaxThinkingTokens, interrupt, steer, supportedModels, supportedCommands, setModel, runProviderCommand, publishAgentctlSessionId, } = result;
         const tempSessionId = resumeSessionId ?? randomUUID();
         const options = {
             projectPath,
@@ -552,11 +1047,14 @@ export class Supervisor {
             sessionId: tempSessionId,
             idleTimeoutMs: this.idleTimeoutMs,
             queue,
+            sessionQueuePersistenceService: this.sessionQueuePersistenceService,
             abortFn: abort,
             isProcessAlive,
             shouldRetainIdleProcess: (sessionId) => this.shouldRetainIdleProcess(sessionId),
             probeLivenessFn: probeLiveness,
             getProviderActivityFn: getProviderActivity,
+            getProviderRetentionFn: getProviderRetention,
+            refreshPromptCacheFn: result.refreshPromptCache,
             pid: () => {
                 const p = result.pid;
                 return typeof p === "function" ? p() : p;
@@ -567,6 +1065,8 @@ export class Supervisor {
             supportedModelsFn: supportedModels,
             supportedCommandsFn: supportedCommands,
             setModelFn: setModel,
+            runProviderCommandFn: runProviderCommand,
+            publishAgentctlSessionIdFn: publishAgentctlSessionId,
             permissionMode: effectiveMode,
             provider: activeProvider.name,
             model: modelSettings?.model,
@@ -576,6 +1076,7 @@ export class Supervisor {
             executor: modelSettings?.executor,
             permissions: modelSettings?.permissions,
             recapMode: modelSettings?.recapMode,
+            recapAfterSeconds: modelSettings?.recapAfterSeconds,
             promptSuggestionMode,
             helperSideModel: modelSettings?.helperSideModel,
         };
@@ -626,6 +1127,7 @@ export class Supervisor {
         return process;
     }
     async resumeSession(sessionId, projectPath, message, permissionMode, modelSettings) {
+        await this.waitForSessionActivation(sessionId);
         // Check if already have a process for this session
         const existingProcessId = this.sessionToProcess.get(sessionId);
         if (existingProcessId) {
@@ -636,13 +1138,14 @@ export class Supervisor {
                     this.unregisterProcess(existingProcess);
                 }
                 else {
+                    let restartExistingProcess = false;
                     // Check if thinking/effort settings changed
-                    const thinkingChanged = existingProcess.thinking?.type !==
-                        (modelSettings?.thinking?.type ?? undefined);
+                    const thinkingChanged = !thinkingConfigsEqual(existingProcess.thinking, modelSettings?.thinking);
                     const effortChanged = existingProcess.effort !== modelSettings?.effort;
                     if (thinkingChanged || effortChanged) {
                         if (thinkingChanged &&
                             !effortChanged &&
+                            canApplyThinkingConfigDynamically(existingProcess.thinking, modelSettings?.thinking) &&
                             existingProcess.supportsThinkingModeChange) {
                             // Toggle adaptive/disabled dynamically via deprecated API
                             const tokens = modelSettings?.thinking?.type === "disabled" ? 0 : 1;
@@ -667,21 +1170,38 @@ export class Supervisor {
                                 sessionId,
                                 processId: existingProcess.id,
                                 oldThinking: existingProcess.thinking?.type,
+                                oldThinkingDisplay: existingProcess.thinking?.type === "adaptive" ||
+                                    existingProcess.thinking?.type === "enabled"
+                                    ? existingProcess.thinking.display
+                                    : undefined,
                                 oldEffort: existingProcess.effort,
                                 newThinking: modelSettings?.thinking?.type,
+                                newThinkingDisplay: modelSettings?.thinking?.type === "adaptive" ||
+                                    modelSettings?.thinking?.type === "enabled"
+                                    ? modelSettings.thinking.display
+                                    : undefined,
                                 newEffort: modelSettings?.effort,
                             }, "Thinking/effort changed, restarting process");
                             await existingProcess.abort();
                             this.unregisterProcess(existingProcess);
+                            restartExistingProcess = true;
                             // Fall through to start a new session with the updated settings
                         }
                     }
                     // Update permission mode if specified
-                    if (permissionMode) {
+                    if (!restartExistingProcess && permissionMode) {
                         existingProcess.setPermissionMode(permissionMode);
                     }
                     // Queue message to existing process (if we didn't fall through to restart)
-                    if (!existingProcess.isTerminated) {
+                    if (!restartExistingProcess && !existingProcess.isTerminated) {
+                        if (modelSettings?.resumeMode === "compact-first") {
+                            await this.queueAfterResumeCompaction({
+                                process: existingProcess,
+                                sessionId,
+                                message,
+                            });
+                            return existingProcess;
+                        }
                         const result = await this.queueProcessMessage(existingProcess, message);
                         if (result.success) {
                             return existingProcess;
@@ -704,46 +1224,322 @@ export class Supervisor {
             };
         }
         const projectId = encodeProjectId(projectPath);
-        // Check if at capacity
-        if (this.isAtCapacity()) {
-            // Try to preempt an idle worker
-            const preemptable = this.findPreemptableWorker();
-            if (preemptable) {
-                await this.preemptWorker(preemptable);
-                // Fall through to start session normally
+        if (this.isAtCapacity() && !this.findPreemptableWorker()) {
+            const result = this.workerQueue.enqueue({
+                type: "resume-session",
+                projectPath,
+                projectId,
+                sessionId,
+                message,
+                permissionMode,
+                modelSettings,
+            });
+            if (isQueueFullError(result)) {
+                return result;
             }
-            else {
-                // Queue the request
-                const result = this.workerQueue.enqueue({
-                    type: "resume-session",
-                    projectPath,
-                    projectId,
+            return {
+                queued: true,
+                queueId: result.queueId,
+                position: result.position,
+            };
+        }
+        if (await this.waitForSessionActivation(sessionId)) {
+            return this.resumeSession(sessionId, projectPath, message, permissionMode, modelSettings);
+        }
+        return this.startSessionActivation(sessionId, async () => {
+            if (this.isAtCapacity()) {
+                const preemptable = this.findPreemptableWorker();
+                if (preemptable) {
+                    await this.preemptWorker(preemptable);
+                }
+                else {
+                    throw new Error("Cannot resume: server is at worker capacity and no idle process can be preempted");
+                }
+            }
+            const provider = this.resolveProvider(modelSettings);
+            const resumeMode = modelSettings?.resumeMode ?? "full";
+            // Use provider if available (preferred)
+            if (provider) {
+                if (resumeMode === "compact-first") {
+                    return this.startCompactFirstProviderResume(projectPath, projectId, message, sessionId, permissionMode, modelSettings, provider);
+                }
+                return this.startProviderSession(projectPath, projectId, message, sessionId, permissionMode, modelSettings, provider);
+            }
+            // Use real SDK if available
+            if (this.realSdk) {
+                if (resumeMode === "compact-first") {
+                    return this.startCompactFirstRealResume(projectPath, projectId, message, sessionId, permissionMode, modelSettings);
+                }
+                return this.startRealSession(projectPath, projectId, message, sessionId, permissionMode, modelSettings);
+            }
+            // Fall back to legacy mock SDK
+            if (resumeMode === "compact-first") {
+                throw new ResumeCompactionError({
                     sessionId,
-                    message,
-                    permissionMode,
-                    modelSettings,
+                    provider: "claude",
+                    attempt: {
+                        status: "unavailable",
+                        reason: "legacy mock SDK does not support compact-first resume",
+                    },
                 });
-                if (isQueueFullError(result)) {
-                    return result;
+            }
+            return this.startLegacySession(projectPath, projectId, message, sessionId, permissionMode);
+        });
+    }
+    /** Whether the resolved provider has a real transcript-fork primitive. */
+    supportsForkSession(providerName) {
+        const provider = this.resolveProvider(providerName ? { providerName } : undefined);
+        return typeof provider?.forkSession === "function";
+    }
+    /**
+     * Fork a session's transcript into a new resumable session, optionally
+     * sliced at a message UUID. Throws when the provider has no fork
+     * primitive — fork must not be emulated (see
+     * topics/session-context-actions.md).
+     */
+    async forkSession(options) {
+        const provider = this.resolveProvider(options.providerName ? { providerName: options.providerName } : undefined);
+        if (!provider) {
+            throw new Error("provider is not available");
+        }
+        if (typeof provider.forkSession !== "function") {
+            throw new Error(`${provider.name} does not support transcript fork`);
+        }
+        return provider.forkSession({
+            sessionId: options.sessionId,
+            cwd: options.projectPath,
+            upToMessageId: options.upToMessageId,
+            title: options.title,
+        });
+    }
+    async generateSummary(providerName, request) {
+        const provider = this.resolveProvider(providerName ? { providerName } : undefined);
+        if (!provider) {
+            throw new Error("provider is not available");
+        }
+        if (typeof provider.generateSummary !== "function") {
+            throw new Error(`${provider.name} does not support summary generation`);
+        }
+        return provider.generateSummary(request);
+    }
+    async archiveHelperFork(childSessionId, parentSessionId, title, providerName, process) {
+        if (!this.sessionMetadataService) {
+            return;
+        }
+        await this.sessionMetadataService.updateMetadata(childSessionId, {
+            title,
+            archived: true,
+            parentSessionId,
+        });
+        await this.sessionMetadataService.setProvider(childSessionId, providerName);
+        await this.sessionMetadataService.setExecutor(childSessionId, process.executor);
+        await this.sessionMetadataService.setRequestedModel(childSessionId, process.requestedModel);
+    }
+    publishRecapListUpdate(process, text, timestamp = new Date().toISOString()) {
+        if (!this.eventBus) {
+            return;
+        }
+        const lastAgentText = formatAgentRecapExcerpt(text);
+        if (!lastAgentText) {
+            return;
+        }
+        const event = {
+            type: "session-updated",
+            sessionId: process.sessionId,
+            projectId: process.projectId,
+            updatedAt: timestamp,
+            lastAgentText,
+            timestamp: new Date().toISOString(),
+        };
+        this.eventBus.emit(event);
+    }
+    async persistRecapOverlay(process, message) {
+        if (!this.sessionMetadataService) {
+            return;
+        }
+        try {
+            await this.sessionMetadataService.addRecapMessage(process.sessionId, message);
+        }
+        catch (error) {
+            getLogger().warn({
+                event: "session_recap_overlay_persist_failed",
+                sessionId: process.sessionId,
+                processId: process.id,
+                projectId: process.projectId,
+                error: error instanceof Error ? error.message : String(error),
+            }, `Failed to persist recap overlay: ${process.sessionId}`);
+        }
+    }
+    async handleRecapResult(process, result) {
+        if (result.syntheticMessage) {
+            await this.persistRecapOverlay(process, result.syntheticMessage);
+        }
+        if (result.emitted && result.text) {
+            this.publishRecapListUpdate(process, result.text, result.syntheticMessage?.timestamp);
+        }
+    }
+    /**
+     * Raise a recap's "summarize since" floor to the latest already-emitted
+     * recap for the session. A recap covers the transcript through (about) its
+     * own timestamp, so a second return event with no assistant output after
+     * the last recap has nothing new to say — regenerating the same summary
+     * from the same context is wasted work and stacks duplicate recap rows.
+     */
+    recapFloorMs(sessionId, sinceMs) {
+        const recaps = this.sessionMetadataService?.getRecapMessages(sessionId);
+        const latest = recaps ? latestRecapMessage(recaps) : undefined;
+        const lastRecapMs = latest ? messageTimestampMs(latest) : null;
+        if (lastRecapMs === null) {
+            return sinceMs;
+        }
+        return sinceMs === null ? lastRecapMs : Math.max(sinceMs, lastRecapMs);
+    }
+    async requestForkedRecap(process, provider, sinceMs, options) {
+        if (!provider.supportsRecaps || !provider.generateSummary) {
+            return {
+                supported: false,
+                emitted: false,
+                reason: "provider does not support recaps",
+            };
+        }
+        sinceMs = this.recapFloorMs(process.sessionId, sinceMs);
+        if (typeof provider.forkSession !== "function") {
+            return process.requestTailedRecapFallback(provider, { sinceMs });
+        }
+        if (this.forkedRecapInFlight.has(process.id)) {
+            return {
+                supported: true,
+                emitted: false,
+                reason: "recap already in flight",
+            };
+        }
+        if (process.state.type === "in-turn") {
+            this.pendingForkedRecapRequests.set(process.id, sinceMs);
+            return {
+                supported: true,
+                emitted: false,
+                reason: "recap deferred until turn completes",
+            };
+        }
+        // A process freshly revived for this recap has an empty in-memory recap
+        // buffer (it never streamed) and will not emit a native away_summary on its
+        // own, so the native wait and the recent-text emptiness gate below would
+        // both wrongly suppress. Skip them: the fork reads the transcript from disk,
+        // and its own empty-text fallback handles a genuinely empty transcript.
+        if (options?.revived !== true) {
+            const nativeRecap = await process.waitForNativeRecapSince(sinceMs, provider.supportsNativeRecaps ? NATIVE_RECAP_FALLBACK_GRACE_MS : 0);
+            if (nativeRecap) {
+                return {
+                    supported: true,
+                    emitted: true,
+                    reason: "native recap emitted",
+                    text: nativeRecap.text,
+                };
+            }
+            const recent = process.getRecentAssistantText(sinceMs);
+            if (recent.length === 0) {
+                return {
+                    supported: true,
+                    emitted: false,
+                    reason: "no recent assistant activity to summarize",
+                };
+            }
+        }
+        const abortController = new AbortController();
+        this.forkedRecapInFlight.set(process.id, abortController);
+        let generatorSessionId;
+        try {
+            const generator = await this.forkSession({
+                sessionId: process.sessionId,
+                projectPath: process.projectPath,
+                providerName: process.provider,
+                title: "Recap generator",
+            });
+            generatorSessionId = generator.sessionId;
+            await this.archiveHelperFork(generator.sessionId, process.sessionId, "Recap generator", process.provider, process);
+            const text = (await provider.generateSummary({
+                purpose: "recap",
+                strategy: "fork",
+                generatorSessionId: generator.sessionId,
+                cwd: process.projectPath,
+                signal: abortController.signal,
+            })).text.trim();
+            if (!text) {
+                return process.requestTailedRecapFallback(provider, { sinceMs });
+            }
+            const lateNativeRecap = process.getNativeRecapSince(sinceMs);
+            if (lateNativeRecap) {
+                return {
+                    supported: true,
+                    emitted: true,
+                    reason: "native recap emitted",
+                    text: lateNativeRecap.text,
+                };
+            }
+            const syntheticMessage = process.emitSyntheticSystemMessage("away_summary", text);
+            return { supported: true, emitted: true, text, syntheticMessage };
+        }
+        catch (error) {
+            // Cancellation on parent activity is expected, not a failure.
+            if (abortController.signal.aborted) {
+                const nativeRecap = process.getNativeRecapSince(sinceMs);
+                if (nativeRecap) {
+                    return {
+                        supported: true,
+                        emitted: true,
+                        reason: "native recap emitted",
+                        text: nativeRecap.text,
+                    };
                 }
                 return {
-                    queued: true,
-                    queueId: result.queueId,
-                    position: result.position,
+                    supported: true,
+                    emitted: false,
+                    reason: "recap cancelled by new activity",
                 };
             }
+            const reason = error instanceof Error ? error.message : String(error);
+            getLogger().warn({
+                event: "session_forked_recap_failed",
+                sessionId: process.sessionId,
+                processId: process.id,
+                projectId: process.projectId,
+                providerName: process.provider,
+                generatorSessionId,
+                error: reason,
+            }, `Forked recap generation failed: ${reason}`);
+            return process.requestTailedRecapFallback(provider, { sinceMs });
         }
-        const provider = this.resolveProvider(modelSettings);
-        // Use provider if available (preferred)
-        if (provider) {
-            return this.startProviderSession(projectPath, projectId, message, sessionId, permissionMode, modelSettings, provider);
+        finally {
+            this.forkedRecapInFlight.delete(process.id);
         }
-        // Use real SDK if available
-        if (this.realSdk) {
-            return this.startRealSession(projectPath, projectId, message, sessionId, permissionMode, modelSettings);
+    }
+    /**
+     * Parent became active again: abort any in-flight forked recap (cancelling
+     * the generator-fork helper turn) and drop a not-yet-started deferred
+     * request, so a returning user's new turn is never shadowed by a stale
+     * recap. See topics/fork-recap.md.
+     */
+    cancelInFlightForkedRecap(process) {
+        const abortController = this.forkedRecapInFlight.get(process.id);
+        if (abortController && !abortController.signal.aborted) {
+            abortController.abort();
         }
-        // Fall back to legacy mock SDK
-        return this.startLegacySession(projectPath, projectId, message, sessionId, permissionMode);
+        this.pendingForkedRecapRequests.delete(process.id);
+    }
+    flushPendingForkedRecapRequest(process) {
+        if (process.recapMode !== "fork" ||
+            process.state.type !== "idle" ||
+            this.forkedRecapInFlight.has(process.id) ||
+            !this.pendingForkedRecapRequests.has(process.id)) {
+            return;
+        }
+        const sinceMs = this.pendingForkedRecapRequests.get(process.id) ?? null;
+        this.pendingForkedRecapRequests.delete(process.id);
+        const provider = getProvider(process.provider);
+        if (!provider) {
+            return;
+        }
+        void this.requestForkedRecap(process, provider, sinceMs).then((result) => this.handleRecapResult(process, result));
     }
     getProcess(processId) {
         return this.processes.get(processId);
@@ -767,7 +1563,7 @@ export class Supervisor {
         const nextEffort = hasEffortUpdate ? updates.effort : process.effort;
         const modelChanged = nextModel !== process.resolvedModel;
         const serviceTierChanged = nextServiceTier !== process.serviceTier;
-        const thinkingChanged = nextThinking?.type !== process.thinking?.type;
+        const thinkingChanged = !thinkingConfigsEqual(process.thinking, nextThinking);
         const effortChanged = nextEffort !== process.effort;
         if (!modelChanged &&
             !serviceTierChanged &&
@@ -796,6 +1592,7 @@ export class Supervisor {
             providerName: process.provider,
             executor: process.executor,
             recapMode: process.recapMode,
+            recapAfterSeconds: process.recapAfterSeconds,
             promptSuggestionMode: process.promptSuggestionMode,
             helperSideModel: process.helperSideModel,
         };
@@ -809,6 +1606,13 @@ export class Supervisor {
             return null;
         }
         process.setRecapConfig(config);
+        this.emitOwnershipChange(process.sessionId, process.projectId, {
+            owner: "self",
+            processId: process.id,
+            permissionMode: process.permissionMode,
+            modeVersion: process.modeVersion,
+            recapAfterSeconds: process.recapAfterSeconds,
+        });
         return process;
     }
     getProcessForSession(sessionId) {
@@ -836,12 +1640,18 @@ export class Supervisor {
         }
         const isActiveSteeringMessage = message.metadata?.deliveryIntent === "steer" &&
             process.state.type === "in-turn";
+        const hasExplicitThinkingSettings = modelSettings?.thinking !== undefined ||
+            modelSettings?.effort !== undefined;
         const requestedThinking = isActiveSteeringMessage
             ? process.thinking
-            : modelSettings?.thinking;
+            : hasExplicitThinkingSettings
+                ? modelSettings?.thinking
+                : process.thinking;
         const requestedEffort = isActiveSteeringMessage
             ? process.effort
-            : modelSettings?.effort;
+            : hasExplicitThinkingSettings
+                ? modelSettings?.effort
+                : process.effort;
         const requestedServiceTier = isActiveSteeringMessage
             ? process.serviceTier
             : (modelSettings?.serviceTier ?? process.serviceTier);
@@ -849,12 +1659,13 @@ export class Supervisor {
         // Service tier is cost-affecting, so changes require an explicit restart
         // rather than being inferred from a normal prompt.
         const serviceTierChanged = process.serviceTier !== requestedServiceTier;
-        const thinkingChanged = process.thinking?.type !== (requestedThinking?.type ?? undefined);
+        const thinkingChanged = !thinkingConfigsEqual(process.thinking, requestedThinking);
         const effortChanged = process.effort !== requestedEffort;
         if (serviceTierChanged || thinkingChanged || effortChanged) {
             if (!serviceTierChanged &&
                 thinkingChanged &&
                 !effortChanged &&
+                canApplyThinkingConfigDynamically(process.thinking, requestedThinking) &&
                 process.supportsThinkingModeChange) {
                 // Toggle thinking dynamically via deprecated API (works for auto↔off)
                 const tokens = requestedThinking?.type === "disabled" ? 0 : 1;
@@ -891,6 +1702,7 @@ export class Supervisor {
                     ...modelSettings,
                     serviceTier: requestedServiceTier,
                     recapMode: modelSettings?.recapMode ?? process.recapMode,
+                    recapAfterSeconds: modelSettings?.recapAfterSeconds ?? process.recapAfterSeconds,
                     promptSuggestionMode: modelSettings?.promptSuggestionMode ?? process.promptSuggestionMode,
                     helperSideModel: modelSettings?.helperSideModel ?? process.helperSideModel,
                 };
@@ -905,6 +1717,10 @@ export class Supervisor {
         if (permissionMode) {
             process.setPermissionMode(permissionMode);
         }
+        // Preemptively compact when this turn would push an already-near-threshold
+        // session over its per-model compact-early limit (task 029). No-op unless
+        // the threshold is set and the idle process is over it.
+        await this.maybeCompactBeforeDelivery(process, sessionId, modelSettings);
         const result = await this.queueProcessMessage(process, message);
         if (result.success) {
             return { success: true, process, restarted: false };
@@ -923,6 +1739,9 @@ export class Supervisor {
         const log = getLogger();
         try {
             for (const process of this.processes.values()) {
+                if (this.queuePatientDeferredMessagesForProcess(process, now, log)) {
+                    continue;
+                }
                 await this.queueHeartbeatTurnForProcess(process, now, log);
             }
             if (!this.getHeartbeatTurnCandidates) {
@@ -938,7 +1757,68 @@ export class Supervisor {
         }
     }
     shouldRetainIdleProcess(sessionId) {
-        return this.getHeartbeatTurnSettings?.(sessionId)?.enabled === true;
+        const process = this.getProcessForSession(sessionId);
+        return (process?.hasPatientDeferredMessages() === true ||
+            this.getHeartbeatTurnSettings?.(sessionId)?.enabled === true);
+    }
+    queuePatientDeferredMessagesForProcess(process, now, log) {
+        if (!process.hasPatientDeferredMessages() ||
+            process.isTerminated ||
+            process.state.type !== "idle" ||
+            process.queueDepth > 0 ||
+            process.isProcessAlive === false) {
+            return false;
+        }
+        const liveness = process.getLivenessSnapshot(new Date(now));
+        if (liveness.derivedStatus !== "verified-idle") {
+            return false;
+        }
+        const fallbackMs = process.state.since.getTime();
+        const quietSinceMs = getHeartbeatResetAtMs(liveness, fallbackMs);
+        if (!Number.isFinite(quietSinceMs)) {
+            return false;
+        }
+        // Each patient entry carries its own patience window (seconds of
+        // verified quiet); promote the elapsed ones and schedule a precise
+        // re-check for the shortest remaining wait.
+        const { promoted, nextPatienceMsRemaining } = process.promoteEligiblePatientDeferredMessages({ quietSinceMs, now });
+        if (nextPatienceMsRemaining !== null) {
+            this.schedulePatientDeferredCheck(process, nextPatienceMsRemaining);
+        }
+        if (!promoted) {
+            return false;
+        }
+        log.info({
+            event: "patient_deferred_messages_promoted",
+            sessionId: process.sessionId,
+            processId: process.id,
+            projectId: process.projectId,
+            quietMs: Math.max(0, now - quietSinceMs),
+            quietSince: new Date(quietSinceMs).toISOString(),
+            livenessStatus: liveness.derivedStatus,
+        }, `Promoted patient deferred messages for session: ${process.sessionId}`);
+        return true;
+    }
+    /**
+     * Arm (or re-arm) the one-shot patient-queue re-check for a process. The
+     * check itself re-derives eligibility and re-arms only while patient
+     * entries remain, so the timer cannot become a standing poll.
+     */
+    schedulePatientDeferredCheck(process, delayMs) {
+        const existing = this.patientCheckTimers.get(process.id);
+        if (existing) {
+            clearTimeout(existing);
+        }
+        const delay = Math.max(250, Math.min(delayMs, 60 * 60 * 1000));
+        const timer = setTimeout(() => {
+            this.patientCheckTimers.delete(process.id);
+            if (!this.processes.has(process.id)) {
+                return;
+            }
+            this.queuePatientDeferredMessagesForProcess(process, Date.now(), getLogger());
+        }, delay);
+        timer.unref();
+        this.patientCheckTimers.set(process.id, timer);
     }
     async queueHeartbeatTurnForProcess(process, now, log) {
         const settings = this.getHeartbeatTurnSettings?.(process.sessionId);
@@ -1304,7 +2184,15 @@ export class Supervisor {
                 reason: "provider not found",
             };
         }
-        return process.requestRecap(provider, options);
+        const result = process.recapMode === "fork"
+            ? await this.requestForkedRecap(process, provider, options?.sinceMs ?? null, { revived: options?.revived === true })
+            : await process.requestRecap(provider, {
+                ...options,
+                sinceMs: this.recapFloorMs(process.sessionId, options?.sinceMs ?? null),
+            });
+        await this.handleRecapResult(process, result);
+        const { syntheticMessage: _syntheticMessage, ...publicResult } = result;
+        return publicResult;
     }
     async interruptProcessWithTimeout(process, options) {
         const log = getLogger();
@@ -1371,6 +2259,7 @@ export class Supervisor {
             providerName,
             executor: sourceProcess.executor,
             permissions: sourceProcess.permissions,
+            recapAfterSeconds: sourceProcess.recapAfterSeconds,
         });
         const log = getLogger();
         if (!("id" in result)) {
@@ -1424,6 +2313,24 @@ export class Supervisor {
             else if (event.type === "complete") {
                 this.unregisterProcess(process);
             }
+            else if (event.type === "message") {
+                this.cacheMissBillingMonitor.observeMessage(process, event.message);
+                if (isAwaySummaryMessage(event.message) &&
+                    event.message.isSynthetic !== true) {
+                    const durable = toDurableRecapMessage(event.message, "provider-native");
+                    if (durable) {
+                        void this.persistRecapOverlay(process, durable);
+                        this.publishRecapListUpdate(process, durable.content, durable.timestamp);
+                        this.cancelInFlightForkedRecap(process);
+                    }
+                }
+            }
+            else if (event.type === "recap-result") {
+                void this.handleRecapResult(process, event.result);
+            }
+            else if (event.type === "context-window-observed") {
+                this.onContextWindowObserved?.(event.model, event.contextWindow, event.provider);
+            }
             else if (event.type === "session-id-changed") {
                 // Update session→process mapping when temp ID is replaced by real ID from SDK
                 // This is critical for ExternalSessionTracker to correctly identify owned sessions
@@ -1459,6 +2366,7 @@ export class Supervisor {
                     processId: process.id,
                     permissionMode: process.permissionMode,
                     modeVersion: process.modeVersion,
+                    recapAfterSeconds: process.recapAfterSeconds,
                 };
                 this.emitOwnershipChange(event.newSessionId, process.projectId, ownership);
                 // Retry early metadata reconciliation with authoritative session ID.
@@ -1480,14 +2388,45 @@ export class Supervisor {
                                 ? "tool-approval"
                                 : "user-question";
                     }
-                    this.emitAgentActivityChange(process.sessionId, process.projectId, event.state.type, pendingInputType);
+                    // A turn that settles to idle while the provider still has background
+                    // work retained should report as active, not idle.
+                    const activity = event.state.type === "idle" && process.isRetainingProviderWork()
+                        ? "in-turn"
+                        : event.state.type;
+                    this.emitAgentActivityChange(process.sessionId, process.projectId, activity, pendingInputType);
                 }
                 // Emit worker activity on any state change (affects hasActiveWork)
                 this.emitWorkerActivity();
+                // A fresh idle boundary starts the patient-queue quiet clock; arm a
+                // prompt re-check so seconds-scale patience does not wait for the
+                // 30s heartbeat tick.
+                if (event.state.type === "idle" &&
+                    process.hasPatientDeferredMessages()) {
+                    this.schedulePatientDeferredCheck(process, 250);
+                }
+                if (event.state.type === "idle") {
+                    this.flushPendingForkedRecapRequest(process);
+                }
+                // Parent started a new turn: cancel any in-flight/deferred forked recap
+                // so a returning user's live turn is not shadowed by a stale recap.
+                if (event.state.type === "in-turn") {
+                    this.cancelInFlightForkedRecap(process);
+                }
+            }
+            else if (event.type === "deferred-queue") {
+                if (event.reason === "queued" &&
+                    process.state.type === "idle" &&
+                    process.hasPatientDeferredMessages()) {
+                    this.schedulePatientDeferredCheck(process, 250);
+                }
+                this.emitWorkerActivity();
             }
             else if (event.type === "terminated") {
                 this.emitProcessTerminated(process.sessionId, process.projectId, process.id, process.provider, event.reason);
             }
+            else if (event.type === "provider-runtime-status-change") {
+                this.emitProviderRuntimeStatusChange(process.sessionId, process.projectId, event.status);
+            }
         });
     }
     registerProcess(process, isNewSession) {
@@ -1510,6 +2449,7 @@ export class Supervisor {
             processId: process.id,
             permissionMode: process.permissionMode,
             modeVersion: process.modeVersion,
+            recapAfterSeconds: process.recapAfterSeconds,
         };
         // Emit session created event for new sessions
         if (isNewSession) {
@@ -1536,6 +2476,15 @@ export class Supervisor {
     }
     unregisterProcess(process) {
         this.observedProcessIds.delete(process.id);
+        this.cacheMissBillingMonitor.forgetProcess(process.id);
+        this.pendingForkedRecapRequests.delete(process.id);
+        this.forkedRecapInFlight.get(process.id)?.abort();
+        this.forkedRecapInFlight.delete(process.id);
+        const patientTimer = this.patientCheckTimers.get(process.id);
+        if (patientTimer) {
+            clearTimeout(patientTimer);
+            this.patientCheckTimers.delete(process.id);
+        }
         if (!this.processes.has(process.id)) {
             return;
         }
@@ -1624,6 +2573,7 @@ export class Supervisor {
         const session = {
             id: process.sessionId,
             projectId: process.projectId,
+            projectName: getProjectName(process.projectPath),
             title: optimistic.title,
             fullTitle: optimistic.fullTitle,
             createdAt: now,
@@ -1676,6 +2626,7 @@ export class Supervisor {
             updatedAt: summary.updatedAt,
             contextUsage: summary.contextUsage,
             model: summary.model,
+            lastAgentText: summary.lastAgentText,
             timestamp: new Date().toISOString(),
         };
         this.eventBus.emit(event);
@@ -1707,6 +2658,37 @@ export class Supervisor {
         };
         this.eventBus.emit(event);
     }
+    emitProviderRuntimeStatusChange(sessionId, projectId, providerRuntimeStatus) {
+        if (!this.eventBus)
+            return;
+        const event = {
+            type: "provider-runtime-status-changed",
+            sessionId,
+            projectId,
+            providerRuntimeStatus,
+            timestamp: new Date().toISOString(),
+        };
+        this.eventBus.emit(event);
+    }
+    handleProviderRetentionChanged(processHolder) {
+        const process = processHolder.process;
+        process?.handleProviderRetentionChanged();
+        this.emitWorkerActivity();
+        // Background work starting/finishing flips an idle session between active
+        // and truly idle without a state-change event. Surface that so inbox/sidebar
+        // activity indicators update live rather than only on the next refresh.
+        if (process && process.state.type === "idle") {
+            this.emitAgentActivityChange(process.sessionId, process.projectId, process.isRetainingProviderWork() ? "in-turn" : "idle");
+        }
+    }
+    processHasActiveWork(process) {
+        if (process.state.type === "in-turn" ||
+            process.state.type === "waiting-input") {
+            return true;
+        }
+        return (process.getLivenessSnapshot().derivedStatus ===
+            "verified-waiting-provider");
+    }
     /**
      * Emit worker activity event for safe restart indicator.
      * Called when workers are added, removed, or change state.
@@ -1714,16 +2696,48 @@ export class Supervisor {
     emitWorkerActivity() {
         if (!this.eventBus)
             return;
-        const hasActiveWork = Array.from(this.processes.values()).some((p) => p.state.type === "in-turn" || p.state.type === "waiting-input");
+        const interruptibleSessionCount = Array.from(this.processes.values()).filter((p) => this.processHasActiveWork(p)).length;
+        const queuedSessionMessageCount = this.getQueuedSessionMessageCount();
         const event = {
             type: "worker-activity-changed",
             activeWorkers: this.processes.size,
+            interruptibleSessionCount,
             queueLength: this.workerQueue.length,
-            hasActiveWork,
+            queuedSessionMessageCount,
+            hasActiveWork: interruptibleSessionCount > 0,
             timestamp: new Date().toISOString(),
         };
         this.eventBus.emit(event);
     }
+    getQueuedSessionMessageCount() {
+        let count = this.workerQueue.length;
+        for (const process of this.processes.values()) {
+            count += process.queueDepth;
+            count += process.getDeferredQueueSummary().length;
+        }
+        return count;
+    }
+    async preserveRestartablePatientQueuesForRestart() {
+        if (!this.sessionQueuePersistenceService || this.workerQueue.length > 0) {
+            return 0;
+        }
+        const processes = Array.from(this.processes.values()).filter((process) => !process.isTerminated);
+        if (processes.some((process) => this.processHasActiveWork(process))) {
+            return 0;
+        }
+        if (processes.some((process) => process.queueDepth > 0 || process.hasVolatileDeferredMessages())) {
+            return 0;
+        }
+        let preservedCount = 0;
+        for (const process of processes) {
+            preservedCount +=
+                await process.preservePatientDeferredMessagesForRestart();
+        }
+        if (preservedCount > 0) {
+            this.emitWorkerActivity();
+        }
+        return preservedCount;
+    }
     // ============ Staleness Detection ============
     /**
      * Terminate processes stuck in "in-turn" with no SDK messages for too long.
@@ -1838,6 +2852,9 @@ export class Supervisor {
                     const result = await this.startSessionInternal(request.projectPath, request.projectId, request.message, request.sessionId, request.permissionMode, request.modelSettings);
                     process = result;
                 }
+                if (request.workstreamId) {
+                    await this.sessionMetadataService?.setWorkstream(process.sessionId, request.workstreamId);
+                }
                 // Emit queue removed event
                 this.eventBus?.emit({
                     type: "queue-request-removed",
@@ -1909,11 +2926,13 @@ export class Supervisor {
      * Returns whether any workers are actively processing or waiting for input.
      */
     getWorkerActivity() {
-        const hasActiveWork = Array.from(this.processes.values()).some((p) => p.state.type === "in-turn" || p.state.type === "waiting-input");
+        const interruptibleSessionCount = Array.from(this.processes.values()).filter((p) => this.processHasActiveWork(p)).length;
         return {
             activeWorkers: this.processes.size,
+            interruptibleSessionCount,
             queueLength: this.workerQueue.length,
-            hasActiveWork,
+            queuedSessionMessageCount: this.getQueuedSessionMessageCount(),
+            hasActiveWork: interruptibleSessionCount > 0,
         };
     }
 }