@cjhyy/code-shell-core 0.8.20 → 0.9.0

package/dist/tool-system/builtin/cron.js

@@ -17,6 +17,11 @@ function fireCronChanged() {
         // Notifying the host is best-effort; never break the tool on it.
     }
 }
+let cronCreateAuthority = null;
+/** Desktop installs a Main-process delegate; other hosts keep the local scheduler path. */
+export function setCronCreateAuthority(authority) {
+    cronCreateAuthority = authority;
+}
 export const cronCreateToolDef = {
     name: "CronCreate",
     description: "Create a scheduled automation job that runs a prompt on a recurring schedule. " +
@@ -125,15 +130,33 @@ export async function cronCreateTool(args, context) {
     // time (the model never supplies it — getCurrentSid() reads the running
     // Engine's ALS context). Empty/unknown sid → treat as standalone.
     const resumeSessionId = args.continueInSession === true && getCurrentSid() ? getCurrentSid() : undefined;
+    const stableWorkspace = context?.workspace && !context.workspace.projectId.startsWith("legacy-")
+        ? {
+            projectId: context.workspace.projectId,
+            rootId: context.workspace.sessionMainRootId,
+        }
+        : undefined;
     let job;
     try {
-        job = cronScheduler.create(name, schedule, prompt, {
+        const createInput = {
+            name,
+            schedule,
+            prompt,
             ...(timezone !== undefined ? { timezone } : {}),
             ...(cwd !== undefined ? { cwd } : {}),
+            ...(stableWorkspace ?? {}),
             ...(permissionLevel !== undefined ? { permissionLevel } : {}),
             ...(once ? { once: true } : {}),
             ...(resumeSessionId !== undefined ? { resumeSessionId } : {}),
-        });
+            ...(getCurrentSid() ? { authoritySessionId: getCurrentSid() } : {}),
+        };
+        if (cronCreateAuthority) {
+            job = await cronCreateAuthority(createInput);
+        }
+        else {
+            const { name: _name, schedule: _schedule, prompt: _prompt, authoritySessionId: _authoritySessionId, ...createOptions } = createInput;
+            job = cronScheduler.create(name, schedule, prompt, createOptions);
+        }
     }
     catch (err) {
         return `Error: ${err instanceof Error ? err.message : String(err)}`;
@@ -162,12 +185,14 @@ export async function cronDeleteTool(args) {
     const id = args.jobId;
     if (!id)
         return "Error: jobId is required";
+    cronScheduler.loadJobs({ arm: false });
     const deleted = cronScheduler.delete(id);
     if (deleted)
         fireCronChanged();
     return deleted ? `Cron job #${id} deleted.` : `Cron job #${id} not found.`;
 }
 export async function cronListTool(_args) {
+    cronScheduler.loadJobs({ arm: false });
     const jobs = cronScheduler.list();
     if (jobs.length === 0)
         return "No cron jobs scheduled.";

package/dist/tool-system/builtin/edit.js

@@ -51,8 +51,10 @@ export async function editTool(args, ctx) {
     if (!existsSync(filePath))
         return `Error: File not found: ${filePath}`;
     try {
-        const approvedPath = getFinalWritePathSnapshot(args, filePath, cwd);
-        const beforeRead = revalidateFinalWritePath(filePath, cwd, approvedPath);
+        const roots = ctx?.workspace?.roots.map((root) => root.path);
+        const digest = ctx?.workspace?.rootsDigest;
+        const approvedPath = getFinalWritePathSnapshot(args, filePath, cwd, roots, digest);
+        const beforeRead = revalidateFinalWritePath(filePath, cwd, approvedPath, roots, digest);
         if ("error" in beforeRead)
             return { ok: false, error: beforeRead.error };
         const raw = await readFile(beforeRead.resolvedPath, "utf-8");
@@ -75,7 +77,7 @@ export async function editTool(args, ctx) {
             }
         }
         const updatedLf = replaceAll ? content.split(oldLf).join(newLf) : content.replace(oldLf, newLf);
-        const beforeWrite = revalidateFinalWritePath(filePath, cwd, approvedPath);
+        const beforeWrite = revalidateFinalWritePath(filePath, cwd, approvedPath, roots, digest);
         if ("error" in beforeWrite)
             return { ok: false, error: beforeWrite.error };
         await writeFileNoFollow(beforeWrite.resolvedPath, applyEol(updatedLf, eol));

package/dist/tool-system/builtin/write.js

@@ -28,14 +28,16 @@ export async function writeTool(args, ctx) {
     const cwd = ctx?.cwd ?? process.cwd();
     const filePath = isAbsolute(rawPath) ? rawPath : resolve(cwd, rawPath);
     try {
-        const approvedPath = getFinalWritePathSnapshot(args, filePath, cwd);
-        const beforeMkdir = revalidateFinalWritePath(filePath, cwd, approvedPath);
+        const roots = ctx?.workspace?.roots.map((root) => root.path);
+        const digest = ctx?.workspace?.rootsDigest;
+        const approvedPath = getFinalWritePathSnapshot(args, filePath, cwd, roots, digest);
+        const beforeMkdir = revalidateFinalWritePath(filePath, cwd, approvedPath, roots, digest);
         if ("error" in beforeMkdir)
             return { ok: false, error: beforeMkdir.error };
         await mkdir(dirname(beforeMkdir.resolvedPath), { recursive: true });
         // mkdir may have crossed an existing symlink in a missing parent chain;
         // resolve again immediately before opening the final file.
-        const beforeWrite = revalidateFinalWritePath(filePath, cwd, approvedPath);
+        const beforeWrite = revalidateFinalWritePath(filePath, cwd, approvedPath, roots, digest);
         if ("error" in beforeWrite)
             return { ok: false, error: beforeWrite.error };
         await writeFileNoFollow(beforeWrite.resolvedPath, content);

package/dist/tool-system/context.d.ts

@@ -189,6 +189,7 @@ export interface SubAgentSpawnResult {
  */
 export interface ToolVisibilityContext {
     cwd: string;
+    workspace?: import("../workspace/workspace-context.js").WorkspaceContext;
     hasGoal: boolean;
     /** Resolved Session identity for per-session extension-tool visibility. */
     sessionId?: string;
@@ -462,7 +463,9 @@ export interface ToolContext {
      * switcher. Undefined outside hosts that can switch this conversation's
      * session workspace.
      */
-    workspace?: import("./workspace-bridge.js").WorkspaceBridge;
+    workspaceBridge?: import("./workspace-bridge.js").WorkspaceBridge;
+    /** Immutable roots authorized for this run. */
+    workspace?: import("../workspace/workspace-context.js").WorkspaceContext;
     /** Host panel discovery/focus bridge. Undefined in non-Desktop/headless engines. */
     panels?: import("./panel-bridge.js").PanelHostBridge;
     /**

package/dist/tool-system/executor.js

@@ -319,7 +319,7 @@ export class ToolExecutor {
             const target = isAbsolutePath(raw) ? raw : resolvePath(this.toolCtx.cwd, raw);
             call = {
                 ...call,
-                args: attachFinalWritePathSnapshot(call.args, target, this.toolCtx.cwd),
+                args: attachFinalWritePathSnapshot(call.args, target, this.toolCtx.cwd, this.toolCtx.workspace?.roots.map((root) => root.path), this.toolCtx.workspace?.rootsDigest),
             };
         }
         const pathPolicyError = await this.enforceDeclaredPathPolicy(toolDef, call.args);

package/dist/tool-system/path-policy.d.ts

@@ -42,10 +42,14 @@ export interface PathClassification {
     reason: string;
     /** Resolved absolute path (with symlinks followed when possible). */
     resolvedPath: string;
+    /** Canonical workspace root containing resolvedPath, when one matched. */
+    matchedRoot?: string;
 }
 export interface ClassifyOptions {
     /** Absolute path of the active workspace (Engine.cwd). */
     workspaceRoot: string;
+    /** Complete authorized root set. Omitted preserves legacy single-root behavior. */
+    workspaceRoots?: readonly string[];
     /** "read" or "write" — different defaults for sensitive paths. */
     operation: PathOperation;
 }
@@ -53,20 +57,24 @@ export interface FinalWritePathSnapshot {
     resolvedPath: string;
     workspacePath: string;
     insideWorkspace: boolean;
+    matchedRoot?: string;
+    rootsDigest?: string;
 }
 export type PathApprovalScope = "once" | "session" | "project";
 /** Test seam: clear the in-memory session grants. */
 export declare function _resetSessionPathGrants(): void;
 export declare function openSessionPathApprovals(sessionId: string): void;
 export declare function clearSessionPathApprovals(sessionId: string): void;
+/** Revoke only grants that point into a root removed from a live project. */
+export declare function clearSessionPathApprovalsUnderRoot(sessionId: string, root: string): void;
 /**
  * Capture the concrete target approved by the executor's first path-policy
  * pass. The snapshot is carried on the internal args object via a symbol, so
  * it cannot collide with an LLM-supplied schema property or leak into logs.
  */
-export declare function attachFinalWritePathSnapshot(args: Record<string, unknown>, filePath: string, workspaceRoot: string): Record<string, unknown>;
-export declare function getFinalWritePathSnapshot(args: Record<string, unknown>, filePath: string, workspaceRoot: string): FinalWritePathSnapshot;
-export declare function revalidateFinalWritePath(filePath: string, workspaceRoot: string, approved: FinalWritePathSnapshot): {
+export declare function attachFinalWritePathSnapshot(args: Record<string, unknown>, filePath: string, workspaceRoot: string, workspaceRoots?: readonly string[], rootsDigest?: string): Record<string, unknown>;
+export declare function getFinalWritePathSnapshot(args: Record<string, unknown>, filePath: string, workspaceRoot: string, workspaceRoots?: readonly string[], rootsDigest?: string): FinalWritePathSnapshot;
+export declare function revalidateFinalWritePath(filePath: string, workspaceRoot: string, approved: FinalWritePathSnapshot, workspaceRoots?: readonly string[], rootsDigest?: string): {
     resolvedPath: string;
 } | {
     error: string;

package/dist/tool-system/path-policy.js

@@ -33,8 +33,9 @@ import { constants, realpathSync, existsSync, readFileSync, writeFileSync, mkdir
 import { open } from "node:fs/promises";
 import { homedir } from "node:os";
 import { randomUUID } from "node:crypto";
-import { dirname, isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path";
+import { dirname, join, relative, sep } from "node:path";
 import { readInstalledPlugins } from "../plugins/installedPlugins.js";
+import { canonicalPath } from "../workspace/canonical-key.js";
 const FINAL_WRITE_PATH_SNAPSHOT = Symbol("codeshell.finalWritePathSnapshot");
 /**
  * Default sensitive path patterns. These are evaluated AFTER home-expansion
@@ -291,6 +292,20 @@ export function clearSessionPathApprovals(sessionId) {
     closedPathApprovalSessions.add(sessionId);
     askChains.delete(sessionId);
 }
+/** Revoke only grants that point into a root removed from a live project. */
+export function clearSessionPathApprovalsUnderRoot(sessionId, root) {
+    const grants = sessionPathGrants.get(sessionId);
+    if (!grants)
+        return;
+    const canonicalRoot = safeRealpath(root);
+    for (const grant of [...grants]) {
+        const grantPath = safeRealpath(grant.prefix);
+        if (isInsideDir(grantPath, canonicalRoot))
+            grants.delete(grant);
+    }
+    if (grants.size === 0)
+        sessionPathGrants.delete(sessionId);
+}
 /**
  * Best-effort resolution. realpath fails when the path doesn't exist yet —
  * the common case for Write creating a new file. We walk up to the nearest
@@ -303,47 +318,28 @@ export function clearSessionPathApprovals(sessionId) {
  * would be misclassified as outside-workspace.
  */
 function safeRealpath(p) {
-    const abs = isAbsolute(p) ? p : resolvePath(process.cwd(), p);
-    // Walk up to the nearest existing ancestor.
-    let candidate = abs;
-    const segments = [];
-    // Cap the walk so a pathological input can't spin forever.
-    for (let i = 0; i < 64; i++) {
-        try {
-            const resolved = realpathSync(candidate);
-            if (segments.length === 0)
-                return resolved;
-            return resolvePath(resolved, ...segments.reverse());
-        }
-        catch {
-            const parent = dirname(candidate);
-            if (parent === candidate) {
-                // Reached root without finding anything that exists — return the
-                // original absolute form so the caller still has a usable path.
-                return abs;
-            }
-            segments.push(candidate.slice(parent.length + (parent.endsWith(sep) ? 0 : 1)));
-            candidate = parent;
-        }
-    }
-    return abs;
+    return canonicalPath(p);
 }
 /**
  * Capture the concrete target approved by the executor's first path-policy
  * pass. The snapshot is carried on the internal args object via a symbol, so
  * it cannot collide with an LLM-supplied schema property or leak into logs.
  */
-export function attachFinalWritePathSnapshot(args, filePath, workspaceRoot) {
+export function attachFinalWritePathSnapshot(args, filePath, workspaceRoot, workspaceRoots, rootsDigest) {
     const resolvedPath = safeRealpath(filePath);
     const workspacePath = safeRealpath(workspaceRoot);
+    const roots = (workspaceRoots?.length ? workspaceRoots : [workspaceRoot]).map(safeRealpath);
+    const matchedRoot = roots.find((root) => isInsideDir(resolvedPath, root));
     const snapshot = {
         resolvedPath,
         workspacePath,
-        insideWorkspace: isInsideDir(resolvedPath, workspacePath),
+        insideWorkspace: matchedRoot !== undefined,
+        matchedRoot,
+        rootsDigest,
     };
     return { ...args, [FINAL_WRITE_PATH_SNAPSHOT]: snapshot };
 }
-export function getFinalWritePathSnapshot(args, filePath, workspaceRoot) {
+export function getFinalWritePathSnapshot(args, filePath, workspaceRoot, workspaceRoots, rootsDigest) {
     const carried = args[FINAL_WRITE_PATH_SNAPSHOT];
     if (carried && typeof carried === "object") {
         return carried;
@@ -353,19 +349,32 @@ export function getFinalWritePathSnapshot(args, filePath, workspaceRoot) {
     // read-to-write interval with a second check before its writeFile.
     const resolvedPath = safeRealpath(filePath);
     const workspacePath = safeRealpath(workspaceRoot);
+    const roots = (workspaceRoots?.length ? workspaceRoots : [workspaceRoot]).map(safeRealpath);
+    const matchedRoot = roots.find((root) => isInsideDir(resolvedPath, root));
     return {
         resolvedPath,
         workspacePath,
-        insideWorkspace: isInsideDir(resolvedPath, workspacePath),
+        insideWorkspace: matchedRoot !== undefined,
+        matchedRoot,
+        rootsDigest,
     };
 }
-export function revalidateFinalWritePath(filePath, workspaceRoot, approved) {
+export function revalidateFinalWritePath(filePath, workspaceRoot, approved, workspaceRoots, rootsDigest) {
     const currentPath = safeRealpath(filePath);
     const currentWorkspace = safeRealpath(workspaceRoot);
     const sameTarget = normPath(currentPath) === normPath(approved.resolvedPath);
     const sameWorkspace = normPath(currentWorkspace) === normPath(approved.workspacePath);
-    const crossedWorkspaceBoundary = approved.insideWorkspace && !isInsideDir(currentPath, currentWorkspace);
-    if (crossedWorkspaceBoundary || !sameTarget || !sameWorkspace) {
+    const currentRoots = (workspaceRoots?.length ? workspaceRoots : [workspaceRoot]).map(safeRealpath);
+    const currentMatchedRoot = currentRoots.find((root) => isInsideDir(currentPath, root));
+    const crossedWorkspaceBoundary = approved.insideWorkspace && currentMatchedRoot === undefined;
+    const changedMatchedRoot = approved.matchedRoot !== undefined &&
+        normPath(currentMatchedRoot ?? "") !== normPath(approved.matchedRoot);
+    const changedRootsDigest = approved.rootsDigest !== undefined && rootsDigest !== approved.rootsDigest;
+    if (crossedWorkspaceBoundary ||
+        changedMatchedRoot ||
+        changedRootsDigest ||
+        !sameTarget ||
+        !sameWorkspace) {
         const reason = crossedWorkspaceBoundary
             ? "final write path resolved outside the workspace after approval"
             : "final write path changed after approval";
@@ -620,11 +629,13 @@ export function classifyPath(rawPath, opts) {
     }
     const expanded = expandTilde(rawPath);
     const resolved = safeRealpath(expanded);
-    const workspace = safeRealpath(opts.workspaceRoot);
+    const workspaceRoots = opts.workspaceRoots?.length ? opts.workspaceRoots : [opts.workspaceRoot];
+    const workspaces = workspaceRoots.map((root) => safeRealpath(root));
     const sensitiveDir = matchSensitiveDir(resolved);
     const sensitiveFile = matchSensitiveFile(resolved);
     const sensitiveLabel = sensitiveDir ?? sensitiveFile;
-    const insideWorkspace = isInsideDir(resolved, workspace);
+    const matchedRoot = workspaces.find((workspace) => isInsideDir(resolved, workspace));
+    const insideWorkspace = matchedRoot !== undefined;
     // Registered Skill resources are managed runtime inputs. Their SKILL.md is
     // already readable through the Skill builtin; allow its contained reference
     // files through the ordinary Read tool as well. A credential-shaped basename
@@ -675,7 +686,12 @@ export function classifyPath(rawPath, opts) {
         };
     }
     if (insideWorkspace) {
-        return { decision: "allow", reason: "inside workspace", resolvedPath: resolved };
+        return {
+            decision: "allow",
+            reason: "inside workspace",
+            resolvedPath: resolved,
+            matchedRoot,
+        };
     }
     // Outside workspace: ask for both read and write. The conservative bias
     // matches the plan's leaning answer to Q1 — ask on sensitive reads, deny
@@ -732,7 +748,11 @@ export async function enforcePathPolicyWithApproval(filePath, operation, ctx) {
     // who chose full access still got prompted for project-external reads.
     if (ctx.permissionMode === "bypassPermissions")
         return null;
-    const c = classifyPath(filePath, { workspaceRoot: ctx.cwd, operation });
+    const c = classifyPath(filePath, {
+        workspaceRoot: ctx.cwd,
+        workspaceRoots: ctx.workspace?.roots.map((root) => root.path),
+        operation,
+    });
     if (c.decision === "allow")
         return null;
     if (c.decision === "deny") {

package/dist/types.d.ts

@@ -188,6 +188,10 @@ export interface SessionWorkspace {
         createdBy: "codeshell";
     };
 }
+export interface SessionProjectBinding {
+    projectId: string;
+    mainRootId: string;
+}
 export interface ContextUsageAnchor {
     promptTokens: number;
     messageCount: number;
@@ -231,6 +235,8 @@ export interface SessionState {
     cwd: string;
     /** Current main/worktree execution pointer. Absent only on legacy state.json files. */
     workspace?: SessionWorkspace;
+    /** Stable Desktop project identity. Absent on legacy/no-repo sessions. */
+    project?: SessionProjectBinding;
     startedAt: number;
     model: string;
     provider: string;

package/dist/workspace/canonical-key.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Resolve a path through symlinks without requiring the leaf to exist.
+ * Missing suffixes are appended to the nearest existing realpathed ancestor.
+ */
+export declare function canonicalPath(input: string): string;
+/** Stable comparison key for project roots and workspace containment decisions. */
+export declare function canonicalKey(input: string): string;

package/dist/workspace/canonical-key.js

@@ -0,0 +1,39 @@
+import { realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, parse, resolve } from "node:path";
+const CASE_INSENSITIVE_PLATFORM = process.platform === "darwin" || process.platform === "win32";
+/**
+ * Resolve a path through symlinks without requiring the leaf to exist.
+ * Missing suffixes are appended to the nearest existing realpathed ancestor.
+ */
+export function canonicalPath(input) {
+    const absolute = isAbsolute(input) ? resolve(input) : resolve(process.cwd(), input);
+    let candidate = absolute;
+    const suffix = [];
+    for (let depth = 0; depth < 64; depth += 1) {
+        try {
+            const existing = realpathSync(candidate);
+            const joined = suffix.length > 0 ? resolve(existing, ...suffix) : resolve(existing);
+            return trimTrailingSeparators(joined);
+        }
+        catch {
+            const parent = dirname(candidate);
+            if (parent === candidate)
+                return trimTrailingSeparators(absolute);
+            suffix.unshift(basename(candidate));
+            candidate = parent;
+        }
+    }
+    return trimTrailingSeparators(absolute);
+}
+/** Stable comparison key for project roots and workspace containment decisions. */
+export function canonicalKey(input) {
+    const normalized = canonicalPath(input);
+    return CASE_INSENSITIVE_PLATFORM ? normalized.toLocaleLowerCase("en-US") : normalized;
+}
+function trimTrailingSeparators(input) {
+    const root = parse(input).root;
+    let end = input.length;
+    while (end > root.length && (input[end - 1] === "/" || input[end - 1] === "\\"))
+        end -= 1;
+    return input.slice(0, end);
+}

package/dist/workspace/workspace-context.d.ts

@@ -0,0 +1,26 @@
+import { canonicalKey, canonicalPath } from "./canonical-key.js";
+export { canonicalKey, canonicalPath };
+export type ProjectId = string;
+export type ProjectRootId = string;
+export interface ProjectRootContext {
+    id: ProjectRootId;
+    path: string;
+    role: "primary" | "secondary";
+}
+export interface WorkspaceContext {
+    version: 1;
+    projectId: ProjectId;
+    projectRevision: number;
+    sessionMainRootId: ProjectRootId;
+    roots: ProjectRootContext[];
+    rootsDigest: string;
+}
+export type WorkspaceContextInput = Omit<WorkspaceContext, "version" | "rootsDigest">;
+export declare function computeWorkspaceRootsDigest(roots: readonly ProjectRootContext[]): string;
+export declare function createWorkspaceContext(input: WorkspaceContextInput): WorkspaceContext;
+export declare function validateWorkspaceContext(value: unknown): WorkspaceContext;
+/** Compatibility context for callers that only possess one cwd. It is never persisted as a binding. */
+export declare function legacySingleRootWorkspace(cwd: string): WorkspaceContext;
+export declare function workspacePrimaryRoot(context: WorkspaceContext): ProjectRootContext;
+/** Paths present in the previous run-scoped root set but absent from the next one. */
+export declare function removedWorkspaceRootPaths(previous: Pick<WorkspaceContext, "roots">, next: Pick<WorkspaceContext, "roots">): string[];

package/dist/workspace/workspace-context.js

@@ -0,0 +1,112 @@
+import { createHash } from "node:crypto";
+import { isAbsolute, relative, sep } from "node:path";
+import { canonicalKey, canonicalPath } from "./canonical-key.js";
+export { canonicalKey, canonicalPath };
+function requireIdentifier(value, label) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 512) {
+        throw new Error(`invalid WorkspaceContext ${label}`);
+    }
+    return value;
+}
+function containsPath(parent, child) {
+    if (parent === child)
+        return true;
+    const rel = relative(parent, child);
+    return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+export function computeWorkspaceRootsDigest(roots) {
+    const keys = roots.map((root) => canonicalKey(root.path)).sort();
+    return createHash("sha256").update(keys.join("\0"), "utf8").digest("hex");
+}
+function validateRoots(roots, sessionMainRootId) {
+    if (roots.length === 0 || roots.length > 256) {
+        throw new Error("WorkspaceContext roots must contain between 1 and 256 entries");
+    }
+    const ids = new Set();
+    const normalized = roots.map((root, index) => {
+        if (!root || typeof root !== "object") {
+            throw new Error(`invalid WorkspaceContext root at index ${index}`);
+        }
+        const id = requireIdentifier(root.id, `roots[${index}].id`);
+        if (ids.has(id))
+            throw new Error(`duplicate root id: ${id}`);
+        ids.add(id);
+        if (typeof root.path !== "string" || root.path.length === 0 || root.path.length > 16_384) {
+            throw new Error(`invalid WorkspaceContext roots[${index}].path`);
+        }
+        if (!isAbsolute(root.path)) {
+            throw new Error(`WorkspaceContext root path must be absolute: ${root.path}`);
+        }
+        if (root.role !== "primary" && root.role !== "secondary") {
+            throw new Error(`invalid WorkspaceContext roots[${index}].role`);
+        }
+        return { id, path: root.path, role: root.role };
+    });
+    const primary = normalized.filter((root) => root.role === "primary");
+    if (primary.length !== 1 || primary[0]?.id !== sessionMainRootId) {
+        throw new Error("WorkspaceContext must have exactly one primary matching sessionMainRootId");
+    }
+    const keys = normalized.map((root) => canonicalKey(root.path));
+    for (let left = 0; left < keys.length; left += 1) {
+        for (let right = left + 1; right < keys.length; right += 1) {
+            if (containsPath(keys[left], keys[right]) || containsPath(keys[right], keys[left])) {
+                throw new Error(`WorkspaceContext roots overlap: ${normalized[left].path} and ${normalized[right].path}`);
+            }
+        }
+    }
+    return normalized;
+}
+export function createWorkspaceContext(input) {
+    const projectId = requireIdentifier(input.projectId, "projectId");
+    const sessionMainRootId = requireIdentifier(input.sessionMainRootId, "sessionMainRootId");
+    if (!Number.isSafeInteger(input.projectRevision) || input.projectRevision < 1) {
+        throw new Error("invalid WorkspaceContext projectRevision");
+    }
+    const roots = validateRoots(input.roots, sessionMainRootId);
+    return {
+        version: 1,
+        projectId,
+        projectRevision: input.projectRevision,
+        sessionMainRootId,
+        roots,
+        rootsDigest: computeWorkspaceRootsDigest(roots),
+    };
+}
+export function validateWorkspaceContext(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("invalid WorkspaceContext");
+    const candidate = value;
+    if (candidate.version !== 1)
+        throw new Error("invalid WorkspaceContext version");
+    const created = createWorkspaceContext({
+        projectId: candidate.projectId,
+        projectRevision: candidate.projectRevision,
+        sessionMainRootId: candidate.sessionMainRootId,
+        roots: candidate.roots,
+    });
+    if (candidate.rootsDigest !== created.rootsDigest) {
+        throw new Error("WorkspaceContext rootsDigest does not match roots");
+    }
+    return created;
+}
+/** Compatibility context for callers that only possess one cwd. It is never persisted as a binding. */
+export function legacySingleRootWorkspace(cwd) {
+    const path = canonicalPath(cwd);
+    const keyDigest = createHash("sha256").update(canonicalKey(path), "utf8").digest("hex");
+    return createWorkspaceContext({
+        projectId: `legacy-${keyDigest}`,
+        projectRevision: 1,
+        sessionMainRootId: "legacy-root",
+        roots: [{ id: "legacy-root", path, role: "primary" }],
+    });
+}
+export function workspacePrimaryRoot(context) {
+    return context.roots.find((root) => root.id === context.sessionMainRootId);
+}
+/** Paths present in the previous run-scoped root set but absent from the next one. */
+export function removedWorkspaceRootPaths(previous, next) {
+    const nextKeys = new Set(next.roots.map((root) => canonicalKey(root.path)));
+    return previous.roots
+        .filter((root) => !nextKeys.has(canonicalKey(root.path)))
+        .map((root) => root.path);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cjhyy/code-shell-core",
-  "version": "0.8.20",
+  "version": "0.9.0",
   "description": "Core engine for code-shell — agent orchestration, tool execution, hooks, protocol. UI-agnostic.",
   "type": "module",
   "main": "./dist/index.js",