@cjhyy/code-shell-core 0.6.0-rc.13 → 0.6.0-rc.15

package/dist/engine/engine.js

@@ -42,12 +42,12 @@ import { MCPManager } from "../tool-system/mcp-manager.js";
 import { SettingsManager, userHome } from "../settings/manager.js";
 import { CredentialStore } from "../credentials/store.js";
 import { isFeatureEnabled, resolveFeatureFlags, } from "../settings/feature-flags.js";
-import { effectiveDisabledList, effectiveBuiltinLists, } from "../capability-control/overlay.js";
+import { effectiveDisabledList, effectiveBuiltinLists } from "../capability-control/overlay.js";
 import { computeEffectiveDisabledLists } from "../capability-control/disabled-lists.js";
 import { FileHistory } from "../session/file-history.js";
 import { patchBackupTargets } from "../tool-system/builtin/apply-patch/backup-targets.js";
 import { resolveSandboxBackend, } from "../tool-system/sandbox/index.js";
-import { resolveAgentPreset, resolveBuiltinToolNames, } from "../preset/index.js";
+import { resolveAgentPreset, resolveBuiltinToolNames } from "../preset/index.js";
 import { ModelPool } from "../llm/model-pool.js";
 import { AgentDefinitionRegistry } from "../agent/agent-definition-registry.js";
 import { defaultCacheDir } from "../llm/model-cache.js";
