openmausbot 0.1.89 → 0.1.90

package/dist-server/server/cloud-home.js

@@ -0,0 +1,218 @@
+// OMB Cloud Pro home machine: the boot contract, the Admin's signed pairing
+// request, and the volume the machine lives on. docs/cloud-pro.md is the
+// contract of record (and openmaus-cloud docs/consumer-cloud.md its Admin
+// half); keep them in step.
+//
+// One Fly app per customer runs this server behind an edge proxy on
+// 0.0.0.0:8080 (server/cloud-home-start.ts). The server itself still binds
+// 127.0.0.1 and every request reaches it with X-Forwarded-* headers, so no
+// request from the network is ever the loopback owner.
+//
+// The Admin never holds a session on the machine. It signs a request with
+// the machine's bootstrap secret (HMAC-SHA256 over the method, path, a
+// timestamp, a nonce and the body's hash); each valid request opens one
+// ordinary pairing window (sessions.ts: single use, at most ten minutes),
+// which the Admin hands to the person's signed-in desktop app.
+//
+// Cloud Pro includes no AI. The person signs in on the machine with their own
+// Claude or ChatGPT account, or an API key, exactly as on any server; nothing
+// on a Cloud home is ever routed to a platform model gateway.
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileAtomic } from "./atomic.js";
+import { hostedWorkspaceConfigured } from "./enterprise.js";
+import { formatPairingCode } from "./sessions.js";
+export const CLOUD_HOME_CONTRACT_VERSION = 1;
+/** Any of these switches the server into Cloud home mode; then all are required. */
+export const CLOUD_HOME_KEYS = ["OMB_CLOUD_ROLE", "OMB_CLOUD_MACHINE_ID", "OMB_CLOUD_ADMIN_URL", "OMB_CLOUD_BOOTSTRAP_SECRET"];
+/** A platform model gateway's settings. A Cloud home never uses them: given
+ * any, it logs one warning, and neither the server nor anything it starts
+ * ever sees them. */
+export const CLOUD_IGNORED_KEYS = ["OMB_HOSTED_MODEL_URL", "OMB_HOSTED_MODEL_TOKEN", "OMB_HOSTED_MODELS"];
+export const CLOUD_PAIRING_PATH = "/api/cloud/pairing";
+export const CLOUD_PAIRING_DEFAULT_TTL_S = 300;
+export const CLOUD_PAIRING_MAX_TTL_S = 600;
+/** How far a signed request's timestamp may be from this machine's clock. */
+export const CLOUD_PAIRING_SKEW_S = 300;
+/** How long a used nonce is refused. Longer than the whole accepted window. */
+export const CLOUD_PAIRING_NONCE_MS = 10 * 60_000;
+const MAX_NONCES = 10_000;
+export const CLOUD_HOME_MARKER = ".omb-cloud-home.json";
+export function cloudHomeConfigured(env = process.env) {
+    return CLOUD_HOME_KEYS.some((key) => env[key] !== undefined);
+}
+function invalid(why) {
+    throw new Error(`Cloud home configuration is invalid: ${why}.`);
+}
+function exactHttpsOrigin(raw, name) {
+    let url;
+    try {
+        if (!raw || raw !== raw.trim())
+            throw new Error();
+        url = new URL(raw);
+    }
+    catch {
+        return invalid(`${name} must be an https origin`);
+    }
+    if (url.protocol !== "https:" || url.username || url.password || (raw !== url.origin && raw !== `${url.origin}/`)) {
+        invalid(`${name} must be an exact https origin with no path`);
+    }
+    return url.origin;
+}
+/** Read the boot contract. Null on any machine that is not a Cloud home;
+ * throws (so the server refuses to start) on a partial or invalid one. */
+export function cloudHomeConfiguration(env = process.env) {
+    if (!cloudHomeConfigured(env))
+        return null;
+    if (env.OMB_DESKTOP_PARENT === "1")
+        invalid("the desktop app cannot run as a Cloud home machine");
+    if (hostedWorkspaceConfigured(env))
+        invalid("a Cloud home is not a hosted team workspace; remove OMB_ADMIN_URL, OMB_ADMIN_WORKSPACE and OMB_ADMIN_MEMBERSHIP");
+    if (env.OMB_CLOUD_ROLE !== "home")
+        invalid('OMB_CLOUD_ROLE must be "home"; this image runs the home machine');
+    const machineId = env.OMB_CLOUD_MACHINE_ID ?? "";
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$/.test(machineId))
+        invalid("OMB_CLOUD_MACHINE_ID must be the Admin's machine id (letters, digits, dashes)");
+    const adminOrigin = exactHttpsOrigin(env.OMB_CLOUD_ADMIN_URL, "OMB_CLOUD_ADMIN_URL");
+    const publicOrigin = exactHttpsOrigin(env.OMB_PUBLIC_URL, "OMB_PUBLIC_URL");
+    const bootstrapSecret = env.OMB_CLOUD_BOOTSTRAP_SECRET ?? "";
+    if (!/^[A-Za-z0-9_-]{43,128}$/.test(bootstrapSecret))
+        invalid("OMB_CLOUD_BOOTSTRAP_SECRET must be at least 256 bits of base64url");
+    const warnings = [];
+    const ignored = CLOUD_IGNORED_KEYS.filter((key) => env[key] !== undefined);
+    if (ignored.length)
+        warnings.push(`ignoring ${ignored.join(", ")}: Cloud Pro includes no AI; people sign in with their own Claude or ChatGPT account, or an API key`);
+    return { machineId, adminOrigin, publicOrigin, bootstrapSecret, warnings };
+}
+/** The environment without a platform gateway's settings (CLOUD_IGNORED_KEYS). */
+export function withoutIgnoredCloudKeys(env) {
+    const kept = { ...env };
+    for (const key of CLOUD_IGNORED_KEYS)
+        delete kept[key];
+    return kept;
+}
+/** The Admin's side of the signature (openmaus-cloud cloudPairingSignature). */
+export function cloudPairingSignature(secret, timestamp, nonce, body) {
+    const bodyHash = createHash("sha256").update(body).digest("base64url");
+    return createHmac("sha256", secret).update(`v1\n${timestamp}\n${nonce}\nPOST\n${CLOUD_PAIRING_PATH}\n${bodyHash}`).digest("base64url");
+}
+/** The Admin's signed request for one pairing window on this machine. */
+export function createCloudPairing(options) {
+    const { secret, sessions } = options;
+    const now = options.now ?? Date.now;
+    const nonces = new Map();
+    const refused = (error) => ({ status: 401, body: { error } });
+    return {
+        /** Everything is checked before anything is opened: the signature (in
+         * constant time; a bad one counts toward the pairing lockout), then the
+         * clock, then the nonce, then the body. Nothing here is ever logged. */
+        handle(input) {
+            const lock = sessions.attemptAllowed(input.source);
+            if (!lock.ok)
+                return { status: 429, body: { error: "rate_limited", retryAfterSeconds: Math.ceil(lock.retryAfterMs / 1000) } };
+            const timestamp = input.timestamp ?? "", nonce = input.nonce ?? "";
+            const presented = /^v1=([A-Za-z0-9_-]{43})$/.exec(input.signature ?? "")?.[1];
+            const expected = Buffer.from(cloudPairingSignature(secret, timestamp, nonce, input.body), "base64url");
+            const given = presented ? Buffer.from(presented, "base64url") : Buffer.alloc(expected.length);
+            const matches = given.length === expected.length && timingSafeEqual(given, expected);
+            if (!presented || !matches || !/^\d{1,12}$/.test(timestamp) || !/^[A-Za-z0-9_-]{16,128}$/.test(nonce)) {
+                sessions.noteFailure(input.source);
+                return refused("invalid_signature");
+            }
+            sessions.clearFailures(input.source);
+            const at = now();
+            if (Math.abs(at / 1000 - Number(timestamp)) > CLOUD_PAIRING_SKEW_S)
+                return refused("stale_request");
+            for (const [seen, until] of nonces)
+                if (until <= at)
+                    nonces.delete(seen);
+            if (nonces.has(nonce))
+                return refused("replayed_request");
+            if (nonces.size >= MAX_NONCES)
+                return { status: 503, body: { error: "busy" } };
+            nonces.set(nonce, at + CLOUD_PAIRING_NONCE_MS);
+            let parsed;
+            try {
+                parsed = input.body.length ? JSON.parse(input.body.toString("utf8")) : {};
+            }
+            catch {
+                return { status: 400, body: { error: "invalid_body" } };
+            }
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                return { status: 400, body: { error: "invalid_body" } };
+            const { label, ttlSeconds } = parsed;
+            // oxlint-disable-next-line no-control-regex
+            if (label !== undefined && (typeof label !== "string" || label.length > 80 || /[\x00-\x1f\x7f]/.test(label)))
+                return { status: 400, body: { error: "invalid_label" } };
+            if (ttlSeconds !== undefined && (!Number.isSafeInteger(ttlSeconds) || ttlSeconds < 1))
+                return { status: 400, body: { error: "invalid_ttl" } };
+            const ttl = Math.min(ttlSeconds ?? CLOUD_PAIRING_DEFAULT_TTL_S, CLOUD_PAIRING_MAX_TTL_S);
+            const opened = sessions.openPairing({
+                scopes: ["admin", "client"],
+                label: typeof label === "string" && label.trim() ? label.trim() : "OMB Cloud",
+                ttlMs: ttl * 1000,
+            });
+            return { status: 200, body: { code: formatPairingCode(opened.code), credential: opened.credential, expiresAt: opened.expiresAt } };
+        },
+    };
+}
+/** The exact bytes the Admin signed, bounded. */
+export function readSignedBody(req, limit = 4096) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0, done = false;
+        req.on("data", (chunk) => {
+            if (done)
+                return;
+            size += chunk.length;
+            if (size > limit) {
+                done = true;
+                reject(Object.assign(new Error("body too large"), { status: 413 }));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => { if (!done) {
+            done = true;
+            resolve(Buffer.concat(chunks));
+        } });
+        req.on("error", (error) => { if (!done) {
+            done = true;
+            reject(Object.assign(error, { status: 400 }));
+        } });
+    });
+}
+// The image's home directory may carry the shell files useradd seeds; a
+// fresh Fly volume carries lost+found. Anything else is someone's data.
+const ADOPTABLE = new Set(["lost+found", ".bash_logout", ".bashrc", ".profile"]);
+/** Bind the volume to this machine on first boot and refuse any other
+ * machine's volume afterwards. Never deletes or rewrites existing data. */
+export function prepareCloudHomeVolume(home, machineId) {
+    mkdirSync(home, { recursive: true, mode: 0o700 });
+    const marker = join(home, CLOUD_HOME_MARKER);
+    if (existsSync(marker)) {
+        const stat = lstatSync(marker);
+        let saved;
+        try {
+            if (!stat.isFile() || stat.size > 4096)
+                throw new Error();
+            saved = JSON.parse(readFileSync(marker, "utf8"));
+        }
+        catch {
+            throw new Error("This volume's Cloud marker is unreadable. No data was changed.");
+        }
+        if (saved?.machine !== machineId)
+            throw new Error("This volume belongs to another Cloud machine. No data was changed.");
+        return "existing";
+    }
+    if (readdirSync(home).some((name) => !ADOPTABLE.has(name))) {
+        throw new Error("Refusing to adopt a data volume that was not made for this Cloud machine. No data was changed.");
+    }
+    writeFileAtomic(marker, JSON.stringify({ version: 1, machine: machineId }) + "\n", { mode: 0o600 });
+    return "new";
+}
+/** What the edge proxy may answer for: the machine's own public name. */
+export function cloudHomeHost(config) {
+    return new URL(config.publicOrigin).hostname;
+}

