@cjhyy/code-shell-core 0.8.20 → 0.9.0

package/dist/protocol/mobile-remote-types.d.ts

@@ -66,10 +66,18 @@ export interface MobilePermissionModeSnapshotEntry {
     mode: PermissionMode;
 }
 export interface MobileProjectMeta {
+    id?: string;
     path: string;
     name: string;
     addedAt?: number;
     pinned?: boolean;
+    roots?: Array<{
+        id: string;
+        path: string;
+        name: string;
+        role: "primary" | "secondary";
+    }>;
+    primaryRootId?: string;
 }
 export type MobileImageMime = "image/png" | "image/jpeg" | "image/webp" | "image/gif";
 export interface MobileImageBase {
@@ -112,6 +120,11 @@ export type MobileClientEvent = {
     sessionId: string;
 } | {
     type: "session.create";
+    /** Stable V2 project identity. null explicitly selects the no-repo workspace. */
+    projectId?: string | null;
+    /** Stable V2 root identity. Omit to use the project's current primary root. */
+    rootId?: string;
+    /** Legacy client compatibility only; Main validates it against mounted roots. */
     cwd?: string | null;
     name?: string;
 } | {
@@ -230,6 +243,8 @@ export type MobileServerEvent = {
     type: "chat.accepted";
     sessionId?: string;
     cwd?: string | null;
+    projectId?: string | null;
+    rootId?: string;
     clientMessageId?: string;
     attachments?: MobileAttachmentSummary[];
 } | {

package/dist/protocol/server.d.ts

@@ -198,6 +198,7 @@ export declare class AgentServer {
      */
     private bgAgentBusUnsubscribe;
     private readonly wakeupsInFlight;
+    private readonly sessionWorkspaceRpc;
     /**
      * Effective session manager for the connection this server serves. Without
      * a resolveIdentity hook this is exactly the host-supplied manager —
@@ -310,8 +311,6 @@ export declare class AgentServer {
      */
     private handleBackgroundWork;
     private handleCloseSession;
-    private handleReleaseWorkspace;
-    private handleSetWorkspace;
     private handleConfigure;
     /**
      * Resolve the Engine that owns a session-scoped query (compact, archive_range,

package/dist/protocol/server.js

@@ -30,6 +30,7 @@ import { redactSecrets } from "../logging/sanitize-messages.js";
 import { compileComposition } from "../composition/compiler.js";
 import { attachProtocolContributions } from "../composition/protocol-attach.js";
 import { computeEffectiveDisabledLists } from "../capability-control/disabled-lists.js";
+import { SessionWorkspaceRpcHandlers } from "./session-workspace-rpc.js";
 import { describePluginCommands, expandPluginCommandBody, scanPluginCommands, MAX_PLUGIN_COMMAND_ARGUMENT_CHARS, } from "../plugins/pluginCommandsLoader.js";
 function isValidRunAttachment(value) {
     if (!value || typeof value !== "object")
@@ -380,6 +381,7 @@ export class AgentServer {
      */
     bgAgentBusUnsubscribe = null;
     wakeupsInFlight = new Set();
+    sessionWorkspaceRpc;
     /**
      * Effective session manager for the connection this server serves. Without
      * a resolveIdentity hook this is exactly the host-supplied manager —
@@ -425,6 +427,14 @@ export class AgentServer {
             throw new Error("AgentServer: either chatManager or engine must be supplied");
         }
         this.transport = options.transport;
+        this.sessionWorkspaceRpc = new SessionWorkspaceRpcHandlers({
+            transport: this.transport,
+            getChatManager: () => this.chatManager,
+            getLegacyEngine: () => this.legacyEngine,
+            getLastSlice: (sessionId) => this.lastSliceBySession.get(sessionId),
+            rememberSessionSlice: (sessionId, slice) => this.rememberSessionSlice(sessionId, slice),
+            wireInteractiveSession: (session, sessionId) => this.wireInteractiveSession(session, sessionId),
+        });
         // Protocol surface from the compiled composition. Each contributing
         // module may attach one observer; the server calls them at every
         // lifecycle hook point and isolates per-observer failures.
@@ -787,10 +797,16 @@ export class AgentServer {
                 await this.handleCloseSession(req);
                 break;
             case Methods.ReleaseWorkspace:
-                this.handleReleaseWorkspace(req);
+                this.sessionWorkspaceRpc.release(req);
                 break;
             case Methods.SetWorkspace:
-                this.handleSetWorkspace(req);
+                this.sessionWorkspaceRpc.set(req);
+                break;
+            case Methods.MigrateSessionMainRoot:
+                await this.sessionWorkspaceRpc.migrateMainRoot(req);
+                break;
+            case Methods.CompleteSessionMainRootMigration:
+                this.sessionWorkspaceRpc.completeMainRootMigration(req);
                 break;
             case Methods.GoalExtend:
                 this.handleGoalExtend(req);
@@ -1153,6 +1169,7 @@ export class AgentServer {
         }
         const sessionConfig = {
             cwd: params.cwd,
+            workspaceContext: params.workspaceContext,
             projectTrusted: params.projectTrusted,
             preset: params.preset ??
                 (params.behaviorMode === ISOLATED_TASK_BEHAVIOR_MODE ? "general" : undefined),
@@ -1226,6 +1243,7 @@ export class AgentServer {
             }
             const run = session.enqueueTurn(params.task, {
                 cwd: params.cwd,
+                workspaceContext: params.workspaceContext,
                 displayText: displayText || undefined,
                 injected: params.injected === true,
                 attachments: Array.isArray(params.attachments) ? params.attachments : undefined,
@@ -1358,6 +1376,7 @@ export class AgentServer {
             });
             const result = await this.legacyEngine.run(params.task, {
                 cwd: params.cwd,
+                workspaceContext: params.workspaceContext,
                 sessionId: params.sessionId,
                 displayText: displayText || undefined,
                 injected: params.injected === true,
@@ -1944,55 +1963,6 @@ export class AgentServer {
         backgroundJobRegistry.dropForSession(params.sessionId);
         this.transport.send(createResponse(req.id, { ok: true }));
     }
-    // ─── ReleaseWorkspace ──────────────────────────────────────────
-    handleReleaseWorkspace(req) {
-        const params = (req.params ?? {});
-        if (typeof params.sessionId !== "string" || params.sessionId.length === 0) {
-            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "sessionId is required"));
-            return;
-        }
-        if (this.chatManager) {
-            const session = this.chatManager.get(params.sessionId);
-            if (!session) {
-                this.transport.send(createResponse(req.id, { ok: true, workspace: null }));
-                return;
-            }
-            const engine = session.engine;
-            const workspace = engine.releaseSessionWorkspace?.(params.sessionId) ?? null;
-            this.transport.send(createResponse(req.id, { ok: true, workspace }));
-            return;
-        }
-        const engine = this.legacyEngine;
-        const workspace = engine?.releaseSessionWorkspace?.(params.sessionId) ?? null;
-        this.transport.send(createResponse(req.id, { ok: true, workspace }));
-    }
-    handleSetWorkspace(req) {
-        const params = (req.params ?? {});
-        if (typeof params.sessionId !== "string" || params.sessionId.length === 0) {
-            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "sessionId is required"));
-            return;
-        }
-        if (!params.workspace ||
-            typeof params.workspace !== "object" ||
-            typeof params.workspace.root !== "string" ||
-            params.workspace.root.length === 0 ||
-            (params.workspace.kind !== "main" && params.workspace.kind !== "worktree")) {
-            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "valid workspace is required"));
-            return;
-        }
-        const engine = this.chatManager
-            ? this.chatManager.get(params.sessionId)?.engine
-            : this.legacyEngine;
-        if (!engine) {
-            this.transport.send(createResponse(req.id, { ok: true, workspace: null }));
-            return;
-        }
-        const workspace = engine.setSessionWorkspace?.(params.sessionId, params.workspace);
-        this.transport.send(createResponse(req.id, {
-            ok: workspace !== undefined && workspace !== null,
-            workspace: workspace ?? null,
-        }));
-    }
     // ─── Configure ──────────────────────────────────────────────────
     handleConfigure(req) {
         const params = (req.params ?? {});

package/dist/protocol/session-workspace-rpc.d.ts

@@ -0,0 +1,23 @@
+import type { Engine } from "../engine/engine.js";
+import type { ChatSession } from "./chat-session.js";
+import type { ChatSessionManager, EngineConfigSlice } from "./chat-session-manager.js";
+import type { Transport } from "./transport.js";
+import { type RpcRequest } from "./types.js";
+interface SessionWorkspaceRpcDependencies {
+    transport: Transport;
+    getChatManager(): ChatSessionManager | null;
+    getLegacyEngine(): Engine | null;
+    getLastSlice(sessionId: string): EngineConfigSlice | undefined;
+    rememberSessionSlice(sessionId: string, slice: EngineConfigSlice): void;
+    wireInteractiveSession(session: ChatSession, sessionId: string): void;
+}
+/** Protocol boundary for Session workspace ownership and root migration. */
+export declare class SessionWorkspaceRpcHandlers {
+    private readonly deps;
+    constructor(deps: SessionWorkspaceRpcDependencies);
+    release(req: RpcRequest): void;
+    set(req: RpcRequest): void;
+    migrateMainRoot(req: RpcRequest): Promise<void>;
+    completeMainRootMigration(req: RpcRequest): void;
+}
+export {};

package/dist/protocol/session-workspace-rpc.js

@@ -0,0 +1,171 @@
+import { canonicalKey } from "../workspace/canonical-key.js";
+import { validateWorkspaceContext, workspacePrimaryRoot, } from "../workspace/workspace-context.js";
+import { createErrorResponse, createResponse, ErrorCodes, } from "./types.js";
+/** Protocol boundary for Session workspace ownership and root migration. */
+export class SessionWorkspaceRpcHandlers {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    release(req) {
+        const params = (req.params ?? {});
+        if (typeof params.sessionId !== "string" || params.sessionId.length === 0) {
+            this.deps.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "sessionId is required"));
+            return;
+        }
+        const manager = this.deps.getChatManager();
+        if (manager) {
+            const session = manager.get(params.sessionId);
+            if (!session) {
+                this.deps.transport.send(createResponse(req.id, { ok: true, workspace: null }));
+                return;
+            }
+            const workspace = session.engine.releaseSessionWorkspace?.(params.sessionId) ?? null;
+            this.deps.transport.send(createResponse(req.id, { ok: true, workspace }));
+            return;
+        }
+        const workspace = this.deps.getLegacyEngine()?.releaseSessionWorkspace?.(params.sessionId) ?? null;
+        this.deps.transport.send(createResponse(req.id, { ok: true, workspace }));
+    }
+    set(req) {
+        const params = (req.params ?? {});
+        if (typeof params.sessionId !== "string" || params.sessionId.length === 0) {
+            this.deps.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "sessionId is required"));
+            return;
+        }
+        if (!params.workspace ||
+            typeof params.workspace !== "object" ||
+            typeof params.workspace.root !== "string" ||
+            params.workspace.root.length === 0 ||
+            (params.workspace.kind !== "main" && params.workspace.kind !== "worktree")) {
+            this.deps.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "valid workspace is required"));
+            return;
+        }
+        const manager = this.deps.getChatManager();
+        const engine = manager ? manager.get(params.sessionId)?.engine : this.deps.getLegacyEngine();
+        if (!engine) {
+            this.deps.transport.send(createResponse(req.id, { ok: true, workspace: null }));
+            return;
+        }
+        const workspace = engine.setSessionWorkspace?.(params.sessionId, params.workspace);
+        this.deps.transport.send(createResponse(req.id, {
+            ok: workspace !== undefined && workspace !== null,
+            workspace: workspace ?? null,
+        }));
+    }
+    async migrateMainRoot(req) {
+        const params = (req.params ?? {});
+        if (!validMigrationParams(params)) {
+            this.deps.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "valid Session root migration is required"));
+            return;
+        }
+        let workspaceContext;
+        try {
+            workspaceContext = validateWorkspaceContext(params.workspaceContext);
+            const primary = workspacePrimaryRoot(workspaceContext);
+            if (workspaceContext.projectId !== params.project.projectId ||
+                workspaceContext.sessionMainRootId !== params.project.mainRootId ||
+                canonicalKey(primary.path) !== canonicalKey(params.mainRoot)) {
+                throw new Error("migration target authority does not match the requested root");
+            }
+        }
+        catch (error) {
+            this.deps.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, error instanceof Error ? error.message : "valid target authority is required"));
+            return;
+        }
+        const manager = this.deps.getChatManager();
+        let engine;
+        let residentSession;
+        if (manager) {
+            const ownership = manager.beginSessionMigration(params.sessionId, params.ownershipToken);
+            if (ownership.status === "not-resident") {
+                this.deps.transport.send(createResponse(req.id, {
+                    status: "not-resident",
+                    ownershipToken: ownership.ownershipToken,
+                }));
+                return;
+            }
+            if (ownership.status === "failed") {
+                this.deps.transport.send(createResponse(req.id, {
+                    status: "failed",
+                    error: ownership.error,
+                }));
+                return;
+            }
+            residentSession = ownership.session;
+            engine = residentSession.engine;
+        }
+        else {
+            engine = this.deps.getLegacyEngine();
+        }
+        if (!engine) {
+            this.deps.transport.send(createResponse(req.id, {
+                status: "failed",
+                error: "Session migration owner is unavailable",
+            }));
+            return;
+        }
+        try {
+            const workspace = residentSession
+                ? await manager.migrateResidentSessionMainRoot(params.sessionId, {
+                    project: params.project,
+                    mainRoot: params.mainRoot,
+                    workspaceContext,
+                    projectTrusted: params.projectTrusted,
+                })
+                : engine.migrateSessionMainRoot?.(params.sessionId, params.project, params.mainRoot);
+            if (!workspace)
+                throw new Error(`Session ${params.sessionId} migration was not committed`);
+            if (residentSession) {
+                this.deps.rememberSessionSlice(params.sessionId, {
+                    ...(this.deps.getLastSlice(params.sessionId) ?? {}),
+                    cwd: params.mainRoot,
+                    workspaceContext,
+                    projectTrusted: params.projectTrusted,
+                });
+                this.deps.wireInteractiveSession(residentSession, params.sessionId);
+            }
+            this.deps.transport.send(createResponse(req.id, {
+                status: "migrated",
+                workspace,
+            }));
+        }
+        catch (error) {
+            this.deps.transport.send(createResponse(req.id, {
+                status: "failed",
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        }
+    }
+    completeMainRootMigration(req) {
+        const params = (req.params ?? {});
+        if (typeof params.sessionId !== "string" ||
+            params.sessionId.length === 0 ||
+            typeof params.ownershipToken !== "string" ||
+            params.ownershipToken.length === 0 ||
+            params.ownershipToken.length > 128) {
+            this.deps.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "valid migration claim is required"));
+            return;
+        }
+        if (!this.deps.getChatManager()?.completeSessionMigration(params.sessionId, params.ownershipToken)) {
+            this.deps.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "migration claim is not active"));
+            return;
+        }
+        this.deps.transport.send(createResponse(req.id, { released: true }));
+    }
+}
+function validMigrationParams(params) {
+    return (typeof params.sessionId === "string" &&
+        params.sessionId.length > 0 &&
+        Boolean(params.project) &&
+        typeof params.project?.projectId === "string" &&
+        params.project.projectId.length > 0 &&
+        typeof params.project.mainRootId === "string" &&
+        params.project.mainRootId.length > 0 &&
+        typeof params.mainRoot === "string" &&
+        params.mainRoot.length > 0 &&
+        typeof params.projectTrusted === "boolean" &&
+        typeof params.ownershipToken === "string" &&
+        params.ownershipToken.length > 0 &&
+        params.ownershipToken.length <= 128);
+}

