@cjhyy/code-shell-capability-coding 0.8.8 → 0.8.10

package/dist/cc-orchestrator/external-agent-session-store.d.ts

@@ -22,14 +22,16 @@ export type ExternalAgentSessionRecord = Omit<ExternalAgentSessionBinding, "crea
 export declare function defaultExternalAgentSessionStorePath(): string;
 export declare class ExternalAgentSessionStore {
     private readonly file;
+    private readonly pendingBindings;
     constructor(file?: string);
     /** Snapshot all known bindings. Returned objects are detached from the
      *  persisted array so read-only consumers (for example room discovery) can
      *  correlate worktree sessions without gaining a mutation path. */
     list(): ExternalAgentSessionBinding[];
     get(cli: ExternalAgentCli, sessionId: string): ExternalAgentSessionBinding | undefined;
-    record(binding: ExternalAgentSessionRecord): void;
+    record(binding: ExternalAgentSessionRecord): Promise<void>;
     private load;
+    private loadForWrite;
     private save;
     private withLock;
 }

package/dist/cc-orchestrator/external-agent-session-store.js

@@ -1,4 +1,6 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { codeShellHome, logger, normalizeCwdPath } from "@cjhyy/code-shell-core/extension";
 const LOCK_WAIT_MS = 5_000;
