@cjhyy/code-shell-core 0.9.0 → 0.9.1

package/dist/engine/engine-workspace-authority.d.ts

@@ -2,12 +2,27 @@ import type { SessionProjectBinding, SessionState, SessionWorkspace } from "../t
 import { type SessionManager } from "../session/session-manager.js";
 import type { SessionMessageRouter, SessionMessageToolService } from "../session/session-message.js";
 import { type WorkspaceContext } from "../workspace/workspace-context.js";
+export interface SyntheticRunWorkspace {
+    cwd: string;
+    workspaceContext?: WorkspaceContext;
+}
 export declare class SessionWorkspaceAuthorityTracker {
     private readonly contexts;
     remember(sessionId: string, context: WorkspaceContext): void;
+    get(sessionId: string): WorkspaceContext | undefined;
     delete(sessionId: string): void;
     clear(): void;
 }
+/**
+ * Reconstruct authoritative options for a core-originated continuation.
+ * Interactive turns carry a fresh WorkspaceContext from their host, whereas
+ * background-result wakeups must rebase the last trusted context onto the
+ * SessionWorkspace persisted after a worktree switch.
+ */
+export declare function resolveSyntheticRunWorkspace(sessionManager: SessionManager, authorities: SessionWorkspaceAuthorityTracker, config: {
+    cwd?: string;
+    workspaceContext?: WorkspaceContext;
+}, sessionId: string): SyntheticRunWorkspace;
 export declare function createAuthorizedSessionMessageService(options: {
     sessionManager: SessionManager;
     router: SessionMessageRouter | undefined;

package/dist/engine/engine-workspace-authority.js

@@ -1,7 +1,7 @@
 import { assertSafeSessionId } from "../session/session-manager.js";
 import { clearSessionPathApprovalsUnderRoot } from "../tool-system/path-policy.js";
 import { canonicalKey } from "../workspace/canonical-key.js";
-import { removedWorkspaceRootPaths, } from "../workspace/workspace-context.js";
+import { rebaseWorkspacePrimaryRoot, removedWorkspaceRootPaths, } from "../workspace/workspace-context.js";
 export class SessionWorkspaceAuthorityTracker {
     contexts = new Map();
     remember(sessionId, context) {
@@ -13,6 +13,9 @@ export class SessionWorkspaceAuthorityTracker {
         }
         this.contexts.set(sessionId, context);
     }
+    get(sessionId) {
+        return this.contexts.get(sessionId);
+    }
     delete(sessionId) {
         this.contexts.delete(sessionId);
     }
@@ -20,6 +23,34 @@ export class SessionWorkspaceAuthorityTracker {
         this.contexts.clear();
     }
 }
+/**
+ * Reconstruct authoritative options for a core-originated continuation.
+ * Interactive turns carry a fresh WorkspaceContext from their host, whereas
+ * background-result wakeups must rebase the last trusted context onto the
+ * SessionWorkspace persisted after a worktree switch.
+ */
+export function resolveSyntheticRunWorkspace(sessionManager, authorities, config, sessionId) {
+    const workspace = sessionManager.getSessionWorkspace(sessionId);
+    const cwd = workspace?.root ?? sessionManager.readSessionMainRoot(sessionId) ?? config.cwd ?? process.cwd();
+    const binding = sessionManager.readSessionProjectBinding(sessionId);
+    const baseContext = authorities.get(sessionId) ?? config.workspaceContext;
+    // A legacy Session with no host authority must stay legacy. Passing a
+    // synthesized prior-run context would persist a spurious project binding.
+    if (!binding && !config.workspaceContext)
+        return { cwd };
+    if (!baseContext) {
+        throw new Error(`Session ${sessionId} has a project binding but no WorkspaceContext`);
+    }
+    if (binding &&
+        (binding.projectId !== baseContext.projectId ||
+            binding.mainRootId !== baseContext.sessionMainRootId)) {
+        throw new Error(`Session ${sessionId} WorkspaceContext does not match its project binding`);
+    }
+    return {
+        cwd,
+        workspaceContext: rebaseWorkspacePrimaryRoot(baseContext, cwd),
+    };
+}
 export function createAuthorizedSessionMessageService(options) {
     const { sessionManager, router, sourceSessionId } = options;
     const sourceRoot = sessionManager.readSessionMainRoot(sourceSessionId);

package/dist/engine/engine.d.ts

@@ -10,6 +10,7 @@ import { type GoalConfig, type GoalExtension } from "../goal/lifecycle.js";
 import { type CompactStrategy } from "../context/manager.js";
 import { SessionManager, type ForkSessionOptions, type ForkSessionResult, type SummaryForkOptions } from "../session/session-manager.js";
 import type { SessionMessageRouter } from "../session/session-message.js";
+import { type SyntheticRunWorkspace } from "./engine-workspace-authority.js";
 import type { AskUserFn } from "../tool-system/builtin/ask-user.js";
 import type { CapabilityOverride, CapabilityOverrides } from "../settings/schema.js";
 import { type FeatureFlagName } from "../settings/feature-flags.js";
@@ -495,6 +496,7 @@ export declare class Engine {
     getCurrentModel(): string;
     getHookRegistry(): HookRegistry;
     getSessionManager(): SessionManager;
+    resolveSessionRunWorkspace(sessionId: string): SyntheticRunWorkspace;
     /**
      * Apply a field-level disk update and rebase this Engine's matching live
      * bundle onto the returned revision so its next whole-state CAS can proceed.

package/dist/engine/engine.js

@@ -23,7 +23,7 @@ import { ContextManager } from "../context/manager.js";
 import { CONTEXT_PACKAGE_MAX_OUTPUT_TOKENS, buildAnchoredSummaryMessage, buildContextPackagePromptFromSerialized, estimateTokens, groupMessagesByApiRound, serializeContextPackageMessages, clampContextRatios as clampContextRatiosImpl, } from "../context/compaction.js";
 import { PromptComposer } from "../prompt/composer.js";
 import { SessionManager, isEphemeralSessionState, sessionsRoot, } from "../session/session-manager.js";
-import { createAuthorizedSessionMessageService, migrateOwnedSessionMainRoot, releaseOwnedSessionWorkspace, SessionWorkspaceAuthorityTracker, setOwnedSessionWorkspace, } from "./engine-workspace-authority.js";
+import { createAuthorizedSessionMessageService, migrateOwnedSessionMainRoot, releaseOwnedSessionWorkspace, resolveSyntheticRunWorkspace, SessionWorkspaceAuthorityTracker, setOwnedSessionWorkspace, } from "./engine-workspace-authority.js";
 import { createRunUsageAccounting, wireRunModelFacade } from "./run-accounting.js";
 import { logger, runWithSid } from "../logging/logger.js";
 import { recordSessionStart } from "../logging/session-recorder.js";
@@ -2404,6 +2404,9 @@ export class Engine {
     getSessionManager() {
         return this.sessionManager;
     }
+    resolveSessionRunWorkspace(sessionId) {
+        return resolveSyntheticRunWorkspace(this.sessionManager, this.workspaceAuthorities, this.config, sessionId);
+    }
     /**
      * Apply a field-level disk update and rebase this Engine's matching live
      * bundle onto the returned revision so its next whole-state CAS can proceed.

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  *
  * Public API exports.
  */
-export declare const VERSION = "0.9.0";
+export declare const VERSION = "0.9.1";
 export type { Message, ContentBlock, ToolDefinition, ToolCall, ToolResult, RegisteredTool, TranscriptEvent, TranscriptEventType, SessionState, SessionKind, SessionWorkspace, SessionProjectBinding, SessionForkLineage, ContextUsageAnchor, SessionStatus, TokenUsage, CompiledInput, PermissionDecision, PermissionMode, PermissionRule, TurnPhase, TurnResult, TerminalReason, TurnCompletionKind, StreamEvent, StreamCallback, LLMConfig, ClientDefaults, LLMResponse, Settings, MCPServerConfig, } from "./types.js";
 export type { GoalConfig, GoalLifecycleConfig, GoalLifecyclePhase, GoalLifecycleTerminalReason, GoalLifecycleV1, } from "./goal/lifecycle.js";
 export { FrameworkError, LLMError, LLMRateLimitError, ContextLimitError, ToolError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError, PermissionDeniedError, SessionError, TranscriptError, ConfigError, CompositionError, SandboxUnavailableError, } from "./exceptions.js";

package/dist/index.js

@@ -3,7 +3,7 @@
  *
  * Public API exports.
  */
-export const VERSION = "0.9.0";
+export const VERSION = "0.9.1";
 // ─── Exceptions ──────────────────────────────────────────────────
 export { FrameworkError, LLMError, LLMRateLimitError, ContextLimitError, ToolError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError, PermissionDeniedError, SessionError, TranscriptError, ConfigError, CompositionError, SandboxUnavailableError, } from "./exceptions.js";
 // ─── Composition (AgentModule / ResolvedComposition) ─────────────

package/dist/protocol/background-result-wakeup.d.ts

@@ -0,0 +1,18 @@
+import type { StreamEvent } from "../types.js";
+import type { ApprovalRouter } from "../tool-system/permission.js";
+import type { ChatSession } from "./chat-session.js";
+import type { ChatSessionManager } from "./chat-session-manager.js";
+interface BackgroundResultWakeOptions {
+    sessionId: string;
+    manager: ChatSessionManager | null;
+    rehydrate(sessionId: string): Promise<ChatSession | null>;
+    approvalRouter: ApprovalRouter;
+    onStream(event: StreamEvent): void;
+}
+/**
+ * Drain pending background results into exactly one synthetic continuation.
+ * Busy sessions are awaited so a completion cannot fall into the gap between
+ * the notification bus callback and the interactive run-boundary re-check.
+ */
+export declare function wakeSessionForBackgroundResults({ sessionId, manager, rehydrate, approvalRouter, onStream, }: BackgroundResultWakeOptions): Promise<boolean>;
+export {};

package/dist/protocol/background-result-wakeup.js

@@ -0,0 +1,101 @@
+import { logger } from "../logging/logger.js";
+import { buildNotificationMessage, notificationQueue, } from "../tool-system/builtin/agent-notifications.js";
+/**
+ * Drain pending background results into exactly one synthetic continuation.
+ * Busy sessions are awaited so a completion cannot fall into the gap between
+ * the notification bus callback and the interactive run-boundary re-check.
+ */
+export async function wakeSessionForBackgroundResults({ sessionId, manager, rehydrate, approvalRouter, onStream, }) {
+    if (!manager) {
+        logger.debug("bg_wakeup.skipped", { sessionId, reason: "no_chat_manager" });
+        return false;
+    }
+    if (manager.isUnavailable(sessionId)) {
+        logger.debug("bg_wakeup.skipped", { sessionId, reason: "session_unavailable" });
+        return false;
+    }
+    let session = manager.get(sessionId) ?? (await rehydrate(sessionId));
+    if (!session) {
+        logger.debug("bg_wakeup.skipped", { sessionId, reason: "session_missing" });
+        return false;
+    }
+    while (session.isBusy()) {
+        logger.debug("bg_wakeup.waiting_for_idle", {
+            sessionId,
+            pendingCount: notificationQueue.getSnapshot(sessionId).length,
+        });
+        await session.settled;
+        if (manager.isUnavailable(sessionId)) {
+            logger.debug("bg_wakeup.skipped", {
+                sessionId,
+                reason: "session_became_unavailable",
+            });
+            return false;
+        }
+        const current = manager.get(sessionId);
+        if (!current) {
+            logger.debug("bg_wakeup.skipped", { sessionId, reason: "session_evicted_after_settle" });
+            return false;
+        }
+        session = current;
+    }
+    // Headless/automation runs are one-shot and have no continuation consumer.
+    if (session.engine.isHeadless()) {
+        logger.debug("bg_wakeup.skipped", { sessionId, reason: "headless" });
+        return false;
+    }
+    // A user Stop must win over a later background completion.
+    if (session.wasCancelledSinceLastTurn()) {
+        logger.debug("bg_wakeup.skipped", { sessionId, reason: "cancelled_since_last_turn" });
+        return false;
+    }
+    let runWorkspace = {};
+    try {
+        const resolver = session.engine.resolveSessionRunWorkspace;
+        runWorkspace = resolver?.call(session.engine, sessionId) ?? {};
+    }
+    catch (error) {
+        // Resolve before draining so an unavailable authoritative worktree context
+        // leaves the completion recoverable by a later user run.
+        logger.warn("bg_wakeup.workspace_unavailable", {
+            sessionId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return false;
+    }
+    const pending = notificationQueue.drainAll(sessionId);
+    if (pending.length === 0) {
+        logger.debug("bg_wakeup.skipped", { sessionId, reason: "no_pending_results" });
+        return false;
+    }
+    const task = `<system-reminder>\n${buildNotificationMessage(pending)}\n</system-reminder>`;
+    try {
+        const result = await session.enqueueTurn(task, {
+            injected: true,
+            ...runWorkspace,
+            onStream,
+            approvalRouter,
+        });
+        if (result.turnCount === 0) {
+            const restored = notificationQueue.restoreResults(sessionId, pending);
+            logger.warn("bg_wakeup.turn_not_started", {
+                sessionId,
+                restored,
+                reason: result.reason,
+                text: result.text.slice(0, 500),
+            });
+            return false;
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const restored = notificationQueue.restoreResults(sessionId, pending);
+        logger.warn("bg_wakeup.turn_failed", { sessionId, error: message, restored });
+        // A setup failure can occur before the turn loop emits its own terminal
+        // event. Emit an error so every renderer clears its busy state, but keep
+        // the result queued so a later user turn can consume it safely.
+        onStream({ type: "error", error: message || "background wakeup failed" });
+        return false;
+    }
+    return true;
+}

package/dist/protocol/server.d.ts

@@ -218,10 +218,10 @@ export declare class AgentServer {
      * Guards:
      * - chatManager path only (the legacy single-engine / headless path drives
      *   its own loop and has no idle-session-resume concept).
-     * - Session must exist AND be idle. If it's busy, we do nothing: the in-flight
-     *   run's end-of-turn `drainAll` already collects every pending notification,
-     *   so a second run would be redundant — and `enqueueTurn` while busy would
-     *   queue a spurious extra turn.
+     * - Session must exist. If it is busy, keep ownership of this wake request and
+     *   wait for `settled` before draining. Merely returning here loses a wake when
+     *   the bus event races the run-boundary re-check: both triggers can observe
+     *   the other as in-flight and leave the result queued forever.
      * - We `drainAll` exactly here and feed the items into the woken turn. This
      *   also merges a burst of near-simultaneous completions into one wakeup:
      *   the first drains all currently-pending items; subsequent bus events for

package/dist/protocol/server.js

@@ -18,12 +18,13 @@ import { diskDefaultsFrom } from "../engine/engine.js";
 import { ISOLATED_TASK_BEHAVIOR_MODE } from "../engine/run-types.js";
 import { isProtectedSettingKey, SettingsManager } from "../settings/manager.js";
 import { getApprovalRouter, getInteractiveApprovalBackend, } from "../tool-system/permission.js";
-import { agentNotificationBus, notificationQueue, buildNotificationMessage, notificationEnvelopeToLegacyStreamEvent, } from "../tool-system/builtin/agent-notifications.js";
+import { agentNotificationBus, notificationQueue, notificationEnvelopeToLegacyStreamEvent, } from "../tool-system/builtin/agent-notifications.js";
 import { backgroundShellManager } from "../runtime/background-shell.js";
 import { backgroundJobRegistry } from "../tool-system/builtin/background-jobs.js";
 import { listBackgroundWorkForUI } from "../tool-system/builtin/background-work.js";
 import { logger } from "../logging/logger.js";
 import { nanoid } from "nanoid";
+import { wakeSessionForBackgroundResults } from "./background-result-wakeup.js";
 import { assertSafeSessionId, SessionManager } from "../session/session-manager.js";
 import { redactLlmConfig, maskSecretValue } from "./redact.js";
 import { redactSecrets } from "../logging/sanitize-messages.js";
@@ -498,22 +499,29 @@ export class AgentServer {
         // hands us.
         this.bgAgentBusUnsubscribe = agentNotificationBus.subscribe((envelope) => {
             const sessionId = envelope.to.sessionId;
-            const event = notificationEnvelopeToLegacyStreamEvent(envelope);
-            if (event)
-                this.notify(Methods.StreamEvent, { sessionId, event });
-            // Background work that finishes while the session is IDLE (a
+            try {
+                const event = notificationEnvelopeToLegacyStreamEvent(envelope);
+                if (event)
+                    this.notify(Methods.StreamEvent, { sessionId, event });
+            }
+            finally {
+                // Waking the model is the durable-consumption path; forwarding the
+                // legacy UI event is only an observation path. A renderer transport
+                // failure after accepting the event must not strand the result in the
+                // queue, so schedule the wake from finally.
+                if (envelope.kind === "result")
+                    this.maybeWakeIdleSession(sessionId);
+            }
+            // Background work that finishes while the session is idle (a
             // run_in_background Bash like a download, a background sub-agent, or a
             // video poll — the engine no longer parks on any of them) would otherwise
             // leave its completion sitting in the queue until the user manually sends.
             // Wake the session with one run carrying the notification so the model
             // reads "download complete" and continues on its own (the persisted goal
             // is judged that turn). If the work finishes while a run is still in
-            // flight, the idle guard below skips it and the run-boundary re-check
-            // (trigger B) drains it at end-of-turn instead. A never-exiting dev server
-            // emits no completion, so it never wakes anything (no task/service
-            // classification needed).
-            if (envelope.kind === "result")
-                this.maybeWakeIdleSession(sessionId);
+            // flight, wakeIdleSession waits for that run to settle and then queues the
+            // continuation. A never-exiting dev server emits no completion, so it
+            // never wakes anything (no task/service classification needed).
         });
         // Notify client we're ready
         this.notify(Methods.Status, { status: "ready" });
@@ -527,10 +535,10 @@ export class AgentServer {
      * Guards:
      * - chatManager path only (the legacy single-engine / headless path drives
      *   its own loop and has no idle-session-resume concept).
-     * - Session must exist AND be idle. If it's busy, we do nothing: the in-flight
-     *   run's end-of-turn `drainAll` already collects every pending notification,
-     *   so a second run would be redundant — and `enqueueTurn` while busy would
-     *   queue a spurious extra turn.
+     * - Session must exist. If it is busy, keep ownership of this wake request and
+     *   wait for `settled` before draining. Merely returning here loses a wake when
+     *   the bus event races the run-boundary re-check: both triggers can observe
+     *   the other as in-flight and leave the result queued forever.
      * - We `drainAll` exactly here and feed the items into the woken turn. This
      *   also merges a burst of near-simultaneous completions into one wakeup:
      *   the first drains all currently-pending items; subsequent bus events for
@@ -551,67 +559,22 @@ export class AgentServer {
                 this.maybeWakeIdleSession(sessionId);
             }
         })
-            .catch(() => {
+            .catch((error) => {
             this.wakeupsInFlight.delete(sessionId);
+            logger.warn("bg_wakeup.failed", {
+                sessionId,
+                error: error instanceof Error ? error.message : String(error),
+            });
         });
     }
     async wakeIdleSession(sessionId) {
-        if (!this.chatManager)
-            return false;
-        if (this.chatManager.isUnavailable(sessionId))
-            return false;
-        const session = this.chatManager.get(sessionId) ?? (await this.rehydrateSessionForWake(sessionId));
-        if (!session || session.isBusy())
-            return false;
-        // Headless / automation runs are one-shot: the caller takes result.text and
-        // is gone, so there's no consumer for a woken continuation turn. Headless
-        // already drained its background sub-agents inside engine.run before
-        // returning; any remaining queued notification (video/shell) must NOT spin
-        // an orphan turn. Only the interactive path auto-continues.
-        if (session.engine.isHeadless())
-            return false;
-        // Don't resurrect a session the user just Stopped: cancel() leaves it idle
-        // (active=null) so isBusy() reads false, but auto-running a fresh turn here
-        // would defeat the Stop. The flag clears the moment the user sends again.
-        if (session.wasCancelledSinceLastTurn())
-            return false;
-        const pending = notificationQueue.drainAll(sessionId);
-        if (pending.length === 0)
-            return false;
-        const task = `<system-reminder>\n${buildNotificationMessage(pending)}\n</system-reminder>`;
-        try {
-            await session.enqueueTurn(task, {
-                // Synthetic notification, not the user's own input: persisted with an
-                // `injected` flag so a disk rebuild doesn't render it as a phantom user
-                // bubble (the live UI shows only the woken assistant's reply).
-                injected: true,
-                onStream: (event) => this.notify(Methods.StreamEvent, { sessionId, event }),
-                approvalRouter: this.approvalRouter,
-            });
-        }
-        catch (err) {
-            // A wakeup turn failing must not crash the bus fan-out. The drained
-            // notifications are already in the transcript via the run's messages;
-            // log and move on.
-            logger.warn("bg_wakeup.turn_failed", {
-                sessionId,
-                error: err.message,
-            });
-            // Belt-and-braces, mirroring the send() path's run().then(clear-busy):
-            // the renderer set the composer "working" spinner on this run's
-            // session_started, and clears it on turn_complete/error. A failure
-            // BEFORE the turn-loop runs (e.g. a setup error) emits neither, which
-            // would leave the spinner stuck. Emit a terminal `error` (NOT a
-            // turn_complete) so the renderer clears busy AND a woken automation
-            // session's runStatus flips to "failed" rather than being mislabeled
-            // "completed". If the turn-loop already emitted its own `error`, this is
-            // a harmless duplicate (busy already cleared, status already failed).
-            this.notify(Methods.StreamEvent, {
-                sessionId,
-                event: { type: "error", error: err?.message ?? "background wakeup failed" },
-            });
-        }
-        return true;
+        return wakeSessionForBackgroundResults({
+            sessionId,
+            manager: this.chatManager,
+            rehydrate: (id) => this.rehydrateSessionForWake(id),
+            approvalRouter: this.approvalRouter,
+            onStream: (event) => this.notify(Methods.StreamEvent, { sessionId, event }),
+        });
     }
     async rehydrateSessionForWake(sessionId) {
         if (!this.chatManager)
@@ -1286,11 +1249,12 @@ export class AgentServer {
                 petWorkDelegation: result.petWorkDelegation,
             };
             this.transport.send(createResponse(req.id, runResult));
-            // Run-boundary re-check (trigger B): the session is idle now. If a
-            // background task (shell/video) completed DURING this run, its bus event
-            // fired while we were busy and trigger A skipped it — drain it now and
-            // wake a continuation turn. Interactive path only; headless already
-            // drained its sub-agents inside engine.run before returning.
+            // Run-boundary re-check (trigger B): normally trigger A already owns a
+            // completion that arrived while this run was busy and is waiting on the
+            // session's `settled` promise. Keep this check as a recovery path for a
+            // missed/delayed bus event and for results committed at the run boundary.
+            // Interactive path only; headless already drained its sub-agents inside
+            // engine.run before returning.
             this.maybeWakeIdleSession(sid);
         }
         catch (err) {

package/dist/settings/manager.d.ts

@@ -192,6 +192,13 @@ export declare class SettingsManager {
     /** Resolve the project root once and refuse a linked/non-directory state root. */
     private tryProjectSettingsPath;
     private readJsonObject;
+    /**
+     * Same resolution as readJsonObject (JSON wins, sibling YAML is folded in),
+     * but a resolved file that cannot be read as a bounded object THROWS instead
+     * of degrading to {}. Only the read-modify-write path uses this: rewriting
+     * the whole object off a silently-empty read destroys the file's contents.
+     */
+    private readJsonObjectForMutation;
     private atomicWriteJson;
     private writeBackup;
     /**

package/dist/settings/manager.js

@@ -367,7 +367,11 @@ export class SettingsManager {
         // from the added serialization.
         const release = acquireFileLock(path);
         try {
-            const current = parseConfigFile(path) ?? {};
+            // Strict read: an existing-but-unreadable user settings file must abort
+            // the write rather than be rewritten from {}. This file can hold plaintext
+            // API keys, so silently replacing it with just the new key is the worst
+            // possible outcome. See readConfigFileForMutation.
+            const current = readConfigFileForMutation(path) ?? {};
             setDottedSetting(current, key, value);
             // Atomic write: stage to .tmp, then rename, so a concurrent read can't
             // catch a half-written file. mode 0o600 — settings.json can hold plaintext
@@ -575,6 +579,29 @@ export class SettingsManager {
             return {};
         return parseConfigFile(resolved) ?? {};
     }
+    /**
+     * Same resolution as readJsonObject (JSON wins, sibling YAML is folded in),
+     * but a resolved file that cannot be read as a bounded object THROWS instead
+     * of degrading to {}. Only the read-modify-write path uses this: rewriting
+     * the whole object off a silently-empty read destroys the file's contents.
+     */
+    readJsonObjectForMutation(path) {
+        const resolved = resolveConfigPath(path);
+        if (!resolved) {
+            // resolveConfigPath returns null both for "no candidate exists" and for
+            // "a candidate exists but is unsafe" (symlink, non-file, or over the size
+            // bound). Only the former may start from {}; the latter must not be
+            // overwritten, so re-check the candidates before deciding.
+            for (const candidate of settingsCandidatePaths(path)) {
+                if (existsSync(candidate)) {
+                    throw new Error(`settings file exists but could not be read as a valid, bounded object: ${candidate}. ` +
+                        `Refusing to overwrite it. Fix or move the file, then retry.`);
+                }
+            }
+            return {};
+        }
+        return readConfigFileForMutation(resolved) ?? {};
+    }
     atomicWriteJson(path, data) {
         assertSafeSettingsWriteTarget(path);
         const serialized = JSON.stringify(data, null, 2);
@@ -616,8 +643,10 @@ export class SettingsManager {
         try {
             assertSafeSettingsWriteTarget(path);
             // Re-read INSIDE the lock: a snapshot taken before acquiring it would be
-            // exactly the stale value that drops the other writer's key.
-            const current = this.readJsonObject(path);
+            // exactly the stale value that drops the other writer's key. Strict read:
+            // an existing-but-unreadable file must abort the mutation rather than be
+            // rewritten from {} — see readConfigFileForMutation.
+            const current = this.readJsonObjectForMutation(path);
             if (mutate(current) === false)
                 return;
             this.atomicWriteJson(path, current);
@@ -698,6 +727,38 @@ function parseConfigFile(path) {
     }
     return null;
 }
+/**
+ * Strict counterpart of `parseConfigFile` for the read-modify-write path.
+ *
+ * A mutation rewrites the WHOLE object, so it must be able to tell "absent"
+ * (start from {}) from "present but unreadable" (malformed, oversize, or
+ * otherwise unreadable). `parseConfigFile` deliberately folds every one of
+ * those to null so an ordinary load can skip a corrupt layer and still boot —
+ * but a writer that treats null as {} silently replaces the user's file with
+ * an object holding only the new key. Fail closed here instead; the caller's
+ * lock is still held, so the file is left byte-for-byte untouched.
+ *
+ * Returns undefined only when the file genuinely does not exist.
+ */
+function readConfigFileForMutation(path) {
+    if (!existsSync(path))
+        return undefined;
+    const parsed = parseConfigFile(path);
+    if (parsed === null) {
+        // Deliberately does not include the file's contents — settings may hold
+        // plaintext credentials and this message reaches tool output.
+        throw new Error(`settings file exists but could not be read as a valid, bounded object: ${path}. ` +
+            `Refusing to overwrite it. Fix or move the file, then retry.`);
+    }
+    return parsed;
+}
+/** The .json path plus the sibling YAML paths resolveConfigPath would consider,
+ *  in the same precedence order. Used by the mutation path to tell "nothing is
+ *  there" from "something is there but unsafe to read". */
+function settingsCandidatePaths(jsonPath) {
+    const base = jsonPath.replace(/\.json$/, "");
+    return [jsonPath, `${base}.yaml`, `${base}.yml`];
+}
 /** Read through a no-follow descriptor so a settings-file symlink cannot escape its layer. */
 function readBoundedRegularFile(path) {
     let fd;

package/dist/tool-system/builtin/agent-notifications.d.ts

@@ -132,6 +132,14 @@ declare class NotificationQueue {
     drain(sessionId: string, predicate: (envelope: NotificationEnvelope) => boolean): NotificationEnvelope[];
     /** Compatibility consumer: only terminal results, never direction/progress. */
     drainAll(sessionId: string): ResultEnvelope[];
+    /**
+     * Restore terminal results that a consumer drained but could not deliver.
+     * Existing envelopes retain their ids/sequences and are prepended ahead of
+     * results that arrived during the failed delivery attempt. This is an
+     * internal mailbox rollback, so it deliberately does not republish bus
+     * events (which would recursively schedule another wake immediately).
+     */
+    restoreResults(sessionId: string, envelopes: readonly ResultEnvelope[]): number;
     clearProgress(sessionId: string, agentId: string, runtimeGeneration?: number): boolean;
     clearDirections(sessionId: string, runtimeGeneration: number): boolean;
     reset(sessionId?: string): void;

package/dist/tool-system/builtin/agent-notifications.js

@@ -191,6 +191,25 @@ class NotificationQueue {
     drainAll(sessionId) {
         return this.drain(sessionId, (item) => item.kind === "result");
     }
+    /**
+     * Restore terminal results that a consumer drained but could not deliver.
+     * Existing envelopes retain their ids/sequences and are prepended ahead of
+     * results that arrived during the failed delivery attempt. This is an
+     * internal mailbox rollback, so it deliberately does not republish bus
+     * events (which would recursively schedule another wake immediately).
+     */
+    restoreResults(sessionId, envelopes) {
+        if (!isValidSessionId(sessionId) || envelopes.length === 0)
+            return 0;
+        const bucket = this.buckets.get(sessionId) ?? [];
+        const ids = new Set(bucket.map((item) => item.id));
+        const restored = envelopes.filter((item) => item.kind === "result" && item.to.sessionId === sessionId && !ids.has(item.id));
+        if (restored.length === 0)
+            return 0;
+        this.buckets.set(sessionId, [...restored, ...bucket]);
+        this.notify();
+        return restored.length;
+    }
     clearProgress(sessionId, agentId, runtimeGeneration) {
         const bucket = this.buckets.get(sessionId);
         if (!bucket?.length)

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

@@ -2,6 +2,17 @@
  * ConfigTool — read or update project settings.
  */
 import type { ToolDefinition } from "../../types.js";
+import { SettingsManager } from "../../settings/manager.js";
 import type { ToolContext } from "../context.js";
 export declare const configToolDef: ToolDefinition;
+export interface ConfigToolDeps {
+    makeSettingsManager(cwd: string, scope: "full" | "project"): SettingsManager;
+    /** Test seam: awaited inside the write path, after the key/value checks and
+     *  before the value is persisted, so a test can park one writer in the
+     *  read→write window and drive a deterministic interleaving. */
+    beforeWrite?: () => Promise<void>;
+}
+/** Factory so tests can inject a SettingsManager (barrier/fake); production
+ *  uses the default instance-per-call, matching the other builtins. */
+export declare function makeConfigTool(deps?: ConfigToolDeps): (args: Record<string, unknown>, ctx?: ToolContext) => Promise<string>;
 export declare function configTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;

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

@@ -1,9 +1,9 @@
 /**
  * ConfigTool — read or update project settings.
  */
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { setDottedSetting } from "../../settings/manager.js";
+import { SettingsManager, setDottedSetting } from "../../settings/manager.js";
 import { enforcePathPolicyWithApproval } from "../path-policy.js";
 export const configToolDef = {
     name: "Config",
@@ -28,7 +28,20 @@ export const configToolDef = {
         required: ["action"],
     },
 };
+const DEFAULT_DEPS = {
+    makeSettingsManager: (cwd, scope) => new SettingsManager(cwd, scope),
+};
+/** Factory so tests can inject a SettingsManager (barrier/fake); production
+ *  uses the default instance-per-call, matching the other builtins. */
+export function makeConfigTool(deps = DEFAULT_DEPS) {
+    return async function configTool(args, ctx) {
+        return runConfigTool(args, ctx, deps);
+    };
+}
 export async function configTool(args, ctx) {
+    return runConfigTool(args, ctx, DEFAULT_DEPS);
+}
+async function runConfigTool(args, ctx, deps) {
     const action = args.action;
     const cwd = ctx?.cwd ?? process.cwd();
     const configPath = join(cwd, ".code-shell", "settings.json");
@@ -52,18 +65,18 @@ export async function configTool(args, ctx) {
             return "Error: 'key' is required for write action.";
         if (value === undefined)
             return "Error: 'value' is required for write action.";
-        // Read or create settings
-        let settings = {};
-        if (existsSync(configPath)) {
-            settings = JSON.parse(readFileSync(configPath, "utf-8"));
-        }
+        // Validate the key BEFORE touching disk, preserving the existing contract
+        // that an unsafe dotted key is rejected without creating settings.json.
+        // setDottedSetting is the same validator saveProjectSetting applies inside
+        // the lock; running it here on a throwaway object only surfaces the error.
         try {
-            setDottedSetting(settings, key, value);
+            setDottedSetting({}, key, value);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             return `Error: ${message}`;
         }
+        await deps.beforeWrite?.();
         // Never resurrect a deleted project root: a recursive mkdir of
         // <cwd>/.code-shell would recreate `cwd` itself as an empty shell when the
         // directory has been deleted (e.g. a stale session pointing at a removed
@@ -71,8 +84,40 @@ export async function configTool(args, ctx) {
         if (!existsSync(cwd)) {
             return `Error: project directory does not exist: ${cwd}`;
         }
-        mkdirSync(join(cwd, ".code-shell"), { recursive: true });
-        writeFileSync(configPath, JSON.stringify(settings, null, 2), "utf-8");
+        // Persist through SettingsManager rather than a hand-rolled
+        // read → modify → writeFileSync. That path had no lock and no temp+rename,
+        // so two writers that both read before either wrote each persisted their
+        // own stale snapshot and silently dropped the other's key (the class
+        // documented in utils/file-mutex.ts). saveProjectSetting re-reads inside
+        // the lock, writes atomically, and invalidates the merged cache so a
+        // following read sees this write.
+        //
+        // Side effect worth knowing about on a YAML-configured project:
+        // SettingsManager reads a sibling settings.yaml when settings.json is
+        // absent but always writes back JSON, so the first write folds the YAML
+        // content into a new settings.json and the now-shadowed YAML is left on
+        // disk. That is SettingsManager's established behaviour for every caller,
+        // and it is strictly better than what this tool used to do (write the one
+        // new key and lose the YAML content entirely) — so it is inherited
+        // deliberately rather than special-cased here.
+        //
+        // saveProjectSetting throws on a hostile state dir (a `.code-shell` that is
+        // a file or a link) and on an existing-but-unreadable settings file, where
+        // it refuses to overwrite rather than rewrite from {}. The old hand-rolled
+        // write also threw on those inputs, but let the exception escape; every
+        // other failure in this tool is reported as a string, so convert it here.
+        //
+        // Note the file mode also changed: the old writeFileSync left settings.json
+        // at the umask default (typically 0644), while SettingsManager writes 0600.
+        // settings.json can hold plaintext API keys, so owner-only is the intended
+        // posture — an existing world-readable file is tightened on its next write.
+        try {
+            deps.makeSettingsManager(cwd, "project").saveProjectSetting(key, value, cwd);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return `Error: ${message}`;
+        }
         return `Updated ${key} = ${JSON.stringify(value)}`;
     }
     return `Unknown action: ${action}. Use 'read' or 'write'.`;

package/dist/tool-system/builtin/view-image.js

@@ -39,7 +39,8 @@ export const viewImageToolDef = {
             },
             imageNumber: {
                 type: "number",
-                description: "Image history number N from an earlier [image #N, already provided] placeholder.",
+                description: "Positive image history number N from an earlier [image #N, already provided] " +
+                    "placeholder. Omit this field entirely when path is provided; do not send 0.",
             },
             detail: {
                 type: "string",
@@ -53,7 +54,12 @@ export async function viewImageTool(args, ctx) {
     const rawPath = args.path;
     const rawImageNumber = args.imageNumber;
     const hasPath = typeof rawPath === "string" && rawPath.trim().length > 0;
-    const hasImageNumber = rawImageNumber !== undefined && rawImageNumber !== null;
+    const hasImageNumberInput = rawImageNumber !== undefined && rawImageNumber !== null;
+    // Some tool-calling models materialize every optional numeric property with
+    // a zero sentinel. With a real path, imageNumber: 0 unambiguously means
+    // "unused" because valid history numbers start at 1. Accept that one
+    // compatibility shape while keeping path + a real image number forbidden.
+    const hasImageNumber = hasImageNumberInput && !(hasPath && rawImageNumber === 0);
     if (hasPath === hasImageNumber) {
         return "Error: provide exactly one of path or imageNumber";
     }

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

@@ -22,5 +22,14 @@ export declare function validateWorkspaceContext(value: unknown): WorkspaceConte
 /** 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;
+/**
+ * Rebase only the Session's primary runtime path while preserving the host's
+ * authoritative project/root identities and the mounted secondary roots.
+ *
+ * A worktree switch changes where the primary root executes; it does not mint
+ * a new project or root id. Rebuilding through createWorkspaceContext also
+ * recomputes rootsDigest and re-runs the overlap/absolute-path validation.
+ */
+export declare function rebaseWorkspacePrimaryRoot(context: WorkspaceContext, primaryPath: string): WorkspaceContext;
 /** 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

@@ -103,6 +103,22 @@ export function legacySingleRootWorkspace(cwd) {
 export function workspacePrimaryRoot(context) {
     return context.roots.find((root) => root.id === context.sessionMainRootId);
 }
+/**
+ * Rebase only the Session's primary runtime path while preserving the host's
+ * authoritative project/root identities and the mounted secondary roots.
+ *
+ * A worktree switch changes where the primary root executes; it does not mint
+ * a new project or root id. Rebuilding through createWorkspaceContext also
+ * recomputes rootsDigest and re-runs the overlap/absolute-path validation.
+ */
+export function rebaseWorkspacePrimaryRoot(context, primaryPath) {
+    return createWorkspaceContext({
+        projectId: context.projectId,
+        projectRevision: context.projectRevision,
+        sessionMainRootId: context.sessionMainRootId,
+        roots: context.roots.map((root) => root.id === context.sessionMainRootId ? { ...root, path: primaryPath } : root),
+    });
+}
 /** 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)));

package/package.json

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