openmausbot 0.1.89 → 0.1.91

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

@@ -0,0 +1,418 @@
+// Move to Cloud (docs/cloud-pro.md): a person's one-time copy of their local
+// workspace onto their OMB Cloud home. The desktop exports the ordinary
+// encrypted workspace backup (workspace-backup.ts) and uploads it here in
+// parts; this machine then previews and restores it like any other backup,
+// so everything that backup policy keeps out (credentials, sign-ins, pairing
+// and sessions, runtime state) stays where it is on both sides.
+//
+// What this file adds: the workspace's size and contents, a resumable upload
+// slot, the space check for the machine's fixed-size volume, a backup of the
+// Cloud's own workspace taken before it is replaced ("Restore previous Cloud"
+// swaps it back), and the tidying that keeps that backup the only copy left
+// behind. Everything lives under `.backups`, which no snapshot includes and
+// no restore replaces.
+import { createHash, randomBytes } from "node:crypto";
+import { createReadStream, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statfsSync, writeFileSync } from "node:fs";
+import { open } from "node:fs/promises";
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { writeFileAtomic } from "./atomic.js";
+import { MAX_WORKSPACE_BACKUP_FILES, MAX_WORKSPACE_BACKUP_UPLOAD_BYTES, omittedFromWorkspaceBackup, removeWorkspaceBackupJob, stageWorkspaceBackup, } from "./workspace-backup.js";
+/** The part size the desktop sends; a part may be at most CLOUD_MOVE_MAX_PART_BYTES. */
+export const CLOUD_MOVE_PART_BYTES = 16 * 1024 ** 2;
+export const CLOUD_MOVE_MAX_PART_BYTES = 64 * 1024 ** 2;
+export const CLOUD_MOVE_MAX_BYTES = MAX_WORKSPACE_BACKUP_UPLOAD_BYTES;
+export const CLOUD_MOVE_MAX_FILES = MAX_WORKSPACE_BACKUP_FILES;
+/** Headroom kept free on the volume after a move's own files. */
+export const CLOUD_MOVE_SPACE_MARGIN = 256 * 1024 ** 2;
+// Encrypted header plus tag: anything smaller cannot be a backup.
+const MIN_BYTES = 60;
+const SHA256 = /^[a-f0-9]{64}$/;
+// An upload nobody has touched for a day is abandoned, not resumable.
+const UPLOAD_STALE_MS = 24 * 3600_000;
+const fail = (message, status, extra = {}) => Object.assign(new Error(message), { status, ...extra });
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+function rosterLength(path) {
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        return Array.isArray(value) ? value.length : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** What the person would call their work: bots, rooms, and the conversations
+ * they took part in (a starter bot's greeting is not a chat). */
+export function workspaceContents(dataDir) {
+    let chats = 0;
+    const database = join(dataDir, "messages.db");
+    if (existsSync(database)) {
+        const db = new DatabaseSync(database, { timeout: 5_000 });
+        try {
+            const columns = db.prepare("SELECT name FROM pragma_table_info('messages')").all().map((row) => String(row.name));
+            if (columns.length) {
+                const who = columns.includes("role") ? "role" : "json_extract(json, '$.role')";
+                chats = Number(db.prepare(`SELECT COUNT(DISTINCT thread_id) AS chats FROM messages WHERE ${who} = 'user'`).get()?.chats ?? 0);
+            }
+        }
+        finally {
+            db.close();
+        }
+    }
+    return { bots: rosterLength(join(dataDir, "bots.json")), rooms: rosterLength(join(dataDir, "groups.json")), chats };
+}
+/** A fresh machine: its one starter bot at most, no rooms, nobody has chatted. */
+export function isEmptyWorkspace(contents) {
+    return contents.bots <= 1 && contents.rooms === 0 && contents.chats === 0;
+}
+/** Bytes and files a backup of this workspace would carry, by the export's
+ * own rules. An estimate: live files can change before the export. */
+export function workspaceMoveSize(dataDir) {
+    let bytes = 0, files = 0;
+    const walk = (directory, prefix) => {
+        for (const name of readdirSync(directory)) {
+            const path = prefix ? `${prefix}/${name}` : name;
+            if (omittedFromWorkspaceBackup(path))
+                continue;
+            const stat = lstatSync(join(directory, name));
+            if (stat.isSymbolicLink())
+                continue;
+            if (stat.isDirectory())
+                walk(join(directory, name), path);
+            else if (stat.isFile()) {
+                bytes += stat.size;
+                files++;
+            }
+            if (files > CLOUD_MOVE_MAX_FILES)
+                return;
+        }
+    };
+    if (existsSync(dataDir))
+        walk(dataDir, "");
+    return { bytes, files };
+}
+export function freeVolumeBytes(path) {
+    const disk = statfsSync(path, { bigint: true });
+    const free = disk.bavail * disk.bsize;
+    return free > BigInt(Number.MAX_SAFE_INTEGER) ? Number.MAX_SAFE_INTEGER : Number(free);
+}
+/** Peak extra space a move of `upload` bytes needs: the upload, its decrypted
+ * copy and its staged files exist together while it is checked; the restore
+ * then installs from the staged copy. Replacing a workspace first backs it up
+ * (a snapshot and its archive, briefly both). */
+export function moveSpaceNeeded(upload, current, replacing) {
+    return 3 * upload + (replacing ? 2 * current : 0) + CLOUD_MOVE_SPACE_MARGIN;
+}
+function privateFolder(path) {
+    mkdirSync(path, { recursive: true, mode: 0o700 });
+    const stat = lstatSync(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw fail("Backup storage must be a real folder, not a link.", 500);
+    return path;
+}
+const backupsRoot = (dataDir) => privateFolder(join(dataDir, ".backups"));
+// Reads never create the folder; beginUpload does.
+const uploadFolder = (dataDir) => join(dataDir, ".backups", "cloud-move");
+const uploadMetaPath = (dataDir) => join(uploadFolder(dataDir), "upload.json");
+const uploadPartPath = (dataDir) => join(uploadFolder(dataDir), "upload.part");
+function readUploadMeta(dataDir) {
+    try {
+        const value = JSON.parse(readFileSync(uploadMetaPath(dataDir), "utf8"));
+        if (record(value) && typeof value.sha256 === "string" && SHA256.test(value.sha256) && Number.isSafeInteger(value.bytes) && Number.isSafeInteger(value.updatedAt)) {
+            return value;
+        }
+    }
+    catch { /* none, or unreadable: a fresh upload replaces it */ }
+    return null;
+}
+function receivedBytes(dataDir) {
+    try {
+        const stat = lstatSync(uploadPartPath(dataDir));
+        return stat.isFile() ? stat.size : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+export function uploadStatus(dataDir) {
+    const meta = readUploadMeta(dataDir);
+    return meta ? { sha256: meta.sha256, bytes: meta.bytes, received: Math.min(receivedBytes(dataDir), meta.bytes) } : null;
+}
+export function discardUpload(dataDir) {
+    rmSync(uploadPartPath(dataDir), { force: true });
+    rmSync(uploadMetaPath(dataDir), { force: true });
+}
+/** Check a declared upload: its size, file count and SHA-256. */
+export function validUploadDeclaration(input) {
+    if (typeof input.sha256 !== "string" || !SHA256.test(input.sha256))
+        throw fail("This is not a workspace backup.", 400);
+    if (!Number.isSafeInteger(input.bytes) || input.bytes < MIN_BYTES)
+        throw fail("This is not a workspace backup.", 400);
+    if (input.bytes > CLOUD_MOVE_MAX_BYTES)
+        throw fail("This workspace is larger than the 10 GB a move can carry.", 413);
+    if (input.files !== undefined && (!Number.isSafeInteger(input.files) || input.files < 0 || input.files > CLOUD_MOVE_MAX_FILES)) {
+        throw fail("This workspace has more than the 100,000 files a move can carry.", 413);
+    }
+    return { sha256: input.sha256, bytes: input.bytes };
+}
+/** Start an upload, or continue the same file's upload where it stopped. */
+export function beginUpload(dataDir, declared, now = Date.now()) {
+    const existing = readUploadMeta(dataDir);
+    if (existing && existing.sha256 === declared.sha256 && existing.bytes === declared.bytes && existing.updatedAt + UPLOAD_STALE_MS > now && receivedBytes(dataDir) <= declared.bytes) {
+        writeFileAtomic(uploadMetaPath(dataDir), JSON.stringify({ ...existing, updatedAt: now }), { mode: 0o600 });
+        return { ...declared, received: receivedBytes(dataDir) };
+    }
+    discardUpload(dataDir);
+    backupsRoot(dataDir);
+    privateFolder(uploadFolder(dataDir));
+    writeFileSync(uploadPartPath(dataDir), "", { mode: 0o600, flag: "wx" });
+    writeFileAtomic(uploadMetaPath(dataDir), JSON.stringify({ ...declared, updatedAt: now }), { mode: 0o600 });
+    return { ...declared, received: 0 };
+}
+/** Store one part at `offset`. A part already stored is accepted again
+ * without writing; any other offset than the next one answers where the
+ * upload stands (409, `received`). A failed part is cut back off. */
+export async function writeUploadPart(dataDir, sha256, offset, length, body, now = Date.now()) {
+    const meta = readUploadMeta(dataDir);
+    if (!meta || meta.sha256 !== sha256)
+        throw fail("This upload is not in progress on your Cloud. Start the move again.", 404);
+    if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(length) || length <= 0 || length > CLOUD_MOVE_MAX_PART_BYTES) {
+        throw fail("Invalid upload part.", 400);
+    }
+    if (offset + length > meta.bytes)
+        throw fail("The upload is larger than the file it declared.", 413);
+    const received = receivedBytes(dataDir);
+    const drain = async () => { for await (const _chunk of body) { /* already stored */ } };
+    if (offset + length <= received) {
+        await drain();
+        return received;
+    }
+    if (offset !== received) {
+        await drain();
+        throw fail("The upload continues from another point.", 409, { received });
+    }
+    const handle = await open(uploadPartPath(dataDir), "r+");
+    let written = 0;
+    try {
+        for await (const chunk of body) {
+            if (written + chunk.length > length)
+                throw fail("The upload part is larger than it declared.", 413);
+            let done = 0;
+            while (done < chunk.length)
+                done += (await handle.write(chunk, done, chunk.length - done, offset + written + done)).bytesWritten;
+            written += chunk.length;
+        }
+        if (written !== length)
+            throw fail("The upload part was incomplete.", 400);
+        await handle.sync();
+    }
+    catch (error) {
+        await handle.truncate(received).catch(() => { });
+        throw error;
+    }
+    finally {
+        await handle.close();
+    }
+    writeFileAtomic(uploadMetaPath(dataDir), JSON.stringify({ ...meta, updatedAt: now }), { mode: 0o600 });
+    return received + length;
+}
+/** The complete upload's path, once its size and SHA-256 match what was declared. */
+export async function completedUpload(dataDir, sha256) {
+    const status = uploadStatus(dataDir);
+    if (!status || status.sha256 !== sha256)
+        throw fail("This upload is not in progress on your Cloud. Start the move again.", 404);
+    if (status.received !== status.bytes)
+        throw fail("The upload is not complete yet.", 409, { received: status.received });
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(uploadPartPath(dataDir), { highWaterMark: 1024 * 1024 }))
+        hash.update(chunk);
+    if (hash.digest("hex") !== sha256) {
+        discardUpload(dataDir);
+        throw fail("The uploaded file was damaged on the way. Start the move again.", 400);
+    }
+    return uploadPartPath(dataDir);
+}
+const previousFolder = (dataDir) => join(dataDir, ".backups", "cloud-previous");
+const nextPreviousFolder = (dataDir) => join(dataDir, ".backups", "cloud-previous.next");
+const moveRestoresPath = (dataDir) => join(dataDir, ".backups", "cloud-move-restores.json");
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+function readPrevious(folder) {
+    try {
+        const value = JSON.parse(readFileSync(join(folder, "previous.json"), "utf8"));
+        if (!record(value) || typeof value.password !== "string" || typeof value.createdAt !== "string" || !record(value.contents))
+            return null;
+        if (!lstatSync(join(folder, "workspace.ombbackup")).isFile())
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+/** The previous Cloud that can be put back, never its password. A fresh
+ * Cloud's (its starter bot, nothing else) is kept but not offered. */
+export function previousCloud(dataDir) {
+    const previous = readPrevious(previousFolder(dataDir));
+    if (!previous || isEmptyWorkspace(previous.contents))
+        return null;
+    return { createdAt: previous.createdAt, ...previous.contents, bytes: lstatSync(join(previousFolder(dataDir), "workspace.ombbackup")).size };
+}
+/** Back up this workspace as the next previous Cloud, for the restore
+ * `restoreId`. `create` is createWorkspaceBackup, run by the caller inside
+ * the maintenance gate. It becomes the previous Cloud only once startup has
+ * installed that restore. */
+export async function prepareNextPreviousCloud(dataDir, restoreId, create) {
+    const password = randomBytes(32).toString("base64url");
+    const contents = workspaceContents(dataDir);
+    const created = await create(password);
+    const next = nextPreviousFolder(dataDir);
+    try {
+        backupsRoot(dataDir);
+        rmSync(next, { recursive: true, force: true });
+        privateFolder(next);
+        renameSync(created.path, join(next, "workspace.ombbackup"));
+        const meta = { password, createdAt: new Date().toISOString(), contents, forRestore: restoreId };
+        writeFileAtomic(join(next, "previous.json"), JSON.stringify(meta), { mode: 0o600 });
+        return { createdAt: meta.createdAt, ...contents };
+    }
+    catch (error) {
+        rmSync(next, { recursive: true, force: true });
+        throw error;
+    }
+    finally {
+        try {
+            removeWorkspaceBackupJob(dataDir, created.id);
+        }
+        catch { /* The export job expires with the others. */ }
+    }
+}
+/** Drop a next previous Cloud whose restore did not commit. */
+export function discardNextPreviousCloud(dataDir) {
+    rmSync(nextPreviousFolder(dataDir), { recursive: true, force: true });
+}
+/** Stage the previous Cloud for an ordinary restore; its archive stays. */
+export async function stagePreviousCloud(dataDir, appVersion) {
+    const previous = readPrevious(previousFolder(dataDir));
+    if (!previous || isEmptyWorkspace(previous.contents))
+        throw fail("There is no previous Cloud to restore.", 404);
+    const archive = join(previousFolder(dataDir), "workspace.ombbackup");
+    const staged = await stageWorkspaceBackup(dataDir, archive, { password: previous.password, currentAppVersion: appVersion });
+    return { ...staged, bytes: lstatSync(archive).size };
+}
+/** The archive size of the previous Cloud (0 without one), for space checks. */
+export function previousCloudArchiveBytes(dataDir) {
+    try {
+        return lstatSync(join(previousFolder(dataDir), "workspace.ombbackup")).size;
+    }
+    catch {
+        return 0;
+    }
+}
+function readMoveRestores(dataDir) {
+    try {
+        const value = JSON.parse(readFileSync(moveRestoresPath(dataDir), "utf8"));
+        return Array.isArray(value) ? value.filter((id) => typeof id === "string" && UUID.test(id)) : [];
+    }
+    catch {
+        return [];
+    }
+}
+function writeMoveRestores(dataDir, ids) {
+    backupsRoot(dataDir);
+    if (ids.length)
+        writeFileAtomic(moveRestoresPath(dataDir), JSON.stringify([...new Set(ids)]), { mode: 0o600 });
+    else
+        rmSync(moveRestoresPath(dataDir), { force: true });
+}
+/** Remember a restore made by a move or a swap back, before it commits, so
+ * its safety copy and staged files are tidied once it is installed. */
+export function noteMoveRestore(dataDir, restoreId) {
+    writeMoveRestores(dataDir, [...readMoveRestores(dataDir), restoreId]);
+}
+export function forgetMoveRestore(dataDir, restoreId) {
+    writeMoveRestores(dataDir, readMoveRestores(dataDir).filter((id) => id !== restoreId));
+}
+/** Delete a staged job, and its safety copy, by id: guarded paths only. */
+export function removeMoveFiles(dataDir, id) {
+    if (!UUID.test(id))
+        return;
+    for (const name of [id, `safety-${id}`]) {
+        const path = join(dataDir, ".backups", name);
+        try {
+            const stat = lstatSync(path);
+            if (stat.isDirectory() && !stat.isSymbolicLink())
+                rmSync(path, { recursive: true, force: true });
+        }
+        catch { /* already gone */ }
+    }
+}
+function pendingRestoreId(dataDir) {
+    try {
+        const value = JSON.parse(readFileSync(join(dataDir, ".backups", "pending-restore.json"), "utf8"));
+        return record(value) && typeof value.id === "string" ? value.id : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** At a Cloud home's startup, after any pending restore was applied:
+ * - a next previous Cloud becomes the previous Cloud once its restore is
+ *   installed, and is dropped otherwise;
+ * - moves' and swaps' restores, once settled, keep no safety copy or staged
+ *   files (the previous Cloud is the one undo point);
+ * - an upload nobody has touched for a day is deleted.
+ * Never touches a restore still waiting to be applied. */
+export function tidyCloudMoveStorage(dataDir, restored, now = Date.now()) {
+    if (!existsSync(join(dataDir, ".backups")))
+        return;
+    const pending = pendingRestoreId(dataDir);
+    const next = readPrevious(nextPreviousFolder(dataDir));
+    if (next && next.forRestore !== pending) {
+        if (restored.restored && restored.id === next.forRestore) {
+            rmSync(previousFolder(dataDir), { recursive: true, force: true });
+            renameSync(nextPreviousFolder(dataDir), previousFolder(dataDir));
+        }
+        else
+            discardNextPreviousCloud(dataDir);
+    }
+    else if (!next && existsSync(nextPreviousFolder(dataDir)) && !pending)
+        discardNextPreviousCloud(dataDir);
+    const settled = readMoveRestores(dataDir).filter((id) => id !== pending);
+    for (const id of settled)
+        removeMoveFiles(dataDir, id);
+    writeMoveRestores(dataDir, readMoveRestores(dataDir).filter((id) => id === pending));
+    if (restored.id && settled.includes(restored.id)) {
+        // The receipt must not point at a safety copy that is gone.
+        delete restored.safetyCopyPath;
+        try {
+            const receipt = join(dataDir, ".backups", "last-restore.json");
+            const value = JSON.parse(readFileSync(receipt, "utf8"));
+            if (record(value) && value.id === restored.id && "safetyCopyPath" in value) {
+                delete value.safetyCopyPath;
+                writeFileAtomic(receipt, JSON.stringify(value), { mode: 0o600 });
+            }
+        }
+        catch { /* no receipt */ }
+    }
+    const upload = readUploadMeta(dataDir);
+    if ((upload && upload.updatedAt + UPLOAD_STALE_MS <= now) || (!upload && existsSync(uploadPartPath(dataDir))))
+        discardUpload(dataDir);
+}
+/** Bytes under `.backups`: what backups, safety copies and moves hold on the volume. */
+export function backupsBytes(dataDir) {
+    let bytes = 0;
+    const walk = (directory) => {
+        for (const name of readdirSync(directory)) {
+            const stat = lstatSync(join(directory, name));
+            if (stat.isDirectory() && !stat.isSymbolicLink())
+                walk(join(directory, name));
+            else if (stat.isFile())
+                bytes += stat.size;
+        }
+    };
+    try {
+        walk(join(dataDir, ".backups"));
+    }
+    catch { /* none yet */ }
+    return bytes;
+}

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)