package/dist/protocol/types.d.ts

@@ -7,7 +7,7 @@
  *   Server → Client: notifications (stream events, approval requests)
  *   Server → Client: responses (results of requests)
  */
-import type { InputAttachmentMeta, LegacyPetWorkspaceOption, LegacyPetWorkDelegation, StreamEvent, TokenUsage, TerminalReason, ApprovalRequest, ApprovalResult, PermissionMode, SessionForkLineage, SessionKind, SessionWorkspace } from "../types.js";
+import type { InputAttachmentMeta, LegacyPetWorkspaceOption, LegacyPetWorkDelegation, StreamEvent, TokenUsage, TerminalReason, ApprovalRequest, ApprovalResult, PermissionMode, SessionForkLineage, SessionKind, SessionProjectBinding, SessionWorkspace } from "../types.js";
 import type { RunBehaviorMode } from "../engine/run-types.js";
 import type { SessionMessageTarget } from "../session/session-message.js";
 export type PendingApprovalKind = "tool_approval" | "ask_user" | "internal";
@@ -69,6 +69,12 @@ export type { InputAttachmentKind, InputAttachmentOrigin, InputAttachmentMeta }
 export interface RunParams {
     sessionId: string;
     task: string;
+    /** Renderer/mobile project hint. Desktop Main resolves it to authoritative roots. */
+    projectId?: string;
+    /** Renderer/mobile root hint. Desktop Main resolves it within projectId. */
+    rootId?: string;
+    /** Trusted host-injected roots. Desktop Main strips any renderer/mobile supplied value. */
+    workspaceContext?: import("../workspace/workspace-context.js").WorkspaceContext;
     /**
      * Optional user-facing representation of `task`. The model still receives
      * the full task, while session feeds and transcript replay show this text.
@@ -273,6 +279,40 @@ export interface SetWorkspaceParams {
     sessionId: string;
     workspace: SessionWorkspace;
 }
+/** Atomically rebind every main-root field through the live Session owner. */
+export interface MigrateSessionMainRootParams {
+    sessionId: string;
+    project: SessionProjectBinding;
+    mainRoot: string;
+    /** Main-resolved target authority used to construct the replacement Engine. */
+    workspaceContext: import("../workspace/workspace-context.js").WorkspaceContext;
+    /** Trust decision for the target main root, resolved by the host trust store. */
+    projectTrusted: boolean;
+    /** Main-minted nonce used to fence and later release a non-resident handoff. */
+    ownershipToken: string;
+}
+/**
+ * Proven ownership result for a Session main-root migration.
+ *
+ * `not-resident` is the only result that authorizes a durable host fallback.
+ * The ownership token fences a concurrent getOrCreate until the host reports
+ * that its atomic disk commit (or failed attempt) has finished.
+ */
+export type MigrateSessionMainRootResult = {
+    status: "migrated";
+    workspace: SessionWorkspace;
+} | {
+    status: "not-resident";
+    ownershipToken: string;
+} | {
+    status: "failed";
+    error: string;
+};
+/** Release the non-resident ownership fence after Main's durable attempt. */
+export interface CompleteSessionMainRootMigrationParams {
+    sessionId: string;
+    ownershipToken: string;
+}
 /** Inject context into a session transcript. */
 export interface InjectParams {
     sessionId: string;
@@ -500,6 +540,10 @@ export declare const Methods: {
     readonly ReleaseWorkspace: "agent/releaseWorkspace";
     /** Persist a workspace pointer through the live session owner. */
     readonly SetWorkspace: "agent/setWorkspace";
+    /** Atomically migrate a Session's main-root authority through its live owner. */
+    readonly MigrateSessionMainRoot: "agent/migrateSessionMainRoot";
+    /** Release a non-resident migration fence after Main's durable attempt. */
+    readonly CompleteSessionMainRootMigration: "agent/completeSessionMainRootMigration";
     /** Extend a running goal's turn/budget ceilings mid-run (TODO 3.1). */
     readonly GoalExtend: "agent/goalExtend";
     /** Edit or pause/resume a session's persisted goal. */

package/dist/protocol/types.js

@@ -46,6 +46,10 @@ export const Methods = {
     ReleaseWorkspace: "agent/releaseWorkspace",
     /** Persist a workspace pointer through the live session owner. */
     SetWorkspace: "agent/setWorkspace",
+    /** Atomically migrate a Session's main-root authority through its live owner. */
+    MigrateSessionMainRoot: "agent/migrateSessionMainRoot",
+    /** Release a non-resident migration fence after Main's durable attempt. */
+    CompleteSessionMainRootMigration: "agent/completeSessionMainRootMigration",
     /** Extend a running goal's turn/budget ceilings mid-run (TODO 3.1). */
     GoalExtend: "agent/goalExtend",
     /** Edit or pause/resume a session's persisted goal. */

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

@@ -118,6 +118,8 @@ export declare class SessionManager {
      * fallback when a worktree is unavailable or is being released.
      */
     readSessionMainRoot(sessionId: string): string | undefined;
+    /** Cheap durable project-binding read; absent for legacy/no-repo Sessions. */
+    readSessionProjectBinding(sessionId: string): import("../types.js").SessionProjectBinding | undefined;
     /** Cheap durable classification read. Legacy sessions are ordinary work sessions. */
     readSessionKind(sessionId: string): SessionKind | undefined;
     /** Cheap durable digital-human binding read. */
@@ -154,6 +156,22 @@ export declare class SessionManager {
      * is a safety pointer and resume breadcrumb.
      */
     setSessionWorkspace(sessionId: string, workspace: SessionWorkspace): number;
+    /**
+     * Commit a Session main-root migration as one state.json replacement.
+     *
+     * `cwd`, the durable project binding, and the execution workspace are one
+     * consistency unit: exposing any subset would let a resumed run combine the
+     * old authority with a new path. Derived availability such as dir_missing is
+     * deliberately absent from this patch and is recomputed by the host.
+     */
+    migrateSessionMainRoot(sessionId: string, project: import("../types.js").SessionProjectBinding, mainRoot: string): number;
+    /**
+     * Commit a host-owned offline migration only if the durable snapshot Main
+     * just revalidated is still current. Unlike the ordinary field-level writer,
+     * this must not retry onto a newer revision: a new writer means ownership is
+     * no longer provably unchanged, so the migration fails closed.
+     */
+    migrateSessionMainRootIfRevision(sessionId: string, project: import("../types.js").SessionProjectBinding, mainRoot: string, expectedStateRevision: number | undefined): number;
     /** Read the durable archival timestamp; undefined = not archived / unprovable. */
     readSessionArchivedAt(sessionId: string): number | undefined;
     /** Set (number) or clear (undefined) the durable archival marker. */

package/dist/session/session-manager.js

@@ -505,6 +505,29 @@ export class SessionManager {
             return undefined;
         }
     }
+    /** Cheap durable project-binding read; absent for legacy/no-repo Sessions. */
+    readSessionProjectBinding(sessionId) {
+        try {
+            assertSafeSessionId(sessionId);
+            const processLocal = this.processLocalBundle(sessionId);
+            const state = processLocal
+                ? processLocal.state
+                : sessionId.startsWith("qchat-")
+                    ? undefined
+                    : JSON.parse(readFileSync(join(this.sessionsDir, sessionId, "state.json"), "utf-8"));
+            const project = state?.project;
+            return project &&
+                typeof project.projectId === "string" &&
+                project.projectId.length > 0 &&
+                typeof project.mainRootId === "string" &&
+                project.mainRootId.length > 0
+                ? { projectId: project.projectId, mainRootId: project.mainRootId }
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
     /** Cheap durable classification read. Legacy sessions are ordinary work sessions. */
     readSessionKind(sessionId) {
         try {
@@ -686,6 +709,70 @@ export class SessionManager {
         }
         return this.updateSessionState(sessionId, { workspace });
     }
+    /**
+     * Commit a Session main-root migration as one state.json replacement.
+     *
+     * `cwd`, the durable project binding, and the execution workspace are one
+     * consistency unit: exposing any subset would let a resumed run combine the
+     * old authority with a new path. Derived availability such as dir_missing is
+     * deliberately absent from this patch and is recomputed by the host.
+     */
+    migrateSessionMainRoot(sessionId, project, mainRoot) {
+        if (!project ||
+            typeof project.projectId !== "string" ||
+            project.projectId.length === 0 ||
+            typeof project.mainRootId !== "string" ||
+            project.mainRootId.length === 0 ||
+            typeof mainRoot !== "string" ||
+            mainRoot.length === 0) {
+            throw new SessionError(`invalid main-root migration for ${sessionId}`);
+        }
+        return this.updateSessionState(sessionId, {
+            project: { ...project },
+            cwd: mainRoot,
+            workspace: { root: mainRoot, kind: "main" },
+        });
+    }
+    /**
+     * Commit a host-owned offline migration only if the durable snapshot Main
+     * just revalidated is still current. Unlike the ordinary field-level writer,
+     * this must not retry onto a newer revision: a new writer means ownership is
+     * no longer provably unchanged, so the migration fails closed.
+     */
+    migrateSessionMainRootIfRevision(sessionId, project, mainRoot, expectedStateRevision) {
+        assertSafeSessionId(sessionId);
+        if (!project ||
+            typeof project.projectId !== "string" ||
+            project.projectId.length === 0 ||
+            typeof project.mainRootId !== "string" ||
+            project.mainRootId.length === 0 ||
+            typeof mainRoot !== "string" ||
+            mainRoot.length === 0) {
+            throw new SessionError(`invalid main-root migration for ${sessionId}`);
+        }
+        const state = this.readPersistedState(sessionId);
+        if (state.stateRevision !== expectedStateRevision) {
+            throw new SessionError(`Session state revision conflict for ${sessionId}`);
+        }
+        Object.assign(state, {
+            project: { ...project },
+            cwd: mainRoot,
+            workspace: { root: mainRoot, kind: "main" },
+        });
+        const result = this.saveStateAttempt(state);
+        if (result.ok)
+            return state.stateRevision;
+        if (result.reason === "generation_conflict") {
+            throw new SessionError(`Session generation conflict for ${sessionId}`);
+        }
+        if (result.reason === "lock_conflict") {
+            throw new SessionError(`Session state lock contention for ${sessionId}`);
+        }
+        if (result.reason === "kind_conflict") {
+            throw new SessionError(`Session kind is immutable for ${sessionId}`);
+        }
+        throw new SessionError(`Session state revision conflict for ${sessionId}`);
+    }
     /** Read the durable archival timestamp; undefined = not archived / unprovable. */
     readSessionArchivedAt(sessionId) {
         try {

package/dist/tool-system/builtin/cron.d.ts

@@ -3,6 +3,7 @@
  */
 import type { ToolDefinition } from "../../types.js";
 import type { ToolContext } from "../context.js";
+import type { CronJob, CreateJobOptions } from "../../automation/scheduler.js";
 export { cronListToolDef } from "./cron-list.definition.js";
 /** Sink notified after a cron job is created/deleted, so the host (Electron
  *  main) can reload+arm the scheduler that actually executes jobs. The worker
@@ -10,6 +11,16 @@ export { cronListToolDef } from "./cron-list.definition.js";
  *  host never learns about an AI-created job until the user opens the UI. */
 type CronChangedSink = () => void;
 export declare function setCronChangedSink(sink: CronChangedSink | null): void;
+export interface CronCreateAuthorityInput extends CreateJobOptions {
+    name: string;
+    schedule: string;
+    prompt: string;
+    /** Current Engine Session, used by Desktop Main as authority even for standalone jobs. */
+    authoritySessionId?: string;
+}
+export type CronCreateAuthority = (input: CronCreateAuthorityInput) => Promise<CronJob>;
+/** Desktop installs a Main-process delegate; other hosts keep the local scheduler path. */
+export declare function setCronCreateAuthority(authority: CronCreateAuthority | null): void;
 export declare const cronCreateToolDef: ToolDefinition;
 export declare function cronCreateTool(args: Record<string, unknown>, context?: ToolContext): Promise<string>;
 export declare const cronDeleteToolDef: ToolDefinition;