@steipete/oracle 0.18.0 → 0.19.0

package/dist/src/remote/server.js

@@ -8,7 +8,12 @@ import { randomBytes, randomUUID } from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
 import { mkdtemp, rm, mkdir, writeFile, stat, realpath } from "node:fs/promises";
 import chalk from "chalk";
+import { materializeStagedFallbackBundle } from "../browser/prompt.js";
 import { runBrowserMode } from "../browserMode.js";
+import { resolveBrowserConfig } from "../browser/config.js";
+import { RunSlots } from "./runSlots.js";
+export { RunSlots } from "./runSlots.js";
+import { loadUserConfig } from "../config.js";
 import { MAX_REMOTE_ARTIFACT_BYTES } from "./types.js";
 import { getCookies } from "@steipete/sweet-cookie";
 import { CHATGPT_URL } from "../browser/constants.js";
@@ -20,6 +25,8 @@ import { computeFileSha256, sanitizeArtifactFilename, sanitizeArtifactMimeType,
 const ARTIFACT_PROTOCOL_VERSION = 1;
 const REMOTE_ARTIFACT_TTL_MS = 30 * 60 * 1000;
 const ARTIFACT_CAPABILITIES = {
+    runCancellation: true,
+    deferredFallbackBundling: true,
     artifactTransfer: true,
     artifactProtocolVersion: ARTIFACT_PROTOCOL_VERSION,
     maxArtifactBytes: MAX_REMOTE_ARTIFACT_BYTES,
@@ -40,8 +47,29 @@ async function findAvailablePort() {
         });
     });
 }
