openmausbot 0.1.96 → 0.1.98

package/dist-server/server/checkpoints.js

@@ -14,7 +14,9 @@
 //
 // Failure policy: checkpointing is best-effort convenience, never load-bearing.
 // Any git failure disables the feature for that bot for the rest of the
-// session and logs — nothing here ever throws into the turn path.
+// session and logs — nothing here ever throws into the turn path. A git call
+// that hits the timeout disables only that bot+folder, so a slow folder costs
+// one wait and one log line, not one wait per turn.
 //
 // Adapted from the checkpoint designs of Cline, Roo-Code, and Gemini CLI
 // (all Apache-2.0): the per-call GIT_DIR/GIT_WORK_TREE/GIT_CONFIG_* env
@@ -24,6 +26,7 @@
 import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { readdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { isAbsolute, join, parse, resolve } from "node:path";
 import { DATA_DIR } from "./config.js";
@@ -117,9 +120,20 @@ Thumbs.db
 `;
 // gpgsign off: the user's global config may demand signing, and a shadow
 // commit must never block on a passphrase prompt. Automatic GC stays off:
-// explicit GC runs inside the same serialization as each snapshot, after the
-// previous snapshot's objects are no longer needed.
+// explicit GC runs in the same per-folder queue as snapshots and diffs, on
+// the throttle below, after the objects it drops are no longer needed.
 const GITCONFIG = "[commit]\n\tgpgsign = false\n[core]\n\tautocrlf = false\n[gc]\n\tauto = 0\n";
+/** Hard ceiling on one git call. A hung git (index lock, dead network
+ * filesystem, cloud placeholders being downloaded) would otherwise jam the
+ * per-repo queue for the whole session. */
+const GIT_TIMEOUT_MS = 120_000;
+// The snapshot is awaited before every turn's dispatch, so GC does not run on
+// every snapshot: collect after this many HEAD-advancing snapshots of one
+// folder, or sooner when loose objects (git's own gc.auto default) or new
+// object data pile up. Counters are per process and reset on restart.
+export const GC_EVERY_COMMITS = 25;
+const GC_LOOSE_OBJECTS = 6_700;
+const GC_NEW_DATA_KIB = 262_144;
 /** One failed git call disables checkpoints for that bot until restart —
  * a broken shadow repo must cost the user one log line, not a failed turn. */
 const disabledBots = new Set();
@@ -127,6 +141,30 @@ function disable(botId, message) {
     disabledBots.add(botId);
     console.warn(`workspace checkpoints disabled for bot ${botId} this session: ${message}`);
 }
+/** A git call that hit GIT_TIMEOUT_MS (not a cancellation). The folder is
+ * too slow to snapshot — waiting that long again on every turn is worse than
+ * having no checkpoint, so only that bot+folder is switched off. */
+class GitTimeoutError extends Error {
+}
+/** Bot+folder pairs (keyed by shadow dir) switched off after a timeout. */
+const disabledFolders = new Set();
+function disableFolder(shadow, botId, worktree, message) {
+    if (disabledFolders.has(shadow))
+        return;
+    disabledFolders.add(shadow);
+    console.warn(`workspace checkpoints disabled for bot ${botId} in ${worktree} this session: ${message}`);
+}
+/** The shadow dir doubles as the bot+folder key. Null when the folder cannot
+ * be resolved (the refusal check reports that case). */
+function folderShadow(botId, cwd) {
+    try {
+        const worktree = realpathSync(resolve(cwd));
+        return { worktree, shadow: shadowDir(botId, worktree) };
+    }
+    catch {
+        return null;
+    }
+}
 // probed once: either the system has a usable git or checkpoints stay off
 let gitProbe = null;
 function gitAvailable() {
@@ -198,16 +236,23 @@ function gitEnv(shadow, cwd) {
     env.GIT_COMMITTER_EMAIL = "checkpoint@openmausbot.local";
     return env;
 }
+/** execFile reports its own timeout as a killed child; a cancellation via
+ * `signal` arrives as an AbortError instead and is not a timeout. */
+function gitFailure(command, err, stderr, signal) {
+    if (err.killed && err.name !== "AbortError" && !signal?.aborted) {
+        return new GitTimeoutError(`git ${command} timed out after ${GIT_TIMEOUT_MS / 1000} s`);
+    }
+    return new Error(`git ${command}: ${(stderr || err.message).trim().slice(0, 400)}`);
+}
 /** Run one git command against the shadow repo. cwd is the WORK TREE — the
- * "." pathspec in add resolves relative to it. A hung git (index lock, dead
- * network filesystem) would otherwise jam the per-repo queue for the whole
- * session, so every call carries a hard timeout. */
+ * "." pathspec in add resolves relative to it. Every call carries the
+ * GIT_TIMEOUT_MS hard timeout. */
 function runGit(args, cwd, env, signal) {
     return new Promise((resolvePromise, rejectPromise) => {
         signal?.throwIfAborted();
-        execFile("git", args, { cwd, env, signal, windowsHide: true, encoding: "utf8", timeout: 120_000, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+        execFile("git", args, { cwd, env, signal, windowsHide: true, encoding: "utf8", timeout: GIT_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
             if (err)
-                rejectPromise(new Error(`git ${args[0]}: ${(stderr || err.message).trim().slice(0, 400)}`));
+                rejectPromise(gitFailure(args[0], err, stderr, signal));
             else
                 resolvePromise(stdout);
         });
@@ -220,13 +265,13 @@ function runGit(args, cwd, env, signal) {
 function hasStagedChanges(cwd, env, signal) {
     return new Promise((resolvePromise, rejectPromise) => {
         signal?.throwIfAborted();
-        execFile("git", ["diff", "--cached", "--quiet", "--ignore-submodules=dirty"], { cwd, env, signal, windowsHide: true, encoding: "utf8", timeout: 120_000, maxBuffer: 16 * 1024 * 1024 }, (err, _stdout, stderr) => {
+        execFile("git", ["diff", "--cached", "--quiet", "--ignore-submodules=dirty"], { cwd, env, signal, windowsHide: true, encoding: "utf8", timeout: GIT_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 }, (err, _stdout, stderr) => {
             if (err === null)
                 resolvePromise(false);
             else if (err.code === 1)
                 resolvePromise(true);
             else
-                rejectPromise(new Error(`git diff: ${(stderr || err.message).trim().slice(0, 400)}`));
+                rejectPromise(gitFailure("diff", err, stderr, signal));
         });
     });
 }
@@ -241,26 +286,30 @@ function serialize(key, fn) {
     chains.set(key, run.then(() => undefined, () => undefined));
     return run;
 }
-// A ref per running turn. Every snapshot parents only the empty base and the
-// cleanup after it prunes whatever HEAD no longer reaches — so when a bot's
-// threads work side by side in one folder, a sibling's snapshot would discard
-// the pre-turn commit a still-running turn diffs against at its end. A pin
-// keeps that commit reachable until release(). The pin's name is hashed so
-// any token is a legal ref name.
+// A ref per running turn. Every snapshot parents only the empty base and a
+// collection prunes whatever HEAD no longer reaches — so when a bot's threads
+// work side by side in one folder, a collection after a sibling's snapshot
+// would discard the pre-turn commit a still-running turn diffs against at its
+// end. A pin keeps that commit reachable until release(). The pin's name is
+// hashed so any token is a legal ref name.
 const LIVE_REFS = "refs/omb-live/";
 function liveRef(pin) {
     return LIVE_REFS + createHash("sha256").update(pin).digest("hex").slice(0, 16);
 }
 // Pins outlive the process that wrote them (a crash mid-turn), so the first
 // use of each shadow in this process drops every pin left behind: no turn of
-// ours can be live in a shadow this process has not touched yet.
+// ours can be live in a shadow this process has not touched yet. Dropping one
+// makes the next snapshot's collection due (see collectionDue).
 const sweptShadows = new Set();
+const droppedPins = new Set();
 async function sweepLiveRefs(cwd, env, shadow, signal) {
     if (sweptShadows.has(shadow))
         return;
     const stale = (await runGit(["for-each-ref", "--format=%(refname)", LIVE_REFS], cwd, env, signal)).split("\n").filter(Boolean);
     for (const ref of stale)
         await runGit(["update-ref", "-d", ref], cwd, env, signal);
+    if (stale.length > 0)
+        droppedPins.add(shadow);
     sweptShadows.add(shadow);
 }
 /** Create the shadow repo on first use; self-heal its config files on every
@@ -309,32 +358,190 @@ async function ensureShadow(cwd, env, shadow, signal) {
     }
     await sweepLiveRefs(cwd, env, shadow, signal);
 }
+/** Folder listings in flight at once (libuv's pool has four threads). */
+const LISTING_CONCURRENCY = 4;
+/** Case-insensitive file systems only (APFS/HFS+ as macOS formats them,
+ * NTFS): does a staged path, or one of its folders, now exist on disk under a
+ * different case? git init sets core.ignorecase there, so an incremental
+ * `add -A` matches `R0` to the staged `r0` and keeps the old spelling
+ * forever. Reads folder listings only — each folder holding a staged path
+ * once, asynchronously, so a big tree never stalls the event loop — never
+ * file contents. Names compare in NFC: git stores precomposed paths on macOS,
+ * readdir returns names as they were created. */
+async function caseRenamed(cwd, paths) {
+    if (paths.length === 0)
+        return false;
+    const pending = new Set([""]);
+    for (const path of paths) {
+        for (let slash = path.indexOf("/"); slash > 0; slash = path.indexOf("/", slash + 1))
+            pending.add(path.slice(0, slash));
+    }
+    const listings = new Map();
+    const queue = [...pending];
+    const read = async () => {
+        for (let dir = queue.pop(); dir !== undefined; dir = queue.pop()) {
+            try {
+                const exact = new Set((await readdir(join(cwd, dir))).map((name) => name.normalize("NFC")));
+                listings.set(dir, { exact, folded: new Set([...exact].map((name) => name.toLowerCase())) });
+            }
+            catch {
+                listings.set(dir, null); // gone or unreadable: add -A handles deletions itself
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(LISTING_CONCURRENCY, queue.length) }, read));
+    const folders = new Map();
+    const renamed = (path, isFolder) => {
+        const known = isFolder ? folders.get(path) : undefined;
+        if (known !== undefined)
+            return known;
+        const slash = path.lastIndexOf("/");
+        const parent = slash < 0 ? "" : path.slice(0, slash);
+        const name = path.slice(slash + 1).normalize("NFC");
+        const names = listings.get(parent) ?? null;
+        let verdict;
+        if (names === null)
+            verdict = false;
+        else if (!names.exact.has(name))
+            verdict = names.folded.has(name.toLowerCase()); // else simply deleted
+        else
+            verdict = parent !== "" && renamed(parent, true);
+        if (isFolder)
+            folders.set(path, verdict);
+        return verdict;
+    };
+    return paths.some((path) => renamed(path, false));
+}
+/** Would an incremental `git add -A` leave the shadow index different from
+ * one rebuilt from empty? Only in four cases, all detected here: a tracked
+ * path is now ignored or inside a cache-tagged directory (add -A never drops
+ * tracked files), a folder holding tracked files became a nested repository
+ * (add -A keeps the files instead of a gitlink), a recorded nested
+ * repository lost its .git (add -A keeps the stale gitlink), or — on a
+ * case-insensitive file system — a tracked path was renamed by case only
+ * (add -A keeps the old spelling). */
+async function indexNeedsRebuild(cwd, env, signal) {
+    // If the index cannot be inspected (say, a listing past maxBuffer on a huge
+    // folder), rebuild: that is always correct, just slower.
+    const list = (args) => runGit(args, cwd, env, signal).catch((e) => {
+        if (e instanceof GitTimeoutError || signal?.aborted)
+            throw e;
+        return null;
+    });
+    const ignored = await list(["ls-files", "--cached", "--ignored", "--exclude-standard", "-z"]);
+    if (ignored === null || ignored.length > 0)
+        return true;
+    const staged = await list(["ls-files", "--stage", "-z"]);
+    if (staged === null)
+        return true;
+    const paths = [];
+    const parents = new Set();
+    for (const entry of staged.split("\0")) {
+        const tab = entry.indexOf("\t");
+        if (tab < 0)
+            continue;
+        const path = entry.slice(tab + 1);
+        paths.push(path);
+        if (entry.startsWith("160000 ")) {
+            if (!existsSync(join(cwd, path, ".git")))
+                return true;
+            continue;
+        }
+        for (let slash = path.indexOf("/"); slash > 0; slash = path.indexOf("/", slash + 1))
+            parents.add(path.slice(0, slash));
+    }
+    for (const dir of parents)
+        if (existsSync(join(cwd, dir, ".git")))
+            return true;
+    return (process.platform === "darwin" || process.platform === "win32") && (await caseRenamed(cwd, paths));
+}
+/** Stage the work tree into the shadow index. The index persists between
+ * snapshots so `git add -A` only re-reads files whose stat data changed;
+ * rebuilding it from empty re-reads and re-hashes every file (and downloads
+ * every cloud placeholder). It is rebuilt only when indexNeedsRebuild says an
+ * incremental add would differ, so the staged content always matches a
+ * from-empty rebuild. Only the shadow index changes; no user index or
+ * work-tree file does. */
+async function stageWorkTree(cwd, env, signal) {
+    if (await indexNeedsRebuild(cwd, env, signal))
+        await runGit(["read-tree", "--empty"], cwd, env, signal);
+    await runGit(["add", "-A", "--ignore-errors", "."], cwd, env, signal);
+}
 /** Capture fully before advancing HEAD: null when the add was partial, so a
  * partial capture never replaces the last usable checkpoint or authorizes
  * removal of its objects. */
 async function commitAll(cwd, env, label, signal) {
     const previous = (await runGit(["rev-parse", "HEAD"], cwd, env, signal)).trim();
     try {
-        // Rebuild only the shadow index so newly ignored/cache-tagged files stop
-        // pinning old blobs; no user index or work-tree file is changed.
-        await runGit(["read-tree", "--empty"], cwd, env, signal);
-        await runGit(["add", "-A", "--ignore-errors", "."], cwd, env, signal);
+        await stageWorkTree(cwd, env, signal);
     }
-    catch {
+    catch (e) {
+        // A timeout is not an unreadable file: the caller switches the folder off.
+        if (e instanceof GitTimeoutError)
+            throw e;
         return null;
     }
     const changed = await hasStagedChanges(cwd, env, signal);
     const base = (await runGit(["rev-list", "--max-parents=0", "HEAD"], cwd, env, signal)).trim();
     const count = (await runGit(["rev-list", "--count", "HEAD"], cwd, env, signal)).trim();
     if (!changed && Number(count) <= 2)
-        return previous;
+        return { hash: previous, advanced: false, compacted: false };
     const tree = (await runGit(["write-tree"], cwd, env, signal)).trim();
     const message = changed ? label : (await runGit(["show", "-s", "--format=%B", "HEAD"], cwd, env, signal)).trim();
     // Parent only the empty marker, never the previous snapshot: keeping the
     // previous commit as an ancestor would retain every old tree indefinitely.
     const hash = (await runGit(["commit-tree", tree, "-p", base, "-m", message], cwd, env, signal)).trim();
     await runGit(["update-ref", "HEAD", hash, previous], cwd, env, signal);
-    return hash;
+    return { hash, advanced: true, compacted: Number(count) > 2 };
+}
+/** HEAD-advancing snapshots per shadow since this process last collected. */
+const commitsSinceGc = new Map();
+/** Pack size (KiB) first counted after the last collection — the live
+ * snapshot. Packs also grow between collections: `git add` streams files over
+ * core.bigFileThreshold straight into new packs. */
+const packBaselineKib = new Map();
+/** A collection the throttle asked for, held until that turn's settled diff
+ * has been queued, or — when the turn settled without one — until the next
+ * snapshot, which runs it first (see snapshot and diffWorkingTree). */
+const pendingCollections = new Map();
+/** Queue the folder's pending collection behind whatever was just queued for
+ * it. Nothing awaits it. */
+function releaseCollection(shadow) {
+    const collect = pendingCollections.get(shadow);
+    if (collect === undefined)
+        return;
+    pendingCollections.delete(shadow);
+    void serialize(shadow, collect);
+}
+/** Throttle for collectObsolete (see GC_EVERY_COMMITS). */
+async function collectionDue(shadow, result, cwd, env, signal) {
+    // A compaction or a swept leftover pin frees a whole tree at once: reclaim it now.
+    const freed = droppedPins.delete(shadow) || result.compacted;
+    if (!result.advanced && !freed)
+        return false;
+    const commits = (commitsSinceGc.get(shadow) ?? 0) + (result.advanced ? 1 : 0);
+    commitsSinceGc.set(shadow, commits);
+    let due = freed || commits >= GC_EVERY_COMMITS;
+    if (!due) {
+        // Advisory only: a failed count must not cost the snapshot just taken.
+        const counted = await runGit(["count-objects", "-v"], cwd, env, signal).catch(() => "");
+        if (counted !== "") {
+            const field = (name) => Number(new RegExp(`^${name}: (\\d+)$`, "m").exec(counted)?.[1] ?? 0);
+            const pack = field("size-pack");
+            if (!packBaselineKib.has(shadow))
+                packBaselineKib.set(shadow, pack);
+            // Every loose object is new since the last collection (gc packs or
+            // prunes them all). Only pack growth counts, so a folder whose live
+            // snapshot alone passes the ceiling does not collect every turn.
+            const newData = field("size") + Math.max(0, pack - packBaselineKib.get(shadow));
+            due = field("count") >= GC_LOOSE_OBJECTS || newData >= GC_NEW_DATA_KIB;
+        }
+    }
+    if (due) {
+        commitsSinceGc.set(shadow, 0);
+        packBaselineKib.delete(shadow);
+    }
+    return due;
 }
 async function collectObsolete(cwd, env) {
     // No caller may still need an unpinned previous tree: HEAD stays reachable,
@@ -349,8 +556,8 @@ async function collectObsolete(cwd, env) {
     }
 }
 /** Snapshot the folder. Returns the checkpoint hash, or null when the
- * feature is off for this bot, git is missing, the folder is refused, or a
- * file could not be read.
+ * feature is off for this bot or folder, git is missing, the folder is
+ * refused, or a file could not be read.
  * With `pin`, the returned commit stays reachable through later snapshots of
  * the same folder until release(pin) — for a turn that will diff against it
  * when it ends. Never throws — this is called fire-and-forget on the turn path. */
@@ -363,30 +570,47 @@ export async function snapshot(botId, cwd, label, signal, opts) {
         return null;
     if (refusalReason(cwd) !== null)
         return null;
+    const folder = folderShadow(botId, cwd);
+    if (folder === null || disabledFolders.has(folder.shadow))
+        return null;
+    const { worktree, shadow } = folder;
     try {
-        const worktree = realpathSync(resolve(cwd));
-        const shadow = shadowDir(botId, worktree);
+        // Still pending from the previous snapshot: that turn settled without a
+        // diff. Collect ahead of this snapshot, not behind it, so this turn's own
+        // diff never queues behind GC and the object counts below see the
+        // collected repo (a stale count would make GC due again at once).
+        releaseCollection(shadow);
         return await serialize(shadow, async () => {
             const env = gitEnv(shadow, worktree);
             await ensureShadow(worktree, env, shadow, signal);
-            const hash = await commitAll(worktree, env, label, signal);
-            if (!hash)
+            const result = await commitAll(worktree, env, label, signal);
+            if (!result)
                 return null;
             if (opts?.pin)
-                await runGit(["update-ref", liveRef(opts.pin), hash], worktree, env, signal);
-            await collectObsolete(worktree, env);
-            return hash;
+                await runGit(["update-ref", liveRef(opts.pin), result.hash], worktree, env, signal);
+            // Never awaited by the turn waiting on this snapshot, and held for that
+            // turn's settled diff: diffWorkingTree queues it behind itself, so GC
+            // never eats into the digest's capture window.
+            if (await collectionDue(shadow, result, worktree, env, signal)) {
+                pendingCollections.set(shadow, () => collectObsolete(worktree, env));
+            }
+            return result.hash;
         });
     }
     catch (e) {
-        if (!signal?.aborted)
-            disable(botId, e instanceof Error ? e.message : String(e));
+        if (signal?.aborted)
+            return null;
+        const message = e instanceof Error ? e.message : String(e);
+        if (e instanceof GitTimeoutError)
+            disableFolder(shadow, botId, worktree, message);
+        else
+            disable(botId, message);
         return null;
     }
 }
-/** Let go of a pinned pre-turn commit: the next snapshot's cleanup may
- * reclaim it. Queued behind the shadow's pending operations, so a digest's
- * diff already in that queue still finds its commit. Best-effort like the
+/** Let go of a pinned pre-turn commit: the next collection may reclaim it.
+ * Queued behind the shadow's pending operations, so a digest's diff already
+ * in that queue still finds its commit. Best-effort like the
  * rest of this module — a pin that cannot be dropped costs one log line and
  * is swept on the next start. */
 export async function release(botId, cwd, pin) {
@@ -411,14 +635,15 @@ export async function diffWorkingTree(botId, cwd, fromHash, signal) {
         return null;
     if (disabledBots.has(botId) || !(await gitAvailable()) || refusalReason(cwd) !== null)
         return null;
+    const folder = folderShadow(botId, cwd);
+    if (folder === null || disabledFolders.has(folder.shadow))
+        return null;
+    const { worktree, shadow } = folder;
     try {
-        const worktree = realpathSync(resolve(cwd));
-        const shadow = shadowDir(botId, worktree);
         const env = gitEnv(shadow, worktree);
-        return await serialize(shadow, async () => {
+        const run = serialize(shadow, async () => {
             await ensureShadow(worktree, env, shadow, signal);
-            await runGit(["read-tree", "--empty"], worktree, env, signal);
-            await runGit(["add", "-A", "--ignore-errors", "."], worktree, env, signal);
+            await stageWorkTree(worktree, env, signal);
             const out = await runGit(["diff", "--cached", "--name-status", "--no-renames", "-z", fromHash], worktree, env, signal);
             const diff = { changed: [], added: [], deleted: [] };
             const fields = out.split("\0").filter((field) => field.length > 0);
@@ -434,8 +659,14 @@ export async function diffWorkingTree(botId, cwd, fromHash, signal) {
             }
             return diff;
         });
+        // The collection this turn's snapshot left pending runs behind this
+        // diff, never ahead of it.
+        releaseCollection(shadow);
+        return await run;
     }
-    catch {
+    catch (e) {
+        if (e instanceof GitTimeoutError && !signal?.aborted)
+            disableFolder(shadow, botId, worktree, e.message);
         return null;
     }
 }

package/dist-server/server/cli-setup.js

@@ -118,7 +118,7 @@ const NATIVE = [
 async function connectNative(choice, id, entry, io, deps) {
     const cli = typeof rawObject(entry.config).cli === "string" ? rawObject(entry.config).cli : choice.cli;
     io.log("Connecting your account…");
-    io.log("Sign-in stays with your provider. Its account limits apply; OMB never asks for your password.");
+    io.log("Sign-in stays with your provider. Its account limits apply; OpenMausBot never asks for your password.");
     let state = await deps.inspect(id, entry);
     if (state.snapshot.state !== "available") {
         if (cli !== choice.cli)
@@ -143,7 +143,7 @@ async function connectNative(choice, id, entry, io, deps) {
         await deps.runCli(cli, args, entry.environment);
         state = await deps.inspect(id, entry);
         if (state.snapshot.state !== "available" || !state.snapshot.authenticated) {
-            throw new Error("Sign-in was not confirmed. Your OMB settings are unchanged; complete provider sign-in and try again.");
+            throw new Error("Sign-in was not confirmed. Your OpenMausBot settings are unchanged; complete provider sign-in and try again.");
         }
     }
     else {
@@ -294,7 +294,7 @@ export async function runSetup(options, io = defaultSetupIo(), deps = dependenci
     catch (error) {
         if (!(error instanceof SetupCancelled))
             throw error;
-        io.log("\nSetup cancelled. No OMB settings were changed. Provider sign-ins or installs already completed are kept.");
+        io.log("\nSetup cancelled. No OpenMausBot settings were changed. Provider sign-ins or installs already completed are kept.");
         return false;
     }
     finally {

package/dist-server/server/cloud-computer-tools.js

@@ -15,6 +15,8 @@ export const CLOUD_COMPUTER_TOOLS = [
     tool("open_url", "Request opening an HTTP or HTTPS URL in the cloud desktop browser; inspect the screen to confirm it loaded.", { url: { type: "string", pattern: "^https?://", maxLength: 2000 } }, ["url"]),
     tool("exec", "Run a shell command on the assigned cloud computer.", { command: { type: "string", minLength: 1, maxLength: 4000 } }, ["command"]),
 ];
+/** A call the gate let through while no Boat had landed for the turn. */
+export const CLOUD_COMPUTER_NOT_READY = "The cloud computer is not ready. This call was not performed. Take a fresh screenshot in a moment.";
 const quote = (value) => "'" + value.replace(/'/g, "'\\''") + "'";
 const buttons = { left: 1, middle: 2, right: 3 };
 const scrollButtons = { up: 4, down: 5, left: 6, right: 7 };
@@ -85,9 +87,11 @@ export async function runCloudComputerTool(cfg, boxId, name, args, signal) {
 }
 /** One JSON-RPC request from harness-mcp-proxy, answered with its MCP
  * `result`. The order is the safety argument: arguments are checked before
- * the control gate (which may claim the seat), a person's control refuses
- * the call before anything reaches the Boat, and the turn's capability must
- * still be live before and after the Boat acts. */
+ * the control gate (which may claim the seat, and for a cloud computer
+ * mounted before it existed, create or wake it), a person's control refuses
+ * the call before anything reaches the Boat, the Boat is read only once the
+ * gate has let the call through, and the turn's capability must still be
+ * live before and after the Boat acts. Listing the tools touches no Boat. */
 export async function cloudComputerRpc(request, deps) {
     if (request?.method === "tools/list") {
         deps.assertActive();
@@ -104,7 +108,10 @@ export async function cloudComputerRpc(request, deps) {
     deps.assertActive();
     if (control.held)
         return { isError: true, content: [{ type: "text", text: control.blockedReason || CONTROL_REFUSAL_PLAIN }] };
-    const result = await runCloudComputerTool(deps.cfg, deps.boxId, params.name, args, deps.signal);
+    const boxId = deps.boxId();
+    if (!boxId)
+        return { isError: true, content: [{ type: "text", text: CLOUD_COMPUTER_NOT_READY }] };
+    const result = await runCloudComputerTool(deps.cfg, boxId, params.name, args, deps.signal);
     deps.assertActive();
     return result;
 }

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

@@ -1,4 +1,4 @@
-// Entry point of the OMB Cloud Pro home image (deploy/fly/Dockerfile).
+// Entry point of the OMB Cloud Pro home image (the Dockerfile's cloud-home target).
 //
 // Starts as root, hands a fresh Fly volume (mounted root-owned at /data) to
 // the unprivileged `maus` user, and stays a small root supervisor of two
@@ -77,7 +77,7 @@ export function cloudHomeChildEnvironments(config, env, home) {
 /** Why the root supervisor must not run or trust `files`, or null: each
  * must be root's and not writable by anyone else (nor any folder above it),
  * and none may live on the volume `home`, which `maus` owns. The image makes its code
- * root's (deploy/fly/Dockerfile); a file `maus` could rewrite would run as
+ * root's (the Dockerfile's cloud-home target); a file `maus` could rewrite would run as
  * root at the next start, or be handed the secrets. */
 export function codeTrustProblem(files, home, stat = statSync) {
     const volume = posix.join(home, "/");
@@ -117,7 +117,7 @@ export function startCloudHome(env = process.env) {
     process.umask(0o077);
     const config = cloudHomeConfiguration(env);
     if (!config)
-        throw new Error("This image runs an OMB Cloud home machine; set its boot contract (docs/cloud-pro.md).");
+        throw new Error("This image runs a My Cloud machine for OpenMausBot Cloud; set its boot contract (docs/cloud-pro.md).");
     // Logged here once: the server child never sees what they are about.
     for (const warning of config.warnings)
         console.warn(`cloud home: ${warning}`);
@@ -155,7 +155,7 @@ export function startCloudHome(env = process.env) {
     if (ids) {
         const problem = codeTrustProblem([process.execPath, fileURLToPath(import.meta.url), join(here, "index.js"), edgeBin, edgeConfig], home);
         if (problem)
-            throw new Error(`This image's code is not safe to run as root: ${problem}. Rebuild it from deploy/fly/Dockerfile.`);
+            throw new Error(`This image's code is not safe to run as root: ${problem}. Rebuild it with docker build --target cloud-home.`);
     }
     const { server, edge, secrets, dropped } = cloudHomeChildEnvironments(config, env, home);
     // Names only, never values: what the server does not get from here.

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

