@cjhyy/code-shell-core 0.8.20 → 0.9.0

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.0";
+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.0";
 // ─── 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/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;
 }
 /**

package/dist/protocol/chat-session-manager.js

@@ -34,6 +34,9 @@ export class ChatSessionManager {
     closingSessions = new Map();
     closedSessions = new Set();
     sessionGeneration = new Map();
+    sessionSlices = new Map();
+    migrationClaims = new Map();
+    residentMigrations = new Map();
     runtime;
     /** Identity scope this manager serves ("local" unless injected). */
     identity;
@@ -78,11 +81,133 @@ export class ChatSessionManager {
         });
     }
     async getOrCreate(sessionId, slice) {
-        const closing = this.closingSessions.get(sessionId);
-        if (closing) {
-            await closing;
+        // A non-resident migration claim is a short ownership handoff to Main.
+        // Wait rather than fail the user's run: once Main atomically commits (or
+        // aborts) and releases the token, the Engine is created from current disk.
+        for (;;) {
+            const residentMigration = this.residentMigrations.get(sessionId);
+            if (residentMigration) {
+                await residentMigration.released;
+                continue;
+            }
+            const claim = this.migrationClaims.get(sessionId);
+            if (claim) {
+                await claim.released;
+                continue;
+            }
+            const closing = this.closingSessions.get(sessionId);
+            if (closing) {
+                await closing;
+                continue;
+            }
+            // No await separates the final claim check from getOrCreateNow. On this
+            // process's event loop, either this creates the resident owner first or
+            // beginSessionMigration installs the fence first; both cannot win.
+            return this.getOrCreateNow(sessionId, slice);
+        }
+    }
+    /**
+     * 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, ownershipToken) {
+        if (this.residentMigrations.has(sessionId)) {
+            return { status: "failed", error: `Session ${sessionId} migration is already in progress` };
+        }
+        const resident = this.sessions.get(sessionId);
+        if (resident)
+            return { status: "resident", session: resident };
+        if (this.closingSessions.has(sessionId)) {
+            return { status: "failed", error: `Session ${sessionId} is closing` };
+        }
+        if (this.migrationClaims.has(sessionId)) {
+            return { status: "failed", error: `Session ${sessionId} migration is already in progress` };
+        }
+        let release;
+        const released = new Promise((resolve) => {
+            release = resolve;
+        });
+        this.migrationClaims.set(sessionId, { ownershipToken, released, release });
+        return { status: "not-resident", ownershipToken };
+    }
+    /** Release only the exact claim minted for this Session. */
+    completeSessionMigration(sessionId, ownershipToken) {
+        const claim = this.migrationClaims.get(sessionId);
+        if (!claim || claim.ownershipToken !== ownershipToken)
+            return false;
+        this.migrationClaims.delete(sessionId);
+        claim.release();
+        return true;
+    }
+    /**
+     * 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.
+     */
+    async migrateResidentSessionMainRoot(sessionId, target) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            throw new Error(`Session ${sessionId} is not resident`);
+        if (session.isBusy() || session.queueDepth() > 0) {
+            throw new Error(`Session ${sessionId} is running or has queued turns`);
+        }
+        if (this.residentMigrations.has(sessionId) || this.migrationClaims.has(sessionId)) {
+            throw new Error(`Session ${sessionId} migration is already in progress`);
+        }
+        let release;
+        const released = new Promise((resolve) => {
+            release = resolve;
+        });
+        this.residentMigrations.set(sessionId, { released, release });
+        const previous = session.engine;
+        let candidate;
+        let committed = false;
+        try {
+            const previousSlice = this.sessionSlices.get(sessionId) ?? {};
+            const permissionMode = previous.getPermissionMode?.() ?? previousSlice.permissionMode;
+            const nextSlice = {
+                ...previousSlice,
+                cwd: target.mainRoot,
+                workspaceContext: target.workspaceContext,
+                projectTrusted: target.projectTrusted,
+                ...(permissionMode ? { permissionMode } : {}),
+            };
+            const built = this.factory(nextSlice);
+            if (built === previous) {
+                throw new Error(`Session ${sessionId} Engine factory reused the resident owner`);
+            }
+            candidate = built;
+            if (permissionMode && candidate.getPermissionMode?.() !== permissionMode) {
+                candidate.setPermissionMode?.(permissionMode);
+            }
+            const candidateGeneration = this.engineSessionManager(candidate)?.registerSessionGeneration(sessionId) ??
+                this.sessionGeneration.get(sessionId) ??
+                1;
+            candidate.restoreSessionModel?.(sessionId);
+            const workspace = previous.migrateSessionMainRoot(sessionId, target.project, target.mainRoot);
+            session.replaceEngine(previous, candidate);
+            this.sessionGeneration.set(sessionId, candidateGeneration);
+            this.sessionSlices.set(sessionId, nextSlice);
+            committed = true;
+            await this.disposeEngine(previous, sessionId);
+            return workspace;
+        }
+        catch (error) {
+            if (!committed && candidate)
+                await this.disposeEngine(candidate, sessionId);
+            throw error;
+        }
+        finally {
+            this.residentMigrations.delete(sessionId);
+            release();
         }
-        return this.getOrCreateNow(sessionId, slice);
     }
     /**
      * Cold-resume a persisted session using its own cwd. The first detached
@@ -129,6 +254,7 @@ export class ChatSessionManager {
         const sessionManager = this.engineSessionManager(engine);
         const generation = sessionManager?.registerSessionGeneration(sessionId) ?? 1;
         this.sessionGeneration.set(sessionId, generation);
+        this.sessionSlices.set(sessionId, { ...slice });
         this.sessions.set(sessionId, session);
         // A direct user run is an explicit resume/open and may clear the tombstone.
         // Background wakeups must check isUnavailable() before reaching this path.
@@ -201,6 +327,10 @@ export class ChatSessionManager {
         return this.closeSession(sessionId, true);
     }
     closeSession(sessionId, markClosed) {
+        const migration = this.residentMigrations.get(sessionId);
+        if (migration) {
+            return migration.released.then(() => this.closeSession(sessionId, markClosed));
+        }
         const alreadyClosing = this.closingSessions.get(sessionId);
         if (alreadyClosing)
             return alreadyClosing;
@@ -237,6 +367,7 @@ export class ChatSessionManager {
             else
                 this.closedSessions.delete(sessionId);
             this.sessionGeneration.delete(sessionId);
+            this.sessionSlices.delete(sessionId);
         };
         if (!s.isBusy()) {
             finishClose();
@@ -278,6 +409,9 @@ export class ChatSessionManager {
      * immediately afterward (the TUI REPL) doesn't orphan detached dev servers.
      */
     async closeAllAsync() {
+        for (const [sessionId, claim] of [...this.migrationClaims]) {
+            this.completeSessionMigration(sessionId, claim.ownershipToken);
+        }
         await Promise.all([...this.sessions.keys()].map((id) => this.close(id)));
         // App/worker shutdown — reap every background shell so a detached
         // `npm run dev` doesn't outlive the process as an orphan holding a port
@@ -335,6 +469,35 @@ export class ChatSessionManager {
             });
         });
     }
