@cjhyy/code-shell-core 0.8.20 → 0.9.1

package/dist/engine/run-workspace.js

@@ -1,4 +1,6 @@
 import { resolveRunProfileState } from "./run-setup.js";
+import { canonicalKey } from "../workspace/canonical-key.js";
+import { legacySingleRootWorkspace, validateWorkspaceContext, workspacePrimaryRoot, } from "../workspace/workspace-context.js";
 /**
  * Resolve the working directory for a run. Precedence for legacy sessions:
  *   options.cwd  >  resumed session's state.cwd  >  config.cwd  >  process.cwd()
@@ -93,6 +95,37 @@ export async function resolveRunWorkspace(args) {
             configCwd: args.configCwd,
             processCwd: args.processCwd,
         });
+    const rawWorkspaceContext = options?.workspaceContext ?? args.configWorkspaceContext;
+    let workspaceContext;
+    try {
+        workspaceContext = rawWorkspaceContext
+            ? validateWorkspaceContext(rawWorkspaceContext)
+            : legacySingleRootWorkspace(cwd);
+    }
+    catch (error) {
+        return workspaceError(options?.sessionId, error instanceof Error ? error.message : String(error));
+    }
+    const authoritativeWorkspaceContext = rawWorkspaceContext !== undefined;
+    const primary = workspacePrimaryRoot(workspaceContext);
+    if (canonicalKey(primary.path) !== canonicalKey(cwd)) {
+        return workspaceError(options?.sessionId, `WorkspaceContext primary does not match effective cwd: ${primary.path} != ${cwd}`);
+    }
+    if (workspaceResume?.ok &&
+        workspaceResume.reason !== "legacy" &&
+        canonicalKey(workspaceResume.workspace.root) !== canonicalKey(primary.path)) {
+        return workspaceError(options?.sessionId, "WorkspaceContext primary does not match SessionWorkspace");
+    }
+    const binding = options?.sessionId
+        ? args.sessionManager.readSessionProjectBinding(options.sessionId)
+        : undefined;
+    if (binding && !authoritativeWorkspaceContext) {
+        return workspaceError(options?.sessionId, "bound Session requires an authoritative WorkspaceContext");
+    }
+    if (binding &&
+        (binding.projectId !== workspaceContext.projectId ||
+            binding.mainRootId !== workspaceContext.sessionMainRootId)) {
+        return workspaceError(options?.sessionId, "WorkspaceContext does not match persisted project binding");
+    }
     const profileState = profile?.disableWorkspaceProfile
         ? {
             workspaceProfile: undefined,
@@ -114,7 +147,21 @@ export async function resolveRunWorkspace(args) {
             runPermissionMode,
             runPlanMode,
             cwd,
+            workspaceContext,
+            authoritativeWorkspaceContext,
             profileState,
         },
     };
 }
+function workspaceError(sessionId, message) {
+    return {
+        ok: false,
+        result: {
+            text: `ERROR: ${message}`,
+            reason: "completed",
+            sessionId: sessionId ?? "workspace-invalid",
+            turnCount: 0,
+            usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+        },
+    };
+}

package/dist/engine/subagent-spawner.d.ts

@@ -21,6 +21,7 @@ export interface CreateSubAgentSpawnerDeps {
     parentSandbox: SandboxConfig;
     presetName: AgentPresetName;
     cwd: string;
+    workspaceContext?: import("../workspace/workspace-context.js").WorkspaceContext;
     permissionMode: NonNullable<EngineConfig["permissionMode"]>;
     modelPool?: ModelPool;
     appendParentSubagent: (agentId: string, description: string) => void;

package/dist/engine/subagent-spawner.js

@@ -233,6 +233,7 @@ export function createSubAgentSpawner(deps) {
                     retryMaxAttempts: 2,
                 },
                 cwd: deps.cwd,
+                workspaceContext: deps.workspaceContext ?? deps.parentConfig.workspaceContext,
                 permissionMode: deps.permissionMode,
                 preset: deps.presetName,
                 enabledBuiltinTools: scope.enabled,

package/dist/engine/types.d.ts

@@ -33,6 +33,8 @@ export interface EngineConfig {
      */
     clientDefaults?: ClientDefaults;
     cwd?: string;