@@ -445,6 +445,7 @@ export class Engine {
                 new ToolRegistry({
                     builtinTools: resolveBuiltinToolNames({
                         preset: this.preset.name,
+                        host: config.builtinToolHost,
                         enabledBuiltinTools: builtinLists.enabledBuiltinTools,
                         disabledBuiltinTools: builtinLists.disabledBuiltinTools,
                     }),
@@ -635,6 +636,10 @@ export class Engine {
     setBrowserBridge(bridge) {
         this.config.browserBridge = bridge;
     }
+    /** Inject the host-backed workspace bridge after construction. */
+    setWorkspaceBridge(bridge) {
+        this.config.workspaceBridge = bridge;
+    }
     /**
      * Queue a user message to be spliced into the in-flight run for `sessionId`
      * at the next turn-loop step boundary — the 不打断 steering path (vs cancel +
@@ -736,7 +741,7 @@ export class Engine {
      */
     async run(task, options) {
         const workspaceResume = options?.sessionId && this.sessionManager.exists(options.sessionId)
-            ? this.sessionManager.resolveSessionWorkspaceForResume(options.sessionId)
+            ? await this.sessionManager.resolveSessionWorkspaceForResume(options.sessionId)
             : undefined;
         if (workspaceResume && !workspaceResume.ok) {
             return {
@@ -971,6 +976,7 @@ export class Engine {
                     preset: this.preset.name,
                     enabledBuiltinTools: childEnabled,
                     disabledBuiltinTools: childDisabled,
+                    builtinToolHost: this.config.builtinToolHost,
                     customSystemPrompt: this.config.customSystemPrompt,
                     appendSystemPrompt: [this.config.appendSystemPrompt, req.appendSystemPrompt].filter(Boolean).join("\n\n") ||
                         undefined,
@@ -1311,6 +1317,24 @@ export class Engine {
                     messages[lastIdx] = { role: "user", content: promptSubmitHook.updatedPrompt };
                 }
             }
+            const contextManager = new ContextManager({
+                maxTokens: this.resolveMaxContextTokens(),
+                // Drop undefined fields so they don't clobber ContextManager defaults
+                // (spread of `{x: undefined}` would override the default with undefined).
+                ...Object.fromEntries(Object.entries(this.resolveContextRatios()).filter(([, v]) => v !== undefined)),
+            });
+            this.lastContextManager = contextManager;
+            const persistedContextAnchor = session.state.contextUsageAnchor;
+            const contextAnchorCompatible = persistedContextAnchor !== undefined &&
+                (persistedContextAnchor.provider === undefined ||
+                    persistedContextAnchor.provider === this.config.llm.provider) &&
+                (persistedContextAnchor.model === undefined ||
+                    persistedContextAnchor.model === this.config.llm.model) &&
+                (persistedContextAnchor.messageCount <= messages.length ||
+                    persistedContextAnchor.estimateAtAnchor !== undefined);
+            const seededContextAnchor = contextAnchorCompatible
+                ? contextManager.seedActualUsage(persistedContextAnchor)
+                : undefined;
             // Rough token estimate of the full prompt so the UI's ctx bar isn't 0%
             // before the first real usage_update arrives. The authoritative count
             // comes from `usage.promptTokens` after the first LLM response — this is
@@ -1322,10 +1346,12 @@ export class Engine {
             const sid = session.state.sessionId;
             const needsCtxSeed = !this.ctxSeedSent.has(sid);
             const roughPromptTokens = needsCtxSeed
-                ? messages.reduce((sum, m) => {
-                    const text = typeof m.content === "string" ? m.content : JSON.stringify(m.content);
-                    return sum + Math.ceil(text.length / 4);
-                }, 0)
+                ? seededContextAnchor
+                    ? contextManager.checkLimits(messages).tokens
+                    : messages.reduce((sum, m) => {
+                        const text = typeof m.content === "string" ? m.content : JSON.stringify(m.content);
+                        return sum + Math.ceil(text.length / 4);
+                    }, 0)
                 : 0;
             if (needsCtxSeed)
                 this.ctxSeedSent.add(sid);
@@ -1383,13 +1409,6 @@ export class Engine {
             // Wire abort signal for cascading cancellation + per-Engine ToolContext
             toolExecutor.setSignal(options?.signal);
             toolExecutor.setContext(toolCtx);
-            const contextManager = new ContextManager({
-                maxTokens: this.resolveMaxContextTokens(),
-                // Drop undefined fields so they don't clobber ContextManager defaults
-                // (spread of `{x: undefined}` would override the default with undefined).
-                ...Object.fromEntries(Object.entries(this.resolveContextRatios()).filter(([, v]) => v !== undefined)),
-            });
-            this.lastContextManager = contextManager;
             const { disabledSkills, disabledPlugins } = this.readDisabledLists();
             const promptComposer = new PromptComposer({
                 cwd,
@@ -1451,6 +1470,7 @@ export class Engine {
                     (normalizeGoal(options?.goal) !== undefined ||
                         session.state.activeGoal !== undefined ||
                         normalizeGoal(this.config.goal) !== undefined),
+                settingsScope: this.config.settingsScope ?? "project",
             };
             toolCtx.toolVisibility = toolVisibility;
             // #7: per-turn project builtin override. The toolRegistry's builtin tool
@@ -1761,6 +1781,13 @@ export class Engine {
                 consumeSteer: (source) => this.consumeSteer(sid, source),
                 claimClientMessageId: (clientMessageId, source) => claimClientMessageId(session, clientMessageId, source),
                 recordCumulativeUsage,
+                recordContextUsageAnchor: (anchor) => {
+                    session.state.contextUsageAnchor = {
+                        ...anchor,
+                        provider: this.config.llm.provider,
+                        model: this.config.llm.model,
+                    };
+                },
                 // Clear the persisted goal for a self-reported completion / confirmed
                 // cancel. Clears the in-RAM session's activeGoal (so THIS run's later
                 // turns don't re-arm) AND persists it, and drops the in-flight stop
@@ -2359,7 +2386,6 @@ export class Engine {
     refreshRuntimeConfig(patch, version) {
         if (version <= this.lastAppliedConfigVersion)
             return;
-        const prevServers = this.config.mcpServers ?? {};
         const prevPresetName = this.preset.name;
         this.config = { ...this.config, ...patch };
         // #2: re-resolve the prompt-affecting preset so the next-turn PromptComposer
@@ -2370,11 +2396,17 @@ export class Engine {
             // The builtin tool SET is ctor-frozen and may be shared via runtime — we
             // do NOT rebuild it here. If the new preset implies a different builtin
             // tool set, that part of the change only lands on session restart.
-            const prevTools = resolveBuiltinToolNames({ preset: prevPresetName })
+            const prevTools = resolveBuiltinToolNames({
+                preset: prevPresetName,
+                host: this.config.builtinToolHost,
+            })
                 .slice()
                 .sort()
                 .join(",");
-            const nextTools = resolveBuiltinToolNames({ preset: nextPreset.name })
+            const nextTools = resolveBuiltinToolNames({
+                preset: nextPreset.name,
+                host: this.config.builtinToolHost,
+            })
                 .slice()
                 .sort()
                 .join(",");
@@ -2461,6 +2493,41 @@ export class Engine {
         }
         return had;
     }
+    /**
+     * Reset a session's workspace pointer back to its main root. If the session is
+     * actively running, mutate that live SessionBundle first so the run's next
+     * saveState cannot resurrect a stale worktree pointer.
+     */
+    releaseSessionWorkspace(sessionId) {
+        if (!sessionId || !this.sessionManager.exists(sessionId))
+            return null;
+        const mainRoot = this.sessionManager.readCwd(sessionId) ??
+            (this.activeRunSession?.state.sessionId === sessionId
+                ? this.activeRunSession.state.cwd
+                : undefined);
+        if (!mainRoot)
+            return null;
+        const workspace = { root: mainRoot, kind: "main" };
+        if (this.activeRunSession?.state.sessionId === sessionId) {
+            this.activeRunSession.state.workspace = workspace;
+        }
+        try {
+            const bundle = this.activeRunSession?.state.sessionId === sessionId
+                ? this.activeRunSession
+                : this.sessionManager.resume(sessionId);
+            bundle.state.workspace = workspace;
+            this.sessionManager.saveState(bundle.state);
+        }
+        catch {
+            try {
+                this.sessionManager.setSessionWorkspace(sessionId, workspace);
+            }
+            catch {
+                return null;
+            }
+        }
+        return workspace;
+    }
     injectContext(sessionId, content) {
         const session = this.sessionManager.resume(sessionId);
         session.transcript.appendMessage("assistant", content);
@@ -2954,6 +3021,17 @@ export class Engine {
             return undefined;
         }
     }
+    readWorktreeBranchPrefix(cwd) {
+        if (this.config.isSubAgent === true || !cwd)
+            return undefined;
+        try {
+            const settings = this.getSettingsManager().get();
+            return settings.worktree?.branchPrefix;
+        }
+        catch {
+            return undefined;
+        }
+    }
     async resolveWorktreeSetupSandbox(cwd) {
         if (!cwd)
             return undefined;
@@ -2978,6 +3056,7 @@ export class Engine {
             toolRegistry: this.toolRegistry,
             askUser: this.config.askUser,
             browser: this.config.browserBridge,
+            workspace: this.config.workspaceBridge,
             injectCredentialToBrowser: this.config.injectCredentialToBrowser,
             isSubAgent: this.config.isSubAgent === true,
             // Credential tools narrow their disk reads to this scope: a project/

package/dist/engine/turn-loop.d.ts

@@ -4,7 +4,7 @@
  * Following Claude Code's po_() pattern:
  * pre_check → model_call → post_check → tool_exec → context_mgmt → hook_notify → next turn
  */
-import type { Message, StreamCallback, TerminalReason, ContentBlock, ToolResult, TokenUsage } from "../types.js";
+import type { Message, StreamCallback, TerminalReason, ContentBlock, ToolResult, TokenUsage, ContextUsageAnchor } from "../types.js";
 import type { SteerItem } from "./steer-queue.js";
 import { ModelFacade } from "./model-facade.js";
 import { ToolExecutor } from "../tool-system/executor.js";
@@ -88,6 +88,8 @@ export interface TurnLoopDeps {
      * Returns the updated counters so usage_update can carry both metric scopes.
      */
     recordCumulativeUsage?: (usage: TokenUsage) => CumulativeUsageCounters;
+    /** Persist the latest context-estimation anchor derived from provider usage. */
+    recordContextUsageAnchor?: (anchor: ContextUsageAnchor) => void;
     /**
      * Reads/clears any user messages queued for THIS session via the steering
      * channel (Engine.enqueueSteer) while a run is in flight. Consumed at the top

package/dist/engine/turn-loop.js

@@ -553,7 +553,9 @@ export class TurnLoop {
                 // compaction decisions use hybrid (actual + delta) estimation rather than
                 // pure heuristics. Without this the manager falls back to char/4 estimates.
                 if (response.usage?.promptTokens !== undefined) {
-                    this.deps.contextManager.recordActualUsage(response.usage.promptTokens, messages.length, messages);
+                    const anchor = this.deps.contextManager.recordActualUsage(response.usage.promptTokens, messages.length, messages);
+                    if (anchor)
+                        this.deps.recordContextUsageAnchor?.(anchor);
                 }
                 messages = this.markPendingImagesConsumed(messages);
                 // Truncation that cut off a TOOL CALL: the model overflowed
@@ -800,7 +802,7 @@ export class TurnLoop {
                 const resultBlocks = [];
                 for (const result of results) {
                     resultBlocks.push(toolResultToBlock(result));
-                    this.deps.transcript.appendToolResult(result.id, result.toolName, result.result, result.error);
+                    this.deps.transcript.appendToolResult(result.id, result.toolName, result.result, result.error, result.contentBlocks);
                     this.config.onStream?.({ type: "tool_result", result });
                 }
                 // Fire-and-forget tool use summary (non-blocking). The whole chain is

package/dist/engine/types.d.ts

@@ -75,6 +75,8 @@ export interface EngineConfig {
     /** Browser automation bridge (browser_* tools). Wired by the host (desktop)
      *  after construction via setBrowserBridge. Undefined → tools degrade. */
     browserBridge?: import("../tool-system/browser-bridge.js").BrowserBridge;
+    /** Host-backed workspace switch bridge (desktop only). */
+    workspaceBridge?: import("../tool-system/workspace-bridge.js").WorkspaceBridge;
     /** Inject a cookie credential into the built-in browser (InjectCredential
      *  tool). Wired by the host after construction via setInjectCredential.
      *  Undefined → the tool degrades with a clear "no browser" error. */
@@ -127,6 +129,12 @@ export interface EngineConfig {
      * automation shown; tui hidden). Sub-agents override to "subagent".
      */
     origin?: SessionOrigin;
+    /**
+     * Host-specific builtin tool surface. Desktop replaces the legacy core
+     * worktree tools with SwitchSessionWorkspace because Electron main owns the
+     * authoritative workspace switch service and UI refresh path.
+     */
+    builtinToolHost?: "desktop";
     /**
      * Optional shared EngineRuntime providing pre-constructed shared resources
      * (modelPool, toolRegistry, etc.). When provided, Engine uses these instead

package/dist/git/worktree/crud.d.ts

@@ -0,0 +1,69 @@
+import type { SandboxBackend } from "../../tool-system/sandbox/index.js";
+export interface WorktreeSession {
+    originalCwd: string;
+    worktreePath: string;
+    worktreeName: string;
+    worktreeBranch: string;
+    originalBranch?: string;
+    sessionId: string;
+    createdAt: number;
+}
+/** Per-platform setup/cleanup scripts (a project's localEnvironment). */
+export interface PlatformScripts {
+    default?: string;
+    macos?: string;
+    linux?: string;
+    windows?: string;
+}
+export interface CreateWorktreeOptions {
+    prefix?: string;
+}
+/**
+ * Pick the setup/cleanup script for the running platform, falling back to
+ * `default`. Empty/whitespace-only scripts are treated as absent so a project
+ * can leave a platform key blank without spawning an empty shell. `platform`
+ * defaults to `process.platform` so callers usually omit it; tests pass a
+ * fixed value.
+ */
+export declare function selectPlatformScript(scripts: PlatformScripts | undefined, platform?: NodeJS.Platform): string | undefined;
+/**
+ * Create an isolated git worktree for an agent session.
+ */
+export declare function createWorktree(cwd: string, slug: string, sessionId: string, opts?: CreateWorktreeOptions): Promise<WorktreeSession>;
+export interface WorktreeSetupResult {
+    /** True if no setup script was configured for this platform (nothing ran). */
+    skipped: boolean;
+    /** True if a script ran and exited 0. */
+    ok: boolean;
+    /** Combined stdout/stderr, for surfacing to the user on failure. */
+    output: string;
+    /** Exit code when a script ran; undefined when skipped. */
+    exitCode?: number | null;
+}
+/**
+ * Run a project's `localEnvironment.setupScripts` once, in the freshly-created
+ * worktree's root, right after `git worktree add`.
+ */
+export declare function runWorktreeSetup(worktreePath: string, script: string | undefined, opts?: {
+    sandbox?: SandboxBackend;
+    shellEnv?: Record<string, string>;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<WorktreeSetupResult>;
+export interface RemoveWorktreeResult {
+    /** True once `git worktree remove` completed and the directory is gone. */
+    dirRemoved: boolean;
+    /** The branch targeted for deletion when removeBranch=true. */
+    branch?: string;
+    /** True when removeBranch=true and branch deletion completed. */
+    branchDeleted?: boolean;
+    /** Non-empty when the worktree directory is gone but branch deletion failed. */
+    branchError?: string;
+}
+export interface RemoveWorktreeOptions {
+    prefix?: string;
+}
+/**
+ * Remove a worktree and optionally its branch.
+ */
+export declare function removeWorktree(worktreePath: string, removeBranch?: boolean, opts?: RemoveWorktreeOptions): RemoveWorktreeResult;

package/dist/git/worktree/crud.js

@@ -0,0 +1,206 @@
+import { existsSync, lstatSync, mkdirSync, readdirSync, symlinkSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { safeSpawnShell } from "../../runtime/safe-spawn.js";
+import { buildSandboxEnv, defaultShellBinary, mergeShellEnv } from "../../runtime/spawn-common.js";
+import { execGit, execGitSync, gitErrorMessage } from "./git-exec.js";
+import { assertBranchNotCheckedOut, currentBranch, findGitRoot } from "./query.js";
+import { applyPrefix, isManagedWorktreeBranch, validateWorktreeSlug } from "./slug.js";
+/**
+ * Pick the setup/cleanup script for the running platform, falling back to
+ * `default`. Empty/whitespace-only scripts are treated as absent so a project
+ * can leave a platform key blank without spawning an empty shell. `platform`
+ * defaults to `process.platform` so callers usually omit it; tests pass a
+ * fixed value.
+ */
+export function selectPlatformScript(scripts, platform = process.platform) {
+    if (!scripts)
+        return undefined;
+    const key = platform === "darwin" ? "macos" : platform === "win32" ? "windows" : "linux";
+    // A blank platform key shouldn't shadow a real `default` — fall through.
+    const platformScript = scripts[key]?.trim() ? scripts[key] : undefined;
+    const candidate = platformScript ?? scripts.default;
+    const trimmed = candidate?.trim();
+    return trimmed ? candidate : undefined;
+}
+/**
+ * Create an isolated git worktree for an agent session.
+ */
+export async function createWorktree(cwd, slug, sessionId, opts = {}) {
+    validateWorktreeSlug(slug);
+    const gitRoot = await findGitRoot(cwd);
+    const branchName = applyPrefix(opts.prefix, slug, sessionId);
+    const worktreePath = resolve(gitRoot, "..", `.worktrees/${slug}-${sessionId.slice(0, 8)}`);
+    await assertBranchNotCheckedOut(gitRoot, branchName);
+    const originalBranch = await currentBranch(gitRoot);
+    // The argv form keeps branchName/worktreePath as literal positional
+    // arguments even if a future caller bypasses validateWorktreeSlug.
+    await execGit(gitRoot, ["worktree", "add", "-b", branchName, worktreePath], 30000);
+    // Symlink large directories to avoid disk bloat.
+    symlinkLargeDirectories(gitRoot, worktreePath);
+    return {
+        originalCwd: cwd,
+        worktreePath,
+        worktreeName: slug,
+        worktreeBranch: branchName,
+        originalBranch,
+        sessionId,
+        createdAt: Date.now(),
+    };
+}
+/**
+ * Run a project's `localEnvironment.setupScripts` once, in the freshly-created
+ * worktree's root, right after `git worktree add`.
+ */
+export async function runWorktreeSetup(worktreePath, script, opts = {}) {
+    const trimmed = script?.trim();
+    if (!trimmed)
+        return { skipped: true, ok: true, output: "" };
+    const shell = defaultShellBinary();
+    const backend = opts.sandbox;
+    const baseEnv = backend && backend.name !== "off" ? buildSandboxEnv() : { ...process.env };
+    const env = mergeShellEnv(baseEnv, opts.shellEnv);
+    const result = await safeSpawnShell(trimmed, {
+        cwd: worktreePath,
+        env,
+        timeoutMs: opts.timeoutMs ?? 120_000,
+        maxOutputBytes: 1024 * 1024,
+        sandbox: backend,
+        shell,
+        signal: opts.signal,
+    });
+    const parts = [];
+    if (result.stdout)
+        parts.push(result.stdout);
+    if (result.stderr)
+        parts.push(result.stderr);
+    const output = parts.join("\n").trim();
+    if (result.aborted)
+        return { skipped: false, ok: false, output: output || "setup aborted" };
+    if (result.timedOut)
+        return { skipped: false, ok: false, output: output || "setup timed out" };
+    if (result.spawnFailed) {
+        return { skipped: false, ok: false, output: result.error ?? "failed to spawn setup script" };
+    }
+    return { skipped: false, ok: result.exitCode === 0, output, exitCode: result.exitCode };
+}
+/**
+ * Remove a worktree and optionally its branch.
+ */
+export function removeWorktree(worktreePath, removeBranch = false, opts = {}) {
+    // The MAIN repo root, not the worktree's own toplevel. `git rev-parse
+    // --show-toplevel` from inside a worktree returns the worktree path, which
+    // is about to be deleted; the branch-delete must run from the main repo,
+    // which outlives the worktree. Derive it from the common git dir.
+    let mainRoot;
+    try {
+        const commonDir = execGitSync(worktreePath, ["rev-parse", "--path-format=absolute", "--git-common-dir"], 5000).trim();
+        mainRoot = dirname(commonDir);
+    }
+    catch (err) {
+        throw new Error(`failed to inspect worktree ${worktreePath}: ${gitErrorMessage(err)}`, {
+            cause: err,
+        });
+    }
+    // Capture the worktree's branch BEFORE removing the worktree — afterwards
+    // the directory is gone and `git branch --show-current` in it would fail.
+    let branch = "";
+    if (removeBranch) {
+        try {
+            branch = execGitSync(worktreePath, ["branch", "--show-current"], 5000).trim();
+        }
+        catch (err) {
+            throw new Error(`failed to determine branch for worktree ${worktreePath}: ${gitErrorMessage(err)}`, { cause: err });
+        }
+        if (!branch) {
+            throw new Error(`failed to determine branch for worktree ${worktreePath}`);
+        }
+        if (!isManagedWorktreeBranch(branch, opts.prefix)) {
+            throw new Error(`refusing to delete non-CodeShell worktree branch ${branch}`);
+        }
+    }
+    try {
+        execGitSync(mainRoot, ["worktree", "remove", worktreePath, "--force"], 30000);
+    }
+    catch (err) {
+        throw new Error(`failed to remove worktree ${worktreePath}: ${gitErrorMessage(err)}`, {
+            cause: err,
+        });
+    }
+    if (removeBranch) {
+        try {
+            execGitSync(mainRoot, ["branch", "-D", branch], 10000);
+        }
+        catch (err) {
+            return {
+                dirRemoved: true,
+                branch,
+                branchDeleted: false,
+                branchError: gitErrorMessage(err),
+            };
+        }
+    }
+    return removeBranch ? { dirRemoved: true, branch, branchDeleted: true } : { dirRemoved: true };
+}
+/**
+ * Symlink large directories (node_modules, .venv, etc.) from main repo to
+ * worktree. Also links each monorepo workspace package's private
+ * `node_modules` (e.g. `packages/desktop/node_modules`, where bun keeps
+ * un-hoisted deps like electron) so a fresh worktree can build/run the whole
+ * workspace, not just the packages whose deps happen to be hoisted to the root.
+ */
+function symlinkLargeDirectories(sourceRoot, worktreePath) {
+    const largeDirs = ["node_modules", ".venv", "vendor", ".pnpm-store"];
+    for (const dir of largeDirs) {
+        linkDir(join(sourceRoot, dir), join(worktreePath, dir));
+    }
+    // Monorepo workspace packages keep private node_modules that are NOT hoisted
+    // to the root. Link `<pkg>/node_modules` for each package under `packages/`.
+    const packagesDir = join(sourceRoot, "packages");
+    if (!dirExists(packagesDir))
+        return;
+    let pkgNames;
+    try {
+        pkgNames = readdirSync(packagesDir);
+    }
+    catch {
+        return;
+    }
+    for (const pkg of pkgNames) {
+        const source = join(packagesDir, pkg, "node_modules");
+        if (!dirExists(source))
+            continue;
+        const targetPkgDir = join(worktreePath, "packages", pkg);
+        // The worktree only has package dirs that exist in this branch's tree; a
+        // package present in the main repo but not checked out here is skipped.
+        if (!dirExists(targetPkgDir)) {
+            try {
+                mkdirSync(targetPkgDir, { recursive: true });
+            }
+            catch {
+                continue;
+            }
+        }
+        linkDir(source, join(targetPkgDir, "node_modules"));
+    }
+}
+function dirExists(path) {
+    try {
+        return lstatSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function linkDir(source, target) {
+    // Windows directory symlinks need admin/Developer Mode and throw EPERM for a
+    // normal user; NTFS junctions don't and behave the same for our purpose.
+    const linkType = process.platform === "win32" ? "junction" : "dir";
+    if (dirExists(source) && !existsSync(target)) {
+        try {
+            symlinkSync(source, target, linkType);
+        }
+        catch {
+            // Symlink/junction might fail on some systems — non-fatal.
+        }
+    }
+}

package/dist/git/worktree/diff.d.ts

@@ -0,0 +1,14 @@
+export interface WorktreeDiffSummary {
+    /** Best-effort base used for the branch comparison, usually main/master. */
+    baseRef?: string;
+    /** Unique files changed either by commits ahead of base or by uncommitted changes. */
+    changedFiles: number;
+    /** Commits reachable from HEAD but not from baseRef. */
+    aheadCommits: number;
+    /** True when `git status --porcelain` reports local changes. */
+    hasUncommittedChanges: boolean;
+}
+export declare function getWorktreeDiff(worktreePath: string, baseRef?: string): Promise<WorktreeDiffSummary>;
+export declare function worktreeHasUncommittedChanges(worktreePath: string): Promise<boolean>;
+export declare function worktreeHasUncommittedOrAheadChanges(worktreePath: string, baseRef?: string): Promise<boolean>;
+export declare function findComparisonBaseRef(cwd: string): Promise<string | undefined>;

package/dist/git/worktree/diff.js

@@ -0,0 +1,82 @@
+import { gitOutput } from "./git-exec.js";
+export async function getWorktreeDiff(worktreePath, baseRef) {
+    const comparisonBase = baseRef && (await commitRefExists(worktreePath, baseRef))
+        ? baseRef
+        : await findComparisonBaseRef(worktreePath);
+    return diffSummary(worktreePath, comparisonBase);
+}
+export async function worktreeHasUncommittedChanges(worktreePath) {
+    const out = await gitOutput(worktreePath, ["status", "--porcelain"], 10000);
+    return (out?.trim().length ?? 0) > 0;
+}
+export async function worktreeHasUncommittedOrAheadChanges(worktreePath, baseRef) {
+    if (await worktreeHasUncommittedChanges(worktreePath))
+        return true;
+    const comparisonBase = baseRef && (await commitRefExists(worktreePath, baseRef))
+        ? baseRef
+        : await findComparisonBaseRef(worktreePath);
+    return comparisonBase ? (await aheadCommitCount(worktreePath, comparisonBase)) > 0 : false;
+}
+export async function findComparisonBaseRef(cwd) {
+    for (const ref of ["main", "master", "origin/main", "origin/master"]) {
+        if (await commitRefExists(cwd, ref))
+            return ref;
+    }
+    return undefined;
+}
+async function commitRefExists(cwd, ref) {
+    const out = await gitOutput(cwd, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], 5000);
+    return out !== undefined;
+}
+async function diffSummary(cwd, baseRef) {
+    const [dirtyFiles, committedFiles, aheadCommits] = await Promise.all([
+        statusFileSet(cwd),
+        baseRef ? changedFilesSinceBase(cwd, baseRef) : Promise.resolve(new Set()),
+        baseRef ? aheadCommitCount(cwd, baseRef) : Promise.resolve(0),
+    ]);
+    const changedFiles = new Set([...dirtyFiles, ...committedFiles]);
+    return {
+        ...(baseRef ? { baseRef } : {}),
+        changedFiles: changedFiles.size,
+        aheadCommits,
+        hasUncommittedChanges: dirtyFiles.size > 0,
+    };
+}
+async function changedFilesSinceBase(cwd, baseRef) {
+    const out = await gitOutput(cwd, ["diff", "--name-only", `${baseRef}...HEAD`]);
+    const raw = out ?? (await gitOutput(cwd, ["diff", "--name-only", `${baseRef}..HEAD`])) ?? "";
+    return new Set(raw
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean));
+}
+async function aheadCommitCount(cwd, baseRef) {
+    const out = await gitOutput(cwd, ["rev-list", "--count", `${baseRef}..HEAD`]);
+    const n = Number.parseInt(out?.trim() ?? "0", 10);
+    return Number.isFinite(n) ? n : 0;
+}
+async function statusFileSet(cwd) {
+    const raw = (await gitOutput(cwd, ["status", "--porcelain=v1"])) ?? "";
+    const files = new Set();
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        const path = line.slice(3).trim();
+        if (!path)
+            continue;
+        const renameTarget = path.includes(" -> ") ? path.split(" -> ").at(-1) : path;
+        if (renameTarget)
+            files.add(unquoteGitPath(renameTarget));
+    }
+    return files;
+}
+function unquoteGitPath(path) {
+    if (!path.startsWith('"') || !path.endsWith('"'))
+        return path;
+    try {
+        return JSON.parse(path);
+    }
+    catch {
+        return path.slice(1, -1);
+    }
+}

package/dist/git/worktree/git-exec.d.ts

@@ -0,0 +1,7 @@
+export declare const GIT_BIN: string;
+export declare function execGit(cwd: string, args: string[], timeout?: number): Promise<string>;
+export declare function execGitSync(cwd: string, args: string[], timeout?: number): string;
+export declare function gitOutput(cwd: string, args: string[], timeout?: number): Promise<string | undefined>;
+export declare function gitOutputSync(cwd: string, args: string[], timeout?: number): string | undefined;
+export declare function gitErrorMessage(err: unknown): string;
+export declare function normalizeBranchName(branch: string): string;