@fungi.computer/computer 0.0.0-stage → 0.0.1

package/dist/fleet/inventory.js

@@ -0,0 +1,152 @@
+import { words } from "@fungi.computer/cairn";
+import { defineIdFamily } from "@fungi.computer/cairn/id";
+import { z } from "zod";
+import { ComputerInventoryError, computerPageSchema, } from "./inventory-wire.js";
+const computerIds = defineIdFamily({
+    family: "computer",
+    version: 1,
+    kinds: { computer: { prefix: "computer" } },
+});
+const rowSchema = z.strictObject({
+    computer_id: z.string().min(1),
+    name: z.string().min(1).max(256),
+    actor_kind: z.string().min(1),
+    actor_id: z.string().min(1).max(256),
+    active: z.number().int().min(0).max(1),
+    created_at: z.number().int().nonnegative(),
+    updated_at: z.number().int().nonnegative(),
+});
+const receiptSchema = z.strictObject({
+    requested_name: z.string().min(1).max(256).nullable(),
+    request_id: z.string().min(1).max(256),
+    actor_kind: z.string().min(1),
+    actor_id: z.string().min(1).max(256),
+    name: z.string().min(1).max(256),
+    computer_id: z.string().min(1),
+});
+const selectRow = "SELECT computer_id,name,actor_kind,actor_id,active,created_at,updated_at FROM hub_team_computers";
+function actorColumns(actor) {
+    return { actorId: actor.id, actorKind: actor.kind };
+}
+function sameActor(actorKind, actorId, actor) {
+    return actor.kind === actorKind && actor.id === actorId;
+}
+/** Durable Computer inventory and replay receipts, without host admission policy. */
+export function createFleetInventory(options) {
+    const { sql } = options;
+    const ensure = () => {
+        sql.exec("CREATE TABLE IF NOT EXISTS hub_team_computers (computer_id TEXT PRIMARY KEY, name TEXT NOT NULL UNIQUE, actor_kind TEXT NOT NULL, actor_id TEXT NOT NULL, active INTEGER NOT NULL DEFAULT 1 CHECK (active IN (0,1)), created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL) STRICT");
+        sql.exec("CREATE TABLE IF NOT EXISTS hub_team_computer_create_receipts (request_id TEXT PRIMARY KEY, actor_kind TEXT NOT NULL, actor_id TEXT NOT NULL, requested_name TEXT, name TEXT NOT NULL, computer_id TEXT NOT NULL REFERENCES hub_team_computers(computer_id)) STRICT");
+    };
+    const decode = (row) => {
+        const id = computerIds.computer.parse(row.computer_id);
+        if (!id.ok)
+            throw new ComputerInventoryError("partial_init");
+        return {
+            computerId: id.value,
+            name: row.name,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+        };
+    };
+    const nameIsTaken = (name) => sql
+        .exec("SELECT computer_id FROM hub_team_computers WHERE name=?", name)
+        .toArray().length > 0;
+    const generatedName = () => {
+        // Cairn's default two-word names are candidates, not registered unique IDs.
+        // Add entropy on collision instead of rejecting an otherwise valid create.
+        for (const count of [2, 3, 4]) {
+            const candidate = words({ count });
+            if (!nameIsTaken(candidate))
+                return candidate;
+        }
+        throw new ComputerInventoryError("name_taken");
+    };
+    const read = (computerId) => {
+        const raw = sql
+            .exec(`${selectRow} WHERE computer_id=?`, computerId)
+            .toArray()[0];
+        if (raw === undefined)
+            return null;
+        const row = rowSchema.safeParse(raw);
+        if (!row.success)
+            throw new ComputerInventoryError("partial_init");
+        return row.data.active === 0 ? null : decode(row.data);
+    };
+    const count = () => z
+        .strictObject({ count: z.number().int().nonnegative() })
+        .parse(sql
+        .exec("SELECT COUNT(*) AS count FROM hub_team_computers")
+        .toArray()[0]).count;
+    const list = (input) => {
+        const { limit, offset } = computerPageSchema.parse(input);
+        const rows = sql
+            .exec(`${selectRow} WHERE active=1 ORDER BY created_at DESC,computer_id DESC LIMIT ? OFFSET ?`, limit + 1, offset)
+            .toArray()
+            .map((raw) => {
+            const row = rowSchema.safeParse(raw);
+            if (!row.success)
+                throw new ComputerInventoryError("partial_init");
+            return decode(row.data);
+        });
+        return {
+            computers: rows.slice(0, limit),
+            nextOffset: rows.length > limit ? offset + limit : null,
+        };
+    };
+    /** Every active Computer in this inventory. */
+    const ids = () => {
+        const found = [];
+        let offset = 0;
+        while (offset !== null) {
+            const page = list({ limit: 100, offset });
+            found.push(...page.computers.map(({ computerId }) => computerId));
+            offset = page.nextOffset;
+        }
+        return found;
+    };
+    /** Validate an existing receipt before the host decides whether a new create is funded. */
+    const replay = (actor, request) => {
+        const prior = sql
+            .exec("SELECT request_id,actor_kind,actor_id,requested_name,name,computer_id FROM hub_team_computer_create_receipts WHERE request_id=?", request.requestId)
+            .toArray()[0];
+        if (prior !== undefined) {
+            const receipt = receiptSchema.safeParse(prior);
+            if (!receipt.success)
+                throw new ComputerInventoryError("partial_init");
+            if (!sameActor(receipt.data.actor_kind, receipt.data.actor_id, actor) ||
+                receipt.data.requested_name !== (request.name ?? null))
+                throw new ComputerInventoryError("request_conflict");
+            const stored = rowSchema.safeParse(sql
+                .exec(`${selectRow} WHERE computer_id=?`, receipt.data.computer_id)
+                .toArray()[0]);
+            if (!stored.success ||
+                stored.data.active === 0 ||
+                stored.data.name !== receipt.data.name ||
+                stored.data.actor_kind !== receipt.data.actor_kind ||
+                stored.data.actor_id !== receipt.data.actor_id)
+                throw new ComputerInventoryError("partial_init");
+            return decode(stored.data);
+        }
+        return null;
+    };
+    /** The host has admitted creation; identity and its receipt commit together. */
+    const create = (actor, request) => options.transactionSync(() => {
+        const prior = replay(actor, request);
+        if (prior !== null)
+            return prior;
+        const name = request.name ?? generatedName();
+        if (request.name !== undefined && nameIsTaken(name))
+            throw new ComputerInventoryError("name_taken");
+        const computerId = computerIds.computer.generate();
+        const now = Date.now();
+        const columns = actorColumns(actor);
+        sql.exec("INSERT INTO hub_team_computers (computer_id,name,actor_kind,actor_id,active,created_at,updated_at) VALUES (?,?,?,?,?,?,?)", computerId, name, columns.actorKind, columns.actorId, 1, now, now);
+        sql.exec("INSERT INTO hub_team_computer_create_receipts (request_id,actor_kind,actor_id,requested_name,name,computer_id) VALUES (?,?,?,?,?,?)", request.requestId, columns.actorKind, columns.actorId, request.name ?? null, name, computerId);
+        const created = read(computerId);
+        if (created === null)
+            throw new ComputerInventoryError("partial_init");
+        return created;
+    });
+    return { ensure, replay, create, read, list, ids, count };
+}

