@cjhyy/code-shell-server 0.9.46 → 0.9.48

package/README.md

@@ -83,6 +83,10 @@ Desktop Web 和 Hub 在注销或显式撤销会话时，会关闭该会话尚未
 响应，包括正在下载的文件，并停止源文件读取、释放句柄。其他会话的下载不受影响；
 已经返回接受结果的后台任务仍由原来的任务生命周期管理。注销请求本身仍返回成功。
 
+Hub 认证每次读取磁盘上的当前会话；只有需要更新活动时间时才获取写锁，并在锁内
+重新验证撤销与过期状态。Hub 与 Mobile 静态文件按打开时的大小流式发送，`HEAD`
+只返回元数据；客户端断开会停止读取。首页和 SPA 回退也遵守静态目录边界。
+
 ## code-shell-serve — 个人 Hub Web host
 
 在任意机器上把一个 workspace 变成浏览器可访问的 CodeShell：

package/dist/hub/auth-store.d.ts

@@ -40,6 +40,7 @@ export declare class HubAuthStore {
     }): Promise<HubSessionGrant>;
     login(input: HubLoginInput, replaceToken?: string): Promise<HubSessionGrant>;
     authenticate(token: string | undefined): HubSession | null;
+    private findSession;
     listSessions(): HubSession[];
     /** Offline restore must not resurrect sessions revoked after the snapshot. */
     revokeAllSessions(): void;
@@ -49,6 +50,7 @@ export declare class HubAuthStore {
     private toPublic;
     private mutate;
     private ensureDirectory;
+    private assertDirectory;
     private read;
     private write;
 }

package/dist/hub/auth-store.js