package/dist-server/server/cloud-overflow.js

@@ -0,0 +1,167 @@
+/** Consent, cost, and idle-stop policy for overflowing a local computer
+ * wait onto a per-second-billed cloud seat (#1655).
+ *
+ * Like server/claim-idle.ts this module is deliberately synchronous and
+ * clock-injected: the server decides every transition on its single
+ * thread and tests pin time exactly. Nothing here starts or stops a
+ * machine — the wiring does, and only when the decision says to. Keep
+ * this module free of server imports. */
+import { computerWaitDuration } from "./computer-wait.js";
+/** Default idle stop: a cloud seat no real screen work has touched for
+ * this long is stopped (archived), because billing runs per second while
+ * it runs. "A few idle minutes" per the issue. */
+export const CLOUD_SEAT_IDLE_STOP_MS = 5 * 60_000;
+/** Retry cadence for an idle stop that failed (#1655): the first retry
+ * after one minute, doubling per failure up to ten. A failed stop keeps
+ * its lease — the seat still bills — so the sweep always retries instead
+ * of abandoning a running machine. */
+export const CLOUD_SEAT_SLEEP_RETRY_MS = 60_000;
+export const CLOUD_SEAT_SLEEP_RETRY_MAX_MS = 10 * 60_000;
+export function cloudOverflowAction(situation) {
+    if (!situation.featureEnabled || !situation.cloudConfigured || situation.perSecondCostUsd === null)
+        return { kind: "off" };
+    if (situation.started)
+        return { kind: "none" };
+    if (situation.consented)
+        return { kind: "start" };
+    if (situation.offered)
+        return { kind: "none" };
+    return { kind: "offer" };
+}
+/** Per-conversation consent plus the offer bookkeeping that keeps the
+ * card to one per conversation until it is revoked. A thread the operator
+ * allowlisted in config carries standing consent and never needs the
+ * card. */
+export class CloudOverflowConsent {
+    grants = new Map();
+    offers = new Map();
+    revocations = new Set();
+    /** Consent for this conversation. With `perSecondCostUsd`, a card
+     * consent counts only at the rate its card showed — an allowlisted
+     * thread carries the operator's standing consent, and the operator is
+     * also the one who sets the rate. */
+    consented(threadId, allowlistedThreads = new Set(), perSecondCostUsd) {
+        if (this.revocations.has(threadId))
+            return false;
+        if (allowlistedThreads.has(threadId))
+            return true;
+        const grant = this.grants.get(threadId);
+        if (!grant)
+            return false;
+        return perSecondCostUsd === undefined || grant.perSecondCostUsd === perSecondCostUsd;
+    }
+    /** `perSecondCostUsd` is the rate the answered card showed. */
+    grant(threadId, perSecondCostUsd, now = Date.now()) {
+        this.revocations.delete(threadId);
+        this.grants.set(threadId, { at: now, perSecondCostUsd });
+    }
+    /** Revoking also clears the offered mark, so a later wait in the same
+     * conversation may ask again instead of meeting silence. */
+    revoke(threadId) {
+        const had = this.grants.delete(threadId);
+        this.revocations.add(threadId);
+        this.offers.delete(threadId);
+        return had;
+    }
+    /** A card is outstanding for this conversation — at the given rate
+     * when one is supplied, so a config change re-offers with the new
+     * price instead of meeting silence at the old one. */
+    offered(threadId, perSecondCostUsd) {
+        const offer = this.offers.get(threadId);
+        if (!offer)
+            return false;
+        return perSecondCostUsd === undefined || offer.perSecondCostUsd === perSecondCostUsd;
+    }
+    /** The rate the outstanding card showed, or null when no card is out. */
+    offeredRate(threadId) {
+        return this.offers.get(threadId)?.perSecondCostUsd ?? null;
+    }
+    markOffered(threadId, perSecondCostUsd, now = Date.now()) {
+        this.offers.set(threadId, { at: now, perSecondCostUsd });
+    }
+}
+/** One running cloud seat started by overflow. `touch` is called only
+ * for real computer tool completions on that seat — screen-poller frames
+ * never reach it, exactly like #1653's activity clock, so preview
+ * traffic cannot keep a paid machine awake. */
+export class CloudSeatLease {
+    botId;
+    threadId;
+    /** The claim generation that started the seat: a stop releases the Box
+     * claim for exactly this owner, never a newer turn's. */
+    generation;
+    startedAt;
+    idleStopMs;
+    lastActivityAt;
+    sleepRetryNotBefore = 0;
+    sleepRetryMs = CLOUD_SEAT_SLEEP_RETRY_MS;
+    constructor(init) {
+        const idleStopMs = init.idleStopMs ?? CLOUD_SEAT_IDLE_STOP_MS;
+        if (!Number.isFinite(idleStopMs) || idleStopMs <= 0)
+            throw new Error("Cloud seat idle stop window must be positive");
+        this.botId = init.botId;
+        this.threadId = init.threadId;
+        this.generation = init.generation;
+        this.startedAt = init.now ?? Date.now();
+        this.lastActivityAt = this.startedAt;
+        this.idleStopMs = idleStopMs;
+    }
+    touch(now = Date.now()) {
+        this.lastActivityAt = now;
+        // Real work earns a fresh stop attempt: the backoff only paces
+        // retries against an idle seat that keeps failing to sleep.
+        this.sleepRetryNotBefore = 0;
+        this.sleepRetryMs = CLOUD_SEAT_SLEEP_RETRY_MS;
+    }
+    /** An idle stop may run now — true until a failure defers it. */
+    sleepDue(now = Date.now()) {
+        return now >= this.sleepRetryNotBefore;
+    }
+    /** The idle stop failed: keep the lease and back off, bounded, so the
+     * sweep retries gently instead of hammering a sick Box — and never
+     * abandons a seat that still bills. */
+    deferSleep(now = Date.now()) {
+        this.sleepRetryNotBefore = now + this.sleepRetryMs;
+        this.sleepRetryMs = Math.min(this.sleepRetryMs * 2, CLOUD_SEAT_SLEEP_RETRY_MAX_MS);
+    }
+    idleFor(now = Date.now()) {
+        return Math.max(0, now - this.lastActivityAt);
+    }
+    idleElapsed(now = Date.now()) {
+        return now - this.lastActivityAt >= this.idleStopMs;
+    }
+}
+/** Dollars per second at rate-card precision: enough places for small
+ * per-second rates to stay visible, trailing zeros trimmed but never
+ * past two decimals. */
+export function formatPerSecondUsd(perSecondCostUsd) {
+    let text = perSecondCostUsd.toFixed(6).replace(/0+$/, "");
+    if (text.endsWith("."))
+        text += "00";
+    else {
+        const decimals = text.length - text.indexOf(".") - 1;
+        if (decimals < 2)
+            text += "0".repeat(2 - decimals);
+    }
+    return "$" + text;
+}
+/** The consent card (#1655): the per-second cost sits beside the local
+ * wait picture before any choice is made, and nothing starts without an
+ * explicit consent the person still has to give. */
+export function cloudOverflowOfferText(opts) {
+    const idleStopMs = opts.idleStopMs ?? CLOUD_SEAT_IDLE_STOP_MS;
+    const estimate = opts.waitEstimateMs === undefined ? "" : ` Recent local waits here have taken about ${computerWaitDuration(opts.waitEstimateMs)}.`;
+    return `This computer is busy. Its work can overflow to a cloud computer for ${formatPerSecondUsd(opts.perSecondCostUsd)} per second.${estimate} Nothing starts without your consent — allow cloud overflow for this conversation to start it; the cloud computer stops after ${computerWaitDuration(idleStopMs)} idle.`;
+}
+export function cloudSeatStartedText(opts) {
+    const idleStopMs = opts.idleStopMs ?? CLOUD_SEAT_IDLE_STOP_MS;
+    return `Cloud computer started at ${formatPerSecondUsd(opts.perSecondCostUsd)} per second. It stops automatically after ${computerWaitDuration(idleStopMs)} idle, and the local wait continues until this computer is free.`;
+}
+export function cloudSeatStoppedText(idleMs) {
+    return `Cloud computer stopped after ${computerWaitDuration(idleMs)} idle — billing pauses while it sleeps.`;
+}
+export function cloudOverflowConsentText(allowed, idleStopMs = CLOUD_SEAT_IDLE_STOP_MS) {
+    return allowed
+        ? `Cloud overflow allowed for this conversation. A waiting turn may start the cloud computer; it stops after ${computerWaitDuration(idleStopMs)} idle.`
+        : "Cloud overflow consent revoked. Waits stay local, and no cloud computer starts without a new consent.";
+}