+    /** Trusted host-provided root authorization for runs created by this Engine. */
+    workspaceContext?: import("../workspace/workspace-context.js").WorkspaceContext;
     maxTurns?: number;
     /**
      * Override the goal-mode consecutive-stop-block cap (TODO 3.1). Falls back to

package/dist/index.d.ts

@@ -3,8 +3,8 @@
  *
  * Public API exports.
  */
-export declare const VERSION = "0.8.20";
-export type { Message, ContentBlock, ToolDefinition, ToolCall, ToolResult, RegisteredTool, TranscriptEvent, TranscriptEventType, SessionState, SessionKind, SessionWorkspace, SessionForkLineage, ContextUsageAnchor, SessionStatus, TokenUsage, CompiledInput, PermissionDecision, PermissionMode, PermissionRule, TurnPhase, TurnResult, TerminalReason, TurnCompletionKind, StreamEvent, StreamCallback, LLMConfig, ClientDefaults, LLMResponse, Settings, MCPServerConfig, } from "./types.js";
+export declare const VERSION = "0.9.1";
+export type { Message, ContentBlock, ToolDefinition, ToolCall, ToolResult, RegisteredTool, TranscriptEvent, TranscriptEventType, SessionState, SessionKind, SessionWorkspace, SessionProjectBinding, SessionForkLineage, ContextUsageAnchor, SessionStatus, TokenUsage, CompiledInput, PermissionDecision, PermissionMode, PermissionRule, TurnPhase, TurnResult, TerminalReason, TurnCompletionKind, StreamEvent, StreamCallback, LLMConfig, ClientDefaults, LLMResponse, Settings, MCPServerConfig, } from "./types.js";
 export type { GoalConfig, GoalLifecycleConfig, GoalLifecyclePhase, GoalLifecycleTerminalReason, GoalLifecycleV1, } from "./goal/lifecycle.js";
 export { FrameworkError, LLMError, LLMRateLimitError, ContextLimitError, ToolError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError, PermissionDeniedError, SessionError, TranscriptError, ConfigError, CompositionError, SandboxUnavailableError, } from "./exceptions.js";
 export { compileComposition, toCompositionSnapshot, computeCompositionDigest, compositionToolCatalog, resolvePresetFromComposition, } from "./composition/index.js";
@@ -62,7 +62,7 @@ export { AgentClient, type BackgroundAgentCompletedHandler } from "./protocol/cl
 export { createInProcessTransport, StdioTransport, type Transport } from "./protocol/transport.js";
 export { SocketTransport, listenTcp, type TcpListenResult } from "./protocol/tcp-transport.js";
 export { createServer, createClient, type CreateServerOptions, type CreateClientOptions, type ServerHandle, } from "./protocol/factories.js";
-export { Methods, ErrorCodes, type RpcMessage, type RunResult, type ForkSessionParams, type ForkSessionResult as ProtocolForkSessionResult, } from "./protocol/types.js";
+export { Methods, ErrorCodes, type RpcMessage, type RunResult, type ForkSessionParams, type ForkSessionResult as ProtocolForkSessionResult, type MigrateSessionMainRootResult, } from "./protocol/types.js";
 export type * from "./protocol/mobile-remote-types.js";
 export { Transcript } from "./session/transcript.js";
 export { SessionManager, sessionMainRoot, codeShellHome, sessionsRoot, buildForkState, buildForkTranscript, type ForkSessionOptions, type ForkSessionResult, } from "./session/session-manager.js";

package/dist/index.extension.d.ts

@@ -26,7 +26,7 @@ export type { ExposureRationale } from "./tool-system/external-tool-exposure.js"
 export { webSearchTool } from "./tool-system/builtin/web-search.js";
 export { webFetchTool } from "./tool-system/builtin/web-fetch.js";
 export { extractJSON, extractJSONArray } from "./utils/json.js";
-export type { ExtensionQueryHandler, ExtensionTool, } from "./tool-system/capability-module.js";
+export type { ExtensionQueryHandler, ExtensionTool } from "./tool-system/capability-module.js";
 export type { SessionWorkspace } from "./types.js";
 export type { CapabilityArtifactDetector, CapabilityDynamicContextProvider, CapabilityToolServiceHost, } from "./capabilities/index.js";
 export type { AgentModule, AgentEngineContributions, AgentProtocolContributions, AgentModuleToolContribution, ResolvedComposition, } from "./composition/types.js";

package/dist/index.internal.d.ts