@@ -109,17 +109,11 @@ export { cloudHomeOffersPlace } from "../shared/cloud-home.js";
  * place it offers. A turn's error shows 160 characters, so each fits. */
 export function cloudHomePlaceRefusal(place) {
     if (place === "local")
-        return "This computer isn't a place on your OMB Cloud: its bots run in the cloud. Set Works on to Auto, Cloud or Browser, or lend your Mac under Settings → OMB Cloud.";
+        return "This computer isn't a place on My Cloud. Set Works on to Auto, Cloud computer or Browser, or lend your Mac under Settings → OpenMausBot Cloud.";
     if (place === "vm")
-        return "Bots on your OMB Cloud can't use a Local VM: the cloud machine has no container runtime. Set Works on to Auto, Cloud or Browser.";
+        return "Bots on My Cloud can't use a Local VM. Set Works on to Auto, Cloud computer or Browser.";
     return undefined;
 }
-/** What a turn is told when Cloud is chosen but no Boat account is set up (no
- * key of the person's and no included Boat). A Cloud home has no Local VM to
- * suggest instead. */
-export function boatNotConfiguredMessage(cloudHome) {
-    return `Cloud Boat is not configured — add a Boat API key or choose ${cloudHome ? "Browser" : "Local VM"}`;
-}
 /** The Cloud's setup checklist (docs/cloud-pro.md) has a "try something"
  * step that is done once a bot's turn finishes on the machine itself. The
  * server records when, once, in this Cloud's own onboarding record: that
@@ -198,7 +192,7 @@ export function createCloudPairing(options) {
             const ttl = Math.min(ttlSeconds ?? CLOUD_PAIRING_DEFAULT_TTL_S, browser ? CLOUD_BROWSER_SIGN_IN_MAX_TTL_S : CLOUD_PAIRING_MAX_TTL_S);
             const opened = sessions.openPairing({
                 scopes: ["admin", "client"],
-                label: typeof label === "string" && label.trim() ? label.trim() : "OMB Cloud",
+                label: typeof label === "string" && label.trim() ? label.trim() : "OpenMausBot Cloud",
                 ttlMs: ttl * 1000,
                 browser,
                 ...(browser ? { owner: owner } : {}),

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

@@ -29,7 +29,7 @@
 import { lstatSync, readFileSync } from "node:fs";
 import { z } from "zod";
 import { writeFileAtomic } from "./atomic.js";
-export const CLOUD_PERSONAL_REFUSAL = "OMB Cloud is personal: only your own devices can connect.";
+export const CLOUD_PERSONAL_REFUSAL = "My Cloud is personal: only your own devices can connect.";
 const KEY = /^p_[\w-]{22}$/;
 const keys = z.array(z.string().regex(KEY)).max(100_000);
 const recordFile = z.object({