package/dist/fleet/lifecycle.d.ts

@@ -0,0 +1,99 @@
+import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
+import type { ComputerDO as NativeComputerDO, OnBoxVmContainerHost } from "../index.js";
+import { type ContainerRuntimeStart, type HostedBacking, type AttachedBackend, type AttachedBackendView } from "../computer-backends.js";
+import { ComputerRuntimeUsage } from "./runtime-usage.js";
+import type { ComputerGrant } from "./wire.js";
+/** Runtime observations consumed by the host; never host callbacks. */
+export type FleetLifecycleFact = Readonly<{
+    kind: "reservation.release" | "reservation.monitor";
+}> | Readonly<{
+    kind: "diagnostic";
+    event: string;
+    code: string;
+    cause?: unknown;
+}>;
+/** Native runtime and storage capabilities, without host policy or settlement. */
+export type FleetLifecyclePorts = Readonly<{
+    storage: WatchdogSqliteOwner & Pick<DurableObjectStorage, "getAlarm" | "setAlarm">;
+    alarm: Pick<DurableObjectState, "waitUntil">;
+    computerId: string | undefined;
+    runtimeWatchMs: string | undefined;
+    backend: Readonly<{
+        state: Pick<DurableObjectState, "id" | "waitUntil"> & {
+            container?: Pick<NonNullable<DurableObjectState["container"]>, "running" | "monitor" | "destroy">;
+        };
+        onBoxVmHost: (hostId: string) => Pick<OnBoxVmContainerHost, "state" | "inventory" | "destroy">;
+        hostedContainerHost: (backing: HostedBacking) => Pick<ReturnType<NativeComputerDO["getWorkspaceContainer"]>, "restart">;
+        readyWorkspace: () => Promise<{
+            push: (id: string) => Promise<number>;
+            pull: (id: string) => Promise<object>;
+        }>;
+        workspace: () => {
+            push: (id: string) => Promise<number>;
+        };
+        syncRecycledWorkspace: (backing: HostedBacking) => Promise<void>;
+        attachedBackends: () => readonly AttachedBackend[];
+        describeBackends: () => AttachedBackendView[];
+        requireHostedRoute: () => {
+            backing: HostedBacking;
+            id: string;
+        };
+        containerRunning: (backing: HostedBacking) => Promise<boolean>;
+        vmQueuePosition: (hostId: string) => Promise<number | null>;
+    }>;
+}>;
+/** A grant refused before native execution. The host maps it to its public error. */
+export declare class FleetGrantRefused extends Error {
+    constructor();
+}
+/** Runtime activity, interval observations and recycling under host-issued grants. */
+export declare class FleetLifecycle {
+    #private;
+    private readonly ports;
+    readonly usage: ComputerRuntimeUsage;
+    constructor(ports: FleetLifecyclePorts);
+    get recycleRuntimeId(): string | undefined;
+    takeFacts(): FleetLifecycleFact[];
+    private diagnostic;
+    /** Keep pending starts visible while the host obtains admission and capacity. */
+    beginHostedStart(): () => void;
+    /** Read liveness without waking a sleeping backend. Queue state wins over booting. */
+    readComputerState(): Promise<{
+        state: "queued";
+        position: number;
+    } | {
+        state: "running" | "starting";
+        position?: never;
+    } | {
+        state: "running" | "sleeping";
+        position?: never;
+    }>;
+    /** The Computer page's read: each attached backend and its live status. */
+    readAttachedBackends(): Promise<(Omit<AttachedBackendView, "status"> & {
+        status: AttachedBackendView["status"] | "queued";
+        queuePosition: number | null;
+    })[]>;
+    /** Native execution remains the callback; policy has already become a grant. */
+    run<T>(grant: ComputerGrant, backing: HostedBacking, run: () => Promise<T>): Promise<T>;
+    /** Transport traffic advances activity; an idle open connection does not. */
+    trackResponse(backing: HostedBacking, response: Response): Response;
+    containerRuntimeStarted(start: ContainerRuntimeStart): void;
+    armRuntimeWatch(due: number): Promise<void>;
+    syncRecycledWorkspace(backing: HostedBacking): Promise<void>;
+    private finishVmRecycle;
+    private recycleQuietVms;
+    private observeRuntime;
+    awaitRecycle(): Promise<void>;
+    /** Reconcile durable observations before the host delivers usage facts. */
+    observe(): Promise<HostedBacking[]>;
+    /** The host supplies current permission; this owner chooses quiet runtime candidates. */
+    recycle(grant: ComputerGrant | null): Promise<void>;
+    watch(delivered: boolean, running: number): Promise<void>;
+    private recycleWatchDelay;
+    private observeOpenRuntimes;
+    /** Stop requested backends; failures remain host-readable observations. */
+    stop(runningBackings: readonly HostedBacking[]): Promise<void>;
+    /** Stop all known runtimes and report any still running. */
+    stopAll(reason: string): Promise<HostedBacking[]>;
+    private destroyRuntime;
+}

