@cjhyy/code-shell-server 0.8.0

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

@@ -0,0 +1,765 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, appendFileSync, rmSync, } from "node:fs";
+import { join, resolve } from "node:path";
+/**
+ * The exact shape createRoom() generates: `room_<base36>_<base36>`. Anything
+ * else — path separators, `..`, NUL, empty — is rejected before it can reach a
+ * filesystem path, closing the room-storage traversal via client-supplied
+ * event.roomId.
+ */
+const ROOM_ID_RE = /^room_[a-z0-9]+_[a-z0-9]+$/;
+/**
+ * Minimum gap between room.json rewrites for `lastActiveAt`.
+ *
+ * The field only drives idle pruning, which is measured in hours, so writing it
+ * per message bought nothing and cost a full file rewrite each time.
+ */
+const LAST_ACTIVE_THROTTLE_MS = 10_000;
+export function isValidRoomId(id) {
+    return typeof id === "string" && ROOM_ID_RE.test(id);
+}
+/**
+ * Tools whose `can_use_tool` control request is a structured host call, not a
+ * yes/no permission gate, AND for which we have nothing to collect from the
+ * user — so a plain allow/deny card is a dead end and we auto-allow instead
+ * (echoing the original input back as updatedInput). Skill is the only one:
+ * it just needs its args echoed.
+ *
+ * AskUserQuestion is handled separately (NOT here): it needs the user's actual
+ * choice, baked into updatedInput.answers — auto-allowing the unanswered input
+ * is what made claude report "The user did not answer the questions".
+ */
+const AUTO_ALLOW_TOOLS = new Set(["Skill"]);
+/**
+ * Build the `updatedInput` that answers an AskUserQuestion `can_use_tool`
+ * request. Empirically (claude CLI, verified against the live control protocol
+ * + the Agent SDK docs), the answer must go in an `answers` RECORD keyed by each
+ * question's `question` text, with STRING values (arrays/objects fail schema
+ * validation). For multiSelect the caller joins chosen labels with ", ". The
+ * original `questions` array is passed through (claude validates against it).
+ * `answersByQuestion` maps question text → answer string.
+ */
+export function buildAskUserUpdatedInput(input, answersByQuestion) {
+    const obj = (input ?? {});
+    const questions = Array.isArray(obj.questions) ? obj.questions : [];
+    const answers = {};
+    for (const q of questions) {
+        const text = q?.question;
+        if (typeof text === "string" && typeof answersByQuestion[text] === "string") {
+            answers[text] = answersByQuestion[text];
+        }
+    }
+    return { ...obj, answers };
+}
+/**
+ * Parse an AskUserQuestion input into the first question's prompt/header/options
+ * so the UI can render a choice card. The room UI answers one question at a time
+ * (the first); returns undefined for a non-AskUser / malformed input (no
+ * questions), which the caller treats as "fall back to auto-allow".
+ */
+export function askUserPrompt(input) {
+    const obj = (input ?? {});
+    const q0 = (Array.isArray(obj.questions) ? obj.questions[0] : undefined);
+    if (!q0 || typeof q0.question !== "string")
+        return undefined;
+    const options = Array.isArray(q0.options)
+        ? q0.options
+            .map((o) => o?.label)
+            .filter((l) => typeof l === "string")
+        : [];
+    return {
+        question: q0.question,
+        header: typeof q0.header === "string" ? q0.header : undefined,
+        options,
+        multiSelect: q0.multiSelect === true,
+    };
+}
+const ROOM_ATTACHMENT_START = "<codeshell-image-attachments>";
+const ROOM_ATTACHMENT_END = "</codeshell-image-attachments>";
+function roomAttachmentSummary(attachments) {
+    return attachments.map((attachment) => ({
+        name: attachment.originalName ?? attachment.relPath ?? attachment.path,
+        mime: attachment.mime,
+        size: attachment.size,
+        path: attachment.relPath ?? attachment.path,
+    }));
+}
+export function roomTurnText(text, attachments) {
+    if (attachments.length === 0)
+        return text;
+    const paths = attachments.map((attachment) => `- ${attachment.relPath ?? attachment.path} (${attachment.mime ?? "image"})`);
+    return [
+        text.trim(),
+        ROOM_ATTACHMENT_START,
+        "The following images are available as workspace-relative files:",
+        ...paths,
+        ROOM_ATTACHMENT_END,
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+export function stripRoomAttachmentBlock(text) {
+    const start = text.indexOf(ROOM_ATTACHMENT_START);
+    if (start < 0)
+        return text;
+    const end = text.indexOf(ROOM_ATTACHMENT_END, start);
+    return (end < 0
+        ? text.slice(0, start)
+        : `${text.slice(0, start)}${text.slice(end + ROOM_ATTACHMENT_END.length)}`).trim();
+}
+/**
+ * Owns room lifecycle and the on-disk message log (the authoritative source).
+ * A room's resident agent is started on open() and its normalized events are
+ * appended to messages.jsonl and mirrored via onMessage. seq is monotonic per
+ * room so the phone can sync incrementally.
+ */
+export class RoomManager {
+    opts;
+    agents = 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
+     * suppressed so the same CLI output is not pushed twice. */
+    transcriptFollowedRooms = new Set();
+    /** Pending AskUserQuestion control requests, keyed by `${roomId}:${requestId}`.
+     *  Holds the raw tool input so respondApproval can bake the user's answer into
+     *  the `answers` record the CLI expects. Cleared on response. */
+    pendingAskUser = new Map();
+    /** User turns are echoed immediately for responsive room UX. When a
+     * transcript follower later sees the same CLI-written user line, this queue
+     * suppresses that duplicate. */
+    pendingTranscriptUserEchoes = new Map();
+    /**
+     * Rooms whose agent events must be buffered instead of handled immediately.
+     *
+     * Only set for the duration of `agent.send()` inside `send()`: acceptance has
+     * to be known before the user turn is persisted, but the user turn must still
+     * come FIRST in the history. An agent that emits synchronously from send()
+     * would otherwise have its reply appended ahead of the prompt it answers.
+     */
+    deferredEmitRooms = new Set();
+    deferredEmits = new Map();
+    /**
+     * Last assigned message seq per room, so appends do not re-read the whole
+     * JSONL. Seeded lazily from disk on the first append after startup; dropped
+     * when the room's messages are deleted so the next append re-derives it.
+     */
+    lastSeqByRoom = new Map();
+    /** Throttled lastActiveAt bookkeeping — see touchLastActive. */
+    pendingLastActive = new Map();
+    lastActiveWrittenAt = new Map();
+    now;
+    /** 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
+     *  5-min timeout. Keys are `${roomId}:${requestId}`. */
+    clearPendingAskUser(roomId) {
+        const prefix = `${roomId}:`;
+        for (const key of this.pendingAskUser.keys()) {
+            if (key.startsWith(prefix))
+                this.pendingAskUser.delete(key);
+        }
+    }
+    constructor(opts) {
+        this.opts = opts;
+        this.now = opts.now ?? (() => Date.now());
+        mkdirSync(opts.rootDir, { recursive: true });
+    }
+    roomDir(id) {
+        // roomId reaches path-building from client WS events (room.open/history/
+        // send/close all pass event.roomId straight through), so it is NOT always a
+        // system-generated id — an authenticated device could send "../../etc" and
+        // traverse out of rootDir. Enforce the generated shape (see createRoom:
+        // `room_<base36>_<base36>`) at this single chokepoint so every path-builder
+        // (metaPath/msgPath/getRoom/getMessages/open/send/close) is covered.
+        if (!isValidRoomId(id)) {
+            throw new Error(`invalid roomId: ${JSON.stringify(id)}`);
+        }
+        return join(this.opts.rootDir, id);
+    }
+    metaPath(id) {
+        return join(this.roomDir(id), "room.json");
+    }
+    msgPath(id) {
+        return join(this.roomDir(id), "messages.jsonl");
+    }
+    createRoom(input) {
+        const id = `room_${this.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+        const meta = {
+            id,
+            name: input.name ?? input.cwd.split("/").filter(Boolean).pop() ?? "room",
+            cwd: input.cwd,
+            kind: input.kind ?? "claude-code",
+            permissionMode: input.permissionMode ?? "default",
+            createdAt: this.now(),
+            lastActiveAt: this.now(),
+            claudeSessionId: input.claudeSessionId,
+            linkedSessionMode: input.linkedSessionMode,
+        };
+        mkdirSync(this.roomDir(id), { recursive: true });
+        writeFileSync(this.metaPath(id), JSON.stringify(meta, null, 2), "utf-8");
+        // Audit anchor: the first line records how the room was opened (cwd +
+        // permission mode), so messages.jsonl is self-describing for "what could
+        // this room do" forensics.
+        this.append(id, {
+            from: "system",
+            type: "room_created",
+            text: `cwd=${meta.cwd} permission=${meta.permissionMode}`,
+        });
+        return meta;
+    }
+    listRooms() {
+        if (!existsSync(this.opts.rootDir))
+            return [];
+        const rooms = [];
+        for (const entry of readdirSync(this.opts.rootDir)) {
+            const p = join(this.opts.rootDir, entry, "room.json");
+            if (!existsSync(p))
+                continue;
+            try {
+                rooms.push(JSON.parse(readFileSync(p, "utf-8")));
+            }
+            catch {
+                /* skip corrupt */
+            }
+        }
+        return rooms.sort((a, b) => b.lastActiveAt - a.lastActiveAt);
+    }
+    getRoom(id) {
+        // Invalid ids resolve to "no such room" rather than throwing, so the WS
+        // event handlers (which call this first) degrade to a missing response
+        // instead of crashing on a malicious roomId.
+        if (!isValidRoomId(id))
+            return undefined;
+        const p = this.metaPath(id);
+        if (!existsSync(p))
+            return undefined;
+        try {
+            return JSON.parse(readFileSync(p, "utf-8"));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    nextSeq(id) {
+        // Scan the file ONCE per room, then keep the counter in memory.
+        //
+        // This used to call getMessages(id, 0) on every append — a full synchronous
+        // read + JSON.parse of the entire messages.jsonl just to learn the last seq.
+        // Appending N messages therefore cost O(N²) parsing, all of it on the remote
+        // host's event loop: a long-lived room progressively slowed down new
+        // messages, heartbeats and every other WebSocket client. (Measured: ~32s to
+        // write 2,000 short messages.)
+        const cached = this.lastSeqByRoom.get(id);
+        if (cached !== undefined) {
+            const next = cached + 1;
+            this.lastSeqByRoom.set(id, next);
+            return next;
+        }
+        const msgs = this.getMessages(id, 0);
+        const next = msgs.length === 0 ? 1 : msgs[msgs.length - 1].seq + 1;
+        this.lastSeqByRoom.set(id, next);
+        return next;
+    }
+    append(id, partial) {
+        const ts = this.now();
+        const msg = { seq: this.nextSeq(id), ts, ...partial };
+        appendFileSync(this.msgPath(id), JSON.stringify(msg) + "\n", "utf-8");
+        // Touch lastActiveAt so idle-based pruning measures real activity, not just
+        // creation time — a room chatted with daily should never be reaped.
+        this.touchLastActive(id, ts);
+        this.opts.onMessage(id, msg);
+        return msg;
+    }
+    /**
+     * Refresh the room's `lastActiveAt`, throttled.
+     *
+     * This re-read and rewrote the whole room.json on EVERY appended message. The
+     * field only feeds idle-based pruning (measured in hours), so second-level
+     * precision is worthless while the write cost is paid per message — together
+     * with the old full-history seq scan it made a busy room progressively slower.
+     *
+     * Writes at most once per THROTTLE window per room; `flushLastActive` forces
+     * one out at close/prune time so a room that goes quiet still records its real
+     * last activity.
+     */
+    touchLastActive(id, ts) {
+        this.pendingLastActive.set(id, ts);
+        const lastWrite = this.lastActiveWrittenAt.get(id) ?? 0;
+        if (ts - lastWrite < LAST_ACTIVE_THROTTLE_MS)
+            return;
+        this.flushLastActive(id);
+    }
+    /** Persist a pending lastActiveAt immediately, if there is one. */
+    flushLastActive(id) {
+        const ts = this.pendingLastActive.get(id);
+        if (ts === undefined)
+            return;
+        this.pendingLastActive.delete(id);
+        const meta = this.getRoom(id);
+        if (!meta)
+            return;
+        this.lastActiveWrittenAt.set(id, ts);
+        writeFileSync(this.metaPath(id), JSON.stringify({ ...meta, lastActiveAt: ts }, null, 2), "utf-8");
+    }
+    /** Persist the room's resume id (claude session_id / codex thread_id) so the
+     *  next open() can continue the same conversation. No-op if unchanged. */
+    setRoomSessionId(id, sessionId) {
+        const meta = this.getRoom(id);
+        if (!meta || meta.claudeSessionId === sessionId)
+            return;
+        writeFileSync(this.metaPath(id), JSON.stringify({ ...meta, claudeSessionId: sessionId }, null, 2), "utf-8");
+    }
+    getMessages(id, sinceSeq = 0) {
+        if (!isValidRoomId(id))
+            return [];
+        const p = this.msgPath(id);
+        if (!existsSync(p))
+            return [];
+        const out = [];
+        for (const line of readFileSync(p, "utf-8").split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                const m = JSON.parse(line);
+                if (m.seq > sinceSeq)
+                    out.push(m);
+            }
+            catch {
+                /* skip */
+            }
+        }
+        return out;
+    }
+    latestSeq(id) {
+        return this.getMessages(id).at(-1)?.seq ?? 0;
+    }
+    beginTranscriptFollow(id) {
+        if (this.getRoom(id))
+            this.transcriptFollowedRooms.add(id);
+    }
+    endTranscriptFollow(id) {
+        this.transcriptFollowedRooms.delete(id);
+    }
+    /** Persist normalized transcript-tail messages through the same seq/history/
+     * broadcast path as resident-agent output. */
+    ingestTranscriptMessages(id, messages) {
+        if (!this.transcriptFollowedRooms.has(id) || !this.getRoom(id))
+            return;
+        for (const message of messages) {
+            if (message.from === "user" && typeof message.text === "string") {
+                const text = stripRoomAttachmentBlock(message.text);
+                const pending = this.pendingTranscriptUserEchoes.get(id);
+                const cutoff = this.now() - 60_000;
+                while (pending?.length && pending[0].ts < cutoff)
+                    pending.shift();
+                const matched = pending?.[0]?.text === text;
+                if (matched)
+                    pending.shift();
+                if (pending?.length === 0)
+                    this.pendingTranscriptUserEchoes.delete(id);
+                // `send` already persisted and broadcast this exact user turn. The
+                // transcript remains authoritative for agent/tool output, but must not
+                // render a second copy of the prompt.
+                if (!matched)
+                    this.append(id, { ...message, text });
+            }
+            else {
+                this.append(id, message);
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    openForSession(claudeSessionId, cwd, mode, kind = "claude-code") {
+        // 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({
+                cwd,
+                kind,
+                permissionMode: mode,
+                claudeSessionId: claudeSessionId || undefined,
+            });
+        // 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) {
+            writeFileSync(this.metaPath(meta.id), JSON.stringify({ ...meta, permissionMode: mode }, null, 2), "utf-8");
+            this.close(meta.id); // stop the old-mode process so open() respawns fresh
+        }
+        const { status } = this.open(meta.id);
+        return { roomId: meta.id, status };
+    }
+    /** Bind an external CLI transcript to a room for observation only.
+     *
+     * This method never creates or starts a resident agent. The host must first
+     * prove that an on-disk transcript exists for the exact kind + session id +
+     * cwd tuple. A missing locator, missing transcript, or mismatched identity
+     * fails closed before a room is created.
+     */
+    openLinkedSession(externalSessionId, cwd, kind) {
+        const target = this.requireLinkedSessionTarget({ externalSessionId, cwd, kind });
+        const existing = this.listRooms().find((room) => room.claudeSessionId === target.externalSessionId && room.kind === target.kind);
+        if (existing && resolve(existing.cwd) !== target.cwd) {
+            throw new Error("linked session cwd does not match the existing room");
+        }
+        const isRunning = existing ? this.isOpen(existing.id) : false;
+        let meta;
+        if (existing) {
+            meta = {
+                ...existing,
+                cwd: target.cwd,
+            };
+            // Navigation must not turn an ordinary dormant room into a permanently
+            // observe-only room. Existing linked rooms keep their boundary; ordinary
+            // rooms are observed transiently and remain writable through the normal
+            // open flow.
+            if (meta.cwd !== existing.cwd) {
+                writeFileSync(this.metaPath(meta.id), JSON.stringify(meta, null, 2), "utf-8");
+            }
+        }
+        else {
+            meta = this.createRoom({
+                cwd: target.cwd,
+                kind: target.kind,
+                permissionMode: "default",
+                claudeSessionId: target.externalSessionId,
+                linkedSessionMode: "observe-only",
+            });
+        }
+        const status = isRunning ? "running" : "observing";
+        return { roomId: meta.id, status, mode: meta.permissionMode, cwd: meta.cwd };
+    }
+    /** Explicitly take control of a previously observed external CLI room.
+     * 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) {
+        const target = this.requireLinkedSessionTarget({ externalSessionId, cwd, kind });
+        const meta = this.getRoom(roomId);
+        if (!meta ||
+            meta.claudeSessionId !== target.externalSessionId ||
+            meta.kind !== target.kind ||
+            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,
+        };
+        writeFileSync(this.metaPath(roomId), JSON.stringify(controllableMeta, null, 2), "utf-8");
+        const { status } = this.open(roomId);
+        if (status !== "running") {
+            throw new Error("linked session room is unavailable");
+        }
+        return { roomId, status, mode: controllableMeta.permissionMode, cwd: controllableMeta.cwd };
+    }
+    requireLinkedSessionTarget(target) {
+        if (!target.externalSessionId.trim() ||
+            !target.cwd.trim() ||
+            (target.kind !== "claude-code" && target.kind !== "codex")) {
+            throw new Error("linked session id, cwd, and kind are required");
+        }
+        let resolvedTarget;
+        try {
+            resolvedTarget = this.opts.resolveLinkedSession?.(target);
+        }
+        catch {
+            throw new Error("linked session transcript is unavailable");
+        }
+        if (!resolvedTarget ||
+            typeof resolvedTarget.externalSessionId !== "string" ||
+            typeof resolvedTarget.cwd !== "string" ||
+            resolvedTarget.externalSessionId !== target.externalSessionId ||
+            resolvedTarget.kind !== target.kind ||
+            resolve(resolvedTarget.cwd) !== resolve(target.cwd)) {
+            throw new Error("linked session transcript does not match the requested session");
+        }
+        return { ...target, cwd: resolve(resolvedTarget.cwd) };
+    }
+    /**
+     * Forward a phone-side approval decision to the room's resident agent.
+     * Returns false if the room has no live agent (or it can't take control
+     * responses).
+     */
+    respondApproval(roomId, requestId, decision) {
+        // Reap the stashed AskUser input FIRST, before the agent-existence check.
+        // Otherwise, if the agent already exited, the early return below would skip
+        // the delete and leak the pending entry (and the approval card would hang
+        // until its timeout). Deleting up front is safe: a missing agent means the
+        // request can no longer be answered anyway.
+        const askKey = `${roomId}:${requestId}`;
+        const pending = this.pendingAskUser.get(askKey);
+        if (pending !== undefined)
+            this.pendingAskUser.delete(askKey);
+        const agent = this.agents.get(roomId);
+        if (!agent?.respondControl)
+            return false;
+        // AskUserQuestion: an "allow" carries the user's chosen answer string, which
+        // main (the single source of truth) bakes into the `answers` record keyed by
+        // question text — the only shape the CLI accepts. The raw input was stashed
+        // on approval_request. Deny passes through (claude treats it as "did not
+        // answer", same as the desktop CLI's own cancel).
+        if (pending !== undefined) {
+            if (decision.behavior === "deny") {
+                agent.respondControl(requestId, decision);
+                return true;
+            }
+            const prompt = askUserPrompt(pending);
+            const answersByQuestion = prompt ? { [prompt.question]: decision.answer ?? "" } : {};
+            agent.respondControl(requestId, {
+                behavior: "allow",
+                updatedInput: buildAskUserUpdatedInput(pending, answersByQuestion),
+            });
+            return true;
+        }
+        agent.respondControl(requestId, decision);
+        return true;
+    }
+    /** Open a room: start its resident agent if not already running. Observe-only
+     * linked rooms fail closed until takeOverLinkedSession clears the boundary. */
+    open(id) {
+        const meta = this.getRoom(id);
+        if (!meta)
+            return { status: "missing" };
+        if (meta.linkedSessionMode === "observe-only")
+            return { status: "observing" };
+        if (!this.agents.has(id)) {
+            const agent = this.opts.createAgent(meta, (event) => this.onAgentEvent(id, event));
+            this.agents.set(id, agent);
+            agent.start();
+        }
+        return { status: "running" };
+    }
+    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.
+        if (this.deferredEmitRooms.has(id)) {
+            const queued = this.deferredEmits.get(id) ?? [];
+            queued.push(event);
+            this.deferredEmits.set(id, queued);
+            return;
+        }
+        if (this.transcriptFollowedRooms.has(id) &&
+            (event.type === "text" ||
+                event.type === "tool" ||
+                event.type === "tool_result" ||
+                event.type === "turn_end")) {
+            return;
+        }
+        switch (event.type) {
+            case "text":
+                this.append(id, { from: "agent", type: "text", text: event.text });
+                break;
+            case "tool":
+                this.append(id, {
+                    from: "agent",
+                    type: "tool",
+                    tool: event.tool,
+                    summary: event.summary,
+                    toolId: event.id,
+                    args: event.input,
+                });
+                break;
+            case "tool_result":
+                this.append(id, {
+                    from: "agent",
+                    type: "tool_result",
+                    summary: event.summary,
+                    isError: event.isError,
+                    toolId: event.id,
+                });
+                break;
+            case "turn_end":
+                this.append(id, { from: "agent", type: "turn_end", reason: event.reason });
+                break;
+            case "error":
+                this.append(id, { from: "system", type: "error", text: event.error });
+                break;
+            case "approval_request": {
+                // Skill routes through can_use_tool only to deliver its args (nothing to
+                // ask the user), and emits the request even under bypassPermissions —
+                // auto-allow it, echoing the input back, rather than show a dead-end
+                // card.
+                if (AUTO_ALLOW_TOOLS.has(event.toolName)) {
+                    this.agents
+                        .get(id)
+                        ?.respondControl?.(event.requestId, { behavior: "allow", updatedInput: event.input });
+                    break;
+                }
+                // AskUserQuestion is NOT a permission gate — it needs the user's actual
+                // choice. Parse the options (askUser) so the UI shows a choice card, and
+                // stash the raw input so respondApproval can bake the answer into the
+                // `answers` record the CLI requires. Auto-allowing the unanswered input
+                // is what made claude report "The user did not answer the questions".
+                if (event.toolName === "AskUserQuestion") {
+                    const askUser = askUserPrompt(event.input);
+                    if (askUser) {
+                        this.pendingAskUser.set(`${id}:${event.requestId}`, event.input);
+                        this.append(id, {
+                            from: "agent",
+                            type: "approval",
+                            tool: event.toolName,
+                            summary: askUser.question,
+                        });
+                        this.opts.onApprovalRequest?.(id, { ...event, askUser });
+                        break;
+                    }
+                    // Malformed AskUser (no questions) → auto-allow so the turn isn't
+                    // wedged forever waiting on an answer that can't be collected.
+                    this.agents
+                        .get(id)
+                        ?.respondControl?.(event.requestId, { behavior: "allow", updatedInput: event.input });
+                    break;
+                }
+                this.append(id, {
+                    from: "agent",
+                    type: "approval",
+                    tool: event.toolName,
+                    summary: event.description ?? "",
+                });
+                this.opts.onApprovalRequest?.(id, event);
+                break;
+            }
+            case "exit":
+                this.agents.delete(id);
+                this.clearPendingAskUser(id);
+                // Let the transcript follower synchronously drain final file bytes
+                // before appending the terminal marker. Otherwise an exit that beats
+                // watchFile's poll can drop the last assistant line or place it after
+                // agent_exit in the room stream.
+                this.opts.onRoomEnded?.(id);
+                this.append(id, {
+                    from: "system",
+                    type: "agent_exit",
+                    reason: String(event.code ?? event.signal ?? ""),
+                });
+                break;
+        }
+    }
+    /** Post a user message: persist it, ensure agent running, feed it. */
+    send(id, text, attachments = []) {
+        const meta = this.getRoom(id);
+        if (!meta)
+            return false;
+        const displayText = text.trim();
+        if (!displayText && attachments.length === 0)
+            return false;
+        if (this.open(id).status !== "running")
+            return false;
+        const summaries = roomAttachmentSummary(attachments);
+        const agentText = roomTurnText(displayText, attachments);
+        // Decide acceptance BEFORE persisting, but keep the user turn first in the
+        // history.
+        //
+        // The old order was append-then-send, with send()'s result returned straight
+        // to the phone. `CodexRoomAgent.send()` returns false while a previous turn
+        // is still running, so the phone showed "房间未就绪或已关闭" while the very
+        // same text was already in messages.jsonl and broadcast to every other
+        // client — a message that looks delivered but was never given to the agent.
+        // With attachments it was worse: the handler released the upload claim,
+        // leaving a history entry pointing at an attachment that never materialized.
+        //
+        // Simply moving append() after send() is not enough: an agent that emits its
+        // reply synchronously from send() would land the reply BEFORE the user turn.
+        // So buffer anything the agent emits during the call and flush it after the
+        // user message is appended. (The real Codex agent spawns a child and emits
+        // asynchronously, but ordering must not depend on that.)
+        const agent = this.agents.get(id);
+        if (!agent)
+            return false;
+        this.deferredEmitRooms.add(id);
+        let accepted = false;
+        try {
+            accepted = agent.send(agentText);
+        }
+        finally {
+            this.deferredEmitRooms.delete(id);
+        }
+        const buffered = this.deferredEmits.get(id) ?? [];
+        this.deferredEmits.delete(id);
+        if (!accepted) {
+            // Rejected: nothing about this turn reaches history or the phone.
+            return false;
+        }
+        this.append(id, {
+            from: "user",
+            type: "text",
+            text: displayText,
+            ...(summaries.length ? { attachments: summaries } : {}),
+        });
+        if (this.transcriptFollowedRooms.has(id)) {
+            const pending = this.pendingTranscriptUserEchoes.get(id) ?? [];
+            pending.push({ text: displayText, ts: this.now() });
+            this.pendingTranscriptUserEchoes.set(id, pending);
+        }
+        // Replay whatever the agent produced synchronously, now correctly ordered
+        // after the user turn.
+        for (const event of buffered)
+            this.onAgentEvent(id, event);
+        return true;
+    }
+    close(id) {
+        // A room going quiet must record its REAL last activity, not the last
+        // throttled write.
+        this.flushLastActive(id);
+        this.agents.get(id)?.stop();
+        this.agents.delete(id);
+        this.clearPendingAskUser(id);
+        this.pendingTranscriptUserEchoes.delete(id);
+        this.opts.onRoomEnded?.(id);
+    }
+    closeAll() {
+        const ids = new Set([...this.agents.keys(), ...this.transcriptFollowedRooms]);
+        for (const agent of this.agents.values())
+            agent.stop();
+        this.agents.clear();
+        this.pendingAskUser.clear();
+        this.pendingTranscriptUserEchoes.clear();
+        for (const id of ids)
+            this.opts.onRoomEnded?.(id);
+        this.transcriptFollowedRooms.clear();
+    }
+    isOpen(id) {
+        return this.agents.get(id)?.isRunning() ?? false;
+    }
+    /**
+     * Delete rooms whose last activity is older than maxAgeMs (idle-based GC,
+     * replacing the removed one-shot /cc path's lack of cleanup). A room with a
+     * currently running resident agent is NEVER reaped, regardless of age — only
+     * truly dormant rooms (whole directory) are removed. Returns the ids deleted.
+     */
+    pruneStaleRooms(maxAgeMs) {
+        // Flush pending timestamps first: pruning reads lastActiveAt off disk, and a
+        // throttled-but-unwritten value would make an active room look dormant.
+        for (const id of [...this.pendingLastActive.keys()])
+            this.flushLastActive(id);
+        const cutoff = this.now() - maxAgeMs;
+        const removed = [];
+        for (const meta of this.listRooms()) {
+            if (meta.lastActiveAt > cutoff)
+                continue;
+            if (this.isOpen(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);
+            removed.push(meta.id);
+        }
+        return removed;
+    }
+}