@cjhyy/code-shell-server 0.9.52 → 0.10.1

package/dist/mobile-remote/room-manager.js

@@ -1,5 +1,5 @@
 import { chmodSync, closeSync, existsSync, fchmodSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readSync, realpathSync, readdirSync, renameSync, writeFileSync, appendFileSync, rmSync, } from "node:fs";
-import { readRoomHistoryPage, scanRoomHistory, } from "./room-history.js";
+import { readRoomHistoryPage, scanRoomHistory, scanRoomHistoryAsync, } from "./room-history.js";
 import { randomUUID } from "node:crypto";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { createRoomModelTrace } from "./room-model-tracing.js";
@@ -145,6 +145,9 @@ function parseRoomMessage(value) {
         "reason",
         "toolId",
         "transcriptSource",
+        "clientMessageId",
+        "clientDeviceId",
+        "clientIntentHash",
     ]) {
         const item = raw[field];
         if (item !== undefined && (typeof item !== "string" || item.includes("\0")))
@@ -231,6 +234,50 @@ function askUserQuestions(input) {
         return [];
     return obj.questions.flatMap((q) => parseAskUserQuestion(q) ?? []);
 }
+const ROOM_BUSY_MESSAGES = {
+    queued: "该 CLI 会话有排队、失败或无法确认的消息，它们按当前权限模式提交；请先在队列中处理后再切换权限模式。",
+    switching: "该 CLI 会话正在切换权限模式，请稍后重试。",
+    retiring: "该 CLI 会话的旧进程仍未确认退出；为避免两个进程同时写入同一会话，暂不启动新进程，请稍后重试。",
+    turn: "该 CLI 会话仍有任务在运行或排队，请先停止或等待完成后再切换权限模式。",
+    approval: "该 CLI 会话有待处理的审批或提问，请先处理后再切换权限模式。",
+};
+export class RoomBusyError extends Error {
+    reason;
+    constructor(reason) {
+        super(ROOM_BUSY_MESSAGES[reason]);
+        this.reason = reason;
+        this.name = "RoomBusyError";
+    }
+}
+/** Stable code of RoomInputAcceptedError; callers branch on it, never on text. */
+export const ROOM_INPUT_ACCEPTED = "ROOM_INPUT_ACCEPTED";
+/**
+ * The CLI accepted the input, but recording it (history, trace, echo) failed.
+ * The turn may be running: it must never be retried as if it were rejected.
+ */
+export class RoomInputAcceptedError extends Error {
+    code = ROOM_INPUT_ACCEPTED;
+    constructor(cause) {
+        super(`CLI 已接收这条消息，但会话记录保存失败（${cause instanceof Error ? cause.message : String(cause)}）。请先核对 CLI 会话，不要重复发送。`, { cause });
+        this.name = "RoomInputAcceptedError";
+    }
+}
+/** The room or its process changed between planning and applying a mode change. */
+export class RoomStateChangedError extends Error {
+    constructor(message = "CLI 会话状态已变化，请重新选择权限模式。") {
+        super(message);
+        this.name = "RoomStateChangedError";
+    }
+}
+function canonicalDirectory(path) {
+    const absolute = resolve(path);
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
 const ROOM_ATTACHMENT_START = "<codeshell-image-attachments>";
 const ROOM_ATTACHMENT_END = "</codeshell-image-attachments>";
 function roomAttachmentSummary(attachments) {
@@ -276,6 +323,21 @@ export class RoomManager {
     /** Permission mode each live agent was spawned with. The mode is a spawn-time
      * CLI argument, so room metadata alone cannot prove what a process runs. */
     agentModes = new WeakMap();
+    /** Accepted inputs minus turn_end per room, for agents without isBusy(). A
+     * Claude resident process queues several inputs; each ends with a result. */
+    turnCounts = new Map();
+    /** In-flight mode handoff per room. close() deletes it, so a handoff that is
+     * waiting for the old process can never reopen a room the user closed. */
+    transitions = new Map();
+    /** Detached processes not yet proven exited. This is a process-safety fence,
+     * independent of any operation: close() and cancellation leave it in place,
+     * and no agent may start for the room until the process has really exited,
+     * so one external session never has two writers. */
+    retiring = new Map();
+    retiringProbes = new Map();
+    /** Bumped on every change to a room's process or mode, so a Host approval
+     * granted for one state cannot be applied to another. */
+    revisions = new Map();
     modelTraces = new Map();
     /** Rooms whose visible output is currently sourced from the external CLI's
      * transcript tail. While present, the resident agent's stdout mirror is
@@ -321,6 +383,9 @@ export class RoomManager {
     rootRealPath;
     rootIdentity;
     failedWrites = new Set();
+    preparingInputReceipts = new Map();
+    inputReceipts = new Map();
+    hostTurnHooks = {};
     /** Drop all pending AskUser entries for a room. Called when its agent goes
      *  away (exit/close) so a request that can no longer be answered doesn't leak
      *  in the map (small memory leak) and its approval card doesn't hang until the
@@ -455,6 +520,12 @@ export class RoomManager {
         }
     }
     createRoom(input) {
+        return this.createRoomWithId(this.mintRoomId(), input);
+    }
+    mintRoomId() {
+        return `room_${this.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+    }
+    createRoomWithId(id, input) {
         if (!input ||
             typeof input.cwd !== "string" ||
             !input.cwd ||
@@ -477,7 +548,8 @@ export class RoomManager {
             (input.linkedSessionMode !== undefined && input.linkedSessionMode !== "observe-only")) {
             throw new Error("invalid room metadata");
         }
-        const id = `room_${this.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+        if (!isValidRoomId(id) || existsSync(this.roomDir(id)))
+            throw new RoomStateChangedError();
         const meta = {
             id,
             name: input.name ?? defaultRoomName(input.cwd),
@@ -573,7 +645,14 @@ export class RoomManager {
         const msg = { seq, ts, ...partial };
         try {
             this.appendRoomMessage(id, msg);
-            this.messageStampByRoom.set(id, this.messageStamp(id));
+            const stamp = this.messageStamp(id);
+            this.messageStampByRoom.set(id, stamp);
+            const receipts = this.inputReceipts.get(id);
+            if (receipts) {
+                receipts.stamp = stamp;
+                if (msg.clientMessageId && msg.clientDeviceId && msg.clientIntentHash)
+                    receipts.intents.set(JSON.stringify([msg.clientDeviceId, msg.clientMessageId]), msg.clientIntentHash);
+            }
         }
         catch (error) {
             // Sequence assignment is a commit effect, not an attempt counter. A
@@ -772,40 +851,431 @@ export class RoomManager {
                 sources.add(source);
         }
     }
+    /** Monotonic per-room state revision; see `revisions`. */
+    roomRevision(id) {
+        return this.revisions.get(id) ?? 0;
+    }
+    bumpRevision(id) {
+        this.revisions.set(id, this.roomRevision(id) + 1);
+    }
+    /** The room bound to an external session. Reuse must match BOTH id and kind:
+     * a codex thread id and a claude session id share the `claudeSessionId`
+     * field, so a bare id match could hand back the other CLI's room. */
+    findSessionRoom(sessionId, kind) {
+        if (!sessionId)
+            return undefined;
+        return this.listRooms().find((r) => r.claudeSessionId === sessionId && r.kind === kind);
+    }
+    /** Spawn-time mode of the room's live process, if one is running. */
+    liveMode(id) {
+        const agent = this.agents.get(id);
+        return agent ? this.agentModes.get(agent) : undefined;
+    }
     /**
-     * Open (or create) the room bound to a claude session id, deduping by that id
-     * so a given claude session maps to exactly one room. Returns the room id.
+     * Why the room cannot change its process now. A mode change stops the
+     * process, so it must not interrupt queued/active turns, a pending tool
+     * approval or AskUserQuestion, or a decision that already left the approval
+     * bridge but has not been consumed here yet (its entry stays in the pending
+     * maps until respondApproval consumes it).
      */
-    openForSession(claudeSessionId, cwd, mode, kind = "claude-code") {
-        if (claudeSessionId)
-            this.opts.assertExternalSessionAvailable?.(claudeSessionId, kind);
-        // Reuse must match BOTH id and kind: a codex thread id and a claude session
-        // id live in the same `claudeSessionId` field, so a bare id match could
-        // otherwise hand back a claude room when a codex room was asked for.
-        const existing = claudeSessionId
-            ? this.listRooms().find((r) => r.claudeSessionId === claudeSessionId && r.kind === kind)
-            : undefined;
-        const meta = existing ??
-            this.createRoom({
+    roomBusyReason(id) {
+        const busy = this.executionBusyReason(id);
+        if (busy)
+            return busy;
+        // A Host-held turn was submitted for the current mode. Changing the mode
+        // underneath it would run it with permissions it was not queued under.
+        return this.hostTurnHooks.hasPendingTurns?.(id) ? "queued" : undefined;
+    }
+    /**
+     * The room's own execution state, independent of any Host-held pending
+     * turns: an active or queued CLI input (Codex: a live turn child), a mode
+     * handoff, or an unanswered approval. A Host scheduler waits on this.
+     */
+    executionBusyReason(id) {
+        if (this.transitions.has(id))
+            return "switching";
+        if (this.deferredEmitRooms.has(id))
+            return "turn";
+        const agent = this.agents.get(id);
+        if (agent && (agent.isBusy ? agent.isBusy() : (this.turnCounts.get(id) ?? 0) > 0))
+            return "turn";
+        const prefix = `${id}:`;
+        for (const key of this.pendingAskUser.keys())
+            if (key.startsWith(prefix))
+                return "approval";
+        for (const key of this.pendingApprovalInputs.keys())
+            if (key.startsWith(prefix))
+                return "approval";
+        return undefined;
+    }
+    /**
+     * True while a new input must not be handed to the room: it is executing
+     * or awaiting an approval, switching modes, or a retired process may still
+     * write. Host pending turns are deliberately not counted here.
+     */
+    isExecutionBusy(id) {
+        return this.executionBusyReason(id) !== undefined || this.retiring.has(id);
+    }
+    /** Mode a new input would run under: the live process mode, else the stored one. */
+    effectiveMode(id) {
+        return this.liveMode(id) ?? this.getRoom(id)?.permissionMode;
+    }
+    /**
+     * Host pending-turn integration, installed once by the Host composition.
+     * `hasPendingTurns` blocks every mode change; `beforeClose` runs before an
+     * explicit close signals the process, so pending turns pause first.
+     */
+    setHostTurnHooks(hooks) {
+        this.hostTurnHooks = hooks;
+    }
+    /**
+     * Plan opening an external session's room under `mode` without changing
+     * anything. Throws for a cwd that differs from the room's bound directory,
+     * an occupied external session, or a busy room whose mode would change.
+     */
+    planSessionOpen(input) {
+        const { sessionId, kind, mode } = input;
+        if (typeof sessionId !== "string" || !sessionId)
+            throw new Error("CLI session id is required");
+        this.opts.assertExternalSessionAvailable?.(sessionId, kind);
+        const cwd = canonicalDirectory(input.cwd);
+        const existing = this.findSessionRoom(sessionId, kind);
+        if (!existing) {
+            return {
+                roomId: this.mintRoomId(),
+                created: true,
+                sessionId,
                 cwd,
                 kind,
-                permissionMode: mode,
-                claudeSessionId: claudeSessionId || undefined,
+                toMode: mode,
+                change: true,
+                live: false,
+                observing: false,
+                revision: 0,
+            };
+        }
+        // The approval and the process must name the same directory.
+        if (canonicalDirectory(existing.cwd) !== cwd)
+            throw new Error("该 CLI 会话已绑定到另一个目录，不能在当前目录打开。");
+        const liveMode = this.liveMode(existing.id);
+        const observing = existing.linkedSessionMode === "observe-only";
+        const change = !observing &&
+            (existing.permissionMode !== mode || (liveMode !== undefined && liveMode !== mode));
+        if (this.transitions.has(existing.id))
+            throw new RoomBusyError("switching");
+        // Refused before any Host approval is asked for. settleSessionRoom()
+        // re-probes the retired process, so a later attempt succeeds once it exits.
+        if (!observing && this.retiring.has(existing.id))
+            throw new RoomBusyError("retiring");
+        if (change) {
+            const busy = this.roomBusyReason(existing.id);
+            if (busy)
+                throw new RoomBusyError(busy);
+        }
+        return {
+            roomId: existing.id,
+            created: false,
+            sessionId,
+            cwd,
+            kind,
+            fromMode: liveMode ?? existing.permissionMode,
+            toMode: mode,
+            change,
+            live: liveMode !== undefined,
+            observing,
+            revision: this.roomRevision(existing.id),
+        };
+    }
+    /**
+     * Apply a plan from planSessionOpen. `authorize` runs before anything is
+     * changed and again right before the replacement process is created; a
+     * throw leaves metadata untouched (or restores it) and never starts a CLI.
+     * `revalidate` re-checks asynchronous Host facts after every wait for a
+     * retired process, before that final `authorize`, while the room's handoff
+     * is still owned by this call.
+     */
+    async applySessionOpen(plan, options = {}) {
+        const authorize = () => options.authorize?.();
+        if (plan.created) {
+            if (this.findSessionRoom(plan.sessionId, plan.kind) || this.getRoom(plan.roomId))
+                throw new RoomStateChangedError();
+            authorize();
+            this.opts.assertExternalSessionAvailable?.(plan.sessionId, plan.kind);
+            this.createRoomWithId(plan.roomId, {
+                cwd: plan.cwd,
+                kind: plan.kind,
+                permissionMode: plan.toMode,
+                claudeSessionId: plan.sessionId,
             });
-        // permissionMode is a spawn-time CLI arg (--permission-mode), so it can't be
-        // changed on a live process. If the caller reopens an existing room under a
-        // DIFFERENT mode, persist the new mode and restart the resident agent;
-        // otherwise reopening keeps the running process and the picked mode would be
-        // silently ignored (the "bypassPermissions still prompts" bug).
-        if (existing && existing.permissionMode !== mode) {
-            this.writeRoomMeta(meta.id, { ...meta, permissionMode: mode });
-            this.close(meta.id); // stop the old-mode process so open() respawns fresh
-        }
-        // Metadata alone cannot prove the live process mode (a concurrent takeover
-        // may have rewritten it), so also compare the agent's spawn-time mode.
-        this.retireAgentUnlessMode(meta.id, mode);
-        const { status } = this.open(meta.id);
-        return { roomId: meta.id, status };
+            this.bumpRevision(plan.roomId);
+            try {
+                const status = await this.startAgent(plan.roomId);
+                return { roomId: plan.roomId, status, mode: plan.toMode, changed: true };
+            }
+            catch (error) {
+                // The room now exists but nothing runs in it; every view must see that.
+                this.notifyRoomState(plan.roomId);
+                throw error;
+            }
+        }
+        // Plans are checked against the retired-process fence again after it had a
+        // chance to be proven gone; an unproven process still refuses the start.
+        // No await (and so no gap) unless a retired process is actually fenced.
+        if (this.transitions.has(plan.roomId))
+            throw new RoomBusyError("switching");
+        if (this.retiring.has(plan.roomId)) {
+            if (!(await this.settleRetiring(plan.roomId)))
+                throw new RoomBusyError("retiring");
+            await options.revalidate?.();
+        }
+        const meta = this.getRoom(plan.roomId);
+        if (!meta ||
+            meta.claudeSessionId !== plan.sessionId ||
+            meta.kind !== plan.kind ||
+            canonicalDirectory(meta.cwd) !== plan.cwd ||
+            this.roomRevision(plan.roomId) !== plan.revision)
+            throw new RoomStateChangedError();
+        if (plan.observing) {
+            authorize();
+            return {
+                roomId: plan.roomId,
+                status: "observing",
+                mode: meta.permissionMode,
+                changed: false,
+            };
+        }
+        if (!plan.change) {
+            if (this.transitions.has(plan.roomId))
+                throw new RoomBusyError("switching");
+            authorize();
+            // Reuses a live process untouched; starts a dormant one in its own mode.
+            const status = await this.startAgent(plan.roomId);
+            return { roomId: plan.roomId, status, mode: meta.permissionMode, changed: false };
+        }
+        const status = await this.transitionRoom(plan.roomId, {
+            toMode: plan.toMode,
+            expectedMode: meta.permissionMode,
+            authorize,
+            ...(options.revalidate ? { revalidate: options.revalidate } : {}),
+        });
+        return { roomId: plan.roomId, status, mode: plan.toMode, changed: true };
+    }
+    /**
+     * Open (or create) the room bound to an external session id, deduping by
+     * that id so a given session maps to exactly one room. A different mode is
+     * applied by a guarded process handoff. Hosts that must authorize a mode
+     * use planSessionOpen/applySessionOpen directly.
+     */
+    async openForSession(claudeSessionId, cwd, mode, kind = "claude-code") {
+        // Inline (not settleSessionRoom) so an unfenced room adds no await gap.
+        const existing = this.findSessionRoom(claudeSessionId, kind);
+        if (existing && this.retiring.has(existing.id) && !this.transitions.has(existing.id))
+            await this.settleRetiring(existing.id);
+        const plan = this.planSessionOpen({ sessionId: claudeSessionId, cwd, kind, mode });
+        const result = await this.applySessionOpen(plan);
+        return { roomId: result.roomId, status: result.status, mode: result.mode };
+    }
+    /**
+     * Re-probe a retired process of the session's room (see `retiring`), so a
+     * plan made right afterwards is refused only while that process is really
+     * still alive. Never starts anything.
+     */
+    async settleSessionRoom(sessionId, kind) {
+        const room = this.findSessionRoom(sessionId, kind);
+        // A handoff in progress owns its retired process; the plan reports it busy.
+        if (room && this.retiring.has(room.id) && !this.transitions.has(room.id))
+            await this.settleRetiring(room.id);
+    }
+    /** Resolves true once no retired process of the room can still be alive. */
+    settleRetiring(id) {
+        const agent = this.retiring.get(id);
+        if (!agent)
+            return Promise.resolve(true);
+        const inFlight = this.retiringProbes.get(id);
+        if (inFlight)
+            return inFlight;
+        const probe = this.probeRetired(id, agent).finally(() => {
+            if (this.retiringProbes.get(id) === probe)
+                this.retiringProbes.delete(id);
+        });
+        this.retiringProbes.set(id, probe);
+        return probe;
+    }
+    async probeRetired(id, agent) {
+        let exited;
+        try {
+            if (agent.stopAndWait) {
+                exited = await agent.stopAndWait(this.opts.processExitTimeoutMs ?? 5_000);
+            }
+            else {
+                agent.stop();
+                exited = true;
+            }
+        }
+        catch {
+            exited = false;
+        }
+        if (exited && this.retiring.get(id) === agent) {
+            this.retiring.delete(id);
+            // The shared probe owns publication, so concurrent waiters notify once.
+            if (!this.transitions.has(id))
+                this.notifyRoomState(id);
+        }
+        return !this.retiring.has(id);
+    }
+    /** Synchronous entry points cannot wait: refuse, and re-probe in the
+     * background so the next attempt succeeds once the process is gone. */
+    assertNotRetiring(id) {
+        if (!this.retiring.has(id))
+            return;
+        this.watchRetired(id);
+        throw new RoomBusyError("retiring");
+    }
+    /** Request an exit probe; the shared probe publishes a proven exit once.
+     * A handoff that still owns the room reports its own outcome. */
+    watchRetired(id) {
+        void this.settleRetiring(id);
+    }
+    notifyRoomState(id) {
+        try {
+            this.opts.onRoomStateChanged?.(id);
+        }
+        catch {
+            // A Host broadcast failure must not change the room's outcome.
+        }
+    }
+    /**
+     * Replace a room's process with one in `toMode`. permissionMode is a
+     * spawn-time CLI argument (`--permission-mode` / codex sandbox flags), so a
+     * live process cannot change it. Order matters:
+     *  1. refuse a busy room, before touching anything;
+     *  2. detach the old process, so its late output/exit belongs to nobody, and
+     *     wait (bounded) until it has really exited — never two writers;
+     *  3. re-authorize, then persist the mode and start the replacement;
+     *  4. on any failure restore the previous mode. The old process is already
+     *     gone at that point, so the room reports not running instead of
+     *     pretending the old state came back, and every view is told so.
+     * The detached process stays in `retiring` until its exit is proven: a
+     * timeout, close() or cancellation ends this operation but not the fence.
+     * Transcript followers are not ended: the external session continues.
+     */
+    async transitionRoom(id, input) {
+        const busy = this.roomBusyReason(id);
+        if (busy)
+            throw new RoomBusyError(busy);
+        if (this.retiring.has(id))
+            throw new RoomBusyError("retiring");
+        // A background task writing this external session refuses the switch
+        // before the live process is touched, not after it has been stopped.
+        const before = this.getRoom(id);
+        if (before?.claudeSessionId)
+            this.opts.assertExternalSessionAvailable?.(before.claudeSessionId, before.kind);
+        input.authorize();
+        const token = Symbol(id);
+        this.transitions.set(id, token);
+        this.bumpRevision(id);
+        let snapshot;
+        let metadataWritten = false;
+        /** False only while the detached process may still be alive. */
+        let oldProcessGone = true;
+        let failed = false;
+        try {
+            const agent = this.agents.get(id);
+            if (agent) {
+                // Fence first: from here until its exit is proven nothing may start.
+                this.retiring.set(id, agent);
+                oldProcessGone = false;
+                this.agents.delete(id);
+                this.turnCounts.delete(id);
+                this.modelTraces.get(id)?.finish("cancelled");
+                this.modelTraces.delete(id);
+                this.pendingTranscriptUserEchoes.delete(id);
+                oldProcessGone = await this.settleRetiring(id);
+                if (!oldProcessGone)
+                    throw new Error("旧 CLI 进程未能在时限内退出；为避免两个进程同时写入同一会话，没有启动新模式。");
+                // Facts proven before the wait may have changed during it. The token
+                // still owns the room, so nothing else can start while this awaits.
+                if (this.transitions.get(id) === token)
+                    await input.revalidate?.();
+            }
+            if (this.transitions.get(id) !== token)
+                throw new RoomStateChangedError("CLI 会话已被关闭，权限模式切换已取消。");
+            // The requester and its grant are re-checked right before the
+            // replacement exists; a cancellation leaves the room really stopped.
+            input.authorize();
+            snapshot = this.getRoom(id);
+            if (!snapshot || snapshot.permissionMode !== input.expectedMode)
+                throw new RoomStateChangedError();
+            this.writeRoomMeta(id, { ...snapshot, ...input.patch, permissionMode: input.toMode });
+            metadataWritten = true;
+            const status = await this.startAgent(id, token);
+            if (status !== "running")
+                throw new Error("新模式的 CLI 进程未能启动。");
+            return status;
+        }
+        catch (error) {
+            // A process that may still be alive is not reported as stopped; the
+            // fence is re-probed and the room republished once it is proven gone.
+            if (!oldProcessGone)
+                this.watchRetired(id);
+            if (metadataWritten && snapshot) {
+                try {
+                    const current = this.getRoom(id);
+                    if (current)
+                        this.writeRoomMeta(id, {
+                            ...current,
+                            cwd: snapshot.cwd,
+                            permissionMode: snapshot.permissionMode,
+                            linkedSessionMode: snapshot.linkedSessionMode,
+                        });
+                }
+                catch {
+                    // Surface the original failure; the room reports not running.
+                }
+            }
+            failed = true;
+            throw error;
+        }
+        finally {
+            if (this.transitions.get(id) === token)
+                this.transitions.delete(id);
+            this.bumpRevision(id);
+            // Only the requester receives the error; every other phone and Desktop
+            // window learns the room's real (stopped, restored-mode) state here.
+            if (failed && oldProcessGone)
+                this.notifyRoomState(id);
+        }
+    }
+    /** Start (or reuse) the room's agent and wait until a spawned process exists. */
+    async startAgent(id, transition) {
+        if (transition !== undefined && this.transitions.get(id) !== transition)
+            throw new RoomStateChangedError("CLI 会话已被关闭，权限模式切换已取消。");
+        if (transition === undefined && this.transitions.has(id))
+            throw new RoomBusyError("switching");
+        const { status } = this.openAgent(id);
+        if (status !== "running")
+            return status;
+        const agent = this.agents.get(id);
+        if (!agent?.whenStarted)
+            return status;
+        try {
+            await agent.whenStarted();
+        }
+        catch (error) {
+            if (this.agents.get(id) === agent) {
+                this.agents.delete(id);
+                this.turnCounts.delete(id);
+                try {
+                    agent.stop();
+                }
+                catch {
+                    // Preserve the spawn error.
+                }
+                this.bumpRevision(id);
+            }
+            throw new Error(`CLI 进程启动失败：${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        return this.agents.get(id) === agent && agent.isRunning() ? "running" : "missing";
     }
     /** Bind an external CLI transcript to a room for observation only.
      *
@@ -851,9 +1321,13 @@ export class RoomManager {
      * This is the linked-session operation that may create/start an agent. The
      * external identity is revalidated at takeover time so stale links cannot
      * silently start a different session. */
-    takeOverLinkedSession(roomId, externalSessionId, cwd, kind) {
+    async takeOverLinkedSession(roomId, externalSessionId, cwd, kind) {
         const target = this.requireLinkedSessionTarget({ externalSessionId, cwd, kind });
         this.opts.assertExternalSessionAvailable?.(target.externalSessionId, target.kind);
+        if (this.transitions.has(roomId))
+            throw new RoomBusyError("switching");
+        if (this.retiring.has(roomId) && !(await this.settleRetiring(roomId)))
+            throw new RoomBusyError("retiring");
         const meta = this.getRoom(roomId);
         if (!meta ||
             meta.claudeSessionId !== target.externalSessionId ||
@@ -861,24 +1335,33 @@ export class RoomManager {
             resolve(meta.cwd) !== target.cwd) {
             throw new Error("linked session does not match the requested room");
         }
-        const controllableMeta = {
-            ...meta,
-            cwd: target.cwd,
-            // Observe-only navigation never asks the user to approve a stored
-            // permission mode. A prior bypassPermissions value must not be inherited
-            // silently when takeover starts a new process.
-            permissionMode: "default",
-            linkedSessionMode: undefined,
-        };
-        this.writeRoomMeta(roomId, controllableMeta);
-        // Another view may have taken over and reopened this session under a
-        // different mode. Never report default while feeding that process.
-        this.retireAgentUnlessMode(roomId, controllableMeta.permissionMode);
-        const { status } = this.open(roomId);
+        if (this.transitions.has(roomId))
+            throw new RoomBusyError("switching");
+        // Observe-only navigation never asks the user to approve a stored
+        // permission mode. A prior bypassPermissions value must not be inherited
+        // silently when takeover starts a new process.
+        const patch = { cwd: target.cwd, linkedSessionMode: undefined };
+        const liveMode = this.liveMode(roomId);
+        let status;
+        if (liveMode !== undefined && liveMode !== "default") {
+            // Another view runs this session under a different mode. Replace that
+            // process only when it is idle, and only after it has exited.
+            status = await this.transitionRoom(roomId, {
+                toMode: "default",
+                expectedMode: meta.permissionMode,
+                authorize: () => undefined,
+                patch,
+            });
+        }
+        else {
+            this.writeRoomMeta(roomId, { ...meta, ...patch, permissionMode: "default" });
+            this.bumpRevision(roomId);
+            status = await this.startAgent(roomId);
+        }
         if (status !== "running") {
             throw new Error("linked session room is unavailable");
         }
-        return { roomId, status, mode: controllableMeta.permissionMode, cwd: controllableMeta.cwd };
+        return { roomId, status, mode: "default", cwd: target.cwd };
     }
     requireLinkedSessionTarget(target) {
         if (!target.externalSessionId.trim() ||
@@ -966,14 +1449,25 @@ export class RoomManager {
     /** Open a room: start its resident agent if not already running. Observe-only
      * linked rooms fail closed until takeOverLinkedSession clears the boundary. */
     open(id) {
+        // A mode handoff owns the room until its replacement process exists.
+        if (this.transitions.has(id))
+            throw new RoomBusyError("switching");
+        return this.openAgent(id);
+    }
+    openAgent(id) {
         const meta = this.getRoom(id);
         if (!meta)
             return { status: "missing" };
         if (meta.linkedSessionMode === "observe-only")
             return { status: "observing" };
         if (!this.agents.has(id)) {
+            // Every start path ends here: no second writer while a detached
+            // process of this room may still be alive.
+            this.assertNotRetiring(id);
             if (meta.claudeSessionId)
                 this.opts.assertExternalSessionAvailable?.(meta.claudeSessionId, meta.kind);
+            // Host policy, e.g. a stored bypassPermissions needs a live Host grant.
+            this.opts.authorizeStart?.(meta);
             let agent = undefined;
             agent = this.opts.createAgent(meta, (event) => {
                 // stop() sends a signal; an old process can still drain output or emit
@@ -984,12 +1478,15 @@ export class RoomManager {
             });
             this.agents.set(id, agent);
             this.agentModes.set(agent, meta.permissionMode);
+            this.turnCounts.delete(id);
+            this.bumpRevision(id);
             try {
                 agent.start();
             }
             catch (error) {
                 if (this.agents.get(id) === agent)
                     this.agents.delete(id);
+                this.bumpRevision(id);
                 this.clearPendingApprovals(id);
                 try {
                     agent.stop();
@@ -1006,12 +1503,6 @@ export class RoomManager {
         }
         return { status: "running" };
     }
-    /** Stop a live agent whose spawn-time permission mode differs from `mode`. */
-    retireAgentUnlessMode(id, mode) {
-        const agent = this.agents.get(id);
-        if (agent && this.agentModes.get(agent) !== mode)
-            this.close(id);
-    }
     onAgentEvent(id, event) {
         // Buffered while send() is deciding acceptance — replayed right after the
         // user turn is appended, so a synchronous agent reply cannot precede it.
@@ -1021,6 +1512,19 @@ export class RoomManager {
             this.deferredEmits.set(id, queued);
             return;
         }
+        // Turn accounting must see every event, including the turn_end that the
+        // transcript-follow filter below hides from the stdout mirror.
+        if (event.type === "turn_end") {
+            const remaining = (this.turnCounts.get(id) ?? 0) - 1;
+            if (remaining > 0)
+                this.turnCounts.set(id, remaining);
+            else
+                this.turnCounts.delete(id);
+        }
+        else if (event.type === "exit") {
+            this.turnCounts.delete(id);
+            this.bumpRevision(id);
+        }
         const trace = this.modelTraces.get(id);
         trace?.observe(event);
         if (trace?.ended)
@@ -1099,13 +1603,22 @@ export class RoomManager {
                         ?.respondControl?.(event.requestId, { behavior: "allow", updatedInput: event.input });
                     break;
                 }
-                this.append(id, {
-                    from: "agent",
-                    type: "approval",
-                    tool: event.toolName,
-                    summary: event.description ?? "",
-                });
-                this.pendingApprovalInputs.set(`${id}:${event.requestId}`, event.input);
+                // Record the pending approval BEFORE the message is published: anything
+                // reacting to it (e.g. a Host scheduler) must already see the room busy.
+                const approvalKey = `${id}:${event.requestId}`;
+                this.pendingApprovalInputs.set(approvalKey, event.input);
+                try {
+                    this.append(id, {
+                        from: "agent",
+                        type: "approval",
+                        tool: event.toolName,
+                        summary: event.description ?? "",
+                    });
+                }
+                catch (error) {
+                    this.pendingApprovalInputs.delete(approvalKey);
+                    throw error;
+                }
                 this.opts.onApprovalRequest?.(id, event);
                 break;
             }
@@ -1125,11 +1638,81 @@ export class RoomManager {
                 break;
         }
     }
+    /** Prepare cold receipts outside the synchronous send path; concurrent intents share one scan. */
+    async prepareInputReceipts(id) {
+        if (this.inputReceipts.has(id)) {
+            this.currentInputReceipts(id);
+            return;
+        }
+        const pending = this.preparingInputReceipts.get(id);
+        if (pending)
+            return pending;
+        const work = this.buildInputReceipts(id).finally(() => {
+            if (this.preparingInputReceipts.get(id) === work)
+                this.preparingInputReceipts.delete(id);
+        });
+        this.preparingInputReceipts.set(id, work);
+        return work;
+    }
+    async buildInputReceipts(id) {
+        if (this.failedWrites.has(id))
+            throw new Error("room persistence failed");
+        const path = this.msgPath(id);
+        const intents = new Map();
+        const proof = existsSync(path)
+            ? await scanRoomHistoryAsync(path, parseRoomMessage, (message) => {
+                if (!message.clientMessageId)
+                    return;
+                if (!message.clientDeviceId || !message.clientIntentHash)
+                    throw new Error("room input receipt is incomplete");
+                const key = JSON.stringify([message.clientDeviceId, message.clientMessageId]);
+                const previous = intents.get(key);
+                if (previous && previous !== message.clientIntentHash)
+                    throw new Error("conflicting room input receipts");
+                intents.set(key, message.clientIntentHash);
+            })
+            : { sequence: 0, stamp: "" };
+        if ((existsSync(path) ? this.messageStamp(id) : "") !== proof.stamp)
+            throw new Error("room input history changed; reload before retrying");
+        this.inputReceipts.set(id, { stamp: proof.stamp, intents });
+        // Avoid a second synchronous history scan when the cold Room first appends.
+        if (proof.stamp && !this.lastSeqByRoom.has(id)) {
+            this.lastSeqByRoom.set(id, proof.sequence);
+            this.messageStampByRoom.set(id, proof.stamp);
+        }
+    }
+    currentInputReceipts(id) {
+        const cached = this.inputReceipts.get(id);
+        if (!cached)
+            throw new Error("room input receipts must be prepared before send");
+        const path = this.msgPath(id);
+        if (cached.stamp !== (existsSync(path) ? this.messageStamp(id) : ""))
+            throw new Error("room input history changed; reload before retrying");
+        return cached;
+    }
+    /** A replay never opens a new CLI, reclaims an attachment, or reuses a changed intent. */
+    hasAcceptedInput(id, receipt) {
+        if (!receipt.clientMessageId ||
+            receipt.clientMessageId.length > 200 ||
+            !receipt.clientDeviceId ||
+            receipt.clientDeviceId.length > 256 ||
+            !/^[a-f0-9]{64}$/.test(receipt.clientIntentHash))
+            throw new Error("invalid room input receipt");
+        if (this.failedWrites.has(id))
+            throw new Error("room persistence failed");
+        const cached = this.currentInputReceipts(id);
+        const known = cached.intents.get(JSON.stringify([receipt.clientDeviceId, receipt.clientMessageId]));
+        if (known && known !== receipt.clientIntentHash)
+            throw new Error("同一输入的内容已改变，请核对草稿后作为新消息发送。");
+        return known !== undefined;
+    }
     /** Post a user message: persist it, ensure agent running, feed it. */
-    send(id, text, attachments = []) {
+    send(id, text, attachments = [], receipt) {
         const meta = this.getRoom(id);
         if (!meta)
             return false;
+        if (receipt && this.hasAcceptedInput(id, receipt))
+            return true;
         const displayText = text.trim();
         if (!displayText && attachments.length === 0)
             return false;
@@ -1174,6 +1757,21 @@ export class RoomManager {
             // Rejected: nothing about this turn reaches history or the phone.
             return false;
         }
+        // Counted before the buffered events replay, so a synchronous turn_end
+        // settles exactly this input.
+        if (this.agents.get(id) === agent)
+            this.turnCounts.set(id, (this.turnCounts.get(id) ?? 0) + 1);
+        try {
+            this.recordAcceptedInput(id, meta, agentText, displayText, summaries, buffered, receipt);
+        }
+        catch (error) {
+            // The CLI already has this input. Reporting a plain failure would invite
+            // a second submission of the same turn.
+            throw new RoomInputAcceptedError(error);
+        }
+        return true;
+    }
+    recordAcceptedInput(id, meta, agentText, displayText, summaries, buffered, receipt) {
         if (this.opts.modelTracing) {
             try {
                 let trace = this.modelTraces.get(id);
@@ -1197,6 +1795,7 @@ export class RoomManager {
             from: "user",
             type: "text",
             text: displayText,
+            ...(receipt ?? {}),
             ...(summaries.length ? { attachments: summaries } : {}),
         });
         if (this.transcriptFollowedRooms.has(id)) {
@@ -1208,26 +1807,57 @@ export class RoomManager {
         // after the user turn.
         for (const event of buffered)
             this.onAgentEvent(id, event);
-        return true;
     }
     close(id) {
+        // Stopping is the current turn only: Host-held turns pause BEFORE the
+        // process is signalled, so the idle boundary cannot start the next one.
+        try {
+            this.hostTurnHooks.beforeClose?.(id);
+        }
+        catch {
+            // Bookkeeping must never keep a process alive.
+        }
+        // An explicit close cancels a pending mode handoff: the handoff checks its
+        // token before starting the replacement, so it can never reopen the room.
+        // The retired-process fence is deliberately kept: until the old process is
+        // proven gone, an immediate reopen or send is refused, not double-started.
+        this.transitions.delete(id);
+        this.bumpRevision(id);
         // A room going quiet must record its REAL last activity, not the last
         // throttled write.
         this.flushLastActive(id);
         const agent = this.agents.get(id);
         this.modelTraces.get(id)?.finish("cancelled");
         this.modelTraces.delete(id);
+        // stop() only signals: the process can outlive it by the SIGTERM grace
+        // period. Fence the room before signalling so an immediate send/open/
+        // reopen cannot start a second writer on the same external session. An
+        // agent without stopAndWait() has no exit to wait for (stop() is its exit).
+        const fenced = !!agent?.stopAndWait && !this.retiring.has(id);
+        if (fenced)
+            this.retiring.set(id, agent);
         try {
             agent?.stop();
         }
         finally {
             if (!agent || this.agents.get(id) === agent)
                 this.agents.delete(id);
+            this.turnCounts.delete(id);
             this.clearPendingApprovals(id);
             this.pendingTranscriptUserEchoes.delete(id);
             this.deferredEmitRooms.delete(id);
             this.deferredEmits.delete(id);
             this.opts.onRoomEnded?.(id);
+            try {
+                this.opts.onRoomClosed?.(id);
+            }
+            catch {
+                // A Host bookkeeping failure must not keep the process alive.
+            }
+            // Prove the exit in the background; the room is republished once it is
+            // gone. Until then isOpen() stays true and every start is refused.
+            if (fenced)
+                this.watchRetired(id);
         }
     }
     closeAll() {
@@ -1245,6 +1875,8 @@ export class RoomManager {
             }
         }
         this.agents.clear();
+        this.transitions.clear();
+        this.turnCounts.clear();
         this.pendingAskUser.clear();
         this.pendingApprovalInputs.clear();
         this.pendingTranscriptUserEchoes.clear();
@@ -1262,8 +1894,10 @@ export class RoomManager {
         if (firstError)
             throw firstError;
     }
+    /** True while the room's process runs, or a retired one is not yet proven
+     * gone (a view must not be told the room stopped while it may still write). */
     isOpen(id) {
-        return this.agents.get(id)?.isRunning() ?? false;
+        return (this.agents.get(id)?.isRunning() ?? false) || this.retiring.has(id);
     }
     /**
      * Delete rooms whose last activity is older than maxAgeMs (idle-based GC,
@@ -1281,13 +1915,14 @@ export class RoomManager {
         for (const meta of this.listRooms()) {
             if (meta.lastActiveAt > cutoff)
                 continue;
-            if (this.isOpen(meta.id))
+            if (this.isOpen(meta.id) || this.transitions.has(meta.id))
                 continue; // never reap a live session
             rmSync(this.roomDir(meta.id), { recursive: true, force: true });
             this.agents.delete(meta.id);
             // Drop the cached seq with the files, so a room id that somehow comes back
             // re-derives its counter from disk instead of continuing a dead sequence.
             this.lastSeqByRoom.delete(meta.id);
+            this.inputReceipts.delete(meta.id);
             removed.push(meta.id);
         }
         return removed;