@@ -93,20 +93,36 @@ export class HubAuthStore {
     authenticate(token) {
         if (!token || !TOKEN_PATTERN.test(token))
             return null;
+        // Writers publish by atomic rename. Read the committed record on every
+        // request, but only contend for the writer lock when activity needs saving.
+        this.assertDirectory();
+        const tokenHash = hashToken(token);
+        const record = this.read();
+        const now = this.now();
+        const session = this.findSession(record, tokenHash, now);
+        if (!session)
+            return null;
+        if (now - session.lastSeenAt < 60_000)
+            return this.toPublic(record, session);
         return this.mutate((record) => {
             const now = this.now();
-            const tokenHash = hashToken(token);
-            const session = record.sessions.find((row) => safeHashEqual(row.tokenHash, tokenHash));
-            if (!record.account || !session || session.expiresAt <= now || session.createdAt > now) {
+            // Recheck after taking the lock: a peer may have revoked, replaced or
+            // refreshed the session since the unlocked read. Never write that snapshot.
+            const session = this.findSession(record, tokenHash, now);
+            if (!session)
                 return { result: null, changed: false };
-            }
-            // Persist activity at most once per minute; validation always reads disk.
             const changed = now - session.lastSeenAt >= 60_000;
             if (changed)
                 session.lastSeenAt = now;
             return { result: this.toPublic(record, session), changed };
         });
     }
+    findSession(record, tokenHash, now) {
+        if (!record.account)
+            return null;
+        const session = record.sessions.find((row) => safeHashEqual(row.tokenHash, tokenHash));
+        return session && session.expiresAt > now && session.createdAt <= now ? session : null;
+    }
     listSessions() {
         const record = this.read();
         const now = this.now();
@@ -194,10 +210,13 @@ export class HubAuthStore {
     ensureDirectory() {
         const parent = dirname(this.filePath);
         mkdirSync(parent, { recursive: true, mode: 0o700 });
-        const metadata = lstatSync(parent);
+        this.assertDirectory();
+        chmodSync(parent, 0o700);
+    }
+    assertDirectory() {
+        const metadata = lstatSync(dirname(this.filePath));
         if (!metadata.isDirectory() || metadata.isSymbolicLink())
             throw new Error("Invalid Hub auth directory");
-        chmodSync(parent, 0o700);
     }
     read(allowMissing = false) {
         let descriptor;

package/dist/mobile-remote/codex-room-agent.d.ts

@@ -76,12 +76,6 @@ export declare class CodexRoomAgent implements RoomAgent {
     private child?;
     private threadId?;
     private started;
-    /** True once the CURRENT turn emitted a sealing event (turn_end via
-     *  turn.completed, or an error). Reset at the start of each send(). */
-    private turnSealed;
-    /** True while stop() is tearing the room down, so the exit handler doesn't
-     *  mistake an intentional SIGTERM for a crash. */
-    private stopping;
     constructor(opts: CodexRoomAgentOptions);
     /** No persistent process to launch; a turn's process is spawned on send(). */
     start(): void;

package/dist/mobile-remote/codex-room-agent.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { releaseStdioAfterExit, stopRoomProcess } from "./room-process-stop.js";
 import { createInterface } from "node:readline";
 import { pathWithCommonBins } from "./path-bins.js";
 import { parseCodexJsonLine, extractThreadId } from "./codex-parse.js";
@@ -86,12 +87,6 @@ export class CodexRoomAgent {
     child;
     threadId;
     started = false;
-    /** True once the CURRENT turn emitted a sealing event (turn_end via
-     *  turn.completed, or an error). Reset at the start of each send(). */
-    turnSealed = false;
-    /** True while stop() is tearing the room down, so the exit handler doesn't
-     *  mistake an intentional SIGTERM for a crash. */
-    stopping = false;
     constructor(opts) {
         this.opts = opts;
         this.threadId = opts.resumeThreadId;
@@ -105,7 +100,7 @@ export class CodexRoomAgent {
             return false;
         if (this.child)
             return false; // a turn is already running; one turn at a time
-        this.turnSealed = false; // fresh turn — not yet sealed
+        let turnSealed = false; // This child owns only its own turn and callbacks.
         const args = codexArgsForTurn({ mode: this.opts.permissionMode, threadId: this.threadId });
         const child = spawn(this.opts.command, args, {
             cwd: this.opts.cwd,
@@ -114,11 +109,13 @@ export class CodexRoomAgent {
             stdio: ["pipe", "pipe", "pipe"],
         });
         this.child = child;
-        // Feed the user's prompt over stdin (codex exec reads it because argv ends `-`).
-        child.stdin?.end(text);
+        // Settle on `close` so trailing output is read, without waiting on grandchildren.
+        releaseStdioAfterExit(child);
         if (child.stdout) {
             const rl = createInterface({ input: child.stdout });
             rl.on("line", (line) => {
+                if (this.child !== child)
+                    return;
                 // Capture the thread id (parseCodexJsonLine intentionally drops
                 // thread.started — it's resume-control info, not a render event) so we
                 // can resume on the next turn and persist it across restarts.
@@ -131,7 +128,7 @@ export class CodexRoomAgent {
                     // turn_end / error are the reducer's sealing events — once one fires
                     // for this turn, the exit handler need not synthesize a fallback.
                     if (ev.type === "turn_end" || ev.type === "error")
-                        this.turnSealed = true;
+                        turnSealed = true;
                     this.opts.onEvent(ev);
                 }
             });
@@ -146,17 +143,32 @@ export class CodexRoomAgent {
             errRl.on("line", (line) => stderrLines.push(line));
         }
         child.on("error", (err) => {
+            if (this.child !== child)
+                return;
+            this.child = undefined;
             const isMissing = err.code === "ENOENT";
-            this.turnSealed = true; // this error seals the run in the reducer
+            turnSealed = true; // this error seals the run in the reducer
             this.opts.onEvent({
                 type: "error",
                 error: isMissing
                     ? `未找到命令 "${this.opts.command}"。请先安装 Codex CLI 并确保它在 PATH 中。`
                     : err.message,
             });
+        });
+        child.stdin?.on("error", (error) => {
+            if (this.child !== child)
+                return;
             this.child = undefined;
+            stopRoomProcess(child);
+            this.opts.onEvent({
+                type: "error",
+                error: `Codex input pipe closed${error.code ? ` (${error.code})` : ""}`,
+            });
         });
-        child.on("exit", (code, signal) => {
+        child.on("close", (code, signal) => {
+            if (this.child !== child)
+                return;
+            this.child = undefined;
             // The turn's process is done; the room stays "running" (ready for the next
             // turn). We do NOT emit `exit` here — that would tear the room down in the
             // UI after every turn. turn.completed already produced a `turn_end`.
@@ -164,7 +176,7 @@ export class CodexRoomAgent {
             // is surfaced now so the room shows *why* it failed.
             const stderrErr = codexStderrError(stderrLines, code);
             if (stderrErr) {
-                this.turnSealed = true;
+                turnSealed = true;
                 this.opts.onEvent({ type: "error", error: stderrErr });
             }
             // FALLBACK SEAL (#6): if the process died without ever sealing the turn
@@ -174,14 +186,16 @@ export class CodexRoomAgent {
             const seal = sealEventOnExit({
                 code,
                 signal,
-                turnSealed: this.turnSealed,
-                stopping: this.stopping,
+                turnSealed,
+                stopping: false,
                 hasStderrError: stderrErr != null,
             });
             if (seal)
                 this.opts.onEvent(seal);
-            this.child = undefined;
         });
+        // Register stdin's error owner before writing: early CLI exits fail writes
+        // asynchronously even when end() itself returns successfully.
+        child.stdin?.end(text);
         return true;
     }
     /** The room is "running" once started — independent of whether a turn's
@@ -191,23 +205,9 @@ export class CodexRoomAgent {
     }
     stop() {
         this.started = false;
-        this.stopping = true; // the upcoming SIGTERM exit is intentional, not a crash
         const child = this.child;
         this.child = undefined;
-        if (!child?.pid || child.pid <= 1) {
-            child?.kill("SIGTERM");
-            return;
-        }
-        try {
-            process.kill(-child.pid, "SIGTERM");
-        }
-        catch {
-            try {
-                child.kill("SIGTERM");
-            }
-            catch {
-                /* already gone */
-            }
-        }
+        if (child)
+            stopRoomProcess(child);
     }
 }

package/dist/mobile-remote/mobile-chat-turn.d.ts

@@ -33,6 +33,12 @@ export type DispatchMobileChatTurnResult = {
 } | {
     ok: false;
     message: string;
+    uncertain?: false;
+} | {
+    ok: false;
+    message: string;
+    uncertain: true;
+    clientMessageId: string;
 };
 /** Transaction boundary for mobile chat: workspace → canonical stage → worker ack → finalize. */
 export declare function dispatchMobileChatTurn(input: DispatchMobileChatTurnInput): Promise<DispatchMobileChatTurnResult>;

package/dist/mobile-remote/mobile-chat-turn.js

@@ -63,11 +63,24 @@ export async function dispatchMobileChatTurn(input) {
             : await injectMobileRunAndAwaitAcceptance(input.bridge, request, input.meta);
     }
     catch {
-        acceptance = { ok: false, message: "The selected runtime rejected the submission" };
+        acceptance = {
+            ok: false,
+            uncertain: true,
+            message: "The selected runtime did not confirm the submission",
+        };
     }
     if (!acceptance.ok) {
+        // Worker input refers to the canonical staged files, not these temporary
+        // upload spools. Keep the staged files for a possibly accepted run and
+        // release only the claims so the same intent can retry its attachments.
+        // A late acceptance may never be observed, so uncertain files also need
+        // sent retention rather than expiring as abandoned drafts after one day.
+        if (acceptance.uncertain)
+            await (input.markSent ?? markAttachmentsSent)(cwd, input.sessionId, materialized.metas).catch(() => undefined);
         await settleClaims(input.uploads, input.deviceId, materialized.claims, "release");
-        return { ok: false, message: acceptance.message };
+        return acceptance.uncertain
+            ? { ok: false, message: acceptance.message, uncertain: true, clientMessageId }
+            : { ok: false, message: acceptance.message };
     }
     await (input.markSent ?? markAttachmentsSent)(cwd, input.sessionId, materialized.metas).catch(() => undefined);
     await settleClaims(input.uploads, input.deviceId, materialized.claims, "finalize");

package/dist/mobile-remote/mobile-client-event-validator.js

@@ -52,6 +52,14 @@ export function parseMobileClientEvent(value) {
         case "session.recovery.cancel":
             valid = true;
             break;
+        case "session.legacyBase":
+            valid =
+                boundedString(event.sessionId, 128) &&
+                    boundedString(event.recoveryId, 128) &&
+                    boundedString(event.requestId, 128) &&
+                    ((boundedString(event.throughEventId, 512) && event.cursor === undefined) ||
+                        (boundedString(event.cursor, 2048) && event.throughEventId === undefined));
+            break;
         case "session.outputJournal":
             valid =
                 boundedString(event.sessionId, 128) &&

package/dist/mobile-remote/mobile-run-dispatch.d.ts

@@ -13,6 +13,7 @@ export type MobileRunAcceptance = {
     ok: false;
     message: string;
     code?: number;
+    uncertain?: true;
 };
 /** Inject agent/run and wait for its request-correlated validation/queue acknowledgement. */
 export declare function injectMobileRunAndAwaitAcceptance(bridge: MobileRunBridge, request: MobileRunRequest, meta: WorkerFrameMeta, timeoutMs?: number): Promise<MobileRunAcceptance>;

package/dist/mobile-remote/mobile-run-dispatch.js

@@ -2,7 +2,6 @@
 export function injectMobileRunAndAwaitAcceptance(bridge, request, meta, timeoutMs = 5_000) {
     return new Promise((resolve) => {
         let settled = false;
-        let timer;
         const finish = (result) => {
             if (settled)
                 return;
@@ -40,17 +39,26 @@ export function injectMobileRunAndAwaitAcceptance(bridge, request, meta, timeout
                 // Not JSON or not part of this request.
             }
         });
-        timer = setTimeout(() => finish({ ok: false, message: "worker did not acknowledge the run" }), timeoutMs);
+        const timer = setTimeout(() => finish({ ok: false, uncertain: true, message: "worker did not acknowledge the run" }), timeoutMs);
+        let injecting = false;
         try {
-            bridge.injectWorkerMessage(JSON.stringify({
+            const line = JSON.stringify({
                 jsonrpc: "2.0",
                 id: request.id,
                 method: "agent/run",
                 params: request.params,
-            }), meta);
+            });
+            injecting = true;
+            bridge.injectWorkerMessage(line, meta);
         }
         catch (error) {
-            finish({ ok: false, message: error instanceof Error ? error.message : String(error) });
+            // An injection can fail after queuing bytes. Only serialization failure
+            // proves that this request never reached the transport.
+            finish({
+                ok: false,
+                message: error instanceof Error ? error.message : String(error),
+                ...(injecting ? { uncertain: true } : {}),
+            });
         }
     });
 }

package/dist/mobile-remote/mobile-static.d.ts

@@ -38,12 +38,11 @@ export declare function mobileEntryRedirect(reqUrl: string): string | null;
  *  can see through it. Guarding that would need inode/device policy, and anyone
  *  able to hardlink into the served root can already write files there.
  *
- *  The returned path is the REQUESTED one, not the realpath: callers stream it
- *  directly and the resolved-name contract is relied on elsewhere (on macOS the
- *  realpath of a /var root is /private/var, which would change every result).
- *  That leaves the same synchronous stat-then-read window this module always
- *  had; closing it properly needs an open-then-fstat rework of both callers,
- *  which is out of scope for this fix. */
+ *  The returned path is the REQUESTED one, not the realpath: the resolved-name
+ *  contract is relied on elsewhere (on macOS the realpath of a /var root is
+ *  /private/var, which would change every result). This is only a routing check;
+ *  both HTTP callers open and revalidate the selected file through
+ *  streamStaticFile before returning bytes. */
 export declare function resolveSafe(root: string, subPath: string): string | null;
 export interface MobileStaticOptions {
     /** Absolute path to the built mobile app (out/mobile). */

package/dist/mobile-remote/mobile-static.js

@@ -1,7 +1,7 @@
-import { createReadStream, existsSync, realpathSync, statSync } from "node:fs";
+import { existsSync, realpathSync, statSync } from "node:fs";
 import { isAbsolute, join, normalize, relative, resolve, sep, extname } from "node:path";
 import { request as httpRequest } from "node:http";
-import { contentTypeFor } from "../static-files.js";
+import { contentTypeFor, streamStaticFile } from "../static-files.js";
 /**
  * Serves the built mobile web app (out/mobile) as static assets for the
  * `/mobile` route family, replacing the old inline `mobileRemoteHtml()` string.
@@ -61,12 +61,11 @@ function isContained(root, target) {
  *  can see through it. Guarding that would need inode/device policy, and anyone
  *  able to hardlink into the served root can already write files there.
  *
- *  The returned path is the REQUESTED one, not the realpath: callers stream it
- *  directly and the resolved-name contract is relied on elsewhere (on macOS the
- *  realpath of a /var root is /private/var, which would change every result).
- *  That leaves the same synchronous stat-then-read window this module always
- *  had; closing it properly needs an open-then-fstat rework of both callers,
- *  which is out of scope for this fix. */
+ *  The returned path is the REQUESTED one, not the realpath: the resolved-name
+ *  contract is relied on elsewhere (on macOS the realpath of a /var root is
+ *  /private/var, which would change every result). This is only a routing check;
+ *  both HTTP callers open and revalidate the selected file through
+ *  streamStaticFile before returning bytes. */
 export function resolveSafe(root, subPath) {
     const rootResolved = resolve(root);
     const rel = normalize(subPath || "index.html");
@@ -77,11 +76,11 @@ export function resolveSafe(root, subPath) {
     const full = resolve(join(rootResolved, rel));
     if (!isContained(rootResolved, full))
         return null;
-    if (!existsSync(full) || !statSync(full).isFile())
-        return null;
     // realpathSync throws on a dangling link or a race-deleted file; a missing
     // target is a 404 through the normal contract, never a 500.
     try {
+        if (!existsSync(full) || !statSync(full).isFile())
+            return null;
         if (!isContained(realpathSync(rootResolved), realpathSync(full)))
             return null;
     }
@@ -143,15 +142,15 @@ export function serveMobile(req, res, opts) {
     // stale index.html would reference deleted assets → 404 → blank page until a
     // hard refresh.
     const isHtml = type.startsWith("text/html");
-    res.writeHead(200, {
-        "content-type": type,
-        "cache-control": isHtml
+    void streamStaticFile(req, res, {
+        rootDir: opts.rootDir,
+        filePath: file,
+        cacheControl: isHtml
             ? "no-store"
             : sub.startsWith("assets/")
                 ? "public, max-age=31536000, immutable"
                 : "no-cache",
     });
-    createReadStream(file).pipe(res);
 }
 /** Dev-only: forward the request to the mobile vite dev server. The mobile vite
  *  config sets base "/mobile/", so vite serves its HMR client, module graph, and

package/dist/mobile-remote/remote-host-manager.d.ts

@@ -37,6 +37,8 @@ export interface RemoteHostStarted {
 export interface RemoteHostManagerOptions {
     devices: TrustedDeviceStore;
     outputJournal?: boolean;
+    /** Enable only when the attached selected-session host implements legacy base pages. */
+    legacyBasePages?: boolean;
     onClientEvent: (event: unknown, ws: WebSocket) => void | Promise<void>;
     /**
      * Absolute path to the built mobile app (out/mobile). Defaults to the

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

@@ -126,6 +126,16 @@ export class RemoteHostManager extends EventEmitter {
         const gate = this.passcode;
         this.opts.webApi?.start();
         const server = createServer((req, res) => {
+            let pathname;
+            try {
+                pathname = new URL(req.url ?? "/", "http://localhost").pathname;
+            }
+            catch {
+                res.writeHead(400, { "content-type": "text/plain; charset=utf-8" });
+                res.end("invalid request target");
+                req.resume();
+                return;
+            }
             // Tunnel mode: a passcode gate sits in front of EVERY route. The gate
             // either allows (returns true) or writes its own 401/403 challenge.
             if (gate && !gate.gate(req, res))
@@ -158,9 +168,7 @@ export class RemoteHostManager extends EventEmitter {
                 });
                 return;
             }
-            const uploadPath = req.url
-                ? new URL(req.url, "http://localhost").pathname.match(/^\/api\/mobile\/uploads\/([A-Za-z0-9_-]+)$/)
-                : null;
+            const uploadPath = pathname.match(/^\/api\/mobile\/uploads\/([A-Za-z0-9_-]+)$/);
             if (uploadPath && this.opts.uploads) {
                 void this.opts.uploads.acceptPut(uploadPath[1], req, res);
                 return;
@@ -411,7 +419,14 @@ export class RemoteHostManager extends EventEmitter {
             return {
                 type: "pair.ok",
                 device,
-                ...(this.opts.outputJournal ? { capabilities: { outputJournal: 1 } } : {}),
+                ...(this.opts.outputJournal
+                    ? {
+                        capabilities: {
+                            outputJournal: 1,
+                            ...(this.opts.legacyBasePages ? { legacyBasePages: 1 } : {}),
+                        },
+                    }
+                    : {}),
             };
         }
         if (event.type === "auth.device") {
@@ -427,7 +442,14 @@ export class RemoteHostManager extends EventEmitter {
             return {
                 type: "auth.ok",
                 device,
-                ...(this.opts.outputJournal ? { capabilities: { outputJournal: 1 } } : {}),
+                ...(this.opts.outputJournal
+                    ? {
+                        capabilities: {
+                            outputJournal: 1,
+                            ...(this.opts.legacyBasePages ? { legacyBasePages: 1 } : {}),
+                        },
+                    }
+                    : {}),
             };
         }
         return undefined;

package/dist/mobile-remote/resident-agent.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { releaseStdioAfterExit, stopRoomProcess } from "./room-process-stop.js";
 import { createInterface } from "node:readline";
 import { pathWithCommonBins } from "./path-bins.js";
 /**
@@ -148,14 +149,20 @@ export class ResidentAgentProcess {
             stdio: ["pipe", "pipe", "pipe"],
         });
         this.child = child;
+        // Settle on `close` so trailing output is read, without waiting on grandchildren.
+        releaseStdioAfterExit(child);
         if (child.stdout) {
             const rl = createInterface({ input: child.stdout });
             rl.on("line", (line) => {
+                if (this.child !== child)
+                    return;
                 for (const ev of parseStreamJsonLine(line))
                     this.opts.onEvent(ev);
             });
         }
         child.stderr?.on("data", (chunk) => {
+            if (this.child !== child)
+                return;
             // claude prints non-fatal warnings to stderr; surface as error events
             // only if they look like real errors (cheap heuristic).
             const text = String(chunk);
@@ -167,11 +174,14 @@ export class ResidentAgentProcess {
             if (exited)
                 return;
             exited = true;
-            if (this.child === child)
-                this.child = undefined;
+            if (this.child !== child)
+                return;
+            this.child = undefined;
             this.opts.onEvent({ type: "exit", code, signal });
         };
         child.on("error", (err) => {
+            if (this.child !== child)
+                return;
             const isMissing = err.code === "ENOENT";
             this.opts.onEvent({
                 type: "error",
@@ -184,7 +194,19 @@ export class ResidentAgentProcess {
             if (child.pid === undefined)
                 finish(null, null);
         });
-        child.on("exit", (code, signal) => finish(code, signal));
+        child.stdin?.on("error", (error) => {
+            if (this.child !== child)
+                return;
+            // Pipe errors are emitted by stdin, separately from ChildProcess.error.
+            // Retire this room immediately; its eventual exit must not close a retry.
+            stopRoomProcess(child);
+            this.opts.onEvent({
+                type: "error",
+                error: `Claude Code input pipe closed${error.code ? ` (${error.code})` : ""}`,
+            });
+            finish(null, null);
+        });
+        child.on("close", (code, signal) => finish(code, signal));
     }
     /** Feed one user turn. Returns false if the process isn't running. */
     send(text) {
@@ -206,24 +228,7 @@ export class ResidentAgentProcess {
     stop() {
         const child = this.child;
         this.child = undefined;
-        // Guard pid > 1: process.kill(-1) would SIGTERM every process the user can
-        // reach, and -0 the caller's own group. `!child?.pid` already catches
-        // undefined/0; the `> 1` also rules out the (theoretical) pid-1 case so this
-        // negative-pid group kill is consistent with killProcessGroup's guard.
-        if (!child?.pid || child.pid <= 1) {
-            child?.kill("SIGTERM");
-            return;
-        }
-        try {
-            process.kill(-child.pid, "SIGTERM");
-        }
-        catch {
-            try {
-                child.kill("SIGTERM");
-            }
-            catch {
-                /* already gone */
-            }
-        }
+        if (child)
+            stopRoomProcess(child);
     }
 }

package/dist/mobile-remote/room-manager.d.ts

@@ -119,6 +119,10 @@ export interface RoomManagerOptions {
      * Returning null means the transcript is absent. The returned identity is
      * checked again here so a stale or mismatched locator fails closed. */
     resolveLinkedSession?: (target: Readonly<LinkedSessionTarget>) => LinkedSessionTarget | null | undefined;
+    /** Throws while a background task (DriveAgent) may still be writing this
+     * external session. Checked before any resident agent can start on it, so
+     * desktop and phone entry points share one ownership gate. */
+    assertExternalSessionAvailable?: (externalSessionId: string, kind: RoomKind) => void;
     /** Called whenever a room gains a new persisted message (push to phone). */
     onMessage: (roomId: string, msg: RoomMessage) => void;
     /** Called when a room's resident agent requests tool-use approval. For

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

@@ -777,6 +777,8 @@ export class RoomManager {
      * so a given claude session maps to exactly one room. Returns the room id.
      */
     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.
@@ -851,6 +853,7 @@ export class RoomManager {
      * silently start a different session. */
     takeOverLinkedSession(roomId, externalSessionId, cwd, kind) {
         const target = this.requireLinkedSessionTarget({ externalSessionId, cwd, kind });
+        this.opts.assertExternalSessionAvailable?.(target.externalSessionId, target.kind);
         const meta = this.getRoom(roomId);
         if (!meta ||
             meta.claudeSessionId !== target.externalSessionId ||
@@ -890,8 +893,10 @@ export class RoomManager {
         catch {
             throw new Error("linked session transcript is unavailable");
         }
-        if (!resolvedTarget ||
-            typeof resolvedTarget.externalSessionId !== "string" ||
+        if (!resolvedTarget) {
+            throw new Error("linked session transcript was not found for the requested session");
+        }
+        if (typeof resolvedTarget.externalSessionId !== "string" ||
             typeof resolvedTarget.cwd !== "string" ||
             resolvedTarget.externalSessionId !== target.externalSessionId ||
             resolvedTarget.kind !== target.kind ||
@@ -967,6 +972,8 @@ export class RoomManager {
         if (meta.linkedSessionMode === "observe-only")
             return { status: "observing" };
         if (!this.agents.has(id)) {
+            if (meta.claudeSessionId)
+                this.opts.assertExternalSessionAvailable?.(meta.claudeSessionId, meta.kind);
             let agent = undefined;
             agent = this.opts.createAgent(meta, (event) => {
                 // stop() sends a signal; an old process can still drain output or emit

package/dist/mobile-remote/room-process-stop.d.ts

@@ -0,0 +1,11 @@
+import type { ChildProcess } from "node:child_process";
+/** Retire an unusable room transport without leaving an unresponsive CLI alive. */
+export declare function stopRoomProcess(child: ChildProcess): void;
+/**
+ * `close` waits for every holder of the child's stdout/stderr. A grandchild the
+ * CLI backgrounded with inherited stdio (a dev server, say) keeps them open
+ * after the CLI exits, so the room would never settle. Once the CLI has exited
+ * and its buffered output had a grace period to drain, release the pipes;
+ * the grandchild itself is left running.
+ */
+export declare function releaseStdioAfterExit(child: ChildProcess, graceMs?: number): void;