+    async disposeEngine(engine, sessionId) {
+        const dispose = engine.dispose;
+        if (typeof dispose === "function") {
+            try {
+                await dispose.call(engine);
+            }
+            catch (error) {
+                logger.warn("chat_session.engine_dispose_failed", {
+                    sessionId,
+                    identity: this.identity,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            return;
+        }
+        const mcpPool = this.runtime.mcpPool;
+        if (typeof mcpPool?.unregisterOwner !== "function")
+            return;
+        try {
+            await mcpPool.unregisterOwner(engine);
+        }
+        catch (error) {
+            logger.warn("chat_session.mcp_owner_unregister_failed", {
+                sessionId,
+                identity: this.identity,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
     engineSessionManager(engine) {
         const candidate = engine;
         const manager = candidate.getSessionManager?.();

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

@@ -21,6 +21,7 @@ export interface TurnOpts {
     /** Working directory override for this turn. If omitted, Engine uses its
      *  configured cwd. */
     cwd?: string;
+    workspaceContext?: import("../workspace/workspace-context.js").WorkspaceContext;
     onStream?: (event: StreamEvent) => void;
     /** User-facing text persisted beside the full model-facing task. */
     displayText?: string;
@@ -70,7 +71,7 @@ export interface TurnOpts {
  */
 export declare class ChatSession {
     readonly id: string;
-    readonly engine: Engine;
+    private currentEngine;
     /**
      * Per-session approval callbacks and resolver-free metadata indexed by requestId.
      * `readonly` guards the Map reference (preventing reassignment); the
@@ -111,6 +112,13 @@ export declare class ChatSession {
     private settlePromise;
     private resolveSettled;
     constructor(opts: ChatSessionOptions);
+    get engine(): Engine;
+    /**
+     * Swap the Engine at an idle run boundary without replacing the ChatSession
+     * that owns the queue, stream callback, approvals, idle timestamp and id.
+     * The expected-owner check makes a stale migration fail closed.
+     */
+    replaceEngine(expected: Engine, replacement: Engine): void;
     enqueueTurn(task: string, opts: TurnOpts): Promise<EngineResult>;
     /**
      * Run session maintenance (for example context-package summarization) under

package/dist/protocol/chat-session.js

@@ -7,7 +7,7 @@ import { isSameGoalInstance } from "../goal/lifecycle.js";
  */
 export class ChatSession {
     id;
-    engine;
+    currentEngine;
     /**
      * Per-session approval callbacks and resolver-free metadata indexed by requestId.
      * `readonly` guards the Map reference (preventing reassignment); the
@@ -49,9 +49,26 @@ export class ChatSession {
     resolveSettled = null;
     constructor(opts) {
         this.id = opts.id;
-        this.engine = opts.engine;
+        this.currentEngine = opts.engine;
         this.defaultOnStream = opts.onStream;
     }
+    get engine() {
+        return this.currentEngine;
+    }
+    /**
+     * Swap the Engine at an idle run boundary without replacing the ChatSession
+     * that owns the queue, stream callback, approvals, idle timestamp and id.
+     * The expected-owner check makes a stale migration fail closed.
+     */
+    replaceEngine(expected, replacement) {
+        if (this.active || this.exclusiveOperation || this.queue.length > 0) {
+            throw new Error(`Session ${this.id} is running or has queued turns`);
+        }
+        if (this.currentEngine !== expected) {
+            throw new Error(`Session ${this.id} Engine ownership changed during migration`);
+        }
+        this.currentEngine = replacement;
+    }
     enqueueTurn(task, opts) {
         this.lastActivityAt = Date.now();
         // The user (or a wakeup the guard already let through) is starting a turn —
@@ -283,6 +300,7 @@ export class ChatSession {
             const onStream = next.opts.onStream ?? this.defaultOnStream;
             const result = await this.engine.run(next.task, {
                 cwd: next.opts.cwd,
+                workspaceContext: next.opts.workspaceContext,
                 sessionId: this.id,
                 displayText: next.opts.displayText,
                 signal: this.controller.signal,