openmausbot 0.1.87 → 0.1.89

package/dist-server/server/connector-verdict.js

@@ -33,6 +33,22 @@ export function serviceSlugFor(tool) {
         return null;
     return tool.slice(0, underscore).toLowerCase();
 }
+/** The service a Composio tool name belongs to when the caller knows the
+ * real service slugs. Slugs may contain underscores (bland_ai), which the
+ * plain first-segment split above cannot see — BLAND_AI_MAKE_CALL splits
+ * as "bland". When a known candidate matches the name's prefix, the
+ * longest candidate wins (bland_ai over bland), so an underscored service
+ * keeps its own tools; with no matching candidate the caller falls back
+ * to serviceSlugFor. */
+export function serviceSlugForCandidates(tool, candidates) {
+    let match = null;
+    for (const candidate of candidates) {
+        if (tool.startsWith(candidate.toUpperCase() + "_") && (match === null || candidate.length > match.length)) {
+            match = candidate;
+        }
+    }
+    return match;
+}
 /** Classify one relayed JSON-RPC frame. Anything that is not a tools/call,
  * or is a discovery/connection/platform meta-tool, passes through. */
 export function connectorCallFromFrame(payload) {
@@ -99,16 +115,27 @@ function multiExecuteCall(invoked, args) {
 }
 /** Judge distinct target names against a bot's grants. grants undefined
  * is the legacy all-tools bot and passes everything; an explicit record —
- * including the empty one — allows only what it names. */
-export function evaluateConnectorTools(names, grants) {
+ * including the empty one — allows only what it names. Service keys are
+ * read as own properties only: a name like CONSTRUCTOR_X maps to the
+ * "constructor" service, and the inherited property must never pose as
+ * a grant.
+ * candidates are the caller's connected-service slugs: the real backend
+ * slugs, so an underscored service (bland_ai) keeps its own tools instead
+ * of a plain-prefix grant (bland) capturing them. An empty list means the
+ * connected-service catalog was unreachable, and the plain first-segment
+ * split stands as the fallback — call-time enforcement degrades open, the
+ * same way advertisement filtering does. */
+export function evaluateConnectorTools(names, grants, candidates = []) {
     if (grants === undefined) {
         return { allowed: true, legacy: true, denials: [], rule: "composio" };
     }
     const denials = [];
     let rule = "";
     for (const tool of new Set(names)) {
-        const service = serviceSlugFor(tool);
-        const grant = service === null ? undefined : grants[service];
+        const service = serviceSlugForCandidates(tool, candidates) ?? serviceSlugFor(tool);
+        const grant = service !== null && Object.hasOwn(grants, service)
+            ? grants[service]
+            : undefined;
         if (grant && (grant.tools === "*" || grant.tools.includes(tool))) {
             if (!rule)
                 rule = "connectorTools." + service;

package/dist-server/server/container-computer.js

@@ -7,6 +7,7 @@
 // typing, screenshots, accessibility, or window discovery.
 import { execFile } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
+import { lstatSync } from "node:fs";
 import { chmod, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
@@ -68,6 +69,15 @@ export function perBotLocalVmTarget(botId) {
         label: digest,
     };
 }
+/** Only provisioning creates this durable directory; idle removal keeps it. */
+export function localVmWorkspaceExists(target) {
+    try {
+        return lstatSync(target.workspaceDir, { throwIfNoEntry: false })?.isDirectory() === true;
+    }
+    catch {
+        return false;
+    }
+}
 const LINUX_WHEELS = {
     x86_64: {
         url: "https://files.pythonhosted.org/packages/fa/d7/a43008a328a40c85e7bc706fc20235b9abedc75e28b413817655153157ff/cua_driver-0.20.0-py3-none-manylinux_2_31_x86_64.whl",
@@ -808,6 +818,66 @@ export async function containerComputerScreenshot(runner = sh, platform = proces
 }
 const screenshotStatusCache = new Map();
 const containerMcpPath = SPAWNED_PROXIES.containerMcp;
+const EXEC_DEFAULT_SECONDS = 60;
+const EXEC_MAX_SECONDS = 300;
+const EXEC_OUTPUT_LIMIT = 20_000;
+/** Keep the start and the end: a failure message is nearly always at the end. */
+export function clipExecOutput(text, limit = EXEC_OUTPUT_LIMIT) {
+    if (text.length <= limit)
+        return text;
+    const head = Math.floor(limit / 5);
+    return `${text.slice(0, head)}\n… ${text.length - limit} characters omitted …\n${text.slice(text.length - (limit - head))}`;
+}
+const defaultExecRunner = async (command, args, options) => {
+    const resolved = resolveCliSpawn(command, args);
+    try {
+        const { stdout, stderr } = await run(resolved.command, resolved.args, {
+            timeout: options.timeout,
+            encoding: "utf8",
+            maxBuffer: 64 * 1024 * 1024,
+            env: { ...process.env, PATH: augmentedPath() },
+        });
+        return { stdout, stderr, code: 0 };
+    }
+    catch (error) {
+        const failure = error;
+        // A non-zero exit still carries the output; anything else (runtime missing,
+        // client killed) is a real failure to run at all.
+        if (typeof failure.code === "number") {
+            return { stdout: failure.stdout ?? "", stderr: failure.stderr ?? "", code: failure.code };
+        }
+        throw Object.assign(new Error(failure.killed ? "the command client timed out" : failure.message ?? "could not run the command"), { status: 502 });
+    }
+};
+/** Run one shell command inside a Local VM as the desktop user, in its durable
+ * workspace, and return the exit code and text output. Bots use this instead of
+ * typing into a terminal window and reading screenshots. The limit is enforced
+ * inside the container so a runaway process is really stopped. */
+export async function containerExec(target, command, options = {}) {
+    if (!command.trim())
+        throw Object.assign(new Error("command is required"), { status: 400 });
+    if (command.length > 20_000)
+        throw Object.assign(new Error("command is too long"), { status: 400 });
+    if (options.timeoutSeconds !== undefined && !Number.isFinite(options.timeoutSeconds)) {
+        throw Object.assign(new Error("timeout_seconds must be finite"), { status: 400 });
+    }
+    const runtime = options.runtime ?? (await containerRuntimeStatus()).runtime;
+    if (!runtime)
+        throw Object.assign(new Error("No container runtime is available for the Local VM"), { status: 409 });
+    const seconds = Math.min(Math.max(Math.floor(options.timeoutSeconds ?? EXEC_DEFAULT_SECONDS), 1), EXEC_MAX_SECONDS);
+    const result = await (options.exec ?? defaultExecRunner)(runtime, [
+        "exec",
+        "-u", "cua",
+        "-w", VM_WORKSPACE_GUEST,
+        "-e", "HOME=/home/cua",
+        "-e", `DISPLAY=${DISPLAY}`,
+        target.containerName,
+        "timeout", "-k", "5", String(seconds),
+        "sh", "-lc", command,
+    ], { timeout: (seconds + 20) * 1000 });
+    const timedOut = result.code === 124 || result.code === 137;
+    return { exitCode: result.code, stdout: clipExecOutput(result.stdout), stderr: clipExecOutput(result.stderr), timedOut };
+}
 export function containerComputerMcp(runtime, control, target = SHARED_LOCAL_VM_TARGET) {
     return {
         command: process.execPath,

package/dist-server/server/contracts.js

@@ -12,11 +12,43 @@ export class ProviderError extends Error {
         this.code = code;
     }
 }
+/** The driver proved this attempt never reached a prompt or client-side action,
+ * and its owned process has stopped. The harness may safely recover it. */
+export class TurnNotStartedError extends Error {
+    turnId;
+    constructor(turnId, message) {
+        super(message);
+        this.name = "TurnNotStartedError";
+        this.turnId = turnId;
+    }
+}
 /** Variants are opaque provider IDs, not the cross-engine effort enum. */
 export function isModelVariant(value) {
     return typeof value === "string" && value.length > 0 && value.length <= 256 &&
         value.trim() === value && !/\p{Cc}/u.test(value);
 }
+/** The picker label for a model id when the catalog row carries no display
+ * name: split on the word breaks the catalog treats as separators and
+ * capitalize each part ("gpt-5.4-mini" → "Gpt 5.4 Mini"). Each harness
+ * passes its own break class so existing labels stay byte-for-byte. */
+export function titleCaseModelId(id, wordBreaks) {
+    return id
+        .split(wordBreaks)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(" ");
+}
+/** A picker label that carries a second facet — a display name, a provider
+ * host — beside the model id, unless the facet is already what the id says.
+ * `redundantWhen` decides what counts as "already said" and `decorate` how
+ * the facet is appended, so every harness's labels stay exactly what they
+ * were while the shape is written once. */
+export function qualifiedModelLabel(id, qualifier, options = {}) {
+    const { redundantWhen = () => false, decorate = (facet) => ` — ${facet}` } = options;
+    if (!qualifier || redundantWhen(id, qualifier))
+        return id;
+    return `${id}${decorate(qualifier)}`;
+}
 let eventCounter = 0;
 export const newEventId = () => `ev-${Date.now().toString(36)}-${(eventCounter++).toString(36)}`;
 export const newId = () => crypto.randomUUID();

package/dist-server/server/drivers/acp/core.js

@@ -40,7 +40,7 @@ import { describeSpawnFailure, execCli, killCliTree, spawnCli } from "../../proc
 export function skipSubscriptionAuthForLocalInject(model) {
     return Boolean(decodeInjectId(model));
 }
-import { newEventId, newId } from "../../contracts.js";
+import { newEventId, newId, TurnNotStartedError } from "../../contracts.js";
 import { augmentedPath } from "../../env-path.js";
 import { supportsApprovalMode } from "../../../shared/approval-mode.js";
 import { parseAskQuestions, parseChoices, questionAnswersByQuestion } from "../../../shared/ask-question.js";
@@ -50,6 +50,8 @@ import { commandSummary, toolDetailPreview } from "../../tool-summary.js";
 import { extractMcpImages } from "../../mcp-tool-images.js";
 import { redactSecretsInText } from "../../redact.js";
 import { recoveryPromptFor } from "../../resume-recovery.js";
+import { sessionIdlePolicy } from "../session-idle.js";
+import { classifyError } from "../retry.js";
 /** ACP vendors put the actionable cause in error.data while keeping the
  * JSON-RPC message generic. Only surface known text fields, never a response
  * body/config dump, and redact before bounding the displayed diagnostic. */
@@ -80,6 +82,9 @@ const INIT_TIMEOUT = envOr("OPENMAUS_ACP_INIT_TIMEOUT_MS", 300_000);
 const SESSION_CONFIG_TIMEOUT = envOr("OPENMAUS_ACP_SESSION_CONFIG_TIMEOUT_MS", 300_000); // configureSession's per-request default
 const NEW_SESSION_TIMEOUT = envOr("OPENMAUS_ACP_NEW_SESSION_TIMEOUT_MS", 300_000);
 const LOAD_SESSION_TIMEOUT = envOr("OPENMAUS_ACP_LOAD_SESSION_TIMEOUT_MS", 120_000); // history replay on a long thread is slow
+/** ACP agents may compact their own history without telling the client;
+ * re-send the full prompt after this many bare turns as a backstop. */
+const ACP_PROMPT_RE_ANCHOR_TURNS = 8;
 // Read lazily (not at import) so a test can shorten the window. Unlike the
 // setup calls above, session/prompt legitimately streams for minutes, so a
 // wall-clock deadline would false-positive: this guard only trips when the
@@ -94,6 +99,20 @@ const promptIdleTimeoutMs = () => {
     const ms = Number(raw);
     return Number.isFinite(ms) && ms > 0 ? ms : 0;
 };
+/** Keep a turn's set of running tool calls in step with the agent's
+ * `tool_call` / `tool_call_update` notifications: a call is running from
+ * the first update that is not terminal until one that is. A `tool_call`
+ * without a status is pending (ACP's default); a `tool_call_update` without
+ * one leaves the call as it was. */
+function trackRunningTool(current, update, defaultStatus) {
+    if (typeof update.toolCallId !== "string" || !update.toolCallId)
+        return;
+    const status = update.status ?? defaultStatus;
+    if (status === "completed" || status === "failed")
+        current.runningTools.delete(update.toolCallId);
+    else if (status === "pending" || status === "in_progress")
+        current.runningTools.add(update.toolCallId);
+}
 const CLIENT_FILE_MAX_BYTES = 8 * 1024 * 1024;
 function acpVariantOption(result) {
     const option = (Array.isArray(result?.configOptions) ? result.configOptions : []).find((entry) => entry?.type === "select" && typeof entry.id === "string"
@@ -212,6 +231,24 @@ export function versionFromProbe(stdout, stderr) {
     const err = (stderr ?? "").trim().split(/\r\n|\n|\r/, 1)[0]?.trim() ?? "";
     return err || null;
 }
+/** The first dotted numeric triple in a version banner, or null when there is
+ * none. A wrapper that prints its own banner first still parses: the triple
+ * is the version wherever it appears. */
+export function parseVersionTriple(value) {
+    const match = /(\d+)\.(\d+)\.(\d+)/.exec(value);
+    if (!match)
+        return null;
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+/** Whether `installed` compares at or above `floor`, componentwise. Every
+ * version floor in the tree is a dotted triple. */
+export function versionAtLeast(installed, floor) {
+    for (let i = 0; i < 3; i += 1) {
+        if (installed[i] !== floor[i])
+            return installed[i] > floor[i];
+    }
+    return true;
+}
 export function createAcpDriver(support) {
     const DRIVER_KIND = support.driverKind;
     const SOURCE = support.nativeSource;
@@ -274,11 +311,24 @@ export function createAcpDriver(support) {
             // contract prompts the live session instead of paying the handshake
             // again. An idle session closes after SESSION_IDLE_MS of quiet.
             const sessions = new Map();
-            const configuredIdleMinimum = Number(process.env.OMB_ACP_SESSION_IDLE_MIN_MS);
-            const sessionIdleMinimum = Number.isFinite(configuredIdleMinimum) && configuredIdleMinimum > 0
-                ? configuredIdleMinimum
-                : 10_000;
-            const SESSION_IDLE_MS = Math.max(sessionIdleMinimum, Number(process.env.OMB_ACP_SESSION_IDLE_MS) || 10 * 60_000);
+            // Closing removes a session from the pool, not its native writer lease.
+            // Retain every closing Qwen child until its process tree is gone, even
+            // when Stop or a failed turn lets another turn start during cleanup.
+            const retiring = new Map();
+            const retireChild = async (threadId, child) => {
+                let children = retiring.get(threadId);
+                if (!children)
+                    retiring.set(threadId, children = new Set());
+                children.add(child);
+                const stopped = await killCliTree(child);
+                if (stopped) {
+                    children.delete(child);
+                    if (!children.size && retiring.get(threadId) === children)
+                        retiring.delete(threadId);
+                }
+                return stopped;
+            };
+            const { idleMs: SESSION_IDLE_MS } = sessionIdlePolicy("ACP");
             const closeSession = (threadId, why) => {
                 const session = sessions.get(threadId);
                 if (!session || session.closing)
@@ -290,16 +340,20 @@ export function createAcpDriver(support) {
                 // a new turn must never adopt a closing session
                 sessions.delete(threadId);
                 session.acp.close();
-                // stdin EOF asks the agent to exit; EOF is not a guaranteed exit
-                // signal for ACP agents, so insist after a grace period
+                // EOF is not a guaranteed exit signal. Qwen must be tracked before
+                // another turn can resume its history; other agents keep their grace.
                 try {
                     session.child.stdin.end();
                 }
                 catch { }
-                const kill = setTimeout(() => {
-                    void killCliTree(session.child);
-                }, 5_000);
-                kill.unref?.();
+                if (support.restartOnMcpChange)
+                    void retireChild(threadId, session.child);
+                else {
+                    const kill = setTimeout(() => {
+                        void killCliTree(session.child);
+                    }, 5_000);
+                    kill.unref?.();
+                }
             };
             const armIdle = (threadId) => {
                 const session = sessions.get(threadId);
@@ -418,6 +472,7 @@ export function createAcpDriver(support) {
                 if (!current || current.state.settled)
                     return;
                 current.state.settled = true;
+                current.acknowledge();
                 if (current.interruptTimer)
                     clearTimeout(current.interruptTimer);
                 for (const finish of current.asks.values())
@@ -503,8 +558,9 @@ export function createAcpDriver(support) {
                         if (idleTimer)
                             clearTimeout(idleTimer);
                         idleTimer = setTimeout(() => {
-                            // Waiting for a person is not an unresponsive agent.
-                            if (session.current?.asks.size) {
+                            // Waiting for a person, or for a tool the agent is running,
+                            // is not an unresponsive agent.
+                            if (session.current?.asks.size || session.current?.runningTools.size) {
                                 armIdle();
                                 return;
                             }
@@ -621,6 +677,7 @@ export function createAcpDriver(support) {
                 // server→client permission request → canonical request.opened,
                 // answered fail-closed for the running turn
                 const handleServerRequest = (msg, current) => {
+                    current.state.startupActivity = true;
                     if (msg.method === "fs/read_text_file" || msg.method === "fs/write_text_file") {
                         void handleClientFileRequest(msg);
                         return;
@@ -760,6 +817,9 @@ export function createAcpDriver(support) {
                             current.receiveModelVariants(p.update);
                         return;
                     }
+                    if (current && ["agent_message_chunk", "agent_thought_chunk", "tool_call", "tool_call_update"].includes(p.update?.sessionUpdate)) {
+                        current.state.startupActivity = true;
+                    }
                     if (!current || !current.state.promptSent)
                         return;
                     const u = p.update ?? {};
@@ -793,6 +853,7 @@ export function createAcpDriver(support) {
                         }
                         case "tool_call": {
                             current.flushAssistantText();
+                            trackRunningTool(current, u, "pending");
                             emit({
                                 ...base(threadId, current.turnId),
                                 type: "item.started",
@@ -805,6 +866,7 @@ export function createAcpDriver(support) {
                             break;
                         }
                         case "tool_call_update": {
+                            trackRunningTool(current, u);
                             if (u.status === "completed" || u.status === "failed") {
                                 current.state.producedItem = true;
                                 emit({
@@ -992,8 +1054,8 @@ export function createAcpDriver(support) {
                 // transformEnv-policy supports (opencode). mcpServers are session
                 // establishment inputs — they ride session/new and session/load over
                 // the wire — and the harness mints fresh integration bearer tokens
-                // every turn, so they must not respawn the process; a change instead
-                // re-establishes the session below (see sessionKey).
+                // every turn. Most agents apply changes on live load; those that cache
+                // the old MCP clients must resume on a fresh process (see sessionKey).
                 // The env the spawned child actually receives is part of the
                 // contract too, and arrives hashed as envFingerprint for the same
                 // reason.
@@ -1012,7 +1074,8 @@ export function createAcpDriver(support) {
                 }
                 const pooled = sessions.get(threadId);
                 let session;
-                if (pooled && !pooled.dead && !pooled.closing && pooled.contractKey === contractKey) {
+                if (pooled && !pooled.dead && !pooled.closing && pooled.contractKey === contractKey
+                    && (!support.restartOnMcpChange || pooled.sessionKey === sessionKey)) {
                     // adoption cancels the idle countdown — a running turn is not quiet
                     if (pooled.idleTimer)
                         clearTimeout(pooled.idleTimer);
@@ -1035,7 +1098,13 @@ export function createAcpDriver(support) {
                 // respawns the child, every wire call must reach the live record, so
                 // nothing captures the connection off it.
                 const request = (method, params, timeoutMs, receive, idleMs, idleMessage) => session.acp.request(method, params, timeoutMs, receive, idleMs, idleMessage);
-                const state = { settled: false, promptSent: false, text: "", producedItem: false };
+                const state = { settled: false, promptSent: false, text: "", producedItem: false, startupActivity: false, stopped: false };
+                let acknowledge = () => { };
+                let rejectStartup = (_error) => { };
+                const startupAck = turn.startupRecovery ? new Promise((resolve, reject) => {
+                    acknowledge = () => resolve({ turnId });
+                    rejectStartup = reject;
+                }) : null;
                 const asks = new Map();
                 const modelOf = (result) => {
                     const option = (Array.isArray(result?.configOptions) ? result.configOptions : []).find((entry) => entry?.id === (support.selectModel?.configId ?? "model"));
@@ -1083,12 +1152,15 @@ export function createAcpDriver(support) {
                     turnConfig,
                     controlsHost,
                     state,
+                    acknowledge,
                     asks,
+                    runningTools: new Set(),
                     interruptTimer: null,
                     flushAssistantText,
                     receiveModelVariants,
                 };
                 const interrupt = () => {
+                    state.stopped = true;
                     if (session.sessionId) {
                         session.acp.send({ jsonrpc: "2.0", method: "session/cancel", params: { sessionId: session.sessionId } });
                         if (current.interruptTimer)
@@ -1105,7 +1177,7 @@ export function createAcpDriver(support) {
                         closeSession(threadId, "stop");
                     }
                 };
-                active.set(threadId, { stop: () => closeSession(threadId, "stop"), interrupt, turnId, asks });
+                active.set(threadId, { stop: () => { state.stopped = true; closeSession(threadId, "stop"); }, interrupt, turnId, asks });
                 emit({ ...base(threadId, turnId), type: "turn.started" });
                 session.current = current;
                 (async () => {
@@ -1116,6 +1188,19 @@ export function createAcpDriver(support) {
                         // Returns whether this runtime accepts image prompts, for the
                         // prompt phase below.
                         const handshake = async () => {
+                            // Also covers timeout/reset/re-establishment, not just rotated
+                            // MCP credentials. Stop remains wired while cleanup is pending.
+                            for (const child of retiring.get(threadId) ?? []) {
+                                const stopped = await retireChild(threadId, child);
+                                if (state.settled || session.closing)
+                                    throw new Error("session closed");
+                                if (!stopped) {
+                                    closeSession(threadId, "replace-failed");
+                                    throw new Error(`${support.displayName} could not close its previous tool session. Try again.`);
+                                }
+                            }
+                            if (state.settled || session.closing)
+                                throw new Error("session closed");
                             if (!session.initResult) {
                                 session.initResult = await request("initialize", {
                                     protocolVersion: 1,
@@ -1320,7 +1405,7 @@ export function createAcpDriver(support) {
                         let pendingSplitReceipt = null;
                         if (halves.stable !== null) {
                             const receiptKey = JSON.stringify([threadId, sessionId]);
-                            const composed = splitSessionPrompt(halves.stable, halves.volatile, readPromptSplitReceipt(DRIVER_KIND, receiptKey), promptTurn.system, promptTurn.text, Boolean(turn.mentionTurn));
+                            const composed = splitSessionPrompt(halves.stable, halves.volatile, readPromptSplitReceipt(DRIVER_KIND, receiptKey), promptTurn.system, promptTurn.text, Boolean(turn.mentionTurn), ACP_PROMPT_RE_ANCHOR_TURNS);
                             promptInput = { ...promptTurn, system: "", text: composed.text };
                             pendingSplitReceipt = { key: receiptKey, receipt: composed.receipt };
                         }
@@ -1338,10 +1423,13 @@ export function createAcpDriver(support) {
                         if (turn.variant !== undefined && requestedVariantOption().currentValue !== turn.variant) {
                             throw new Error(`${support.displayName} changed variant before the prompt`);
                         }
+                        if (state.settled || state.stopped || session.closing)
+                            throw new Error("turn stopped");
                         state.promptSent = true;
+                        acknowledge();
                         const promptIdleMs = promptIdleTimeoutMs();
-                        const result = await request("session/prompt", { sessionId, prompt: [{ type: "text", text }, ...imageBlocks] }, undefined, undefined, promptIdleMs, `${DRIVER_KIND} went fully silent ${Math.round(promptIdleMs / 1000)} s after the message and the turn was stopped. ` +
-                            "Raise OPENMAUS_ACP_PROMPT_IDLE_TIMEOUT_MS if this model legitimately takes longer to answer.");
+                        const result = await request("session/prompt", { sessionId, prompt: [{ type: "text", text }, ...imageBlocks] }, undefined, undefined, promptIdleMs, `${DRIVER_KIND} sent nothing for ${Math.round(promptIdleMs / 1000)} s with no tool running, so the turn was stopped as stuck. ` +
+                            "Send the message again to retry. On a self-hosted server, OPENMAUS_ACP_PROMPT_IDLE_TIMEOUT_MS sets this limit (0 turns it off).");
                         if (pendingSplitReceipt) {
                             // session/prompt resolving is the acceptance boundary: a
                             // rejected prompt leaves the receipt unwritten, so the next
@@ -1387,6 +1475,35 @@ export function createAcpDriver(support) {
                             // fallback for existing ACP supports.
                             const needsAuth = code === "invalid_credentials" || code === "inactive_subscription"
                                 || message === support.loginNote;
+                            const failure = classifyError({ text: message });
+                            const transientStartup = failure.transient || (failure.reason === "unknown" && code === "upstream_outage");
+                            const denied = /\b(?:(?:permission|access) denied|(?:approval|permission) (?:required|denied|rejected)|requires? (?:approval|permission)|policy (?:restriction|violation)|(?:blocked|denied|restricted) by (?:the )?policy)\b/i.test(message);
+                            if (turn.startupRecovery && transientStartup && !needsAuth && !denied && (!code || code === "upstream_outage")
+                                && ![-32700, -32600, -32601, -32602].includes(e?.code)
+                                && !state.promptSent && !state.startupActivity && !state.producedItem && !state.text
+                                && !state.stopped && !session.closing && !asks.size && !current.runningTools.size) {
+                                // Quiesce before killing: the child's close event must not
+                                // publish a terminal completion before the harness can recover.
+                                state.settled = true;
+                                session.current = null;
+                                if (current.interruptTimer)
+                                    clearTimeout(current.interruptTimer);
+                                closeSession(threadId, "startup-recovery");
+                                const stopped = await killCliTree(session.child).catch(() => false);
+                                if (current.interruptTimer)
+                                    clearTimeout(current.interruptTimer);
+                                active.delete(threadId);
+                                if (stopped && !state.stopped) {
+                                    rejectStartup(new TurnNotStartedError(turnId, message));
+                                    return;
+                                }
+                                acknowledge();
+                                if (!state.stopped)
+                                    emit({ ...base(threadId, turnId), type: "runtime.error", message });
+                                emit({ ...base(threadId, turnId), type: "turn.completed", ok: state.stopped,
+                                    stopReason: state.stopped ? "cancelled" : "rpc_error", cost: null });
+                                return;
+                            }
                             emit({
                                 ...base(threadId, turnId),
                                 type: "runtime.error",
@@ -1406,7 +1523,7 @@ export function createAcpDriver(support) {
                         }
                     }
                 })();
-                return { turnId };
+                return startupAck ?? { turnId };
             };
             const snapshot = async () => {
                 const env = childEnv();
@@ -1463,6 +1580,10 @@ export function createAcpDriver(support) {
                         // idle pooled sessions have no running turn — close them too
                         for (const threadId of Array.from(sessions.keys()))
                             closeSession(threadId, "stopAll");
+                        for (const [threadId, children] of retiring) {
+                            for (const child of children)
+                                void retireChild(threadId, child);
+                        }
                     },
                     onEvent: (listener) => {
                         listeners.add(listener);
@@ -1474,6 +1595,10 @@ export function createAcpDriver(support) {
                         stop();
                     for (const threadId of Array.from(sessions.keys()))
                         closeSession(threadId, "dispose");
+                    for (const [threadId, children] of retiring) {
+                        for (const child of children)
+                            void retireChild(threadId, child);
+                    }
                     listeners.clear();
                 },
             };

package/dist-server/server/drivers/acp/cursor.js

@@ -1,3 +1,4 @@
+import { titleCaseModelId } from "../../contracts.js";
 import { execCli } from "../../procs.js";
 import { createAcpDriver } from "./core.js";
 /** Translate an argv `--model` slug into the id this ACP session will accept.
@@ -86,13 +87,8 @@ function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
 function labelFor(id, explicit) {
-    if (explicit?.trim())
-        return explicit.trim();
-    return id
-        .split(/[-_./]+/g)
-        .filter(Boolean)
-        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
-        .join(" ");
+    const trimmed = explicit?.trim();
+    return trimmed || titleCaseModelId(id, /[-_./]+/);
 }
 function pushModel(options, seen, id, label, custom = false) {
     if (!SLUG.test(id) || seen.has(id))

package/dist-server/server/drivers/acp/droid.js

@@ -16,8 +16,8 @@
 // options set over the wire (session/set_model, session/set_mode), which is
 // why both live in configureSession() below and NOT in spawnArgs.
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
+import { userHome } from "../../env-path.js";
 import { decodeInjectId, hostApiKey, localHost, mergeLocalInject } from "../local-inject.js";
 import { createAcpDriver } from "./core.js";
 // FACTORY_HOME_OVERRIDE replaces the HOME the CLI resolves, NOT the data root:
@@ -34,7 +34,7 @@ import { createAcpDriver } from "./core.js";
 // out. Names read from the 0.196.0 binary.
 const AUTH_FILES = ["auth.v2.file", "auth.v2.loginkeychain", "auth.v2.keyring"];
 function authFilePaths(env) {
-    const home = env.FACTORY_HOME_OVERRIDE || env.HOME || homedir();
+    const home = env.FACTORY_HOME_OVERRIDE || userHome(env);
     return AUTH_FILES.map((name) => join(home, ".factory", name));
 }
 const INJECT_ID_PREFIX = "custom:openmausbot-";
@@ -42,9 +42,6 @@ export function droidInjectId(host, model) {
     const safe = `${host}-${model}`.replace(/[^a-zA-Z0-9._+-]+/g, "-").replace(/-+/g, "-");
     return `${INJECT_ID_PREFIX}${safe}`;
 }
-function factoryHome(env) {
-    return env.FACTORY_HOME_OVERRIDE || env.HOME || env.USERPROFILE || homedir();
-}
 /** Upsert a BYOK custom model so session/set_model can reach the local host. */
 export function ensureDroidInjectModel(modelId, env = process.env) {
     const inject = decodeInjectId(modelId);
@@ -54,7 +51,7 @@ export function ensureDroidInjectModel(modelId, env = process.env) {
     if (!host)
         return modelId;
     const id = droidInjectId(inject.host, inject.model);
-    const dir = join(factoryHome(env), ".factory");
+    const dir = join(env.FACTORY_HOME_OVERRIDE || userHome(env), ".factory");
     mkdirSync(dir, { recursive: true });
     const path = join(dir, "settings.json");
     let settings = {};
@@ -105,7 +102,7 @@ export function applyDroidLocalAuthEnv(env, modelId) {
     env.FACTORY_API_KEY = "openmausbot-local";
 }
 function readSettings(env) {
-    return JSON.parse(readFileSync(join(factoryHome(env), ".factory", "settings.json"), "utf8"));
+    return JSON.parse(readFileSync(join(env.FACTORY_HOME_OVERRIDE || userHome(env), ".factory", "settings.json"), "utf8"));
 }
 async function resolveModels(env) {
     let catalog = MODELS;

package/dist-server/server/drivers/acp/gemini.js

@@ -26,8 +26,8 @@
 // the ACP flag + auth method ids follow the published Gemini CLI ACP contract
 // and should be re-verified end-to-end once the CLI is present.
 import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
+import { userHome } from "../../env-path.js";
 import { createAcpDriver } from "./core.js";
 // Prefer an explicit key method, then personal OAuth, then Vertex — but fall
 // back to whatever the CLI advertises so a new method id still works.
@@ -37,9 +37,9 @@ const AUTH_PREFERENCE = ["gemini-api-key", "oauth-personal", "vertex-ai"];
  * an enterprise licence may still redeem. A stale consumer credential —
  * the common case since 2026-06-18 — reads as not signed in, which is the
  * truthful answer for an engine that would fail its first turn anyway. */
-function liveOauthCredential() {
+function liveOauthCredential(env) {
     try {
-        const creds = JSON.parse(readFileSync(join(homedir(), ".gemini", "oauth_creds.json"), "utf8"));
+        const creds = JSON.parse(readFileSync(join(userHome(env), ".gemini", "oauth_creds.json"), "utf8"));
         if (typeof creds.access_token !== "string" || creds.access_token.trim().length === 0)
             return false;
         const hasRefresh = typeof creds.refresh_token === "string" && creds.refresh_token.trim().length > 0;
@@ -62,7 +62,7 @@ const nonBlank = (value) => Boolean(value?.trim());
 export function geminiIsAuthenticated(env) {
     return (nonBlank(env.GEMINI_API_KEY) ||
         nonBlank(env.GOOGLE_API_KEY) ||
-        (existsSync(join(homedir(), ".gemini", "oauth_creds.json")) && liveOauthCredential()));
+        (existsSync(join(userHome(env), ".gemini", "oauth_creds.json")) && liveOauthCredential(env)));
 }
 /** Gemini CLI's approval modes, passed through: `--approval-mode auto_edit`
  * approves file edits, `--yolo` approves everything; Gemini has no