@cjhyy/code-shell-core 0.8.20 → 0.9.1

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

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

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

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

package/dist/protocol/types.d.ts

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

package/dist/protocol/types.js

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

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

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

package/dist/session/session-manager.js

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

package/dist/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>;