package/dist-server/server/composio.js

@@ -196,6 +196,11 @@ export function connectorAvailability(cfg, storeState = process.env.OMB_CREDENTI
         return "configured";
     return storeState === "unavailable" ? "unreadable" : "unconfigured";
 }
+export function connectorSetup(cfg, desktopManaged = process.env.OMB_DESKTOP_PARENT === "1") {
+    if (configured(cfg))
+        return "ready";
+    return desktopManaged ? "service-unavailable" : "needs-setup";
+}
 async function brokerRequest(path, init) {
     const broker = brokerAccess();
     if (!broker)

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

@@ -99,7 +99,7 @@ export class ObservationCoordinator {
         this.metrics.retries += 1;
     }
     /** canonicalFrame must describe the full screenshot, even when the image
-     * returned to the model is cropped. A box-provided full-frame hash works. */
+     * returned to the model is cropped. A boat-provided full-frame hash works. */
     observeFrame(canonicalFrame, crop) {
         this.metrics.screenshotsCaptured += 1;
         const hash = canonicalFrame
@@ -107,7 +107,7 @@ export class ObservationCoordinator {
             : null;
         const view = crop ? `${crop.x},${crop.y},${crop.width},${crop.height}` : "full";
         const signature = hash ? `${hash}:${view}` : null;
-        // If the box cannot provide a full-frame hash, fail open and send the
+        // If the boat cannot provide a full-frame hash, fail open and send the
         // valid image. Suppressing a possibly-new crop would be worse.
         const changed = signature === null || signature !== this.lastObservation;
         if (signature)

package/dist-server/server/config.js

@@ -13,6 +13,7 @@ import { isModelVariant } from "./contracts.js";
 import { PROVIDER_ICON_PRESETS, providerIconError } from "../shared/provider-icon.js";
 import { isRemoteMcpServer, parseStoredMcpServer } from "./mcp-registry.js";
 import { parseJson, schemaIssue } from "./schema.js";
+import { CLOUD_SEAT_IDLE_STOP_MS } from "./cloud-overflow.js";
 const optionalText = z.string().optional();
 const SSH_ALIAS = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
 const LEGACY_BROWSER_PROFILE_ID = /^[A-Za-z0-9_-]{1,40}$/;
@@ -87,7 +88,8 @@ const roomConfigSchema = z.object({
         .min(MIN_ROOM_TURN_TIMEOUT_MINUTES)
         .max(MAX_ROOM_TURN_TIMEOUT_MINUTES),
     /** Room handoff tree lifetime. Active execution pauses this clock; the
-     * hard cap is wall-clock and bounds trees that never stop executing. */
+     * hard cap is the maximum stall window, measured wall-clock from the
+     * tree's last durable progress. */
     handoffLifetimeMinutes: z.number().int().min(1).max(MAX_ROOM_TURN_TIMEOUT_MINUTES).optional(),
     handoffMinRunwayMinutes: z.number().int().min(1).max(MAX_ROOM_TURN_TIMEOUT_MINUTES).optional(),
     handoffHardCapMinutes: z.number().int().min(1).max(7 * MAX_ROOM_TURN_TIMEOUT_MINUTES).optional(),
@@ -95,8 +97,14 @@ const roomConfigSchema = z.object({
     (rooms.handoffLifetimeMinutes ?? DEFAULT_ROOM_HANDOFF_LIFETIME_MINUTES) &&
     (rooms.handoffLifetimeMinutes ?? DEFAULT_ROOM_HANDOFF_LIFETIME_MINUTES) <=
         (rooms.handoffHardCapMinutes ?? DEFAULT_ROOM_HANDOFF_HARD_CAP_MINUTES), { message: "rooms handoff bounds must satisfy handoffMinRunwayMinutes <= handoffLifetimeMinutes <= handoffHardCapMinutes" });
+/** Isolation for bot desktops. Migration note (issue #1654): switching
+ * modes changes lease keys and vm-home directories, so desktops cold-start
+ * under the new mode — a pool seat lives in vm-homes/pool-N — while the old
+ * mode's workspaces stay on disk until removed. maxInstances caps per-bot
+ * desktops in per-bot mode, or the pool's seat count in pool mode; it is
+ * not a total across modes. Default stays "shared". */
 const localVmConfigSchema = z.object({
-    mode: z.enum(["shared", "per-bot"]).optional(),
+    mode: z.enum(["shared", "per-bot", "pool"]).optional(),
     maxInstances: z
         .number()
         .int()
@@ -247,6 +255,10 @@ const featureConfigSchema = z.object({
     skillAuthoring: z.boolean().optional(),
     /** Show each tool run in the transcript. Off unless explicitly enabled. */
     showToolCalls: z.boolean().optional(),
+    /** Run a routine inside the conversation it reports to, instead of a hidden
+     * thread. Off unless explicitly enabled. The run still starts from its own
+     * instructions, but the messages stay in that chat. */
+    routinesInConversation: z.boolean().optional(),
     /** Experimental built-in browser. Off until explicitly enabled; each bot
      * also has its own switch. */
     browser: z.boolean().optional(),
@@ -260,8 +272,23 @@ const featureConfigSchema = z.object({
     claudeUserMcp: z.boolean().optional(),
     /** LLM-generated titles for new bot threads. Off until explicitly
      * enabled; a one-shot that fails or answers junk leaves the first-message
-     * snippet in place — see llmThreadTitlesEnabled. */
+    * snippet in place — see llmThreadTitlesEnabled. */
     llmThreadTitles: z.boolean().optional(),
+    /** Before each turn, passages from the bot's own memory files and earlier
+     * conversations that share words with the message ride into the turn.
+     * Read-only; on unless explicitly switched off — see autoRecallEnabled. */
+    autoRecall: z.boolean().optional(),
+    /** Idle release for computer claims (#1653): a desktop seat that stays
+     * screen-quiet for 90 seconds is released to waiting turns while its
+     * holder's turn still lives; the previous holder re-claims directly
+     * for 10 minutes and yields to an occupied seat. Off until baked; see
+     * computerClaimIdleReleaseEnabled for how to enable it by hand. */
+    computerClaimIdleRelease: z.boolean().optional(),
+    /** Consented cloud overflow for local computer waits (#1655): a wait
+     * may offer a per-second-billed cloud seat, but only through an explicit
+     * consent card or a configured allowlist — never a silent Auto default.
+     * Off until baked; see cloudOverflowEnabled for how to enable it by hand. */
+    cloudOverflow: z.boolean().optional(),
 });
 /** First-run progress. Kept in the workspace config rather than a browser so
  * it survives cleared site data and is shared by every paired client. Hint
@@ -376,6 +403,8 @@ const appConfigSchema = z.object({
     /** Project key used for Sessions, catalog and agent tools. userId/sessionId
      * are non-secret local identifiers used to reuse one Composio Session. */
     composio: z.object({ apiKey: optionalText, userId: optionalText, sessionId: optionalText }).optional(),
+    /** Historical config section name "box" (the persisted config.json key); the
+     * provider is Boat now and the key is kept for compatibility. */
     box: z.object({ token: optionalText }).optional(),
     vps: vpsConfigSchema.optional(),
     /** Optional OpenCode key; persisted write-only and passed only to its child. */
@@ -429,10 +458,26 @@ const appConfigSchema = z.object({
         compactAt: z.number().positive().max(10_000_000).optional(),
         autoCompact: z.boolean().optional(),
     }).optional(),
+    /** Memory upkeep timing, for bots with Memory upkeep switched on. */
+    memory: z.object({
+        /** Quiet time after a turn before its facts are captured (ms). */
+        captureQuietMs: z.number().int().min(1_000).max(24 * 60 * 60_000).optional(),
+        /** Local hour (0-23) after which the nightly tidy-up runs. */
+        tidyHour: z.number().int().min(0).max(23).optional(),
+    }).strict().optional(),
     threads: threadsConfigSchema.optional(),
     /** The authorization decision log (server/decision-log.ts): days of month
      * files kept, at least; OMB_DECISION_RETENTION_DAYS wins when set. */
     decisions: z.object({ retentionDays: z.number().int().min(1).max(3650).optional() }).strict().optional(),
+    /** #1655 cloud-overflow settings. perSecondCostUsd is the operator's own
+     * verified rate: with no price configured the feature stays inert rather
+     * than show an invented one. allowlistedThreads carries standing consent
+     * for exact thread ids. */
+    cloudOverflow: z.object({
+        perSecondCostUsd: z.number().positive().max(10).optional(),
+        idleStopMs: z.number().int().positive().max(24 * 60 * 60_000).optional(),
+        allowlistedThreads: z.array(z.string().min(1)).max(1000).optional(),
+    }).strict().optional(),
     localVm: localVmConfigSchema.optional(),
     features: featureConfigSchema.optional(),
     onboarding: onboardingConfigSchema.optional(),
@@ -541,8 +586,9 @@ export function roomTurnTimeoutMinutes(cfg) {
     return cfg.rooms?.turnTimeoutMinutes ?? DEFAULT_ROOM_TURN_TIMEOUT_MINUTES;
 }
 /** Room handoff tree budgets in milliseconds. The tree lifetime pauses
- * while a node is actively executing; the hard cap is wall-clock and bounds
- * trees that never stop. Read when the server starts. */
+ * while a node is actively executing; the hard cap is the maximum stall
+ * window, measured wall-clock from the tree's last durable progress. Read
+ * when the server starts. */
 export function roomHandoffLimits(cfg) {
     return {
         lifetimeMs: (cfg.rooms?.handoffLifetimeMinutes ?? DEFAULT_ROOM_HANDOFF_LIFETIME_MINUTES) * 60_000,
@@ -578,9 +624,26 @@ export function localVmMaxInstances(cfg) {
 export function skillAuthoringEnabled(cfg) {
     return cfg.features?.skillAuthoring !== false;
 }
+/** Automatic recall is read-only, so it is on unless switched off. */
+export function autoRecallEnabled(cfg) {
+    return cfg.features?.autoRecall !== false;
+}
+export const DEFAULT_CAPTURE_QUIET_MS = 2 * 60_000;
+export const DEFAULT_TIDY_HOUR = 3;
+export function captureQuietMs(cfg) {
+    return cfg.memory?.captureQuietMs ?? DEFAULT_CAPTURE_QUIET_MS;
+}
+export function tidyHour(cfg) {
+    return cfg.memory?.tidyHour ?? DEFAULT_TIDY_HOUR;
+}
 export function showToolCallsEnabled(cfg) {
     return cfg.features?.showToolCalls === true;
 }
+/** A routine's turns are posted in the conversation that receives its card.
+ * Off by default, so scheduled work stays in a hidden thread. */
+export function routinesInConversationEnabled(cfg) {
+    return cfg.features?.routinesInConversation === true;
+}
 /** Workspace-level gate for the experimental built-in browser. A bot's own
  * switch sits under it, so either can withhold the browser. */
 export function builtInBrowserEnabled(cfg) {
@@ -614,6 +677,43 @@ export function claudeUserMcpEnabled(cfg) {
 export function llmThreadTitlesEnabled(cfg) {
     return cfg.features?.llmThreadTitles === true;
 }
+/** Idle release for computer claims (#1653): a whole-turn desktop hold
+ * ends after a screen-quiet window (default 90 seconds, screen-poller
+ * frames excluded) instead of at turn settle, and the previous holder
+ * re-claims directly inside a reclaim window (default 10 minutes) while
+ * yielding to a seat another turn already holds. Off unless an explicit
+ * `true` — bake it as a maintainer-only flag first, exactly like
+ * sharedComputers: enable by hand in ~/.openmausbot/config.json
+ * (`{"features": {"computerClaimIdleRelease": true}}`) and restart. */
+export function computerClaimIdleReleaseEnabled(cfg) {
+    return cfg.features?.computerClaimIdleRelease === true;
+}
+/** Consented cloud overflow for local computer waits (#1655): while a turn
+ * waits for a local desktop, it may offer overflow to a per-second-billed
+ * cloud seat — never silently: the card names the cost, and only an
+ * explicit per-conversation consent or a configured allowlist thread may
+ * start the machine, which then hard-stops after an idle window. Off
+ * unless an explicit `true`, like computerClaimIdleRelease: enable by
+ * hand in ~/.openmausbot/config.json
+ * (`{"features": {"cloudOverflow": true}, "cloudOverflow": {"perSecondCostUsd": 0.0004}}`)
+ * and restart. */
+export function cloudOverflowEnabled(cfg) {
+    return cfg.features?.cloudOverflow === true;
+}
+/** The per-second rate shown on the card, or null when the operator has
+ * not set one: the offer fails closed rather than guess a price. */
+export function cloudOverflowPerSecondCostUsd(cfg) {
+    const cost = cfg.cloudOverflow?.perSecondCostUsd;
+    return typeof cost === "number" && Number.isFinite(cost) && cost > 0 ? cost : null;
+}
+/** How long a cloud seat may stay screen-quiet before it is stopped. */
+export function cloudOverflowIdleStopMs(cfg) {
+    return cfg.cloudOverflow?.idleStopMs ?? CLOUD_SEAT_IDLE_STOP_MS;
+}
+/** Threads with standing consent, by exact thread id. */
+export function cloudOverflowAllowlistedThreads(cfg) {
+    return new Set(cfg.cloudOverflow?.allowlistedThreads ?? []);
+}
 /** Config sections no provider driver reads. A write that touches only
  * these must not rebuild the fleet: rebuilding disposes every engine child
  * and reloads it, seconds of work that would also interrupt in-flight
@@ -629,8 +729,10 @@ export const FLEET_NEUTRAL_KEYS = new Set([
     "threads",
     "automaticRecovery",
     "context",
+    "memory",
     "localVm",
     "features",
+    "cloudOverflow",
     "browserProfiles",
     "onboarding",
 ]);
@@ -752,6 +854,7 @@ export function loadConfig() {
     cfg.composio = { ...cfg.composio };
     if (process.env.COMPOSIO_API_KEY !== undefined)
         cfg.composio.apiKey = process.env.COMPOSIO_API_KEY;
+    // BOX_TOKEN keeps its historical name; the provider is Boat.
     cfg.box = { ...cfg.box };
     if (process.env.BOX_TOKEN !== undefined)
         cfg.box.token = process.env.BOX_TOKEN;
@@ -761,6 +864,11 @@ export function loadConfig() {
     cfg.tts = { ...cfg.tts };
     if (process.env.OMB_TTS_KEY !== undefined)
         cfg.tts.key = process.env.OMB_TTS_KEY;
+    // A preset ElevenLabs voice (Cloud Pro sets one) is only a default: a voice or
+    // another speech provider the person picked in Settings always wins.
+    const presetVoice = process.env.OMB_TTS_DEFAULT_VOICE?.trim();
+    if (presetVoice && !cfg.tts.voice?.trim() && (cfg.tts.provider ?? "elevenlabs") === "elevenlabs")
+        cfg.tts.voice = presetVoice;
     if (process.env.OMB_FISH_AUDIO_API_KEY !== undefined)
         cfg.tts.fishKey = process.env.OMB_FISH_AUDIO_API_KEY;
     cfg.imageGen = { ...cfg.imageGen };
@@ -929,7 +1037,7 @@ export function saveConfig(patch, options = {}) {
     const storedProfiles = storedBrowserProfilesSchema.safeParse(disk.browserProfiles);
     if (storedProfiles.success)
         disk.browserProfiles = storedProfiles.data;
-    for (const key of ["xai", "anthropic", "mistral", "openaiCompat", "composio", "box", "opencodeGo", "tts", "imageGen", "profile", "rooms", "threads", "context", "localVm", "features", "budgets", "billing", "decisions", "onboarding", "browserEngine", "newBots"]) {
+    for (const key of ["xai", "anthropic", "mistral", "openaiCompat", "composio", "box", "opencodeGo", "tts", "imageGen", "profile", "rooms", "threads", "context", "memory", "localVm", "features", "cloudOverflow", "budgets", "billing", "decisions", "onboarding", "browserEngine", "newBots"]) {
         const section = checkedPatch[key];
         if (!section)
             continue;
@@ -1138,6 +1246,7 @@ function injectedEnvironment(cfg, driver) {
         environment.set("OPENAI_COMPAT_API_KEY", cfg.openaiCompat.key);
     if (driver === "openai-compat" && cfg.openaiCompat?.url)
         environment.set("OPENAI_COMPAT_URL", cfg.openaiCompat.url);
+    // driverKind "boxAgent" and env BOX_TOKEN keep their historical names.
     if (driver === "boxAgent" && cfg.box?.token)
         environment.set("BOX_TOKEN", cfg.box.token);
     if (driver === "opencodeGo" && cfg.opencodeGo?.apiKey)