package/dist/fleet/lifecycle.js

@@ -0,0 +1,423 @@
+import * as Data from "effect/Data";
+import { computerContainerSleepAfterMs } from "../container-policy.js";
+import { attachedBackendId, } from "../computer-backends.js";
+import { z } from "zod";
+import { ComputerRuntimeUsage } from "./runtime-usage.js";
+import { checkComputerGrant } from "./admission.js";
+const vmRecycleAfterMs = 23 * 60 * 60 * 1_000;
+const vmRecycleQuietMs = 30_000;
+const runtimeWatchSchema = z.coerce
+    .number()
+    .int()
+    .min(1_000)
+    .max(3_600_000)
+    .catch(60_000);
+function runtimeWatchDelay(delivered, running, watchMs) {
+    if (running > 0)
+        return delivered ? watchMs : 1_000;
+    return delivered ? null : 30_000;
+}
+class ComputerVmRecycleError extends Data.TaggedError("ComputerVmRecycleError") {
+}
+/** A grant refused before native execution. The host maps it to its public error. */
+export class FleetGrantRefused extends Error {
+    constructor() {
+        super("Computer grant refused");
+        this.name = "FleetGrantRefused";
+    }
+}
+/** Runtime activity, interval observations and recycling under host-issued grants. */
+export class FleetLifecycle {
+    ports;
+    usage;
+    #watchMs;
+    #hostedOperations = 0;
+    #startingHosted = 0;
+    #lastHostedActivity = Date.now();
+    #recycling;
+    #recycleRuntimeId;
+    #facts = [];
+    constructor(ports) {
+        this.ports = ports;
+        this.#watchMs = runtimeWatchSchema.parse(ports.runtimeWatchMs ?? 60_000);
+        this.usage = new ComputerRuntimeUsage(ports.storage.sql, this.#watchMs);
+    }
+    get recycleRuntimeId() {
+        return this.#recycleRuntimeId;
+    }
+    takeFacts() {
+        const facts = this.#facts;
+        this.#facts = [];
+        return facts;
+    }
+    diagnostic(event, code, cause) {
+        this.#facts.push({ kind: "diagnostic", event, code, cause });
+    }
+    /** Keep pending starts visible while the host obtains admission and capacity. */
+    beginHostedStart() {
+        this.#startingHosted++;
+        return () => {
+            this.#startingHosted--;
+        };
+    }
+    /** Read liveness without waking a sleeping backend. Queue state wins over booting. */
+    async readComputerState() {
+        const backends = await this.readAttachedBackends();
+        const position = backends.find((backend) => backend.queuePosition !== null)?.queuePosition;
+        if (position != null)
+            return { state: "queued", position };
+        if (this.#startingHosted > 0)
+            return { state: "starting" };
+        for (const backing of this.ports.backend.attachedBackends()) {
+            if (backing.kind === "on-box-vm") {
+                const runtime = await this.ports.backend
+                    .onBoxVmHost(backing.hostId)
+                    .state();
+                if (runtime.running)
+                    return {
+                        state: runtime.runtimeId === null
+                            ? "starting"
+                            : "running",
+                    };
+            }
+            else if (backing.kind === "platform-container" &&
+                (await this.ports.backend.containerRunning(backing))) {
+                return { state: "running" };
+            }
+        }
+        return {
+            state: backends.some((backend) => backend.status === "online")
+                ? "running"
+                : "sleeping",
+        };
+    }
+    /** The Computer page's read: each attached backend and its live status. */
+    async readAttachedBackends() {
+        return await Promise.all(this.ports.backend.describeBackends().map(async (backend) => {
+            const queuePosition = backend.kind === "on-box-vm" && backend.hostId !== undefined
+                ? await this.ports.backend.vmQueuePosition(backend.hostId)
+                : null;
+            return {
+                ...backend,
+                status: queuePosition === null ? backend.status : "queued",
+                queuePosition,
+            };
+        }));
+    }
+    /** Native execution remains the callback; policy has already become a grant. */
+    async run(grant, backing, run) {
+        await this.awaitRecycle();
+        if (checkComputerGrant(grant, {
+            computerId: this.ports.computerId ?? "",
+            action: "start",
+            now: Date.now(),
+        }).kind !== "admitted")
+            throw new FleetGrantRefused();
+        this.#hostedOperations++;
+        try {
+            if (backing.kind === "platform-container")
+                this.usage.touchActivity(backing, Date.now());
+            return await run();
+        }
+        finally {
+            this.#hostedOperations--;
+            this.#lastHostedActivity = Date.now();
+            if (backing.kind === "platform-container")
+                this.usage.touchActivity(backing, this.#lastHostedActivity);
+            if (backing.kind === "on-box-vm") {
+                if (!this.usage.hasOpen(backing))
+                    this.#facts.push({ kind: "reservation.release" });
+            }
+            else {
+                this.#facts.push({
+                    kind: this.ports.backend.state.container?.running
+                        ? "reservation.monitor"
+                        : "reservation.release",
+                });
+            }
+        }
+    }
+    /** Transport traffic advances activity; an idle open connection does not. */
+    trackResponse(backing, response) {
+        const socket = response.webSocket ?? null;
+        if (socket === null && response.body === null)
+            return response;
+        let lastRecordedAt = Date.now();
+        const recordTraffic = () => {
+            const now = Date.now();
+            if (now - lastRecordedAt < 30_000)
+                return;
+            lastRecordedAt = now;
+            this.#lastHostedActivity = now;
+            if (backing.kind === "platform-container")
+                this.usage.touchActivity(backing, now);
+        };
+        if (socket !== null) {
+            const pair = new WebSocketPair();
+            const client = pair[0];
+            const server = pair[1];
+            const close = (event) => {
+                const code = event.code === 1000 || (event.code >= 3000 && event.code <= 4999)
+                    ? event.code
+                    : 1000;
+                if (socket.readyState === WebSocket.OPEN)
+                    socket.close(code, event.reason);
+                if (server.readyState === WebSocket.OPEN)
+                    server.close(code, event.reason);
+            };
+            const fail = () => {
+                if (socket.readyState === WebSocket.OPEN)
+                    socket.close(1000, "Terminal transport failed");
+                if (server.readyState === WebSocket.OPEN)
+                    server.close(1000, "Terminal transport failed");
+            };
+            socket.addEventListener("message", (event) => {
+                recordTraffic();
+                server.send(event.data);
+            });
+            server.addEventListener("message", (event) => {
+                recordTraffic();
+                socket.send(event.data);
+            });
+            socket.addEventListener("close", close, { once: true });
+            server.addEventListener("close", close, { once: true });
+            socket.addEventListener("error", fail, { once: true });
+            server.addEventListener("error", fail, { once: true });
+            // Workers delivers binary frames as Blob by default; send accepts bytes.
+            socket.binaryType = "arraybuffer";
+            server.binaryType = "arraybuffer";
+            socket.accept();
+            server.accept();
+            return new Response(null, {
+                status: 101,
+                webSocket: client,
+                headers: response.headers,
+            });
+        }
+        const reader = response.body?.getReader();
+        if (reader === undefined) {
+            return response;
+        }
+        const body = new ReadableStream({
+            async pull(controller) {
+                try {
+                    const result = await reader.read();
+                    if (result.done) {
+                        controller.close();
+                    }
+                    else {
+                        const chunk = z.instanceof(Uint8Array).parse(result.value);
+                        if (chunk.byteLength > 0)
+                            recordTraffic();
+                        controller.enqueue(chunk);
+                    }
+                }
+                catch (cause) {
+                    controller.error(cause);
+                }
+            },
+            async cancel(reason) {
+                await reader.cancel(reason);
+            },
+        });
+        return new Response(body, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+        });
+    }
+    containerRuntimeStarted(start) {
+        this.usage.started(start);
+        this.ports.alarm.waitUntil(this.armRuntimeWatch(Date.now() + this.#watchMs));
+    }
+    async armRuntimeWatch(due) {
+        const alarm = await this.ports.storage.getAlarm();
+        if (alarm === null || alarm > due)
+            await this.ports.storage.setAlarm(due);
+    }
+    async syncRecycledWorkspace(backing) {
+        const workspace = await this.ports.backend.readyWorkspace();
+        const id = attachedBackendId(backing);
+        await workspace.push(id);
+        await workspace.pull(id);
+    }
+    async finishVmRecycle() {
+        for (const row of this.usage.pendingRecycles()) {
+            const backing = row.backing;
+            const current = await this.ports.backend
+                .onBoxVmHost(backing.hostId)
+                .state();
+            if (!(current.running && current.runtimeId === row.runtimeId)) {
+                this.usage.observe(row.runtimeId, {
+                    running: false,
+                    endedAt: row.requestedAt,
+                });
+                if (current.running && current.runtimeId !== null)
+                    this.containerRuntimeStarted({
+                        runtimeId: current.runtimeId,
+                        backing,
+                        startedAt: Date.now(),
+                    });
+            }
+            if (!current.running &&
+                this.#hostedOperations === 0 &&
+                !this.usage.hasAnyOpen())
+                this.#facts.push({ kind: "reservation.release" });
+            this.usage.finishRecycle(row.runtimeId);
+        }
+    }
+    async recycleQuietVms(grant) {
+        if (this.#hostedOperations > 0 ||
+            Date.now() - this.#lastHostedActivity < vmRecycleQuietMs)
+            return;
+        const candidates = this.usage.recycleCandidates(Date.now() - vmRecycleAfterMs);
+        for (const row of candidates) {
+            const backing = row.backing;
+            if (backing.kind !== "on-box-vm" ||
+                grant === null ||
+                checkComputerGrant(grant, {
+                    computerId: this.ports.computerId ?? "",
+                    action: "start",
+                    now: Date.now(),
+                }).kind !== "admitted")
+                continue;
+            const inventory = await this.ports.backend
+                .onBoxVmHost(backing.hostId)
+                .inventory();
+            const vm = inventory.find((entry) => entry.id === this.ports.backend.state.id.toString());
+            if (vm === undefined ||
+                !vm.running ||
+                vm.runtimeId !== row.runtimeId ||
+                Date.now() - vm.lastActive < vmRecycleQuietMs)
+                continue;
+            this.#recycleRuntimeId = row.runtimeId;
+            try {
+                await this.ports.backend.syncRecycledWorkspace(backing);
+                const current = await this.ports.backend
+                    .onBoxVmHost(backing.hostId)
+                    .state();
+                if (!current.running || current.runtimeId !== row.runtimeId)
+                    continue;
+                this.usage.requestRecycle(row.runtimeId, backing, Date.now());
+                await this.armRuntimeWatch(Date.now() + vmRecycleQuietMs);
+                const started = await this.ports.backend
+                    .hostedContainerHost(backing)
+                    .restart({}, false);
+                this.#recycleRuntimeId = started.runtimeId;
+                await this.finishVmRecycle();
+                await this.ports.backend.syncRecycledWorkspace(backing);
+            }
+            finally {
+                this.#recycleRuntimeId = undefined;
+                await this.finishVmRecycle();
+            }
+        }
+    }
+    async observeRuntime(runtimeId, backing, newest) {
+        const now = Date.now();
+        if (backing.kind === "platform-container") {
+            const container = this.ports.backend.state.container;
+            if (newest && container?.running === true) {
+                const deadline = this.usage.idleDeadline(runtimeId, computerContainerSleepAfterMs, now);
+                if (deadline !== null &&
+                    this.#hostedOperations === 0 &&
+                    now >= deadline) {
+                    try {
+                        await container.destroy(new Error("Computer idle timeout"));
+                    }
+                    catch (cause) {
+                        this.diagnostic("computer_idle_stop_failed", "idle_stop", cause);
+                        return { running: true, endedAt: now };
+                    }
+                    return { running: false, endedAt: deadline };
+                }
+                return { running: true, endedAt: now };
+            }
+            return { running: false, endedAt: now };
+        }
+        const state = await this.ports.backend.onBoxVmHost(backing.hostId).state();
+        return {
+            running: state.running && state.runtimeId === runtimeId,
+            endedAt: state.exit?.exitedAt ?? now,
+        };
+    }
+    async awaitRecycle() {
+        const error = await this.#recycling;
+        if (error !== undefined)
+            throw error;
+    }
+    /** Reconcile durable observations before the host delivers usage facts. */
+    async observe() {
+        await this.#recycling;
+        this.usage.ensure();
+        await this.finishVmRecycle();
+        return this.observeOpenRuntimes();
+    }
+    /** The host supplies current permission; this owner chooses quiet runtime candidates. */
+    async recycle(grant) {
+        if (this.#recycling !== undefined)
+            return;
+        const recycling = this.recycleQuietVms(grant).then(() => undefined, (cause) => {
+            const error = new ComputerVmRecycleError({ cause });
+            this.diagnostic("computer_vm_recycle_failed", "vm_recycle", error);
+            return error;
+        });
+        this.#recycling = recycling;
+        try {
+            await recycling;
+        }
+        finally {
+            this.#recycling = undefined;
+        }
+    }
+    async watch(delivered, running) {
+        const delay = runtimeWatchDelay(delivered, running, this.#watchMs);
+        if (delay !== null)
+            await this.armRuntimeWatch(Date.now() + this.recycleWatchDelay(delay));
+    }
+    recycleWatchDelay(delay) {
+        const oldest = this.usage.oldestVmStart();
+        if (oldest === null)
+            return delay;
+        return Math.min(delay, Math.max(vmRecycleQuietMs, oldest + vmRecycleAfterMs - Date.now()));
+    }
+    async observeOpenRuntimes() {
+        const open = this.usage.open();
+        const runningBackings = [];
+        for (const [index, row] of open.entries()) {
+            const observed = await this.observeRuntime(row.runtimeId, row.backing, index === 0);
+            if (observed.running)
+                runningBackings.push(row.backing);
+            this.usage.observe(row.runtimeId, observed);
+        }
+        if (open.length > 0 &&
+            this.#hostedOperations === 0 &&
+            runningBackings.length === 0)
+            this.#facts.push({ kind: "reservation.release" });
+        return runningBackings;
+    }
+    /** Stop requested backends; failures remain host-readable observations. */
+    async stop(runningBackings) {
+        const stopped = await Promise.allSettled(runningBackings.map((backing) => this.destroyRuntime(backing)));
+        if (stopped.some((result) => result.status === "rejected"))
+            this.diagnostic("computer_usage_stop_failed", "usage_stop");
+    }
+    /** Stop all known runtimes and report any still running. */
+    async stopAll(reason) {
+        this.usage.ensure();
+        const backings = this.usage.open().map(({ backing }) => backing);
+        await Promise.all(backings.map((backing) => this.destroyRuntime(backing)));
+        if (this.ports.backend.state.container?.running === true &&
+            backings.length === 0)
+            await this.ports.backend.state.container.destroy(new Error(reason));
+        return this.observeOpenRuntimes();
+    }
+    async destroyRuntime(backing) {
+        if (backing.kind === "on-box-vm") {
+            await this.ports.backend.onBoxVmHost(backing.hostId).destroy();
+            return;
+        }
+        if (this.ports.backend.state.container !== undefined)
+            await this.ports.backend.state.container.destroy(new Error("Computer usage delivery unavailable"));
+    }
+}