@@ -7,6 +7,7 @@
  */
 export { getGraphemeSegmenter, firstGrapheme, lastGrapheme, getWordSegmenter, getRelativeTimeFormat, getTimeZone, getSystemLocaleLanguage, } from "./utils/intl.js";
 export { env } from "./utils/env.js";
+export { canonicalKey, canonicalPath, computeWorkspaceRootsDigest, createWorkspaceContext, legacySingleRootWorkspace, validateWorkspaceContext, workspacePrimaryRoot, type ProjectId, type ProjectRootContext, type ProjectRootId, type WorkspaceContext, type WorkspaceContextInput, } from "./workspace/workspace-context.js";
 export { default as sliceAnsi } from "./utils/sliceAnsi.js";
 export { execFileNoThrow } from "./utils/execFileNoThrow.js";
 export { findExecutable, resolveExecutable, setGitPathOverride, resolveGit, isGitAvailable, resolveGitPath, } from "./utils/exec.js";
@@ -27,7 +28,6 @@ export { getInteractiveApprovalBackend } from "./tool-system/permission.js";
 export { defaultSandboxConfig, type SandboxConfig } from "./tool-system/sandbox/index.js";
 export { buildNotificationMessage, buildNotificationSummary, notificationQueue, agentNotificationBus, notificationItemToStreamEvent, type NotificationItem, } from "./tool-system/builtin/agent-notifications.js";
 export { backgroundJobRegistry } from "./tool-system/builtin/background-jobs.js";
-export type { BackgroundAgentCompletedEvent } from "./types.js";
 export { startAutomation, type StartAutomationDeps, type AutomationHandle, CronScheduler, cronScheduler, type CronExecutionOutcome, type CronJob, type CronJobLifecycleEvent, type CronPermissionLevel, type CronTemplateSource, type CreateJobOptions, type UpdateJobPatch, CronStore, defaultCronStorePath, bindCronToEngine, bindCronToRunManager, type CronRunner, type CronRunRequest, type CronRunResult, type RunSubmitter, isCronExpression, parseCronExpression, nextCronTime, validateSchedule, type ParsedCron, resolveWritePolicy, wrapUntrustedInput, type WritePolicy, runWriteJobInWorktree, type WriteJobGitOps, type RunWriteJobInput, type RunWriteJobResult, } from "./automation/index.js";
 export { asyncAgentRegistry, type AsyncAgentEntry } from "./tool-system/builtin/agent-registry.js";
 export { backgroundShellManager, BackgroundShellManager, type BgShell, type BgShellStatus, } from "./runtime/background-shell.js";
@@ -46,7 +46,7 @@ export { capabilitiesFor, type Capability } from "./llm/capabilities/index.js";
 export { reasoningControlFor, type ReasoningControl, } from "./llm/capabilities/reasoning-control.js";
 export { REASONING_EFFORTS, type ReasoningSetting } from "./llm/reasoning-setting.js";
 export { type ProviderConfig } from "./llm/provider-catalog.js";
-export type { ApprovalRequest, ApprovalResult, ApprovalScope, TaskInfo } from "./types.js";
+export type { ApprovalRequest, ApprovalResult, ApprovalScope, BackgroundAgentCompletedEvent, TaskInfo, } from "./types.js";
 export { fileCache } from "./tool-system/builtin/file-cache.js";
 export { validateToolArgs } from "./tool-system/validation.js";
 export { createOffBackend } from "./tool-system/sandbox/off.js";

package/dist/index.internal.js

@@ -8,6 +8,7 @@
 // ─── Utils (shared primitives used by TUI) ───────────────────────
 export { getGraphemeSegmenter, firstGrapheme, lastGrapheme, getWordSegmenter, getRelativeTimeFormat, getTimeZone, getSystemLocaleLanguage, } from "./utils/intl.js";
 export { env } from "./utils/env.js";
+export { canonicalKey, canonicalPath, computeWorkspaceRootsDigest, createWorkspaceContext, legacySingleRootWorkspace, validateWorkspaceContext, workspacePrimaryRoot, } from "./workspace/workspace-context.js";
 export { default as sliceAnsi } from "./utils/sliceAnsi.js";
 export { execFileNoThrow } from "./utils/execFileNoThrow.js";
 export { findExecutable, resolveExecutable, setGitPathOverride, resolveGit, isGitAvailable, resolveGitPath, } from "./utils/exec.js";