+function validateAdmissionOptions(options) {
+    if (options.maxConcurrentRuns === undefined && options.maxQueuedRuns !== undefined)
+        throw new Error("--max-queued-runs requires --max-concurrent-runs.");
+    if (options.maxConcurrentRuns !== undefined &&
+        (!Number.isSafeInteger(options.maxConcurrentRuns) || options.maxConcurrentRuns < 1))
+        throw new Error("--max-concurrent-runs must be a positive integer.");
+    if (options.maxQueuedRuns !== undefined &&
+        (!Number.isSafeInteger(options.maxQueuedRuns) || options.maxQueuedRuns < 0))
+        throw new Error("--max-queued-runs must be a nonnegative integer.");
+}
 export async function createRemoteServer(options = {}, deps = {}) {
     const runBrowser = deps.runBrowser ?? runBrowserMode;
+    const attachedBrowser = usesHostBrowserAttachment(options.browserConfig);
+    const manualLoginDefault = !attachedBrowser && options.manualLoginDefault;
+    const hostBrowserConfig = options.browserConfig
+        ? {
+            attachRunning: options.browserConfig?.attachRunning,
+            remoteChrome: options.browserConfig?.remoteChrome
+                ? { ...options.browserConfig.remoteChrome }
+                : undefined,
+            approvalWaitMs: options.browserConfig?.approvalWaitMs,
+        }
+        : {};
     const server = http.createServer();
     const logger = options.logger ?? console.log;
     const authToken = options.token ?? randomBytes(16).toString("hex");
@@ -50,8 +78,20 @@ export async function createRemoteServer(options = {}, deps = {}) {
     const color = process.stdout.isTTY
         ? (formatter, msg) => formatter(msg)
         : (_formatter, msg) => msg;
-    // Single-flight guard: remote Chrome can only host one run at a time, so we serialize requests.
-    let busy = false;
+    validateAdmissionOptions(options);
+    const admissionEnabled = options.maxConcurrentRuns !== undefined;
+    const hostConfig = admissionEnabled ? (await loadUserConfig()).config.browser : undefined;
+    const browserTabCap = admissionEnabled
+        ? resolveBrowserConfig({ maxConcurrentTabs: hostConfig?.maxConcurrentTabs }).maxConcurrentTabs
+        : undefined;
+    const requestedConcurrency = options.maxConcurrentRuns ?? 1;
+    const effectiveConcurrency = Math.min(requestedConcurrency, browserTabCap ?? 1);
+    if (effectiveConcurrency < requestedConcurrency) {
+        logger(`[serve] Admitting ${effectiveConcurrency} concurrent run(s): the host tab cap is lower than the requested ${requestedConcurrency}.`);
+    }
+    const slots = new RunSlots(effectiveConcurrency, admissionEnabled ? (options.maxQueuedRuns ?? 8) : 0);
+    let legacyBusy = false;
+    const controllers = new Set();
     const artifactRegistry = new Map();
     if (!process.listenerCount("unhandledRejection")) {
         process.on("unhandledRejection", (reason) => {
@@ -81,6 +121,13 @@ export async function createRemoteServer(options = {}, deps = {}) {
                 version: getCliVersion(),
                 uptimeSeconds: Math.round((Date.now() - startedAt) / 1000),
                 capabilities: ARTIFACT_CAPABILITIES,
+                // So a caller can decide whether to send work now or later, instead of
+                // discovering the answer by being queued.
+                activeRuns: slots.activeCount,
+                queuedRuns: slots.queuedCount,
+                maxConcurrentRuns: slots.capacity,
+                maxQueuedRuns: slots.queueCapacity,
+                admissionMode: admissionEnabled ? "queue" : "legacy",
             }));
             return;
         }
@@ -112,75 +159,146 @@ export async function createRemoteServer(options = {}, deps = {}) {
             res.end(JSON.stringify({ error: "unauthorized" }));
             return;
         }
-        if (busy) {
-            if (verbose) {
-                logger(`[serve] Busy: rejecting new run from ${formatSocket(req)} while another run is active`);
-            }
-            res.writeHead(409, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({ error: "busy" }));
+        const refuse = () => {
+            res.writeHead(admissionEnabled ? 503 : 409, {
+                "Content-Type": "application/json",
+                ...(admissionEnabled ? { "Retry-After": "60" } : {}),
+            });
+            res.end(JSON.stringify({ error: admissionEnabled ? "queue_full" : "busy" }));
+        };
+        if (admissionEnabled ? slots.isSaturated : legacyBusy) {
+            refuse();
             return;
         }
-        busy = true;
+        if (!admissionEnabled)
+            legacyBusy = true;
         const runStartedAt = Date.now();
-        let payload = null;
+        const controller = new AbortController();
+        let signal = admissionEnabled ? controller.signal : undefined;
+        const onClientGone = () => controller.abort();
+        res.on("close", onClientGone);
+        req.on("aborted", onClientGone);
+        controllers.add(controller);
+        const detachController = () => {
+            res.off("close", onClientGone);
+            req.off("aborted", onClientGone);
+            controllers.delete(controller);
+        };
+        let queuePosition = 0;
+        let slotReady = false;
+        let pendingSlot;
+        let release;
+        const reserve = () => {
+            queuePosition = slots.positionFor();
+            pendingSlot = slots.acquire(signal).then((releaseSlot) => {
+                slotReady = true;
+                return releaseSlot;
+            });
+            // A queued request can disconnect before its body finishes parsing.
+            void pendingSlot.catch(() => undefined);
+        };
+        const abandon = async () => {
+            controller.abort();
+            if (pendingSlot)
+                await pendingSlot.then((releaseSlot) => releaseSlot(), () => { });
+            detachController();
+            legacyBusy = false;
+        };
+        // Opt-in admission includes body reception, bounding buffered requests and
+        // preserving arrival order even when a later caller uploads faster.
+        if (admissionEnabled)
+            reserve();
+        let payload;
         try {
-            const body = await readRequestBody(req);
-            payload = JSON.parse(body);
-            if (payload?.browserConfig) {
+            payload = JSON.parse(await readRequestBody(req, controller.signal));
+            if (!payload || typeof payload.prompt !== "string")
+                throw new Error("Missing prompt");
+            payload.options ??= {};
+            if (payload.browserConfig)
                 payload.browserConfig.url = normalizeChatgptUrl(payload.browserConfig.url, CHATGPT_URL);
-            }
         }
         catch {
-            busy = false;
-            res.writeHead(400, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({ error: "invalid_request" }));
+            await abandon();
+            if (!res.destroyed) {
+                res.writeHead(400, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "invalid_request" }));
+            }
             return;
         }
+        if (res.destroyed || req.aborted) {
+            await abandon();
+            return;
+        }
+        if (!admissionEnabled) {
+            signal = payload.options.cancelOnDisconnect === true ? controller.signal : undefined;
+            reserve();
+        }
         res.writeHead(200, { "Content-Type": "application/x-ndjson" });
-        const runId = randomUUID();
-        logger(`[serve] Accepted run ${runId} from ${formatSocket(req)} (prompt ${payload?.prompt?.length ?? 0} chars)`);
-        // Each run gets an isolated temp dir so attachments/logs don't collide.
-        const runDir = await mkdtemp(path.join(os.tmpdir(), `oracle-serve-${runId}-`));
-        const attachmentDir = path.join(runDir, "attachments");
-        await mkdir(attachmentDir, { recursive: true });
         const sendEvent = (event) => {
-            res.write(`${JSON.stringify(event)}\n`);
+            if (!res.destroyed && !res.writableEnded)
+                res.write(`${JSON.stringify(event)}\n`);
         };
-        const attachments = [];
+        if (queuePosition > 0 && !slotReady)
+            sendEvent({
+                type: "log",
+                message: `[serve] Waiting for a browser slot (position ${queuePosition}; ${slots.activeCount} active).`,
+            });
+        try {
+            release = await pendingSlot;
+            signal?.throwIfAborted();
+        }
+        catch (error) {
+            release?.();
+            legacyBusy = false;
+            sendEvent({ type: "error", message: error instanceof Error ? error.message : String(error) });
+            detachController();
+            if (!res.destroyed)
+                res.end();
+            return;
+        }
+        const runId = randomUUID();
+        let runDir = "";
         let fallbackSubmission;
         try {
+            signal?.throwIfAborted();
+            logger(`[serve] Accepted run ${runId} from ${formatSocket(req)} (prompt ${payload.prompt.length} chars)`);
+            runDir = await mkdtemp(path.join(os.tmpdir(), `oracle-serve-${runId}-`));
+            const attachmentDir = path.join(runDir, "attachments");
+            signal?.throwIfAborted();
             const attachmentsPayload = Array.isArray(payload.attachments) ? payload.attachments : [];
-            for (const [index, attachment] of attachmentsPayload.entries()) {
-                const safeName = sanitizeName(attachment.fileName ?? `attachment-${index + 1}`);
-                const filePath = path.join(attachmentDir, safeName);
-                await writeFile(filePath, Buffer.from(attachment.contentBase64, "base64"));
-                attachments.push({
-                    path: filePath,
-                    displayPath: attachment.displayPath,
-                    sizeBytes: attachment.sizeBytes,
-                });
-            }
+            const attachments = await stageRemoteAttachments(attachmentsPayload, attachmentDir, "attachment");
             if (payload.fallbackSubmission) {
                 const fallbackAttachmentDir = path.join(runDir, "fallback-attachments");
-                await mkdir(fallbackAttachmentDir, { recursive: true });
-                const fallbackAttachments = [];
                 const fallbackPayload = Array.isArray(payload.fallbackSubmission.attachments)
                     ? payload.fallbackSubmission.attachments
                     : [];
-                for (const [index, attachment] of fallbackPayload.entries()) {
-                    const safeName = sanitizeName(attachment.fileName ?? `fallback-attachment-${index + 1}`);
-                    const filePath = path.join(fallbackAttachmentDir, safeName);
-                    await writeFile(filePath, Buffer.from(attachment.contentBase64, "base64"));
-                    fallbackAttachments.push({
-                        path: filePath,
-                        displayPath: attachment.displayPath,
-                        sizeBytes: attachment.sizeBytes,
-                    });
-                }
+                const fallbackAttachments = await stageRemoteAttachments(fallbackPayload, fallbackAttachmentDir, "fallback-attachment");
                 fallbackSubmission = {
                     prompt: payload.fallbackSubmission.prompt,
                     attachments: fallbackAttachments,
                 };
+                const pendingBundle = payload.fallbackSubmission.bundle;
+                if (pendingBundle) {
+                    if (!["text", "zip"].includes(pendingBundle.format) ||
+                        !["all", "text-only"].includes(pendingBundle.scope)) {
+                        throw new Error("Invalid fallback bundle format or scope.");
+                    }
+                    let preparation;
+                    const prepare = async () => {
+                        if (!fallbackSubmission)
+                            return;
+                        const prepared = await materializeStagedFallbackBundle({
+                            composerText: fallbackSubmission.prompt,
+                            attachments: fallbackSubmission.attachments,
+                            format: pendingBundle.format,
+                            scope: pendingBundle.scope,
+                            bundleParentDir: runDir,
+                        });
+                        fallbackSubmission.prompt = prepared.composerText;
+                        fallbackSubmission.attachments = prepared.attachments;
+                    };
+                    fallbackSubmission.prepare = () => (preparation ??= prepare());
+                }
             }
             // Reuse the existing browser logger surface so clients see the same log stream.
             const automationLogger = ((message) => {
@@ -192,18 +310,35 @@ export async function createRemoteServer(options = {}, deps = {}) {
             // Preserve an explicit request to leave the completed conversation tab
             // open before the service forces `keepBrowser` for process lifetime.
             const clientRequestedKeepBrowser = payload.browserConfig?.keepBrowser === true;
+            // A client may describe the conversation it wants; it may not describe this
+            // machine. Rebuilding the config from an allowlist rather than deleting
+            // known-bad keys makes that the default: a field added to
+            // BrowserSessionConfig later is host-owned until someone decides otherwise,
+            // instead of reaching Chrome the moment it exists.
+            //
+            // The distinction is not stylistic. `chromePath` names an executable this
+            // process spawns, `remoteChrome` names a debugger to attach to,
+            // `copyProfileSource` names a directory to copy credentials out of, and
+            // `browserTabRef`/`attachRunning` select a tab that may belong to somebody
+            // else's run. With those reachable, a bridge token is not a permission to
+            // ask ChatGPT a question — it is a permission to run code here.
+            payload.browserConfig = {
+                ...pickClientBrowserConfig(payload.browserConfig),
+                ...hostBrowserConfig,
+            };
             // Remote runs rely on the host's authentication policy; never accept cookie payloads from clients.
-            if (payload.browserConfig) {
-                payload.browserConfig.inlineCookies = null;
-                payload.browserConfig.inlineCookiesSource = null;
-                payload.browserConfig.cookieSync = options.cookieSyncDefault === true;
-            }
-            else {
-                payload.browserConfig = {};
-                payload.browserConfig.cookieSync = options.cookieSyncDefault === true;
-            }
+            payload.browserConfig.inlineCookies = null;
+            payload.browserConfig.inlineCookiesSource = null;
+            payload.browserConfig.cookieSync = !attachedBrowser && options.cookieSyncDefault === true;
+            const clientSession = typeof payload.options.sessionId === "string"
+                ? payload.options.sessionId.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 32)
+                : "remote";
+            payload.options.sessionId = `${clientSession || "remote"}-${runId}`;
+            if (browserTabCap !== undefined)
+                payload.browserConfig.maxConcurrentTabs = browserTabCap;
+            signal?.throwIfAborted();
             // Enforce manual-login profile when cookie sync is unavailable (e.g., Windows/WSL).
-            if (options.manualLoginDefault) {
+            if (manualLoginDefault) {
                 payload.browserConfig.manualLogin = true;
                 payload.browserConfig.manualLoginProfileDir = options.manualLoginProfileDir;
                 payload.browserConfig.keepBrowser = true;
@@ -216,17 +351,20 @@ export async function createRemoteServer(options = {}, deps = {}) {
                 attachments,
                 fallbackSubmission,
                 config: payload.browserConfig,
+                signal,
                 // `keepBrowser` above preserves the authenticated shared Chrome
                 // process. This separate service policy closes only a successfully
                 // captured tab owned by this run, preventing one renderer leak per
                 // request while incomplete/reattachable tabs remain untouched.
-                closeOwnedTabOnComplete: Boolean(options.manualLoginDefault && !clientRequestedKeepBrowser),
+                closeOwnedTabOnComplete: Boolean(manualLoginDefault && !clientRequestedKeepBrowser),
+                closeOwnedTabOnCancel: !clientRequestedKeepBrowser,
                 log: automationLogger,
                 heartbeatIntervalMs: payload.options.heartbeatIntervalMs,
                 verbose: payload.options.verbose,
                 sessionId: payload.options.sessionId,
                 followUpPrompts: payload.options.followUpPrompts,
             });
+            signal?.throwIfAborted();
             const artifactRegistration = await registerRemoteArtifacts({
                 runId,
                 result,
@@ -253,15 +391,24 @@ export async function createRemoteServer(options = {}, deps = {}) {
                 : ""}`);
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
+            const cancelled = signal?.aborted === true;
+            const message = cancelled
+                ? "Browser run cancelled."
+                : error instanceof Error
+                    ? error.message
+                    : String(error);
             sendEvent({ type: "error", message });
-            logger(`[serve] Run ${runId} failed after ${Date.now() - runStartedAt}ms: ${message}`);
+            logger(`[serve] Run ${runId} ${cancelled ? "cancelled" : "failed"} after ${Date.now() - runStartedAt}ms: ${message}`);
         }
         finally {
-            busy = false;
-            res.end();
+            detachController();
+            legacyBusy = false;
+            release();
+            if (!res.destroyed)
+                res.end();
             try {
-                await rm(runDir, { recursive: true, force: true });
+                if (runDir)
+                    await rm(runDir, { recursive: true, force: true });
             }
             catch {
                 // ignore cleanup errors
@@ -286,6 +433,8 @@ export async function createRemoteServer(options = {}, deps = {}) {
         port: address.port,
         token: authToken,
         async close() {
+            for (const controller of controllers)
+                controller.abort();
             await new Promise((resolve, reject) => {
                 server.close((err) => (err ? reject(err) : resolve()));
             });
@@ -293,6 +442,7 @@ export async function createRemoteServer(options = {}, deps = {}) {
     };
 }
 export async function serveRemote(options = {}) {
+    validateAdmissionOptions(options);
     const manualProfileDir = options.manualLoginProfileDir ?? path.join(os.homedir(), ".oracle", "browser-profile");
     const preferManualLogin = options.manualLoginDefault ||
         options.cookieSyncDefault !== true ||
@@ -306,6 +456,11 @@ export async function serveRemote(options = {}) {
         console.log("Alternatively, start Windows Chrome with --remote-debugging-port=9222 and use `--remote-chrome <windows-ip>:9222`.");
         return;
     }
+    if (usesHostBrowserAttachment(options.browserConfig)) {
+        console.log("Using the host browser attachment; skipping local Chrome login/bootstrap.");
+        await runRemoteServer(options);
+        return;
+    }
     if (!preferManualLogin) {
         console.log("Warning: Chrome cookie copying can invalidate an active ChatGPT session when tokens rotate. Prefer the default dedicated manual-login profile when possible.");
         // Warm-up: ensure this host has a ChatGPT login before accepting runs.
@@ -349,11 +504,17 @@ export async function serveRemote(options = {}) {
     else {
         console.log(`Detected ${cookies.length} ChatGPT cookies on this host; runs will reuse this session.`);
     }
-    const server = await createRemoteServer({
+    await runRemoteServer({
         ...options,
         manualLoginDefault: preferManualLogin,
         manualLoginProfileDir: manualProfileDir,
     });
+}
+function usesHostBrowserAttachment(config) {
+    return config?.attachRunning === true || Boolean(config?.remoteChrome);
+}
+async function runRemoteServer(options) {
+    const server = await createRemoteServer(options);
     await new Promise((resolve) => {
         const shutdown = () => {
             console.log("Shutting down remote service...");
@@ -550,16 +711,99 @@ function classifySourceUrlKind(sourceUrl) {
     }
     return "chatgpt-file-endpoint";
 }
-async function readRequestBody(req) {
-    const chunks = [];
-    for await (const chunk of req) {
-        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+async function readRequestBody(req, signal) {
+    if (signal?.aborted) {
+        req.destroy();
+        signal.throwIfAborted();
+    }
+    const onAbort = () => req.destroy();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+        const chunks = [];
+        for await (const chunk of req) {
+            chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+        }
+        signal?.throwIfAborted();
+        return Buffer.concat(chunks).toString("utf8");
+    }
+    finally {
+        signal?.removeEventListener("abort", onAbort);
     }
-    return Buffer.concat(chunks).toString("utf8");
 }
-function sanitizeName(raw) {
-    return raw.replace(/[^a-zA-Z0-9._-]/g, "_");
+/**
+ * Fields a remote caller may set: they describe the conversation and its time
+ * budgets. Everything else on BrowserSessionConfig — executable paths, profile
+ * directories, debugger endpoints, tab selection, window mode, cookie policy,
+ * and the shared-profile concurrency limits — is the host's to decide.
+ */
+const CLIENT_BROWSER_CONFIG_FIELDS = [
+    "chatgptUrl",
+    "url",
+    "desiredModel",
+    "modelStrategy",
+    "thinkingTime",
+    "researchMode",
+    "archiveConversations",
+    "resumeConversationUrl",
+    "timeoutMs",
+    "inputTimeoutMs",
+    "attachmentTimeoutMs",
+    "assistantRecheckDelayMs",
+    "assistantRecheckTimeoutMs",
+    "autoReattachDelayMs",
+    "autoReattachIntervalMs",
+    "autoReattachTimeoutMs",
+    "keepBrowser",
+    "debug",
+];
+export function pickClientBrowserConfig(requested) {
+    const accepted = {};
+    if (!requested) {
+        return accepted;
+    }
+    for (const field of CLIENT_BROWSER_CONFIG_FIELDS) {
+        const value = requested[field];
+        if (value !== undefined) {
+            accepted[field] = value;
+        }
+    }
+    return accepted;
 }
+async function stageRemoteAttachments(payload, directory, defaultPrefix) {
+    await mkdir(directory, { recursive: true });
+    const names = payload.map((attachment, index) => {
+        const fallback = `${defaultPrefix}-${index + 1}`;
+        const sanitized = (attachment.fileName ?? fallback).replace(/[^a-zA-Z0-9._-]/g, "_");
+        return !sanitized || sanitized === "." || sanitized === ".." ? fallback : sanitized;
+    });
+    // Reserve future names too, and honor case-insensitive host filesystems.
+    const reserved = new Set(names.map((name) => name.toLowerCase()));
+    const used = new Set();
+    const attachments = [];
+    for (const [index, attachment] of payload.entries()) {
+        const original = names[index];
+        let name = original;
+        if (used.has(name.toLowerCase())) {
+            const extension = path.extname(original);
+            const stem = original.slice(0, original.length - extension.length);
+            let suffix = 2;
+            do {
+                name = `${stem}-${suffix++}${extension}`;
+            } while (reserved.has(name.toLowerCase()));
+        }
+        used.add(name.toLowerCase());
+        reserved.add(name.toLowerCase());
+        const filePath = path.join(directory, name);
+        await writeFile(filePath, Buffer.from(attachment.contentBase64, "base64"), { flag: "wx" });
+        attachments.push({
+            path: filePath,
+            displayPath: attachment.displayPath,
+            sizeBytes: attachment.sizeBytes,
+        });
+    }
+    return attachments;
+}
+// Return conversation identity and observed selection; keep process/profile details on the host.
 function sanitizeResult(result, warnings = []) {
     return {
         answerText: result.answerText,
@@ -568,6 +812,12 @@ function sanitizeResult(result, warnings = []) {
         tookMs: result.tookMs,
         answerTokens: result.answerTokens,
         answerChars: result.answerChars,
+        modelSelection: result.modelSelection,
+        thinkingSelection: result.thinkingSelection,
+        archive: result.archive,
+        tabUrl: result.tabUrl,
+        conversationId: result.conversationId,
+        promptSubmitted: result.promptSubmitted,
         warnings: warnings.length > 0 ? warnings : undefined,
         chromePid: undefined,
         chromePort: undefined,
@@ -580,7 +830,31 @@ function formatSocket(req) {
     const port = socket.remotePort ?? "0";
     return `${host}:${port}`;
 }
+/**
+ * Addresses a client could actually reach this service on.
+ *
+ * A loopback bind is reachable only from this machine, so listing the host's LAN
+ * and tailnet addresses there is not merely noisy — it tells an operator the
+ * service is exposed when it is not, which is the wrong direction for a mistake
+ * about a token that grants browser automation.
+ */
 function formatReachableAddresses(bindAddress, port) {
+    if (isLoopbackAddress(bindAddress)) {
+        return [`${formatHostPort(bindAddress, port)}`];
+    }
+    return formatAllInterfaceAddresses(bindAddress, port);
+}
+function isLoopbackAddress(address) {
+    const normalized = address
+        .trim()
+        .toLowerCase()
+        .replace(/^\[|\]$/g, "");
+    return normalized === "127.0.0.1" || normalized === "::1" || normalized === "localhost";
+}
+function formatHostPort(address, port) {
+    return address.includes(":") ? `[${address}]:${port}` : `${address}:${port}`;
+}
+function formatAllInterfaceAddresses(bindAddress, port) {
     const ipv4 = [];
     const ipv6 = [];
     if (bindAddress && bindAddress !== "::" && bindAddress !== "0.0.0.0") {

package/dist/src/sessionManager.js

@@ -141,12 +141,38 @@ async function writeSessionMetadataFile(sessionId, metadata) {
             encoding: "utf8",
             mode: 0o600,
         });
-        await fs.rename(temporaryPath, targetPath);
+        await renameSessionMetadataFile(temporaryPath, targetPath);
     }
     finally {
         await fs.rm(temporaryPath, { force: true }).catch(() => undefined);
     }
 }
+const METADATA_RENAME_RETRY_DELAYS_MS = [10, 25, 50, 100, 200, 400, 800];
+const RETRIABLE_METADATA_RENAME_CODES = new Set(["EACCES", "EBUSY", "EPERM"]);
+function isRetriableMetadataRenameError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        typeof error.code === "string" &&
+        RETRIABLE_METADATA_RENAME_CODES.has(error.code));
+}
+async function renameSessionMetadataFile(temporaryPath, targetPath) {
+    for (const delayMs of [0, ...METADATA_RENAME_RETRY_DELAYS_MS]) {
+        if (delayMs > 0) {
+            await wait(delayMs);
+        }
+        try {
+            await fs.rename(temporaryPath, targetPath);
+            return;
+        }
+        catch (error) {
+            if (!isRetriableMetadataRenameError(error) ||
+                delayMs === METADATA_RENAME_RETRY_DELAYS_MS.at(-1)) {
+                throw error;
+            }
+        }
+    }
+}
 function requestPath(id) {
     return path.join(sessionDir(id), LEGACY_REQUEST_FILENAME);
 }
@@ -317,6 +343,7 @@ export async function initializeSession(options, cwd, notifications, baseSlugOve
             zombieTimeoutMs: options.zombieTimeoutMs,
             zombieUseLastActivity: options.zombieUseLastActivity,
             writeOutputPath: options.writeOutputPath,
+            writeArtifacts: options.writeArtifacts,
             partialMode: options.partialMode,
             waitPreference: options.waitPreference,
             youtube: options.youtube,
@@ -327,6 +354,7 @@ export async function initializeSession(options, cwd, notifications, baseSlugOve
             browserResumeConversationUrl: options.browserResumeConversationUrl,
             aspectRatio: options.aspectRatio,
             geminiShowThoughts: options.geminiShowThoughts,
+            geminiAllowModelFallback: options.geminiAllowModelFallback,
         },
     };
     await ensureDir(modelsDir(sessionId));
@@ -640,6 +668,13 @@ async function markDeadBrowser(meta) {
         const host = runtime.chromeHost ?? "127.0.0.1";
         signals.push(await isPortOpen(host, runtime.chromePort));
     }
+    // controllerPid: the foreground process that launched this browser run.
+    // When neither chromePid nor chromePort are recorded (common on Linux),
+    // signals[] is empty and the early-return below would skip the reap.
+    // Use the same isProcessAlive() primitive to fill that gap.
+    if (signals.length === 0 && runtime.controllerPid) {
+        signals.push(isProcessAlive(runtime.controllerPid));
+    }
     if (signals.length === 0 || signals.some(Boolean)) {
         return meta;
     }