@@ -9,6 +11,7 @@ export function defaultExternalAgentSessionStorePath() {
 }
 export class ExternalAgentSessionStore {
     file;
+    pendingBindings = new Map();
     constructor(file = defaultExternalAgentSessionStorePath()) {
         this.file = file;
     }
@@ -16,50 +19,40 @@ export class ExternalAgentSessionStore {
      *  persisted array so read-only consumers (for example room discovery) can
      *  correlate worktree sessions without gaining a mutation path. */
     list() {
-        return this.load().map((binding) => ({ ...binding }));
+        const merged = new Map(this.load().map((binding) => [bindingKey(binding), binding]));
+        for (const [key, binding] of this.pendingBindings)
+            merged.set(key, binding);
+        return [...merged.values()].map((binding) => ({ ...binding }));
     }
     get(cli, sessionId) {
         if (!sessionId)
             return undefined;
-        return this.load().find((s) => s.cli === cli && s.sessionId === sessionId);
+        const pending = this.pendingBindings.get(bindingKey({ cli, sessionId }));
+        return pending ?? this.load().find((s) => s.cli === cli && s.sessionId === sessionId);
     }
-    record(binding) {
+    async record(binding) {
         if (!binding.sessionId || !binding.cwd)
             return;
-        this.withLock(() => {
-            const loaded = this.load();
-            const existing = loaded.find((s) => s.cli === binding.cli && s.sessionId === binding.sessionId);
-            const now = binding.lastUsedAt ?? binding.updatedAt ?? Date.now();
-            const next = {
-                cli: binding.cli,
-                sessionId: binding.sessionId,
-                ...((binding.codeShellSessionId ?? existing?.codeShellSessionId)
-                    ? { codeShellSessionId: binding.codeShellSessionId ?? existing?.codeShellSessionId }
-                    : {}),
-                cwd: normalizeCwdPath(binding.cwd),
-                ...((binding.workspaceRoot ?? existing?.workspaceRoot)
-                    ? { workspaceRoot: normalizeCwdPath(binding.workspaceRoot ?? existing.workspaceRoot) }
-                    : {}),
-                ...((binding.worktreePath ?? existing?.worktreePath)
-                    ? { worktreePath: normalizeCwdPath(binding.worktreePath ?? existing.worktreePath) }
-                    : {}),
-                ...((binding.worktreeBranch ?? existing?.worktreeBranch)
-                    ? { worktreeBranch: binding.worktreeBranch ?? existing?.worktreeBranch }
-                    : {}),
-                ...((binding.worktreeBaseRef ?? existing?.worktreeBaseRef)
-                    ? { worktreeBaseRef: binding.worktreeBaseRef ?? existing?.worktreeBaseRef }
-                    : {}),
-                ...((binding.isolation ?? existing?.isolation)
-                    ? { isolation: binding.isolation ?? existing?.isolation }
-                    : {}),
-                createdAt: binding.createdAt ?? existing?.createdAt ?? now,
-                lastUsedAt: now,
-                updatedAt: now,
-            };
-            const sessions = loaded.filter((s) => !(s.cli === binding.cli && s.sessionId === binding.sessionId));
-            sessions.push(next);
-            this.save(sessions);
-        });
+        const key = bindingKey(binding);
+        // Preserve the old immediate-read contract while disk persistence proceeds
+        // without blocking the event loop. This instance overlays the pending value
+        // on list/get until the atomic write finishes.
+        const optimistic = mergeBinding(binding, this.get(binding.cli, binding.sessionId));
+        this.pendingBindings.set(key, optimistic);
+        try {
+            await this.withLock(async () => {
+                const loaded = await this.loadForWrite();
+                const existing = loaded.find((s) => s.cli === binding.cli && s.sessionId === binding.sessionId);
+                const next = mergeBinding(binding, existing);
+                const sessions = loaded.filter((s) => !(s.cli === binding.cli && s.sessionId === binding.sessionId));
+                sessions.push(next);
+                await this.save(sessions);
+            });
+        }
+        finally {
+            if (this.pendingBindings.get(key) === optimistic)
+                this.pendingBindings.delete(key);
+        }
     }
     load() {
         if (!existsSync(this.file))
@@ -80,56 +73,111 @@ export class ExternalAgentSessionStore {
             return [];
         }
     }
-    save(sessions) {
-        const dir = dirname(this.file);
-        if (!existsSync(dir))
-            mkdirSync(dir, { recursive: true });
-        const snapshot = { version: 2, sessions };
-        const tmp = `${this.file}.${process.pid}.${Date.now()}.tmp`;
+    async loadForWrite() {
         try {
-            writeFileSync(tmp, JSON.stringify(snapshot, null, 2) + "\n", "utf-8");
-            renameSync(tmp, this.file);
+            const raw = await readFile(this.file, "utf-8");
+            const parsed = JSON.parse(raw);
+            if (!parsed || !Array.isArray(parsed.sessions)) {
+                throw new Error("external agent session store has an invalid root");
+            }
+            return parsed.sessions.filter(isBinding).map(normalizeBinding);
         }
         catch (err) {
-            rmSync(tmp, { force: true });
+            if (err.code === "ENOENT")
+                return [];
+            logger.warn("external_agent_session_store.write_read_failed", {
+                cat: "cc",
+                file: this.file,
+                error: err instanceof Error ? err.message : String(err),
+            });
             throw err;
         }
     }
-    withLock(fn) {
+    async save(sessions) {
+        const dir = dirname(this.file);
+        await mkdir(dir, { recursive: true, mode: 0o700 });
+        if (process.platform !== "win32")
+            await chmod(dir, 0o700);
+        const snapshot = { version: 2, sessions };
+        const tmp = `${this.file}.${process.pid}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(tmp, JSON.stringify(snapshot, null, 2) + "\n", {
+                encoding: "utf-8",
+                mode: 0o600,
+                flag: "wx",
+            });
+            await rename(tmp, this.file);
+        }
+        finally {
+            await rm(tmp, { force: true }).catch(() => undefined);
+        }
+    }
+    async withLock(fn) {
         const dir = dirname(this.file);
-        if (!existsSync(dir))
-            mkdirSync(dir, { recursive: true });
-        // TODO: move this sync polling lock to an async write queue; callers can
-        // otherwise block the event loop for up to LOCK_WAIT_MS under contention.
+        await mkdir(dir, { recursive: true, mode: 0o700 });
+        if (process.platform !== "win32")
+            await chmod(dir, 0o700);
         const lockDir = `${this.file}.lock`;
         const deadline = Date.now() + LOCK_WAIT_MS;
         while (true) {
             try {
-                mkdirSync(lockDir);
+                await mkdir(lockDir);
                 break;
             }
             catch (err) {
                 const code = err.code;
                 if (code !== "EEXIST")
                     throw err;
-                if (removeStaleLock(lockDir))
+                if (await removeStaleLock(lockDir))
                     continue;
                 if (Date.now() >= deadline) {
                     throw new Error(`timed out waiting for external agent session store lock: ${lockDir}`, {
                         cause: err,
                     });
                 }
-                sleepSync(LOCK_POLL_MS);
+                await delay(LOCK_POLL_MS);
             }
         }
         try {
-            return fn();
+            return await fn();
         }
         finally {
-            rmSync(lockDir, { recursive: true, force: true });
+            await rm(lockDir, { recursive: true, force: true });
         }
     }
 }
+function bindingKey(binding) {
+    return `${binding.cli}\0${binding.sessionId}`;
+}
+function mergeBinding(binding, existing) {
+    const now = binding.lastUsedAt ?? binding.updatedAt ?? Date.now();
+    return {
+        cli: binding.cli,
+        sessionId: binding.sessionId,
+        ...((binding.codeShellSessionId ?? existing?.codeShellSessionId)
+            ? { codeShellSessionId: binding.codeShellSessionId ?? existing?.codeShellSessionId }
+            : {}),
+        cwd: normalizeCwdPath(binding.cwd),
+        ...((binding.workspaceRoot ?? existing?.workspaceRoot)
+            ? { workspaceRoot: normalizeCwdPath(binding.workspaceRoot ?? existing.workspaceRoot) }
+            : {}),
+        ...((binding.worktreePath ?? existing?.worktreePath)
+            ? { worktreePath: normalizeCwdPath(binding.worktreePath ?? existing.worktreePath) }
+            : {}),
+        ...((binding.worktreeBranch ?? existing?.worktreeBranch)
+            ? { worktreeBranch: binding.worktreeBranch ?? existing?.worktreeBranch }
+            : {}),
+        ...((binding.worktreeBaseRef ?? existing?.worktreeBaseRef)
+            ? { worktreeBaseRef: binding.worktreeBaseRef ?? existing?.worktreeBaseRef }
+            : {}),
+        ...((binding.isolation ?? existing?.isolation)
+            ? { isolation: binding.isolation ?? existing?.isolation }
+            : {}),
+        createdAt: binding.createdAt ?? existing?.createdAt ?? now,
+        lastUsedAt: now,
+        updatedAt: now,
+    };
+}
 function normalizeBinding(binding) {
     const updatedAt = finiteTimestamp(binding.updatedAt) ?? Date.now();
     const lastUsedAt = finiteTimestamp(binding.lastUsedAt) ?? updatedAt;
@@ -147,11 +195,11 @@ function normalizeBinding(binding) {
 function finiteTimestamp(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
-function removeStaleLock(lockDir) {
+async function removeStaleLock(lockDir) {
     try {
-        if (Date.now() - statSync(lockDir).mtimeMs <= LOCK_STALE_MS)
+        if (Date.now() - (await stat(lockDir)).mtimeMs <= LOCK_STALE_MS)
             return false;
-        rmSync(lockDir, { recursive: true, force: true });
+        await rm(lockDir, { recursive: true, force: true });
         return true;
     }
     catch (err) {
@@ -160,17 +208,8 @@ function removeStaleLock(lockDir) {
         return false;
     }
 }
-function sleepSync(ms) {
-    try {
-        const view = new Int32Array(new SharedArrayBuffer(4));
-        Atomics.wait(view, 0, 0, ms);
-    }
-    catch {
-        const until = Date.now() + ms;
-        while (Date.now() < until) {
-            // fallback for runtimes where Atomics.wait is unavailable
-        }
-    }
+function delay(ms) {
+    return new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
 }
 function isBinding(value) {
     if (!value || typeof value !== "object")

package/dist/external-runtimes/claude-code/event-translator.js

@@ -66,15 +66,19 @@ export class ClaudeEventTranslator {
     onSystem(message) {
         if (str(message.subtype) !== "init")
             return [];
-        const sessionId = str(message.session_id);
-        if (sessionId)
-            this.runtimeSessionId = sessionId;
+        const runtimeSessionId = str(message.session_id);
+        if (runtimeSessionId)
+            this.runtimeSessionId = runtimeSessionId;
         if (this.sessionStarted)
             return [];
         this.sessionStarted = true;
+        if (!runtimeSessionId)
+            return [];
         // promptTokens is unknown at init; the field is required, and 0 is honest
-        // here rather than a guess.
-        return sessionId ? [{ type: "session_started", sessionId, promptTokens: 0 }] : [];
+        // here rather than a guess. The StreamEvent identity is CodeShell's stable
+        // business session id; Claude's id is a resume key only and must never
+        // replace the renderer's engineSessionId.
+        return [{ type: "session_started", sessionId: this.options.sessionId, promptTokens: 0 }];
     }
     onStreamEvent(message) {
         const event = asRecord(message.event);

package/dist/index.capability.js

@@ -14,6 +14,7 @@ import { codingArtifactDetector, createCodingToolService, findCodingInstructionB
 function defineTool(definition, execute, exposure) {
     return { definition, execute, exposure };
 }
+const unavailableInQuickChat = (context) => context.behaviorProfile !== "quickChatRestricted";
 export const CODING_TOOLS = [
     // `briefTool` remains a root compatibility export, but is deliberately not
     // model-exposed here: its Markdown return value is a tool result, not a
@@ -26,14 +27,14 @@ export const CODING_TOOLS = [
         isConcurrencySafe: false,
         timeoutMs: DRIVE_AGENT_TOOL_TIMEOUT_MS,
         pathPolicy: [{ kind: "arg", arg: "attachmentPaths", operation: "read" }],
-    }, driveAgentTool, { presetTags: ["general", "terminal-coding"] }),
+    }, driveAgentTool, { presetTags: ["general", "terminal-coding"], availability: unavailableInQuickChat }),
     defineTool({
         ...driveAgentJobsToolDef,
         source: "builtin",
         permissionDefault: "allow",
         isReadOnly: false,
         isConcurrencySafe: false,
-    }, driveAgentJobsTool, { presetTags: ["general", "terminal-coding"] }),
+    }, driveAgentJobsTool, { presetTags: ["general", "terminal-coding"], availability: unavailableInQuickChat }),
     defineTool({
         ...driveClaudeCodeToolDef,
         source: "builtin",
@@ -42,7 +43,7 @@ export const CODING_TOOLS = [
         isConcurrencySafe: false,
         timeoutMs: DRIVE_AGENT_TOOL_TIMEOUT_MS,
         pathPolicy: [{ kind: "arg", arg: "attachmentPaths", operation: "read" }],
-    }, driveClaudeCodeTool, { presetTags: ["general", "terminal-coding"] }),
+    }, driveClaudeCodeTool, { presetTags: ["general", "terminal-coding"], availability: unavailableInQuickChat }),
     defineTool({
         ...checkQuotaToolDef,
         source: "builtin",

package/dist/tools/drive-agent.d.ts

@@ -21,7 +21,7 @@ type Runner = (opts: {
 }) => Promise<AgentRunResult>;
 type SessionStore = {
     get(cli: DriveCli, sessionId: string): ExternalAgentSessionBinding | undefined;
-    record(binding: ExternalAgentSessionRecord): void;
+    record(binding: ExternalAgentSessionRecord): void | Promise<void>;
 };
 export interface DriveAgentToolOptions {
     foregroundHandoffMs?: number;

package/dist/tools/drive-agent.js

@@ -107,6 +107,10 @@ export const driveAgentToolDef = {
         required: ["prompt"],
     },
 };
+/** Foreground runs are not background jobs until the handoff deadline. Keep
+ * them visible to conflict detection during that window so another session
+ * cannot launch a writer into the same workspace. */
+const foregroundDriveLeases = new Map();
 function isExternalRuntimeContext(ctx) {
     return (ctx?.externalRuntime === true);
 }
@@ -155,11 +159,20 @@ async function resolveDriveWorkspaceRoot(cwd) {
 function hasRunningDriveWriter(workspaceCwd, workspaceRoot) {
     if (backgroundJobRegistry.listRunningByCwd(workspaceCwd).some(isDriveAgentJob))
         return true;
-    return backgroundJobRegistry
+    if (backgroundJobRegistry
         .list()
         .some((job) => (job.status === "running" || job.status === "cancelling") &&
         isDriveAgentJob(job) &&
-        job.workspaceRoot === workspaceRoot);
+        job.workspaceRoot === workspaceRoot)) {
+        return true;
+    }
+    for (const lease of foregroundDriveLeases.values()) {
+        if (lease.effectiveWorkspaceRoot === workspaceRoot ||
+            lease.workspaceRoot === workspaceRoot) {
+            return true;
+        }
+    }
+    return false;
 }
 async function prepareDriveWorktree(params) {
     const gitRoot = await findGitRoot(params.cwd, params.signal);
@@ -401,7 +414,7 @@ function appendAttachmentPrompt(prompt, paths) {
     }
     return `${prompt}\n${lines.join("\n")}`;
 }
-function recordSuccessfulSession(store, cli, cwd, result, metadata, includeErroredSession = false) {
+async function recordSuccessfulSession(store, cli, cwd, result, metadata, includeErroredSession = false) {
     if ((!includeErroredSession && result.isError) || !result.sessionId)
         return;
     // When the isolation worktree directory was removed during finalization the
@@ -425,7 +438,7 @@ function recordSuccessfulSession(store, cli, cwd, result, metadata, includeError
             ? { worktreeBranch: metadata.worktree.session.worktreeBranch }
             : {};
     try {
-        store.record({
+        await store.record({
             cli,
             sessionId: result.sessionId,
             ...(metadata.codeShellSessionId ? { codeShellSessionId: metadata.codeShellSessionId } : {}),
@@ -445,21 +458,40 @@ function recordSuccessfulSession(store, cli, cwd, result, metadata, includeError
         });
     }
 }
-function duplicateCwdWarning(effectiveWorkspaceCwd, writable) {
+function duplicateCwdError(effectiveWorkspaceCwd, effectiveWorkspaceRoot, writable) {
     if (!writable)
         return undefined;
     const running = backgroundJobRegistry
         .listRunningByCwd(effectiveWorkspaceCwd)
         .filter(isDriveAgentJob);
-    if (running.length === 0)
+    const foreground = [...foregroundDriveLeases.values()].filter((lease) => lease.effectiveWorkspaceRoot === effectiveWorkspaceRoot);
+    if (running.length === 0 && foreground.length === 0)
         return undefined;
-    const jobs = running.map(formatDriveJobListLine).join("; ");
-    const workspaceRoot = running[0]?.effectiveWorkspaceRoot ?? normalizeCwdPath(effectiveWorkspaceCwd);
-    return (`Warning: another DriveAgent job is already running in effective workspace ${workspaceRoot}. ` +
-        "Concurrent writable agents in the same workspace can overwrite each other's work. " +
+    const jobs = [
+        ...running.map(formatDriveJobListLine),
+        ...foreground.map((lease) => `${lease.leaseId}  status=foreground  ${lease.label}`),
+    ].join("; ");
+    return (`Error: another writable DriveAgent is already running in effective workspace ${effectiveWorkspaceRoot}. ` +
+        "Refusing to start a concurrent writer because it could overwrite the other agent's work. " +
         `Run DriveAgentJobs(action:"list", cwd:"${effectiveWorkspaceCwd}") before dispatching parallel work for details/cancellation. ` +
         `Running: ${jobs}`);
 }
+function acquireForegroundDriveLease(params) {
+    const conflict = duplicateCwdError(params.effectiveWorkspaceCwd, params.effectiveWorkspaceRoot, params.writable);
+    if (conflict)
+        return { error: conflict };
+    if (!params.writable)
+        return { release: () => undefined };
+    const leaseId = newDriveJobId();
+    const lease = { leaseId, ...params };
+    foregroundDriveLeases.set(leaseId, lease);
+    return {
+        release: () => {
+            if (foregroundDriveLeases.get(leaseId) === lease)
+                foregroundDriveLeases.delete(leaseId);
+        },
+    };
+}
 function attachDriveCompletion(params) {
     const { jobId, sessionId, label, cli, cwd, workspaceRoot, isolation, worktree, run, sessionStore, readChangedFiles, recordExternalFileChanges, originClientMessageId, } = params;
     void run
@@ -481,7 +513,7 @@ function attachDriveCompletion(params) {
         if (lifecycle) {
             backgroundJobRegistry.recordWorktreeLifecycle(jobId, lifecycle.action);
         }
-        recordSuccessfulSession(sessionStore, cli, cwd, r, { codeShellSessionId: sessionId, workspaceRoot, isolation, worktree, lifecycle }, cancelling);
+        void recordSuccessfulSession(sessionStore, cli, cwd, r, { codeShellSessionId: sessionId, workspaceRoot, isolation, worktree, lifecycle }, cancelling);
         if (changedFiles.length > 0) {
             recordExternalFileChanges?.({
                 jobId,
@@ -574,34 +606,57 @@ function attachDriveCompletion(params) {
     });
 }
 function trackBackgroundRun(params) {
-    const warning = duplicateCwdWarning(params.effectiveWorkspaceCwd, params.writable);
+    const conflict = duplicateCwdError(params.effectiveWorkspaceCwd, params.effectiveWorkspaceRoot, params.writable);
+    if (conflict)
+        return { error: conflict };
     const jobId = newDriveJobId();
-    const run = params.start();
-    backgroundJobRegistry.start(jobId, params.sessionId, params.label, {
-        kind: "drive-agent",
-        launchCwd: params.cwd,
-        effectiveWorkspaceCwd: params.effectiveWorkspaceCwd,
-        workspaceRoot: params.workspaceRoot,
-        isolation: params.isolation,
-        ...(params.worktree
-            ? {
-                worktreePath: params.worktree.session.worktreePath,
-                worktreeBranch: params.worktree.session.worktreeBranch,
-                worktreeBaseRef: params.worktree.session.baseRef,
-                worktreeCleanup: params.worktree.cleanup,
-                worktreeBranchPrefix: params.worktree.branchPrefix,
-            }
-            : {}),
-        cli: params.cli,
-        promptSummary: params.promptSummary,
-        originClientMessageId: params.originClientMessageId,
-        abort: async () => {
-            params.abort();
-            await run.catch(() => undefined);
-        },
-    });
+    let run;
+    try {
+        // Publish ownership before starting the external process. Registry
+        // listeners are synchronous and may re-enter session teardown from the
+        // start notification; starting first would leave that process orphaned.
+        backgroundJobRegistry.start(jobId, params.sessionId, params.label, {
+            kind: "drive-agent",
+            launchCwd: params.cwd,
+            effectiveWorkspaceCwd: params.effectiveWorkspaceCwd,
+            workspaceRoot: params.workspaceRoot,
+            isolation: params.isolation,
+            ...(params.worktree
+                ? {
+                    worktreePath: params.worktree.session.worktreePath,
+                    worktreeBranch: params.worktree.session.worktreeBranch,
+                    worktreeBaseRef: params.worktree.session.baseRef,
+                    worktreeCleanup: params.worktree.cleanup,
+                    worktreeBranchPrefix: params.worktree.branchPrefix,
+                }
+                : {}),
+            cli: params.cli,
+            promptSummary: params.promptSummary,
+            originClientMessageId: params.originClientMessageId,
+            abort: async () => {
+                params.abort();
+                await run?.catch(() => undefined);
+            },
+        });
+    }
+    catch (error) {
+        return {
+            error: `Error: failed to register DriveAgent job: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (backgroundJobRegistry.get(jobId)?.status !== "running") {
+        return { error: "Error: DriveAgent owner session closed before the job could start." };
+    }
+    try {
+        run = params.start();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        backgroundJobRegistry.finish(jobId, { status: "failed", finalText: message });
+        return { error: `Error: failed to start DriveAgent job: ${message}` };
+    }
     attachDriveCompletion({ ...params, jobId, run });
-    return { jobId, ...(warning ? { warning } : {}) };
+    return { jobId };
 }
 async function waitForForegroundOrHandoff(run, handoffMs) {
     if (!Number.isFinite(handoffMs) || handoffMs < 0) {
@@ -674,11 +729,20 @@ export function makeDriveAgentTool(runner = defaultRunner, fixedCli, options = {
                 : process.cwd();
         const requestedCwd = normalizeCwdPath(rawRequestedCwd);
         const requestedWorkspaceRoot = await resolveDriveWorkspaceRoot(requestedCwd);
+        const declaredEffectiveWorkspaceCwd = typeof args.effectiveWorkspaceCwd === "string" && args.effectiveWorkspaceCwd.trim()
+            ? normalizeCwdPath(args.effectiveWorkspaceCwd)
+            : undefined;
+        const conflictCwd = declaredEffectiveWorkspaceCwd ?? requestedCwd;
+        const conflictWorkspaceRoot = conflictCwd === requestedCwd
+            ? requestedWorkspaceRoot
+            : await resolveDriveWorkspaceRoot(conflictCwd);
         const requestedIsolation = driveIsolationArg(args.isolation);
         const hasParallelWriter = !resumeSessionId &&
             isWritableRun &&
-            hasRunningDriveWriter(requestedCwd, requestedWorkspaceRoot);
-        let isolation = requestedIsolation ?? (hasParallelWriter ? "worktree" : "none");
+            hasRunningDriveWriter(conflictCwd, conflictWorkspaceRoot);
+        const canAutoIsolateEffectiveWorkspace = conflictWorkspaceRoot === requestedWorkspaceRoot;
+        let isolation = requestedIsolation ??
+            (hasParallelWriter && canAutoIsolateEffectiveWorkspace ? "worktree" : "none");
         let cwd = isolation === "current" && typeof ctx?.cwd === "string" && ctx.cwd
             ? normalizeCwdPath(ctx.cwd)
             : requestedCwd;
@@ -764,22 +828,16 @@ export function makeDriveAgentTool(runner = defaultRunner, fixedCli, options = {
                 workspaceRoot = managedWorktree.session.originalCwd;
             }
             catch (error) {
-                if (requestedIsolation === "worktree") {
-                    return `Error: failed to create DriveAgent isolation worktree: ${error instanceof Error ? error.message : String(error)}`;
-                }
-                isolation = "none";
-                cwd = requestedCwd;
-                workspaceRoot = requestedWorkspaceRoot;
-                resumeNote =
-                    `Note: parallel worktree isolation was unavailable; continuing in ${requestedCwd}. ` +
-                        `${error instanceof Error ? error.message : String(error)}`;
+                const detail = error instanceof Error ? error.message : String(error);
+                return requestedIsolation === "worktree"
+                    ? `Error: failed to create DriveAgent isolation worktree: ${detail}`
+                    : `Error: another writable DriveAgent already targets this workspace, and automatic worktree isolation failed. Refusing to run both writers in ${requestedCwd}: ${detail}`;
             }
         }
         const effectiveWorkspaceCwd = managedWorktree
             ? managedWorktree.session.worktreePath
-            : typeof args.effectiveWorkspaceCwd === "string" && args.effectiveWorkspaceCwd.trim()
-                ? normalizeCwdPath(args.effectiveWorkspaceCwd)
-                : cwd;
+            : (declaredEffectiveWorkspaceCwd ?? cwd);
+        const effectiveWorkspaceRoot = await resolveDriveWorkspaceRoot(effectiveWorkspaceCwd);
         // Default to bypassPermissions: this tool is a fire-one-turn delegation to
         // an external CLI with nobody watching for approvals, and there is no
         // interactive approval loop here — so under "default" a tool that needs
@@ -825,6 +883,7 @@ export function makeDriveAgentTool(runner = defaultRunner, fixedCli, options = {
                 cli,
                 cwd,
                 effectiveWorkspaceCwd,
+                effectiveWorkspaceRoot,
                 workspaceRoot,
                 isolation,
                 worktree: managedWorktree,
@@ -837,16 +896,30 @@ export function makeDriveAgentTool(runner = defaultRunner, fixedCli, options = {
                 recordExternalFileChanges: ctx?.recordExternalFileChanges,
                 originClientMessageId: ctx?.originClientMessageId,
             });
+            if ("error" in tracked) {
+                const lifecycle = safeFinalizeDriveWorktree(managedWorktree);
+                return appendLifecycleNote(tracked.error, lifecycle);
+            }
             ctx?.runYield?.request("background_notification");
             return [
                 resumeNote,
                 `已在后台启动 ${cliName}（jobId ${tracked.jobId}）。完成后会通知你结果，无需轮询。`,
                 worktreeStartNote(managedWorktree),
-                tracked.warning,
             ]
                 .filter(Boolean)
                 .join("\n");
         }
+        const lease = acquireForegroundDriveLease({
+            effectiveWorkspaceCwd,
+            effectiveWorkspaceRoot,
+            workspaceRoot,
+            label,
+            writable: isWritableRun,
+        });
+        if ("error" in lease) {
+            const lifecycle = safeFinalizeDriveWorktree(managedWorktree);
+            return appendLifecycleNote(lease.error, lifecycle);
+        }
         const foregroundAbort = makeAbortController(callerSignal, true);
         const run = startRun(runner, { ...runOptsBase, signal: foregroundAbort.signal });
         let result;
@@ -855,15 +928,21 @@ export function makeDriveAgentTool(runner = defaultRunner, fixedCli, options = {
         }
         catch (error) {
             const lifecycle = safeFinalizeDriveWorktree(managedWorktree);
+            lease.release();
             return appendLifecycleNote(`${cliName} 运行出错：${error instanceof Error ? error.message : String(error)}`, lifecycle);
         }
         if (result.kind === "handoff" && isValidSessionId(ctx?.sessionId)) {
+            // Registration below is synchronous. Release the foreground lease and
+            // replace it with the background registry entry in the same event-loop
+            // turn, so another dispatch cannot slip into a gap.
+            lease.release();
             const tracked = trackBackgroundRun({
                 sessionId: ctx.sessionId,
                 label,
                 cli,
                 cwd,
                 effectiveWorkspaceCwd,
+                effectiveWorkspaceRoot,
                 workspaceRoot,
                 isolation,
                 worktree: managedWorktree,
@@ -876,30 +955,39 @@ export function makeDriveAgentTool(runner = defaultRunner, fixedCli, options = {
                 recordExternalFileChanges: ctx?.recordExternalFileChanges,
                 originClientMessageId: ctx?.originClientMessageId,
             });
+            if ("error" in tracked) {
+                foregroundAbort.abort();
+                const lifecycle = safeFinalizeDriveWorktree(managedWorktree);
+                return appendLifecycleNote(tracked.error, lifecycle);
+            }
             ctx?.runYield?.request("background_notification");
             return [
                 resumeNote,
                 `${cliName} foreground run exceeded ${foregroundHandoffMs}ms; moved it to background (jobId ${tracked.jobId}). Completion will notify this session, so do not poll.`,
                 worktreeStartNote(managedWorktree),
-                tracked.warning,
             ]
                 .filter(Boolean)
                 .join("\n");
         }
-        const r = result.kind === "completed" ? result.result : await run;
-        const lifecycle = safeFinalizeDriveWorktree(managedWorktree);
-        recordSuccessfulSession(sessionStore, cli, cwd, r, {
-            codeShellSessionId: ctx?.sessionId,
-            workspaceRoot,
-            isolation,
-            worktree: managedWorktree,
-            lifecycle,
-        });
-        const prefix = resumeNote ? `${resumeNote}\n` : "";
-        const finalText = appendLifecycleNote(r.finalText, lifecycle);
-        if (r.isError)
-            return `${prefix}${cliName} 运行出错（session ${r.sessionId}）：\n${finalText}`;
-        return `${prefix}${cliName} 完成（session ${r.sessionId}）：\n${finalText}`;
+        try {
+            const r = result.kind === "completed" ? result.result : await run;
+            const lifecycle = safeFinalizeDriveWorktree(managedWorktree);
+            await recordSuccessfulSession(sessionStore, cli, cwd, r, {
+                codeShellSessionId: ctx?.sessionId,
+                workspaceRoot,
+                isolation,
+                worktree: managedWorktree,
+                lifecycle,
+            });
+            const prefix = resumeNote ? `${resumeNote}\n` : "";
+            const finalText = appendLifecycleNote(r.finalText, lifecycle);
+            if (r.isError)
+                return `${prefix}${cliName} 运行出错（session ${r.sessionId}）：\n${finalText}`;
+            return `${prefix}${cliName} 完成（session ${r.sessionId}）：\n${finalText}`;
+        }
+        finally {
+            lease.release();
+        }
     };
 }
 export const driveAgentTool = makeDriveAgentTool();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cjhyy/code-shell-capability-coding",
-  "version": "0.8.8",
+  "version": "0.8.10",
   "description": "Coding capability pack for the generic code-shell agent core.",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,12 +34,13 @@
   ],
   "scripts": {
     "build": "bun run clean && tsc -p tsconfig.json && bun run copy-assets",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
     "copy-assets": "node ../../scripts/copy-assets.mjs dist/prompt src/prompt/*.md && node ../../scripts/copy-assets.mjs dist/tools/apply-patch src/tools/apply-patch/NOTICE.md src/tools/apply-patch/LICENSE-codex",
     "dev": "bun run copy-assets && tsc -p tsconfig.json --watch --preserveWatchOutput",
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""
   },
   "dependencies": {
-    "@cjhyy/code-shell-core": "0.8.8"
+    "@cjhyy/code-shell-core": "0.8.10"
   },
   "engines": {
     "node": ">=20.10"
@@ -57,4 +58,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}