package/dist/index.js

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

package/dist/plugins/pluginAutomationTemplates.d.ts

@@ -6,6 +6,8 @@ export interface InstantiatePluginAutomationTemplateOptions {
     templateId: string;
     expectedRevision: string;
     cwd?: string;
+    projectId?: string;
+    rootId?: string;
     /** Effective project/global disable list computed by the host for this cwd. */
     disabledPluginNames: ReadonlySet<string>;
     maxJobs?: number;

package/dist/plugins/pluginAutomationTemplates.js

@@ -38,6 +38,10 @@ export function instantiatePluginAutomationTemplate(options) {
     const template = contribution.template;
     return options.scheduler.create(template.title.default, template.schedule, template.prompt, {
         ...(template.workspace === "current" && options.cwd ? { cwd: options.cwd } : {}),
+        ...(template.workspace === "current" && options.projectId
+            ? { projectId: options.projectId }
+            : {}),
+        ...(template.workspace === "current" && options.rootId ? { rootId: options.rootId } : {}),
         ...(template.timezone ? { timezone: template.timezone } : {}),
         permissionLevel: template.permissionLevel,
         templateSource: {

package/dist/prompt/composer.d.ts

@@ -10,8 +10,11 @@ import { type ScanOptions } from "./instruction-scanner.js";
 import { type AgentPreset } from "../preset/index.js";
 import type { BuiltinTool } from "../tool-system/builtin/index.js";
 import type { CapabilityDynamicContextProvider } from "../capabilities/index.js";
+import { type WorkspaceContext } from "../workspace/workspace-context.js";
 export interface ComposerOptions {
     cwd: string;
+    /** Run workspace; omitted by legacy callers that only provide cwd. */
+    workspace?: WorkspaceContext;
     model: string;
     instructionOptions?: ScanOptions;
     /** Resolved preset — used to load section-based prompt. */
@@ -106,9 +109,9 @@ export interface ComposerOptions {
     disableSourcesContext?: boolean;
 }
 export declare class PromptComposer {
-    private readonly options;
     private sectionCache;
     private cachedInstructions;
+    private readonly options;
     constructor(options: ComposerOptions);
     /**
      * Build the system prompt from sections.

package/dist/prompt/composer.js

@@ -11,12 +11,18 @@ import { MemoryManager } from "../session/memory.js";
 import { scanSkills } from "../skills/index.js";
 import { buildSkillListing } from "../tool-system/builtin/skill-prompt.js";
 import { resolveAgentPreset, buildPresetSystemPrompt } from "../preset/index.js";
+import { legacySingleRootWorkspace, validateWorkspaceContext, } from "../workspace/workspace-context.js";
 export class PromptComposer {
-    options;
     sectionCache = new SectionCache();
     cachedInstructions = null;
+    options;
     constructor(options) {
-        this.options = options;
+        this.options = {
+            ...options,
+            workspace: options.workspace === undefined
+                ? legacySingleRootWorkspace(options.cwd)
+                : validateWorkspaceContext(options.workspace),
+        };
     }
     /**
      * Build the system prompt from sections.
@@ -58,7 +64,7 @@ export class PromptComposer {
         const preset = this.options.preset ?? resolveAgentPreset();
         const parts = await Promise.all((this.options.dynamicContextProviders ?? []).map(async (provider) => {
             try {
-                return await provider({ cwd: this.options.cwd, preset });
+                return await provider({ cwd: this.options.cwd, workspace: this.options.workspace, preset });
             }
             catch {
                 // A capability's optional context must not make a turn fail.
@@ -164,6 +170,8 @@ export class PromptComposer {
                 const lines = [
                     `You are an AI agent powered by ${this.options.model}.`,
                     `Working directory: ${this.options.cwd}`,
+                    `Workspace roots (${this.options.workspace.roots.length}):`,
+                    ...this.options.workspace.roots.map((root) => `- [${root.role}] ${root.path} (rootId: ${root.id})`),
                     `Platform: ${process.platform}`,
                     `Shell: ${process.env.SHELL ?? "unknown"}`,
                 ];

package/dist/protocol/background-result-wakeup.d.ts

@@ -0,0 +1,18 @@
+import type { StreamEvent } from "../types.js";
+import type { ApprovalRouter } from "../tool-system/permission.js";
+import type { ChatSession } from "./chat-session.js";
+import type { ChatSessionManager } from "./chat-session-manager.js";
+interface BackgroundResultWakeOptions {
+    sessionId: string;
+    manager: ChatSessionManager | null;
+    rehydrate(sessionId: string): Promise<ChatSession | null>;
+    approvalRouter: ApprovalRouter;
+    onStream(event: StreamEvent): void;
+}
+/**
+ * Drain pending background results into exactly one synthetic continuation.
+ * Busy sessions are awaited so a completion cannot fall into the gap between
+ * the notification bus callback and the interactive run-boundary re-check.
+ */
+export declare function wakeSessionForBackgroundResults({ sessionId, manager, rehydrate, approvalRouter, onStream, }: BackgroundResultWakeOptions): Promise<boolean>;
+export {};

package/dist/protocol/background-result-wakeup.js

@@ -0,0 +1,101 @@
+import { logger } from "../logging/logger.js";
+import { buildNotificationMessage, notificationQueue, } from "../tool-system/builtin/agent-notifications.js";
+/**
+ * Drain pending background results into exactly one synthetic continuation.
+ * Busy sessions are awaited so a completion cannot fall into the gap between
+ * the notification bus callback and the interactive run-boundary re-check.
+ */
+export async function wakeSessionForBackgroundResults({ sessionId, manager, rehydrate, approvalRouter, onStream, }) {
+    if (!manager) {
+        logger.debug("bg_wakeup.skipped", { sessionId, reason: "no_chat_manager" });
+        return false;
+    }
+    if (manager.isUnavailable(sessionId)) {
+        logger.debug("bg_wakeup.skipped", { sessionId, reason: "session_unavailable" });
+        return false;
+    }
+    let session = manager.get(sessionId) ?? (await rehydrate(sessionId));
+    if (!session) {
+        logger.debug("bg_wakeup.skipped", { sessionId, reason: "session_missing" });
+        return false;
+    }
+    while (session.isBusy()) {
+        logger.debug("bg_wakeup.waiting_for_idle", {
+            sessionId,
+            pendingCount: notificationQueue.getSnapshot(sessionId).length,
+        });
+        await session.settled;
+        if (manager.isUnavailable(sessionId)) {
+            logger.debug("bg_wakeup.skipped", {
+                sessionId,
+                reason: "session_became_unavailable",
+            });
+            return false;
+        }
+        const current = manager.get(sessionId);
+        if (!current) {
+            logger.debug("bg_wakeup.skipped", { sessionId, reason: "session_evicted_after_settle" });
+            return false;
+        }
+        session = current;
+    }
+    // Headless/automation runs are one-shot and have no continuation consumer.
+    if (session.engine.isHeadless()) {
+        logger.debug("bg_wakeup.skipped", { sessionId, reason: "headless" });
+        return false;
+    }
+    // A user Stop must win over a later background completion.
+    if (session.wasCancelledSinceLastTurn()) {
+        logger.debug("bg_wakeup.skipped", { sessionId, reason: "cancelled_since_last_turn" });
+        return false;
+    }
+    let runWorkspace = {};
+    try {
+        const resolver = session.engine.resolveSessionRunWorkspace;
+        runWorkspace = resolver?.call(session.engine, sessionId) ?? {};
+    }
+    catch (error) {
+        // Resolve before draining so an unavailable authoritative worktree context
+        // leaves the completion recoverable by a later user run.
+        logger.warn("bg_wakeup.workspace_unavailable", {
+            sessionId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return false;
+    }
+    const pending = notificationQueue.drainAll(sessionId);
+    if (pending.length === 0) {
+        logger.debug("bg_wakeup.skipped", { sessionId, reason: "no_pending_results" });
+        return false;
+    }
+    const task = `<system-reminder>\n${buildNotificationMessage(pending)}\n</system-reminder>`;
+    try {
+        const result = await session.enqueueTurn(task, {
+            injected: true,
+            ...runWorkspace,
+            onStream,
+            approvalRouter,
+        });
+        if (result.turnCount === 0) {
+            const restored = notificationQueue.restoreResults(sessionId, pending);
+            logger.warn("bg_wakeup.turn_not_started", {
+                sessionId,
+                restored,
+                reason: result.reason,
+                text: result.text.slice(0, 500),
+            });
+            return false;
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const restored = notificationQueue.restoreResults(sessionId, pending);
+        logger.warn("bg_wakeup.turn_failed", { sessionId, error: message, restored });
+        // A setup failure can occur before the turn loop emits its own terminal
+        // event. Emit an error so every renderer clears its busy state, but keep
+        // the result queued so a later user turn can consume it safely.
+        onStream({ type: "error", error: message || "background wakeup failed" });
+        return false;
+    }
+    return true;
+}

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

@@ -1,9 +1,10 @@
 import { ChatSession } from "./chat-session.js";
 import type { SessionKind } from "../types.js";
+import type { SessionProjectBinding, SessionWorkspace } from "../types.js";
 import type { Engine } from "../engine/engine.js";
 import type { EngineRuntime } from "../engine/runtime.js";
 import type { EngineConfig } from "../engine/types.js";
-export type EngineConfigSlice = Pick<EngineConfig, "permissionMode" | "preset" | "customSystemPrompt" | "appendSystemPrompt" | "goal" | "maxTurns" | "maxContextTokens" | "cwd" | "projectTrusted" | "sessionStorageDir">;
+export type EngineConfigSlice = Pick<EngineConfig, "permissionMode" | "preset" | "customSystemPrompt" | "appendSystemPrompt" | "goal" | "maxTurns" | "maxContextTokens" | "cwd" | "workspaceContext" | "projectTrusted" | "sessionStorageDir">;
 /** Identity scope every ChatSessionManager belongs to when none is injected. */
 export declare const LOCAL_CHAT_IDENTITY = "local";
 export interface ChatSessionManagerOptions {
@@ -48,11 +49,30 @@ export interface LiveChatSessionSnapshot {
     }>;
 }
 export declare const CLOSED_CHAT_SESSION_TOMBSTONE_LIMIT = 4096;
+export interface ResidentSessionMainRootMigration {
+    project: SessionProjectBinding;
+    mainRoot: string;
+    workspaceContext: import("../workspace/workspace-context.js").WorkspaceContext;
+    projectTrusted: boolean;
+}
+export type SessionMigrationOwnership = {
+    status: "resident";
+    session: ChatSession;
+} | {
+    status: "not-resident";
+    ownershipToken: string;
+} | {
+    status: "failed";
+    error: string;
+};
 export declare class ChatSessionManager {
     private readonly sessions;
     private readonly closingSessions;
     private readonly closedSessions;
     private readonly sessionGeneration;
+    private readonly sessionSlices;
+    private readonly migrationClaims;
+    private readonly residentMigrations;
     readonly runtime: EngineRuntime;
     /** Identity scope this manager serves ("local" unless injected). */
     readonly identity: string;
@@ -76,6 +96,26 @@ export declare class ChatSessionManager {
      */
     forIdentity(identity: string): ChatSessionManager;
     getOrCreate(sessionId: string, slice: EngineConfigSlice): Promise<ChatSession>;
+    /**
+     * Prove whether this worker currently owns a resident Engine, or fence the
+     * Session so Main can perform one durable migration without a re-resume race.
+     */
+    beginSessionMigration(sessionId: string, ownershipToken: string): SessionMigrationOwnership;
+    /** Release only the exact claim minted for this Session. */
+    completeSessionMigration(sessionId: string, ownershipToken: string): boolean;
+    /**
+     * Rebuild an idle resident Engine against a new authoritative main root.
+     *
+     * Transaction order is intentional:
+     * 1. construct and restore the candidate while durable state still points at
+     *    the old owner (factory/restore failure is therefore a no-op),
+     * 2. atomically commit durable state through the old owning Engine,
+     * 3. synchronously swap the Engine inside the existing ChatSession,
+     * 4. dispose the unreachable old Engine before reporting success.
+     *
+     * No await occurs between the idle check, durable commit and owner swap.
+     */
+    migrateResidentSessionMainRoot(sessionId: string, target: ResidentSessionMainRootMigration): Promise<SessionWorkspace>;
     /**
      * Cold-resume a persisted session using its own cwd. The first detached
      * Engine is only a storage probe; all actual work runs on the second Engine
@@ -121,6 +161,7 @@ export declare class ChatSessionManager {
     startIdleSweeper(intervalMs?: number): void;
     stopIdleSweeper(): void;
     private unregisterMcpOwner;
+    private disposeEngine;
     private engineSessionManager;
 }
 /**